docs: follow-ups from the v2.1.220 accuracy review (#161)

* fix(ci): move the EPUB build out of pre-commit into CI The build-epub hooks called scripts/build_epub.py, which raises when the mmdc binary is missing, while check_mermaid.py skips with a warning in the same situation. On arm64 — where @mermaid-js/mermaid-cli has no working build — that made 'pre-commit run --all-files' impossible to satisfy for a docs-only change without --no-verify. Remove the build-epub, vietnamese-build-epub and japanese-build-epub hooks and widen the CI build-epub job to a language matrix so PR-time coverage is not reduced: it previously built en only, and now builds en, vi, zh and ja. zh was covered by neither the hooks nor this job, so a broken zh diagram could only surface at release time. Closes #156 * docs: replace the stale Kroki narrative with local mmdc rendering Commit e76bbe4 swapped the Kroki HTTP dependency for local mmdc rendering but left the docs describing the old design. The claim appeared in seven live files, not the two originally reported: CLAUDE.md, scripts/README.md and their ja/uk/vi copies. Also corrects what the same staleness dragged along: - scripts/README.md documented --timeout and --max-concurrent, which no longer exist, and omitted --mmdc-path, --lang and --puppeteer-config - 'Async concurrent fetching' described a render_all() that is now a plain sequential loop with a dedupe cache - the network-error/rate-limiting troubleshooting entries are replaced with the failures that actually occur now (missing mmdc, Chromium sandbox) CHANGELOG entries recording the Kroki-to-mmdc switch are left alone; they describe the past accurately. Closes #157 * fix(scripts): make the ruff config match files that exist Ruff resolves include/per-file-ignores patterns relative to the directory holding pyproject.toml. Since the config lives in scripts/, the pattern "scripts/**/*.py" meant scripts/scripts/**/*.py, which matches nothing — 'ruff check scripts/' printed 'warning: No Python files found under the given path(s)' and then 'All checks passed!'. per-file-ignores had the same mistake. Both are now relative to scripts/, so ruff sees all 14 files. This silently disabled the pre-commit ruff hooks too, not just the documented command, and two test files had drifted out of format as a result. Reformatting them exposed a second problem: the pre-commit hook pinned ruff v0.8.2 while the CI lint job installs unpinned latest and this venv has 0.15.10. The versions disagree on formatting, so each reverted the other's output, and CI would have started failing on a file the local hook kept rewriting. Bump the hook pin and the requirements-dev floor to 0.15.10 so all three agree. Verified: 'pre-commit run --all-files' is stable across consecutive runs, 'ruff format --check scripts/' and 'ruff check scripts/' both pass, 92 tests pass. Closes #160 * docs: point localized module links at their own trees Files at the root of a language directory used ../NN-module/, which from uk/CATALOG.md resolves to the English 05-mcp/ at the repo root rather than uk/05-mcp/. Readers following a count stated about the localized tree landed in the English one. The link checker never caught it because the English target does exist. Files one level deeper (uk/04-subagents/README.md and friends) were already correct — ../06-hooks/ from there resolves to uk/06-hooks/ — so this is scoped to the 7 depth-1 files that actually escape: CATALOG.md in uk, vi, ja and zh, LEARNING-ROADMAP.md in uk and vi, and ja/claude_concepts_guide.md. 119 links in total. The ../NN- occurrences left in STYLE_GUIDE.md and TRANSLATION_NOTES.md are inside fenced examples showing what a module page should contain, where the ../ form is the correct convention. All 119 rewritten targets were verified to exist. Closes #158 * docs(hooks): stop conflating hook types with hook event categories '**Hook Types** (5 types, 31 events)' sat above four bullets, so the count read as wrong. It was not — the two numbers describe different axes that had been merged into one label. 06-hooks/README.md:126 documents five hook *types*: command, http, prompt, mcp_tool and agent. Those describe how a hook runs. The four bullets are event *categories* — Tool, Session, Task, Lifecycle — holding 31 events (6+7+6+12), and describe when it runs. Split the label so each number belongs to the axis it counts, in all nine affected files: README.md and INDEX.md plus the ja, uk, vi and zh copies. QUICK_REFERENCE.md and LEARNING-ROADMAP.md already stated '5 types' with the handler names attached and needed no change. Closes #159 * chore(scripts): drop the unused httpx dependency httpx was the HTTP client for Kroki rendering. Nothing has imported it since e76bbe4 moved diagram rendering to a local mmdc subprocess — check_links.py, the only other network caller, uses stdlib urllib.request. The PEP 723 blocks in build_epub.py and build_website.py had already dropped it; only the manifests and docs still declared it. Removes it from requirements.txt, pyproject.toml dependencies, the dependency tables and uv --with lines in scripts/README.md and its ja/uk copies, and the .cspell.json word list. Also drops the B113 bandit suppression, which existed solely for an httpx timeout false positive — bandit reports no issues without it. Also corrects two Requirements lines missed in the previous pass: the ja and uk script READMEs still listed an internet connection rather than mmdc. Note: tenacity is now dead for the same reason and is left in place. * chore(scripts): drop the unused tenacity dependency Nothing imports tenacity — the retry logic it was added for went away with the Kroki HTTP fetching in e76bbe4. It was still declared in requirements.txt, pyproject.toml, both `uv run --with` lines and all three dependency tables. * docs(i18n): sync the localized pre-commit check lists The ja/uk/vi CLAUDE.md files still listed build-epub as pre-commit check #5, stale since 6da8184 moved the EPUB build to CI. They also omitted markdown-rendering, and the ja/uk stated counts disagreed with their own lists. Now matches the English CLAUDE.md. * fix(scripts): silence PLR0917 now stable in ruff 0.16 CI installs the latest ruff (uv pip install ruff, unpinned), and 0.16.1 promoted too-many-positional-arguments from preview to stable, hard-failing the Code Quality check on build_epub.py's long-signature draw/helper functions. These sit in the same family as PLR0913, which is already ignored. Add PLR0917 so the local 0.15.10 pin and unpinned CI lint agree again.
2026-08-08 00:08:36 +02:00 · 2026-08-06 07:58:46 +07:00
parent b9a973bf32
commit 4f3fa85d7e
31 changed files with 270 additions and 241 deletions
@@ -123,9 +123,7 @@
    "asyncio",
    "beautifulsoup",
    "ebooklib",
-    "httpx",
    "pillow",
-    "tenacity",
    "cSpell",
    "markdownlint",
    "Kroki",
@@ -143,11 +143,21 @@ jobs:
        run: uv run mypy scripts/ --config-file scripts/pyproject.toml

  build-epub:
-    name: Build EPUB Artifact
+    name: Build EPUB Artifact (${{ matrix.lang }})
    runs-on: ubuntu-latest
    needs: [pytest, lint, security, type-check]
    if: ${{ !failure() && !cancelled() }}

+    # This job is the only gate on the EPUB build — the equivalent pre-commit
+    # hooks were removed because they need a local `mmdc` binary that has no
+    # working arm64 build. The matrix covers every language build_epub.py
+    # accepts, so a broken diagram in any tree fails here rather than at
+    # release time.
+    strategy:
+      fail-fast: false
+      matrix:
+        lang: [en, vi, zh, ja]
+
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
@@ -169,13 +179,17 @@ jobs:
      - name: Build EPUB
        run: |
          echo '{"args":["--no-sandbox","--disable-setuid-sandbox"]}' > /tmp/puppeteer-ci.json
-          uv run scripts/build_epub.py --puppeteer-config /tmp/puppeteer-ci.json
+          uv run scripts/build_epub.py \
+            --lang ${{ matrix.lang }} \
+            --puppeteer-config /tmp/puppeteer-ci.json

      - name: Verify EPUB Created
        run: |
-          if [ -f claude-howto-guide.epub ]; then
+          shopt -s nullglob
+          built=(claude-howto-guide*.epub)
+          if [ ${#built[@]} -gt 0 ]; then
            echo "✅ EPUB built successfully"
-            ls -lh claude-howto-guide.epub
+            ls -lh "${built[@]}"
          else
            echo "❌ EPUB file not found!"
            exit 1
@@ -184,8 +198,9 @@ jobs:
      - name: Upload EPUB Artifact
        uses: actions/upload-artifact@v4
        with:
-          name: claude-howto-guide-epub
-          path: claude-howto-guide.epub
+          name: claude-howto-guide-epub-${{ matrix.lang }}
+          path: claude-howto-guide*.epub
+          if-no-files-found: error
          retention-days: 7
          compression-level: 0

@@ -213,7 +228,7 @@ jobs:
          echo "## Artifacts" >> $GITHUB_STEP_SUMMARY
          echo "- pytest-results-* (coverage and test results)" >> $GITHUB_STEP_SUMMARY
          echo "- bandit-security-report (security scan JSON)" >> $GITHUB_STEP_SUMMARY
-          echo "- claude-howto-guide-epub (built EPUB file)" >> $GITHUB_STEP_SUMMARY
+          echo "- claude-howto-guide-epub-* (built EPUB file, one per language)" >> $GITHUB_STEP_SUMMARY

      - name: Check if all tests passed
        if: |
@@ -7,8 +7,11 @@ default_language_version:

 repos:
  # Ruff - Fast Python linter and formatter
+  # Keep this in step with the `ruff` floor in scripts/requirements-dev.txt and
+  # the unpinned `uv pip install ruff` in the CI lint job. A stale pin here
+  # reformats files the newer ruff in CI then rejects, and vice versa.
  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.2
+    rev: v0.15.10
    hooks:
      - id: ruff
        name: ruff-lint
@@ -104,12 +107,10 @@ repos:
        pass_filenames: false
        types: [markdown]

-      - id: build-epub
-        name: build-epub
-        language: system
-        entry: uv run scripts/build_epub.py
-        pass_filenames: false
-        files: ^(.*\.md|scripts/build_epub\.py)$
+      # The EPUB build is intentionally CI-only (see the `build-epub` job in
+      # .github/workflows/test.yml). It needs a local `mmdc` binary, which has
+      # no working arm64 build, so running it here made the gate impossible to
+      # satisfy on arm64 machines while `check_mermaid.py` skipped silently.

  # Vietnamese documentation checks
  - repo: local
@@ -145,13 +146,6 @@ repos:
        files: ^vi/.*\.md$
        verbose: true

-      - id: vietnamese-build-epub
-        name: vietnamese-build-epub
-        language: system
-        entry: uv run scripts/build_epub.py --lang vi
-        pass_filenames: false
-        files: ^(vi/.*\.md|scripts/build_epub\.py)$
-
  # Japanese documentation checks
  - repo: local
    hooks:
@@ -185,10 +179,3 @@ repos:
        pass_filenames: false
        files: ^ja/.*\.md$
        verbose: true
-
-      - id: japanese-build-epub
-        name: japanese-build-epub
-        language: system
-        entry: uv run scripts/build_epub.py --lang ja
-        pass_filenames: false
-        files: ^(ja/.*\.md|scripts/build_epub\.py)$
@@ -13,7 +13,7 @@ pre-commit run --all-files
 # Tests
 pytest scripts/tests/ -v

-# EPUB build (calls Kroki.io API to render Mermaid — needs network)
+# EPUB build (renders Mermaid with the local mmdc CLI — no network, needs mmdc on PATH)
 uv run scripts/build_epub.py

 # Python tooling
@@ -22,7 +22,7 @@ mypy scripts/ --ignore-missing-imports
 bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
 ```

-Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
+Pre-commit runs 5 doc checks on `.md` changes: markdown-lint, cross-references, mermaid-syntax, link-check, markdown-rendering. All must pass. The EPUB build is **not** a pre-commit hook — it runs in CI only (`build-epub` job in `.github/workflows/test.yml`), because it needs a local `mmdc` binary that has no working arm64 build.

 ## Architecture map

@@ -40,7 +40,7 @@ Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-
 - Internal links use **relative paths** (e.g. `01-slash-commands/README.md`); anchors use `#heading-name`.
 - Code fences **must** declare a language (`bash`, `python`, `json`, …) — the cross-reference check fails otherwise.
 - External URLs must be reachable and stable. No ephemeral links.
- Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
+- Mermaid diagrams must parse (validated pre-commit, and only when `mmdc` is installed — the check skips with a warning otherwise). A broken EPUB build is usually invalid Mermaid or a missing/failing `mmdc`.
 - Commit format: `type(scope): subject` where `scope` matches the module folder (e.g. `feat(slash-commands):`, `docs(memory):`, `fix(README):`).
 - Do not reorganize the `01-`–`10-` numbering. The order is the curriculum.

@@ -222,7 +222,9 @@ Event-driven automation scripts that execute automatically.

 **Usage**: Configured in settings, executed automatically

-**Hook Types** (5 types, 31 events):
+**Hook Types** (5): `command`, `http`, `prompt`, `mcp_tool`, `agent` — how a hook runs.
+
+**Hook Events** (31, in 4 categories) — when it runs:
 - Tool Hooks: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied
 - Session Hooks: SessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop
 - Task Hooks: UserPromptSubmit, UserPromptExpansion, MessageDisplay, TaskCompleted, TaskCreated, TeammateIdle
@@ -482,7 +482,9 @@ Configure hooks in `~/.claude/settings.json`:

 **Usage**: Hooks execute automatically on events

-**Hook Types** (5 types, 31 events):
+**Hook Types** (5): `command`, `http`, `prompt`, `mcp_tool`, `agent` — how a hook runs.
+
+**Hook Events** (31, in 4 categories) — when it runs:
 - **Tool Hooks**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `PermissionRequest`, `PermissionDenied`
 - **Session Hooks**: `SessionStart`, `Setup`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`
 - **Task Hooks**: `UserPromptSubmit`, `UserPromptExpansion`, `MessageDisplay`, `TaskCompleted`, `TaskCreated`, `TeammateIdle`
@@ -136,7 +136,7 @@ Claude Code はツール使用の許可を制御する 6 つの権限モード
 | `bypassPermissions` | すべての権限チェックをスキップ | CI/CD、ヘッドレス環境 |
 | `dontAsk` | 権限が必要なツールをスキップ | 非対話スクリプト |

-> **注**：`auto` モードは対象プラン・モデル・プロバイダの条件を満たす必要がある — [09-advanced-features/](../09-advanced-features/#auto-mode) を参照。`bypassPermissions` は信頼されたサンドボックス環境でのみ利用すること。
+> **注**：`auto` モードは対象プラン・モデル・プロバイダの条件を満たす必要がある — [09-advanced-features/](09-advanced-features/#auto-mode) を参照。`bypassPermissions` は信頼されたサンドボックス環境でのみ利用すること。

 **リファレンス**：[公式ドキュメント](https://code.claude.com/docs/en/permissions)

@@ -16,7 +16,7 @@ Claude How To は Claude Code 機能のチュートリアルリポジトリで

 ### pre-commit 品質チェック

-すべてのドキュメントは、コミット前に 4 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：
+すべてのドキュメントは、コミット前に 5 つの品質チェックを通過しなければならない（pre-commit フックで自動実行される）：

 ```bash
 # pre-commit フックをインストール（毎コミットで実行）
@@ -26,12 +26,14 @@ pre-commit install
 pre-commit run --all-files
 ```

-4 つのチェックは以下のとおり：
+5 つのチェックは以下のとおり：
 1. **markdown-lint** — `markdownlint` による Markdown 構造とフォーマット
 2. **cross-references** — 内部リンク、アンカー、コードフェンスの構文（Python スクリプト）
 3. **mermaid-syntax** — すべての Mermaid 図が正しくパースされるかを検証（Python スクリプト）
 4. **link-check** — 外部 URL が到達可能か（Python スクリプト）
-5. **build-epub** — EPUB がエラーなく生成されるか（`.md` 変更時）
+5. **markdown-rendering** — Markdown が壊れずにレンダリングされるか（Python スクリプト）
+
+EPUB ビルドは pre-commit フック **ではない** — CI のみで実行される（`.github/workflows/test.yml` の `build-epub` ジョブ）。ローカルの `mmdc` バイナリが必要であり、arm64 で動作するビルドが存在しないためである。

 ### 開発環境のセットアップ

@@ -85,11 +87,11 @@ mypy scripts/ --ignore-missing-imports
 ### EPUB ビルド

 ```bash
-# 電子書籍を生成（Mermaid 図を Kroki.io API でレンダリング）
+# 電子書籍を生成（Mermaid 図はローカルの mmdc CLI でレンダリング／ネットワーク不要）
 uv run scripts/build_epub.py

 # オプション付き
-uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
+uv run scripts/build_epub.py --verbose --output custom-name.epub --lang ja
 ```

 ## ディレクトリ構造
@@ -106,7 +108,7 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren
 ├── 09-advanced-features/   # プランニング、シンキング、バックグラウンド
 ├── 10-cli/                 # CLI リファレンス
 ├── scripts/
-│   ├── build_epub.py           # EPUB ジェネレータ（Mermaid を Kroki API でレンダリング）
+│   ├── build_epub.py           # EPUB ジェネレータ（Mermaid をローカル mmdc でレンダリング）
 │   ├── check_cross_references.py   # 内部リンクを検証
 │   ├── check_links.py          # 外部 URL を検証
 │   ├── check_mermaid.py        # Mermaid 構文を検証
@@ -125,7 +127,7 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren

 ### Mermaid 図
 - すべての図は正常にパースできること（pre-commit フックで検査）
- EPUB ビルドは Kroki.io API で図をレンダリングする（インターネット接続が必要）
+- EPUB ビルドはローカルの `mmdc` CLI で図をレンダリングする（ネットワークは不要だが `mmdc` が必要）
 - フローチャート、シーケンス図、アーキテクチャ可視化に Mermaid を使用する

 ### 相互参照
@@ -144,9 +146,9 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren

 2. **スクリプトはユーティリティであり製品ではない** — `scripts/` の Python スクリプトはドキュメント品質と EPUB 生成を支援するものである。実際のコンテンツは番号付きモジュールフォルダにある。

-3. **pre-commit がゲートキーパー** — PR が承認される前に 4 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。
+3. **pre-commit がゲートキーパー** — PR が承認される前に 5 つの品質チェックがすべて通過しなければならない。CI パイプラインは同じチェックを 2 回目のパスとして実行する。

-4. **Mermaid のレンダリングにはネットワークが必要** — EPUB ビルドは図のレンダリングに Kroki.io API を呼び出す。ここでビルドが失敗する場合は、ネットワーク問題か Mermaid 構文エラーが典型的な原因である。
+4. **Mermaid のレンダリングにはローカルの `mmdc` が必要** — EPUB ビルドは図のレンダリングにローカルの `mmdc` CLI を呼び出す（ネットワークは不要）。ここでビルドが失敗する場合は、`mmdc` が未インストールか、Mermaid 構文エラーが典型的な原因である。EPUB ビルド自体は pre-commit では実行されず、CI のみで実行される。

 5. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。

@@ -224,7 +224,9 @@ blog-draft/

 **使い方**：設定で構成し、自動実行される

-**フックの種類**（5 系統、31 イベント）：
+**フックの種類**（5 種）：`command`、`http`、`prompt`、`mcp_tool`、`agent` — フックの実行方式。
+
+**フックイベント**（31 件、4 カテゴリ）— 実行タイミング：
 - ツール系フック：PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、PermissionRequest、PermissionDenied
 - セッション系フック：SessionStart、Setup、SessionEnd、Stop、StopFailure、SubagentStart、SubagentStop
 - タスク系フック：UserPromptSubmit、UserPromptExpansion、MessageDisplay、TaskCompleted、TaskCreated、TeammateIdle
@@ -486,7 +486,9 @@ chmod +x ~/.claude/hooks/*.sh

 **使い方**：イベント発生時にフックが自動実行される

-**フックの種類**（5 系統、31 イベント）：
+**フックの種類**（5 種）：`command`、`http`、`prompt`、`mcp_tool`、`agent` — フックの実行方式。
+
+**フックイベント**（31 件、4 カテゴリ）— 実行タイミング：
 - **ツール系フック**：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PostToolBatch`、`PermissionRequest`、`PermissionDenied`
 - **セッション系フック**：`SessionStart`、`Setup`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`
 - **タスク系フック**：`UserPromptSubmit`、`UserPromptExpansion`、`MessageDisplay`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`
@@ -2896,7 +2896,7 @@ Claude Code は 5 種類（command、http、mcp_tool、prompt、agent）にわ
 - 長時間タスクをフックで実行する
 - 認証情報をハードコードする

-**詳細：** [06-hooks/](../06-hooks/)
+**詳細：** [06-hooks/](06-hooks/)

 ---

@@ -2950,7 +2950,7 @@ Esc + Esc
 }
 ```

-**詳細：** [08-checkpoints/](../08-checkpoints/)
+**詳細：** [08-checkpoints/](08-checkpoints/)

 ---

@@ -3118,7 +3118,7 @@ User: \
 }
 ```

-**詳細ガイド：** [09-advanced-features/](../09-advanced-features/)
+**詳細ガイド：** [09-advanced-features/](09-advanced-features/)

 ---

@@ -13,8 +13,8 @@ Claude How-To の Markdown ファイル群から EPUB 形式の電子書籍を
 ## 特徴

 - フォルダ構成（01-slash-commands、02-memory など）に沿って章を整理する
- Mermaid 図を Kroki.io API 経由で PNG 画像としてレンダリングする
- 非同期並行取得 — すべての図を並列にレンダリングする
+- Mermaid 図をローカルの `mmdc` CLI で PNG 画像としてレンダリングする（ネットワーク不要）
+- 同一の図をキャッシュし、ユニークな図は一度だけレンダリングする
 - プロジェクトロゴから表紙画像を生成する
 - 内部 Markdown リンクを EPUB の章参照へ変換する
 - 厳格モード — レンダリング不能な図があればビルドを失敗させる
@@ -23,7 +23,7 @@ Claude How-To の Markdown ファイル群から EPUB 形式の電子書籍を

 - Python 3.10+
 - [uv](https://github.com/astral-sh/uv)
- Mermaid 図レンダリング用のインターネット接続
+- Mermaid 図レンダリング用の [`mmdc`](https://github.com/mermaid-js/mermaid-cli)（`npm install -g @mermaid-js/mermaid-cli`）

 ## クイックスタート

@@ -53,15 +53,17 @@ python scripts/build_epub.py

 ```
 usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose]
-                     [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT]
+                     [--mmdc-path MMDC_PATH] [--lang {en,vi,zh,ja}]
+                     [--puppeteer-config PUPPETEER_CONFIG]

 options:
  -h, --help            show this help message and exit
  --root, -r ROOT       Root directory (default: repo root)
  --output, -o OUTPUT   Output path (default: claude-howto-guide.epub)
  --verbose, -v         Enable verbose logging
-  --timeout TIMEOUT     API timeout in seconds (default: 30)
-  --max-concurrent N    Max concurrent requests (default: 10)
+  --mmdc-path PATH      Path to mmdc binary (default: mmdc from PATH)
+  --lang {en,vi,zh,ja}  Language to build (default: en)
+  --puppeteer-config P  Puppeteer config JSON passed to mmdc via -p
 ```

 ## 使用例
@@ -73,8 +75,11 @@ uv run scripts/build_epub.py --verbose
 # 出力先をカスタマイズ
 uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub

-# 並行リクエスト数を制限（レート制限を受ける場合）
-uv run scripts/build_epub.py --max-concurrent 5
+# 日本語版をビルド
+uv run scripts/build_epub.py --lang ja
+
+# PATH にない mmdc を指定する
+uv run scripts/build_epub.py --mmdc-path ./node_modules/.bin/mmdc
 ```

 ## 出力
@@ -97,7 +102,7 @@ pytest scripts/tests/ -v
 # または uv で直接実行
 uv run --with pytest --with pytest-asyncio \
    --with ebooklib --with markdown --with beautifulsoup4 \
-    --with httpx --with pillow --with tenacity \
+    --with pillow \
    pytest scripts/tests/ -v
 ```

@@ -110,14 +115,12 @@ PEP 723 のインラインスクリプトメタデータで管理する：
 | `ebooklib` | EPUB 生成 |
 | `markdown` | Markdown から HTML への変換 |
 | `beautifulsoup4` | HTML パース |
-| `httpx` | 非同期 HTTP クライアント |
 | `pillow` | 表紙画像生成 |
-| `tenacity` | リトライ処理 |

 ## トラブルシューティング

-**ネットワークエラーでビルドが失敗する**: インターネット接続と Kroki.io の稼働状況を確認する。`--timeout 60` を試す。
+**`mmdc not found` でビルドが失敗する**: Mermaid CLI をインストールする（`npm install -g @mermaid-js/mermaid-cli`）。`PATH` にない場合は `--mmdc-path` を渡す。arm64 では同梱 Chromium が動作しないため、EPUB は CI（`.github/workflows/test.yml` の `build-epub` ジョブ）でビルドすること。

-**レート制限**: `--max-concurrent 3` で並行リクエスト数を減らす。
+**CI やコンテナで `mmdc` が失敗する**: Chromium にサンドボックスなしのプロファイルが必要。`{"args":["--no-sandbox","--disable-setuid-sandbox"]}` をファイルに書き出し、`--puppeteer-config` で渡す。

 **ロゴが見つからない**: `claude-howto-logo.png` が見つからない場合、スクリプトはテキストのみの表紙を生成する。
@@ -23,8 +23,8 @@ Build an EPUB ebook from the Claude How-To markdown files.
 ## Features

 - Organizes chapters by folder structure (01-slash-commands, 02-memory, etc.)
- Renders Mermaid diagrams as PNG images via Kroki.io API
- Async concurrent fetching - renders all diagrams in parallel
+- Renders Mermaid diagrams as PNG images via the local `mmdc` CLI (no network required)
+- Caches identical diagrams so each unique diagram is rendered only once
 - Generates a cover image from the project logo
 - Converts internal markdown links to EPUB chapter references
 - Strict error mode - fails if any diagram cannot be rendered
@@ -33,7 +33,7 @@ Build an EPUB ebook from the Claude How-To markdown files.

 - Python 3.10+
 - [uv](https://github.com/astral-sh/uv)
- Internet connection for Mermaid diagram rendering
+- [`mmdc`](https://github.com/mermaid-js/mermaid-cli) on `PATH` for Mermaid diagram rendering (`npm install -g @mermaid-js/mermaid-cli`)

 ## Quick Start

@@ -63,15 +63,17 @@ python scripts/build_epub.py

 ```
 usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose]
-                     [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT]
+                     [--mmdc-path MMDC_PATH] [--lang {en,vi,zh,ja}]
+                     [--puppeteer-config PUPPETEER_CONFIG]

 options:
  -h, --help            show this help message and exit
  --root, -r ROOT       Root directory (default: repo root)
  --output, -o OUTPUT   Output path (default: claude-howto-guide.epub)
  --verbose, -v         Enable verbose logging
-  --timeout TIMEOUT     API timeout in seconds (default: 30)
-  --max-concurrent N    Max concurrent requests (default: 10)
+  --mmdc-path PATH      Path to mmdc binary (default: mmdc from PATH)
+  --lang {en,vi,zh,ja}  Language to build (default: en)
+  --puppeteer-config P  Puppeteer config JSON passed to mmdc via -p
 ```

 ## Examples
@@ -83,8 +85,11 @@ uv run scripts/build_epub.py --verbose
 # Custom output location
 uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub

-# Limit concurrent requests (if rate-limited)
-uv run scripts/build_epub.py --max-concurrent 5
+# Build a translated edition
+uv run scripts/build_epub.py --lang vi
+
+# Point at an mmdc that is not on PATH
+uv run scripts/build_epub.py --mmdc-path ./node_modules/.bin/mmdc
 ```

 ## Output
@@ -107,7 +112,7 @@ pytest scripts/tests/ -v
 # Or with uv directly
 uv run --with pytest --with pytest-asyncio \
    --with ebooklib --with markdown --with beautifulsoup4 \
-    --with httpx --with pillow --with tenacity \
+    --with pillow \
    pytest scripts/tests/ -v
 ```

@@ -120,15 +125,13 @@ Managed via PEP 723 inline script metadata:
 | `ebooklib` | EPUB generation |
 | `markdown` | Markdown to HTML conversion |
 | `beautifulsoup4` | HTML parsing |
-| `httpx` | Async HTTP client |
 | `pillow` | Cover image generation |
-| `tenacity` | Retry logic |

 ## Troubleshooting

-**Build fails with network error**: Check internet connectivity and Kroki.io status. Try `--timeout 60`.
+**Build fails with `mmdc not found`**: Install the Mermaid CLI (`npm install -g @mermaid-js/mermaid-cli`), or pass `--mmdc-path` if the binary is not on `PATH`. There is no working arm64 build of the bundled Chromium, so on arm64 machines build the EPUB in CI instead — the `build-epub` job in `.github/workflows/test.yml` covers every language.

-**Rate limiting**: Reduce concurrent requests with `--max-concurrent 3`.
+**`mmdc` fails in CI or a container**: Chromium needs a sandbox-free profile. Write `{"args":["--no-sandbox","--disable-setuid-sandbox"]}` to a file and pass it via `--puppeteer-config`.

 **Missing logo**: The script generates a text-only cover if `claude-howto-logo.png` is not found.

@@ -9,9 +9,7 @@ dependencies = [
    "ebooklib",
    "markdown",
    "beautifulsoup4",
-    "httpx",
    "pillow",
-    "tenacity",
    "jinja2",
 ]

@@ -44,7 +42,9 @@ exclude = ["tests", "tests.*"]
 [tool.ruff]
 target-version = "py310"
 line-length = 88
-include = ["scripts/**/*.py"]
+# Ruff resolves these patterns relative to this file's directory (scripts/),
+# not the repo root — "scripts/**/*.py" would mean scripts/scripts/**/*.py.
+include = ["**/*.py"]
 exclude = [
    ".git",
    ".venv",
@@ -72,6 +72,7 @@ select = [
 ignore = [
    "E501",     # Line too long (handled by formatter)
    "PLR0913",  # Too many arguments
+    "PLR0917",  # Too many positional arguments (stable since ruff 0.16)
    "PLR2004",  # Magic value comparison
    "PLR0915",  # Too many statements
    "PERF203",  # try-except in loop (acceptable for error handling)
@@ -89,7 +90,8 @@ force-single-line = false
 combine-as-imports = true

 [tool.ruff.lint.per-file-ignores]
-"scripts/tests/*.py" = ["S101", "PLR2004"]
+# Also relative to scripts/ — see the note on [tool.ruff] include above.
+"tests/*.py" = ["S101", "PLR2004"]

 [tool.ruff.format]
 quote-style = "double"
@@ -120,4 +122,4 @@ ignore_errors = true
 [tool.bandit]
 targets = ["scripts"]
 exclude_dirs = ["scripts/tests", ".venv", "__pycache__"]
-skips = ["B101", "B113"]  # B113: httpx timeout false positive (timeout is set)
+skips = ["B101"]
@@ -8,6 +8,6 @@ pytest-cov>=4.0.0

 # Code Quality
 pre-commit>=3.6.0
-ruff>=0.8.0
+ruff>=0.15.10
 bandit[toml]>=1.7.7
 mypy>=1.8.0
@@ -2,7 +2,5 @@
 ebooklib==0.18
 markdown==3.7
 beautifulsoup4==4.12.3
-httpx==0.28.1
 pillow==11.1.0
-tenacity==9.0.0
 jinja2==3.1.4
@@ -472,9 +472,9 @@ class TestBuildWebsite:
            "cdn.jsdelivr.net",
            "fonts.googleapis.com",
        ):
-            assert (
-                hostile not in index_html
-            ), f"Built HTML still references {hostile} — CDN should be self-hosted"
+            assert hostile not in index_html, (
+                f"Built HTML still references {hostile} — CDN should be self-hosted"
+            )


 # =============================================================================
@@ -46,11 +46,7 @@ def test_backtick_inside_fence_ignored(repo: Path) -> None:

 def test_backtick_inside_blockquote_fence_ignored(repo: Path) -> None:
    content = (
-        "> note\n"
-        ">\n"
-        "> ```json\n"
-        '> { "key": "value with `inner` backtick" }\n'
-        "> ```\n"
+        '> note\n>\n> ```json\n> { "key": "value with `inner` backtick" }\n> ```\n'
    )
    (repo / "README.md").write_text(content)
    errors = cmr.rule_backtick_in_inline_code(Path("README.md"), content)
@@ -67,19 +63,19 @@ def test_backtick_line_number_reported(repo: Path) -> None:


 def test_unescaped_pipe_in_table_flagged(repo: Path) -> None:
-    content = "| col1 | col2 |\n" "|------|------|\n" "| a | b | c |\n"
+    content = "| col1 | col2 |\n|------|------|\n| a | b | c |\n"
    errors = cmr.rule_unescaped_pipe_in_table(Path("README.md"), content)
    assert any("unescaped-pipe-in-table" in e for e in errors)


 def test_escaped_pipe_passes(repo: Path) -> None:
-    content = "| col1 | col2 |\n" "|------|------|\n" "| [color\\|default] | b |\n"
+    content = "| col1 | col2 |\n|------|------|\n| [color\\|default] | b |\n"
    errors = cmr.rule_unescaped_pipe_in_table(Path("README.md"), content)
    assert errors == []


 def test_pipe_inside_inline_code_in_cell_passes(repo: Path) -> None:
-    content = "| col1 | col2 |\n" "|------|------|\n" "| `a \\| b` | text |\n"
+    content = "| col1 | col2 |\n|------|------|\n| `a \\| b` | text |\n"
    errors = cmr.rule_unescaped_pipe_in_table(Path("README.md"), content)
    assert errors == []

@@ -19,13 +19,13 @@

 | Функція | Вбудовані | Приклади | Разом | Довідник |
 |---------|-----------|----------|-------|----------|
-| **Слеш-команди** | 60+ | 8 | 68+ | [01-slash-commands/](../01-slash-commands/) |
-| **Субагенти** | 6 | 9 | 15 | [04-subagents/](../04-subagents/) |
-| **Навички (Skills)** | 10 вбудованих | 6 | 16 | [03-skills/](../03-skills/) |
-| **Плагіни** | - | 3 | 3 | [07-plugins/](../07-plugins/) |
-| **MCP-сервери** | 1 | 4 | 5 | [05-mcp/](../05-mcp/) |
-| **Хуки** | 31 подія | 10 | 41 | [06-hooks/](../06-hooks/) |
-| **Пам'ять** | 7 типів | 3 | 10 | [02-memory/](../02-memory/) |
+| **Слеш-команди** | 60+ | 8 | 68+ | [01-slash-commands/](01-slash-commands/) |
+| **Субагенти** | 6 | 9 | 15 | [04-subagents/](04-subagents/) |
+| **Навички (Skills)** | 10 вбудованих | 6 | 16 | [03-skills/](03-skills/) |
+| **Плагіни** | - | 3 | 3 | [07-plugins/](07-plugins/) |
+| **MCP-сервери** | 1 | 4 | 5 | [05-mcp/](05-mcp/) |
+| **Хуки** | 31 подія | 10 | 41 | [06-hooks/](06-hooks/) |
+| **Пам'ять** | 7 типів | 3 | 10 | [02-memory/](02-memory/) |
 | **Разом** | **115** | **43** | **158** | |

 ---
@@ -105,7 +105,7 @@

 > **Область**: `Користувач` = персональні процеси (`~/.claude/commands/`), `Проект` = спільні для команди (`.claude/commands/`)

-**Довідник**: [01-slash-commands/](../01-slash-commands/) | [Офіційна документація](https://code.claude.com/docs/en/interactive-mode)
+**Довідник**: [01-slash-commands/](01-slash-commands/) | [Офіційна документація](https://code.claude.com/docs/en/interactive-mode)

 **Швидке встановлення (усі кастомні команди)**:

@@ -128,7 +128,7 @@ Claude Code підтримує 6 режимів дозволів, що конт
 | `bypassPermissions` | Пропустити всі перевірки дозволів | CI/CD, headless-середовища |
 | `dontAsk` | Пропустити інструменти, що потребують дозволу | Неінтерактивне скриптування |

-> **Примітка**: Режим `auto` вимагає відповідного плану, моделі та провайдера — див. [09-advanced-features/](../09-advanced-features/#auto-mode). Використовуйте `bypassPermissions` лише в довірених ізольованих середовищах.
+> **Примітка**: Режим `auto` вимагає відповідного плану, моделі та провайдера — див. [09-advanced-features/](09-advanced-features/#auto-mode). Використовуйте `bypassPermissions` лише в довірених ізольованих середовищах.

 **Довідник**: [Офіційна документація](https://code.claude.com/docs/en/permissions)

@@ -179,7 +179,7 @@ Claude Code підтримує 6 режимів дозволів, що конт

 > **Область**: `Користувач` = персональні (`~/.claude/agents/`), `Проект` = спільні для команди (`.claude/agents/`)

-**Довідник**: [04-subagents/](../04-subagents/) | [Офіційна документація](https://code.claude.com/docs/en/sub-agents)
+**Довідник**: [04-subagents/](04-subagents/) | [Офіційна документація](https://code.claude.com/docs/en/sub-agents)

 **Швидке встановлення (усі кастомні агенти)**:

@@ -225,7 +225,7 @@ cp 04-subagents/*.md .claude/agents/
 | `effort` | string | Рівень зусиль міркування (`low`, `medium`, `high`) |
 | `shell` | string | Оболонка для скриптів (`bash`, `zsh`, `sh`) |

-**Довідник**: [03-skills/](../03-skills/) | [Офіційна документація](https://code.claude.com/docs/en/skills)
+**Довідник**: [03-skills/](03-skills/) | [Офіційна документація](https://code.claude.com/docs/en/skills)

 **Швидке встановлення (усі навички)**:

@@ -272,7 +272,7 @@ cp -r 03-skills/* ~/.claude/skills/
 └── scripts/          # Допоміжні скрипти
 ```

-**Довідник**: [07-plugins/](../07-plugins/) | [Офіційна документація](https://code.claude.com/docs/en/plugins)
+**Довідник**: [07-plugins/](07-plugins/) | [Офіційна документація](https://code.claude.com/docs/en/plugins)

 **Команди управління плагінами**:

@@ -321,7 +321,7 @@ cp -r 03-skills/* ~/.claude/skills/
 }
 ```

-**Довідник**: [05-mcp/](../05-mcp/) | [Документація MCP](https://modelcontextprotocol.io)
+**Довідник**: [05-mcp/](05-mcp/) | [Документація MCP](https://modelcontextprotocol.io)

 **Швидке встановлення (GitHub MCP)**:

@@ -401,7 +401,7 @@ export GITHUB_TOKEN="your_token" && claude mcp add github -- npx -y @modelcontex
 }
 ```

-**Довідник**: [06-hooks/](../06-hooks/) | [Офіційна документація](https://code.claude.com/docs/en/hooks)
+**Довідник**: [06-hooks/](06-hooks/) | [Офіційна документація](https://code.claude.com/docs/en/hooks)

 **Швидке встановлення (усі хуки)**:

@@ -429,7 +429,7 @@ mkdir -p ~/.claude/hooks && cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.cla

 > **Область**: `Організація` = керується адмінами, `Проект` = спільний через git, `Користувач` = персональні, `Локальний` = не комітиться, `Сесія` = автокерований

-**Довідник**: [02-memory/](../02-memory/) | [Офіційна документація](https://code.claude.com/docs/en/memory)
+**Довідник**: [02-memory/](02-memory/) | [Офіційна документація](https://code.claude.com/docs/en/memory)

 **Швидке встановлення**:

@@ -16,7 +16,7 @@ Claude How To — це навчальний репозиторій з функц

 ### Перевірки якості pre-commit

-Уся документація повинна пройти чотири перевірки якості перед комітами (запускаються автоматично через pre-commit хуки):
+Уся документація повинна пройти п'ять перевірок якості перед комітами (запускаються автоматично через pre-commit хуки):

 ```bash
 # Install pre-commit hooks (runs on every commit)
@@ -31,7 +31,9 @@ pre-commit run --all-files
 2. **cross-references** — Внутрішні посилання, якорі, синтаксис блоків коду (Python-скрипт)
 3. **mermaid-syntax** — Валідація коректного парсингу всіх Mermaid-діаграм (Python-скрипт)
 4. **link-check** — Доступність зовнішніх URL (Python-скрипт)
-5. **build-epub** — EPUB генерується без помилок (при змінах `.md`)
+5. **markdown-rendering** — Markdown рендериться без помилок (Python-скрипт)
+
+Збірка EPUB **не є** pre-commit хуком — вона виконується лише в CI (джоб `build-epub` у `.github/workflows/test.yml`), бо потребує локального бінарника `mmdc`, для якого немає робочої збірки під arm64.

 ### Налаштування середовища розробки

@@ -85,11 +87,11 @@ mypy scripts/ --ignore-missing-imports
 ### Збірка EPUB

 ```bash
-# Generate ebook (renders Mermaid diagrams via Kroki.io API)
+# Generate ebook (renders Mermaid diagrams with the local mmdc CLI — no network)
 uv run scripts/build_epub.py

 # With options
-uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
+uv run scripts/build_epub.py --verbose --output custom-name.epub --mmdc-path ./node_modules/.bin/mmdc
 ```

 ## Структура каталогів
@@ -106,7 +108,7 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren
 ├── 09-advanced-features/   # Планування, мислення, фони
 ├── 10-cli/                 # Довідник CLI
 ├── scripts/
-│   ├── build_epub.py           # Генератор EPUB (рендерить Mermaid через Kroki API)
+│   ├── build_epub.py           # Генератор EPUB (рендерить Mermaid через локальний mmdc)
 │   ├── check_cross_references.py   # Валідація внутрішніх посилань
 │   ├── check_links.py          # Перевірка зовнішніх URL
 │   ├── check_mermaid.py        # Валідація синтаксису Mermaid
@@ -125,7 +127,7 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren

 ### Mermaid-діаграми
 - Усі діаграми повинні успішно парситися (перевіряється pre-commit хуком)
- Збірка EPUB рендерить діаграми через Kroki.io API (потрібен інтернет)
+- Збірка EPUB рендерить діаграми через локальний `mmdc` CLI (інтернет не потрібен, але потрібен `mmdc`)
 - Використовуйте Mermaid для блок-схем, діаграм послідовностей та архітектурних візуалізацій

 ### Перехресні посилання
@@ -146,7 +148,7 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren

 3. **Pre-commit — привратник** — Усі перевірки якості повинні пройти перед прийняттям PR. CI-конвеєр запускає ці ж перевірки як другий прохід.

-4. **Рендеринг Mermaid потребує мережі** — Збірка EPUB викликає Kroki.io API для рендерингу діаграм. Помилки збірки тут зазвичай пов'язані з мережею або невалідним синтаксисом Mermaid.
+4. **Рендеринг Mermaid потребує локального `mmdc`** — Збірка EPUB викликає локальний `mmdc` CLI для рендерингу діаграм (мережа не потрібна). Помилки збірки тут зазвичай пов'язані з відсутнім `mmdc` або невалідним синтаксисом Mermaid. Сама збірка EPUB не виконується у pre-commit — лише в CI.

 5. **Це туторіал, а не бібліотека** — При додаванні контенту зосереджуйтесь на чітких поясненнях, готових прикладах та візуальних діаграмах. Цінність — у навчанні концепцій, а не у наданні повторно використовуваного коду.

@@ -231,7 +231,9 @@ blog-draft/

 **Використання**: Налаштовуються в settings, виконуються автоматично

-**Типи хуків** (5 типів, 31 подія):
+**Типи хуків** (5): `command`, `http`, `prompt`, `mcp_tool`, `agent` — як саме виконується хук.
+
+**Події хуків** (31, у 4 категоріях) — коли він виконується:

 - Хуки інструментів: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied
 - Хуки сесії: SessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop
@@ -102,17 +102,17 @@ graph TD

 | Крок | Функція | Складність | Час | Рівень | Залежності | Чому вивчати | Ключові переваги |
 |------|---------|-----------|-----|--------|------------|-------------|-----------------|
-| **1** | [Слеш-команди](../01-slash-commands/) | ⭐ Початківець | 30 хв | Рівень 1 | Немає | Швидкий приріст продуктивності (55+ вбудованих + 5 навичок) | Миттєва автоматизація |
-| **2** | [Пам'ять](../02-memory/) | ⭐⭐ Початківець+ | 45 хв | Рівень 1 | Немає | Необхідна для всіх функцій | Постійний контекст |
-| **3** | [Контрольні точки](../08-checkpoints/) | ⭐⭐ Середній | 45 хв | Рівень 1 | Управління сесіями | Безпечне дослідження | Експериментування, відновлення |
-| **4** | [Основи CLI](../10-cli/) | ⭐⭐ Початківець+ | 30 хв | Рівень 1 | Немає | Базове використання CLI | Інтерактивний та print mode |
-| **5** | [Навички](../03-skills/) | ⭐⭐ Середній | 1 год | Рівень 2 | Слеш-команди | Автоматична експертиза | Повторювані можливості |
-| **6** | [Хуки](../06-hooks/) | ⭐⭐ Середній | 1 год | Рівень 2 | Інструменти, Команди | Автоматизація процесів (31 подія, 5 типів) | Валідація, контроль якості |
-| **7** | [MCP](../05-mcp/) | ⭐⭐⭐ Середній+ | 1 год | Рівень 2 | Конфігурація | Доступ до даних у реальному часі | Інтеграція, API |
-| **8** | [Субагенти](../04-subagents/) | ⭐⭐⭐ Середній+ | 1.5 год | Рівень 2 | Пам'ять, Команди | Складні завдання (6 вбудованих) | Делегування, спеціалізація |
-| **9** | [Розширені функції](../09-advanced-features/) | ⭐⭐⭐⭐⭐ Просунутий | 2-3 год | Рівень 3 | Усі попередні | Інструменти експерта | Планування, Auto Mode, канали |
-| **10** | [Плагіни](../07-plugins/) | ⭐⭐⭐⭐ Просунутий | 2 год | Рівень 3 | Усі попередні | Комплексні рішення | Онбординг команди, дистрибуція |
-| **11** | [Майстерність CLI](../10-cli/) | ⭐⭐⭐ Просунутий | 1 год | Рівень 3 | Рекомендовано: Усі | Майстерність командного рядка | Скрипти, CI/CD |
+| **1** | [Слеш-команди](01-slash-commands/) | ⭐ Початківець | 30 хв | Рівень 1 | Немає | Швидкий приріст продуктивності (55+ вбудованих + 5 навичок) | Миттєва автоматизація |
+| **2** | [Пам'ять](02-memory/) | ⭐⭐ Початківець+ | 45 хв | Рівень 1 | Немає | Необхідна для всіх функцій | Постійний контекст |
+| **3** | [Контрольні точки](08-checkpoints/) | ⭐⭐ Середній | 45 хв | Рівень 1 | Управління сесіями | Безпечне дослідження | Експериментування, відновлення |
+| **4** | [Основи CLI](10-cli/) | ⭐⭐ Початківець+ | 30 хв | Рівень 1 | Немає | Базове використання CLI | Інтерактивний та print mode |
+| **5** | [Навички](03-skills/) | ⭐⭐ Середній | 1 год | Рівень 2 | Слеш-команди | Автоматична експертиза | Повторювані можливості |
+| **6** | [Хуки](06-hooks/) | ⭐⭐ Середній | 1 год | Рівень 2 | Інструменти, Команди | Автоматизація процесів (31 подія, 5 типів) | Валідація, контроль якості |
+| **7** | [MCP](05-mcp/) | ⭐⭐⭐ Середній+ | 1 год | Рівень 2 | Конфігурація | Доступ до даних у реальному часі | Інтеграція, API |
+| **8** | [Субагенти](04-subagents/) | ⭐⭐⭐ Середній+ | 1.5 год | Рівень 2 | Пам'ять, Команди | Складні завдання (6 вбудованих) | Делегування, спеціалізація |
+| **9** | [Розширені функції](09-advanced-features/) | ⭐⭐⭐⭐⭐ Просунутий | 2-3 год | Рівень 3 | Усі попередні | Інструменти експерта | Планування, Auto Mode, канали |
+| **10** | [Плагіни](07-plugins/) | ⭐⭐⭐⭐ Просунутий | 2 год | Рівень 3 | Усі попередні | Комплексні рішення | Онбординг команди, дистрибуція |
+| **11** | [Майстерність CLI](10-cli/) | ⭐⭐⭐ Просунутий | 1 год | Рівень 3 | Рекомендовано: Усі | Майстерність командного рядка | Скрипти, CI/CD |

 **Загальний час навчання**: ~11-13 годин (або перейдіть на свій рівень і заощадьте час)

@@ -163,8 +163,8 @@ cp 02-memory/project-CLAUDE.md ./CLAUDE.md

 Коли освоїтесь, прочитайте:

- [01-slash-commands/README.md](../01-slash-commands/README.md)
- [02-memory/README.md](../02-memory/README.md)
+- [01-slash-commands/README.md](01-slash-commands/README.md)
+- [02-memory/README.md](02-memory/README.md)

 > **Перевірте розуміння**: Запустіть `/lesson-quiz slash-commands` або `/lesson-quiz memory` у Claude Code.

@@ -210,8 +210,8 @@ cat error.log | claude -p "explain this error"

 #### Наступні кроки

- Прочитайте: [08-checkpoints/README.md](../08-checkpoints/README.md)
- Прочитайте: [10-cli/README.md](../10-cli/README.md)
+- Прочитайте: [08-checkpoints/README.md](08-checkpoints/README.md)
+- Прочитайте: [10-cli/README.md](10-cli/README.md)
 - **Готові до Рівня 2!** Переходьте до [Етапу 2A](#етап-2a-автоматизація-навички--хуки)

 > **Перевірте розуміння**: Запустіть `/lesson-quiz checkpoints` або `/lesson-quiz cli`.
@@ -229,10 +229,10 @@ cat error.log | claude -p "explain this error"

 Перед початком Рівня 2 переконайтеся, що ви освоїли концепції Рівня 1:

- [ ] Вмієте створювати та використовувати слеш-команди ([01-slash-commands/](../01-slash-commands/))
- [ ] Налаштували пам'ять проекту через CLAUDE.md ([02-memory/](../02-memory/))
- [ ] Знаєте, як створювати та відновлювати контрольні точки ([08-checkpoints/](../08-checkpoints/))
- [ ] Вмієте використовувати `claude` та `claude -p` з командного рядка ([10-cli/](../10-cli/))
+- [ ] Вмієте створювати та використовувати слеш-команди ([01-slash-commands/](01-slash-commands/))
+- [ ] Налаштували пам'ять проекту через CLAUDE.md ([02-memory/](02-memory/))
+- [ ] Знаєте, як створювати та відновлювати контрольні точки ([08-checkpoints/](08-checkpoints/))
+- [ ] Вмієте використовувати `claude` та `claude -p` з командного рядка ([10-cli/](10-cli/))

 > **Прогалини?** Перегляньте відповідні посібники перед продовженням.

@@ -293,8 +293,8 @@ chmod +x ~/.claude/hooks/pre-tool-check.sh

 - Створіть власну кастомну навичку
 - Налаштуйте додаткові хуки для вашого процесу
- Прочитайте: [03-skills/README.md](../03-skills/README.md)
- Прочитайте: [06-hooks/README.md](../06-hooks/README.md)
+- Прочитайте: [03-skills/README.md](03-skills/README.md)
+- Прочитайте: [06-hooks/README.md](06-hooks/README.md)

 > **Перевірте розуміння**: Запустіть `/lesson-quiz skills` або `/lesson-quiz hooks`.

@@ -348,8 +348,8 @@ cp 04-subagents/*.md .claude/agents/

 - Налаштуйте додаткові MCP-сервери (база даних, Slack тощо)
 - Створіть кастомних субагентів для вашої предметної області
- Прочитайте: [05-mcp/README.md](../05-mcp/README.md)
- Прочитайте: [04-subagents/README.md](../04-subagents/README.md)
+- Прочитайте: [05-mcp/README.md](05-mcp/README.md)
+- Прочитайте: [04-subagents/README.md](04-subagents/README.md)
 - **Готові до Рівня 3!** Переходьте до [Етапу 3A](#етап-3a-розширені-функції)

 > **Перевірте розуміння**: Запустіть `/lesson-quiz mcp` або `/lesson-quiz subagents`.
@@ -367,10 +367,10 @@ cp 04-subagents/*.md .claude/agents/

 Перед початком Рівня 3 переконайтеся, що ви освоїли концепції Рівня 2:

- [ ] Вмієте створювати та використовувати навички з автовикликом ([03-skills/](../03-skills/))
- [ ] Налаштували хуки для автоматизації на основі подій ([06-hooks/](../06-hooks/))
- [ ] Вмієте конфігурувати MCP-сервери для зовнішніх даних ([05-mcp/](../05-mcp/))
- [ ] Знаєте, як використовувати субагентів для делегування ([04-subagents/](../04-subagents/))
+- [ ] Вмієте створювати та використовувати навички з автовикликом ([03-skills/](03-skills/))
+- [ ] Налаштували хуки для автоматизації на основі подій ([06-hooks/](06-hooks/))
+- [ ] Вмієте конфігурувати MCP-сервери для зовнішніх даних ([05-mcp/](05-mcp/))
+- [ ] Знаєте, як використовувати субагентів для делегування ([04-subagents/](04-subagents/))

 > **Прогалини?** Перегляньте відповідні посібники перед продовженням.

@@ -451,7 +451,7 @@ export CLAUDE_AGENT_TEAMS=1

 #### Наступні кроки

- Прочитайте: [09-advanced-features/README.md](../09-advanced-features/README.md)
+- Прочитайте: [09-advanced-features/README.md](09-advanced-features/README.md)

 > **Перевірте розуміння**: Запустіть `/lesson-quiz advanced`.

@@ -526,8 +526,8 @@ done

 #### Наступні кроки

- Прочитайте: [07-plugins/README.md](../07-plugins/README.md)
- Прочитайте: [10-cli/README.md](../10-cli/README.md)
+- Прочитайте: [07-plugins/README.md](07-plugins/README.md)
+- Прочитайте: [10-cli/README.md](10-cli/README.md)
 - Створіть командні CLI-ярлики та плагіни
 - Налаштуйте скрипти пакетної обробки

@@ -563,7 +563,7 @@ done

 1. Скопіюйте одну слеш-команду: `cp 01-slash-commands/optimize.md .claude/commands/`
 2. Спробуйте в Claude Code: `/optimize`
-3. Прочитайте: [01-slash-commands/README.md](../01-slash-commands/README.md)
+3. Прочитайте: [01-slash-commands/README.md](01-slash-commands/README.md)

 **Результат**: Робоча слеш-команда та розуміння основ

@@ -669,26 +669,26 @@ done

 ### 🟢 Рівень 1: Початківець

- [ ] Завершено [01-slash-commands](../01-slash-commands/)
- [ ] Завершено [02-memory](../02-memory/)
+- [ ] Завершено [01-slash-commands](01-slash-commands/)
+- [ ] Завершено [02-memory](02-memory/)
 - [ ] Створено першу кастомну слеш-команду
 - [ ] Налаштовано пам'ять проекту
 - [ ] **Етап 1A досягнуто**
- [ ] Завершено [08-checkpoints](../08-checkpoints/)
- [ ] Завершено основи [10-cli](../10-cli/)
+- [ ] Завершено [08-checkpoints](08-checkpoints/)
+- [ ] Завершено основи [10-cli](10-cli/)
 - [ ] Створено та відновлено контрольну точку
 - [ ] Використано інтерактивний та print mode
 - [ ] **Етап 1B досягнуто**

 ### 🔵 Рівень 2: Середній

- [ ] Завершено [03-skills](../03-skills/)
- [ ] Завершено [06-hooks](../06-hooks/)
+- [ ] Завершено [03-skills](03-skills/)
+- [ ] Завершено [06-hooks](06-hooks/)
 - [ ] Встановлено першу навичку
 - [ ] Налаштовано хук PreToolUse
 - [ ] **Етап 2A досягнуто**
- [ ] Завершено [05-mcp](../05-mcp/)
- [ ] Завершено [04-subagents](../04-subagents/)
+- [ ] Завершено [05-mcp](05-mcp/)
+- [ ] Завершено [04-subagents](04-subagents/)
 - [ ] Підключено GitHub MCP
 - [ ] Створено кастомного субагента
 - [ ] Комбіновано інтеграції у процесі
@@ -696,15 +696,15 @@ done

 ### 🔴 Рівень 3: Просунутий

- [ ] Завершено [09-advanced-features](../09-advanced-features/)
+- [ ] Завершено [09-advanced-features](09-advanced-features/)
 - [ ] Використано режим планування
 - [ ] Налаштовано режими дозволів (6 режимів включно з auto)
 - [ ] Використано auto mode з класифікатором безпеки
 - [ ] Увімкнено розширене мислення
 - [ ] Досліджено канали та голосовий ввід
 - [ ] **Етап 3A досягнуто**
- [ ] Завершено [07-plugins](../07-plugins/)
- [ ] Завершено розширене використання [10-cli](../10-cli/)
+- [ ] Завершено [07-plugins](07-plugins/)
+- [ ] Завершено розширене використання [10-cli](10-cli/)
 - [ ] Налаштовано print mode (`claude -p`) CI/CD
 - [ ] Створено JSON-вивід для автоматизації
 - [ ] Інтегровано Claude в CI/CD-пайплайн
@@ -438,7 +438,9 @@ chmod +x ~/.claude/hooks/*.sh

 **Використання**: Хуки виконуються автоматично за подіями

-**Типи хуків** (5 типів, 31 подія):
+**Типи хуків** (5): `command`, `http`, `prompt`, `mcp_tool`, `agent` — як саме виконується хук.
+
+**Події хуків** (31, у 4 категоріях) — коли він виконується:
 - **Хуки інструментів**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `PermissionRequest`, `PermissionDenied`
 - **Хуки сесій**: `SessionStart`, `Setup`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`
 - **Хуки завдань**: `UserPromptSubmit`, `UserPromptExpansion`, `MessageDisplay`, `TaskCompleted`, `TaskCreated`, `TeammateIdle`
@@ -10,8 +10,8 @@
 ## Функції

 - Організує розділи за структурою каталогів (01-slash-commands, 02-memory тощо)
- Рендерить Mermaid-діаграми як PNG-зображення через Kroki.io API
- Асинхронне паралельне завантаження — рендерить усі діаграми одночасно
+- Рендерить Mermaid-діаграми як PNG-зображення через локальний `mmdc` CLI (без мережі)
+- Кешує однакові діаграми — кожна унікальна діаграма рендериться лише раз
 - Генерує обкладинку з логотипу проєкту
 - Конвертує внутрішні markdown-посилання у посилання на розділи EPUB
 - Суворий режим помилок — падає, якщо діаграма не може бути відрендерена
@@ -20,7 +20,7 @@

 - Python 3.10+
 - [uv](https://github.com/astral-sh/uv)
- Інтернет-з'єднання для рендерингу Mermaid-діаграм
+- [`mmdc`](https://github.com/mermaid-js/mermaid-cli) у `PATH` для рендерингу Mermaid-діаграм (`npm install -g @mermaid-js/mermaid-cli`)

 ## Швидкий старт

@@ -50,15 +50,17 @@ python scripts/build_epub.py

 ```
 usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose]
-                     [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT]
+                     [--mmdc-path MMDC_PATH] [--lang {en,vi,zh,ja}]
+                     [--puppeteer-config PUPPETEER_CONFIG]

 options:
  -h, --help            show this help message and exit
  --root, -r ROOT       Root directory (default: repo root)
  --output, -o OUTPUT   Output path (default: claude-howto-guide.epub)
  --verbose, -v         Enable verbose logging
-  --timeout TIMEOUT     API timeout in seconds (default: 30)
-  --max-concurrent N    Max concurrent requests (default: 10)
+  --mmdc-path PATH      Path to mmdc binary (default: mmdc from PATH)
+  --lang {en,vi,zh,ja}  Language to build (default: en)
+  --puppeteer-config P  Puppeteer config JSON passed to mmdc via -p
 ```

 ## Приклади
@@ -70,8 +72,11 @@ uv run scripts/build_epub.py --verbose
 # Custom output location
 uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub

-# Limit concurrent requests (if rate-limited)
-uv run scripts/build_epub.py --max-concurrent 5
+# Build a translated edition
+uv run scripts/build_epub.py --lang vi
+
+# Point at an mmdc that is not on PATH
+uv run scripts/build_epub.py --mmdc-path ./node_modules/.bin/mmdc
 ```

 ## Вивід
@@ -94,7 +99,7 @@ pytest scripts/tests/ -v
 # Or with uv directly
 uv run --with pytest --with pytest-asyncio \
    --with ebooklib --with markdown --with beautifulsoup4 \
-    --with httpx --with pillow --with tenacity \
+    --with pillow \
    pytest scripts/tests/ -v
 ```

@@ -107,14 +112,12 @@ uv run --with pytest --with pytest-asyncio \
 | `ebooklib` | Генерація EPUB |
 | `markdown` | Конвертація Markdown → HTML |
 | `beautifulsoup4` | Парсинг HTML |
-| `httpx` | Асинхронний HTTP-клієнт |
 | `pillow` | Генерація обкладинки |
-| `tenacity` | Логіка повторних спроб |

 ## Усунення проблем

-**Збірка падає з мережевою помилкою**: Перевірте інтернет-з'єднання та стан Kroki.io. Спробуйте `--timeout 60`.
+**Збірка падає з `mmdc not found`**: Встановіть Mermaid CLI (`npm install -g @mermaid-js/mermaid-cli`) або вкажіть шлях через `--mmdc-path`. На arm64 вбудований Chromium не працює — збирайте EPUB у CI (джоб `build-epub` у `.github/workflows/test.yml`).

-**Обмеження частоти**: Зменште паралельні запити з `--max-concurrent 3`.
+**`mmdc` падає в CI або контейнері**: Chromium потребує профілю без пісочниці. Запишіть `{"args":["--no-sandbox","--disable-setuid-sandbox"]}` у файл і передайте його через `--puppeteer-config`.

 **Відсутній логотип**: Скрипт генерує текстову обкладинку, якщо `claude-howto-logo.png` не знайдено.
@@ -15,13 +15,13 @@

 | Tính Năng | Built-in | Ví Dụ | Tổng | Tham Chiếu |
 |---------|----------|----------|-------|-----------|
-| **Lệnh Slash** | 60+ | 8 | 68+ | [01-slash-commands/](../01-slash-commands/) |
-| **Tác Nhân Con** | 6 | 6 | 12 | [04-subagents/](../04-subagents/) |
-| **Skills** | 10 bundled | 5 | 15 | [03-skills/](../03-skills/) |
-| **Plugins** | - | 3 | 3 | [07-plugins/](../07-plugins/) |
-| **MCP Servers** | 1 | 4 | 5 | [05-mcp/](../05-mcp/) |
-| **Hooks** | 31 sự kiện | 9 | 40 | [06-hooks/](../06-hooks/) |
-| **Bộ Nhớ** | 7 loại | 3 | 10 | [02-memory/](../02-memory/) |
+| **Lệnh Slash** | 60+ | 8 | 68+ | [01-slash-commands/](01-slash-commands/) |
+| **Tác Nhân Con** | 6 | 6 | 12 | [04-subagents/](04-subagents/) |
+| **Skills** | 10 bundled | 5 | 15 | [03-skills/](03-skills/) |
+| **Plugins** | - | 3 | 3 | [07-plugins/](07-plugins/) |
+| **MCP Servers** | 1 | 4 | 5 | [05-mcp/](05-mcp/) |
+| **Hooks** | 31 sự kiện | 9 | 40 | [06-hooks/](06-hooks/) |
+| **Bộ Nhớ** | 7 loại | 3 | 10 | [02-memory/](02-memory/) |
 | **Tổng** | **115** | **38** | **153** | |

 ---
@@ -103,7 +103,7 @@ Commands là các lệnh tắt do người dùng gọi thực hiện các hành

 > **Phạm Vi**: `User` = workflows cá nhân (`~/.claude/commands/`), `Project` = chia sẻ team (`.claude/commands/`)

-**Tham Chiếu**: [01-slash-commands/](../01-slash-commands/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/interactive-mode)
+**Tham Chiếu**: [01-slash-commands/](01-slash-commands/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/interactive-mode)

 **Cài Đặt Nhanh (Tất Cả Custom Commands)**:
 ```bash
@@ -125,7 +125,7 @@ Claude Code hỗ trợ 6 permission modes điều khiển cách tool use đượ
 | `bypassPermissions` | Bỏ qua tất cả kiểm tra permissions | CI/CD, môi trường headless |
 | `dontAsk` | Bỏ qua tools cần yêu cầu permission | Scripting không tương tác |

-> **Lưu Ý**: `auto` mode yêu cầu gói dịch vụ, model, và nhà cung cấp đủ điều kiện — xem [09-advanced-features/](../09-advanced-features/#auto-mode). Chỉ dùng `bypassPermissions` trong môi trường tin cậy, được sandbox.
+> **Lưu Ý**: `auto` mode yêu cầu gói dịch vụ, model, và nhà cung cấp đủ điều kiện — xem [09-advanced-features/](09-advanced-features/#auto-mode). Chỉ dùng `bypassPermissions` trong môi trường tin cậy, được sandbox.

 **Tham Chiếu**: [Tài Liệu Chính Thức](https://code.claude.com/docs/en/permissions)

@@ -175,7 +175,7 @@ Các trợ lý AI chuyên biệt với context bị cô lập cho các tasks c

 > **Phạm Vi**: `User` = cá nhân (`~/.claude/agents/`), `Project` = chia sẻ team (`.claude/agents/`)

-**Tham Chiếu**: [04-subagents/](../04-subagents/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/sub-agents)
+**Tham Chiếu**: [04-subagents/](04-subagents/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/sub-agents)

 **Cài Đặt Nhanh (Tất Cả Custom Agents)**:
 ```bash
@@ -220,7 +220,7 @@ Skills hỗ trợ YAML frontmatter trong `SKILL.md` để cấu hình:
 | `effort` | string | Mức độ effort lý luận (`low`, `medium`, `high`) |
 | `shell` | string | Shell để dùng cho scripts (`bash`, `zsh`, `sh`) |

-**Tham Chiếu**: [03-skills/](../03-skills/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/skills)
+**Tham Chiếu**: [03-skills/](03-skills/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/skills)

 **Cài Đặt Nhanh (Tất Cả Skills)**:
 ```bash
@@ -266,7 +266,7 @@ Bộ sưu tập được đóng gói của commands, agents, MCP servers, và ho
 └── scripts/          # Scripts tiện ích
 ```

-**Tham Chiếu**: [07-plugins/](../07-plugins/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/plugins)
+**Tham Chiếu**: [07-plugins/](07-plugins/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/plugins)

 **Plugin Management Commands**:
 ```bash
@@ -314,7 +314,7 @@ Máy chủ Model Context Protocol cho truy cập công cụ và API bên ngoài.
 }
 ```

-**Tham Chiếu**: [05-mcp/](../05-mcp/) | [Tài Liệu Giao Thức MCP](https://modelcontextprotocol.io)
+**Tham Chiếu**: [05-mcp/](05-mcp/) | [Tài Liệu Giao Thức MCP](https://modelcontextprotocol.io)

 **Cài Đặt Nhanh (GitHub MCP)**:
 ```bash
@@ -392,7 +392,7 @@ Tự động hóa dựa trên sự kiện thực thi shell commands trên các s
 }
 ```

-**Tham Chiếu**: [06-hooks/](../06-hooks/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/hooks)
+**Tham Chiếu**: [06-hooks/](06-hooks/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/hooks)

 **Cài Đặt Nhanh (Tất Cả Hooks)**:
 ```bash
@@ -419,7 +419,7 @@ Ngữ cảnh lưu trữ được tải tự động qua sessions.

 > **Phạm Vi**: `Organization` = được quản lý bởi admins, `Project` = chia sẻ với team qua git, `User` = sở thích cá nhân, `Local` = không được commit, `Session` = được tự động quản lý

-**Tham Chiếu**: [02-memory/](../02-memory/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/memory)
+**Tham Chiếu**: [02-memory/](02-memory/) | [Tài Liệu Chính Thức](https://code.claude.com/docs/en/memory)

 **Cài Đặt Nhanh**:
 ```bash
@@ -27,7 +27,9 @@ Năm kiểm tra là:
 2. **cross-references** — Liên kết nội bộ, anchors, cú pháp code fence (Python script)
 3. **mermaid-syntax** — Xác thực tất cả sơ đồ Mermaid parse đúng (Python script)
 4. **link-check** — Các URL bên ngoài có thể truy cập được (Python script)
-5. **build-epub** — EPUB tạo ra không có lỗi (khi có thay đổi `.md`)
+5. **markdown-rendering** — Markdown render không lỗi (Python script)
+
+Việc build EPUB **không phải** là một pre-commit hook — nó chỉ chạy trong CI (job `build-epub` trong `.github/workflows/test.yml`), vì nó cần binary `mmdc` cục bộ, vốn không có bản build hoạt động trên arm64.

 ### Thiết Lập Môi Trường Phát Triển

@@ -81,11 +83,11 @@ mypy scripts/ --ignore-missing-imports
 ### Build EPUB

 ```bash
-# Tạo ebook (render Mermaid diagrams qua Kroki.io API)
+# Tạo ebook (render Mermaid diagrams bằng mmdc CLI cục bộ — không cần mạng)
 uv run scripts/build_epub.py

 # Với các tùy chọn
-uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
+uv run scripts/build_epub.py --verbose --output custom-name.epub --lang vi
 ```

 ## Cấu Trúc Thư Mục
@@ -102,7 +104,7 @@ uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurren
 ├── 09-advanced-features/   # Lập kế hoạch, suy nghĩ, background tasks
 ├── 10-cli/                 # Tham chiếu CLI
 ├── scripts/
-│   ├── build_epub.py           # EPUB generator (render Mermaid qua Kroki API)
+│   ├── build_epub.py           # EPUB generator (render Mermaid bằng mmdc cục bộ)
 │   ├── check_cross_references.py   # Xác thực liên kết nội bộ
 │   ├── check_links.py          # Kiểm tra các URL bên ngoài
 │   ├── check_mermaid.py        # Xác thực cú pháp Mermaid
@@ -122,7 +124,7 @@ Mỗi thư mục đánh số tuân theo pattern:

 ### Sơ Đồ Mermaid
 - Tất cả sơ đồ phải parse thành công (được kiểm tra bởi pre-commit hook)
- EPUB build render sơ đồ qua Kroki.io API (cần internet)
+- EPUB build render sơ đồ bằng `mmdc` CLI cục bộ (không cần internet, nhưng cần cài `mmdc`)
 - Sử dụng Mermaid cho flowcharts, sequence diagrams, và architecture visuals

 ### Cross-References
@@ -143,7 +145,7 @@ Mỗi thư mục đánh số tuân theo pattern:

 3. **Pre-commit là người gác cổng** — Tất cả năm kiểm tra chất lượng phải pass trước khi PR được chấp nhận. CI pipeline chạy các kiểm tra tương tự như lần thứ hai.

-4. **Mermaid rendering cần network** — EPUB build gọi Kroki.io API để render diagrams. Các lỗi build ở đây thường là vấn đề network hoặc cú pháp Mermaid không hợp lệ.
+4. **Mermaid rendering cần `mmdc` cục bộ** — EPUB build gọi `mmdc` CLI cục bộ để render diagrams (không cần network). Các lỗi build ở đây thường là do chưa cài `mmdc` hoặc cú pháp Mermaid không hợp lệ. Bản thân EPUB build không chạy trong pre-commit — nó chỉ chạy trong CI.

 5. **Đây là tutorial, không phải thư viện** — Khi thêm nội dung, tập trung vào giải thích rõ ràng, ví dụ copy-paste, và sơ đồ trực quan. Giá trị nằm ở việc dạy các khái niệm, không cung cấp code có thể tái sử dụng.

@@ -218,7 +218,9 @@ Các script tự động hóa dựa trên sự kiện thực thi tự động.

 **Cách Dùng**: Cấu hình trong settings, thực thi tự động

-**Hook Types** (5 types, 31 events):
+**Hook Types** (5): `command`, `http`, `prompt`, `mcp_tool`, `agent` — cách hook chạy.
+
+**Hook Events** (31, trong 4 nhóm) — khi nào hook chạy:
 - Tool Hooks: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied
 - Session Hooks: SessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop
 - Task Hooks: UserPromptSubmit, UserPromptExpansion, MessageDisplay, TaskCompleted, TaskCreated, TeammateIdle
@@ -92,17 +92,17 @@ graph TD

 | Bước | Tính Năng | Độ Phức Tạp | Thời Gian | Cấp Độ | Dependencies | Tại Sao Học Cái Này | Lợi Ích Chính |
 |------|---------|-----------|----------|-------|--------------|------------------|--------------|
-| **1** | [Lệnh Slash](../01-slash-commands/) | ⭐ Người mới | 30 phút | Level 1 | None | Gains năng suất nhanh (55+ built-in + 10 bundled skills) | Tự động hóa tức thì, tiêu chuẩn team |
-| **2** | [Bộ Nhớ](../02-memory/) | ⭐⭐ Người mới+ | 45 phút | Level 1 | None | Thiết yếu cho tất cả tính năng | Ngữ cảnh lưu trữ, sở thích |
-| **3** | [Checkpoints](../08-checkpoints/) | ⭐⭐ Trung cấp | 45 phút | Level 1 | Quản lý session | Khám phá an toàn | Thử nghiệm, phục hồi |
-| **4** | [CLI Cơ Bản](../10-cli/) | ⭐⭐ Người mới+ | 30 phút | Level 1 | None | Sử dụng CLI cốt | Mode tương tác & print |
-| **5** | [Skills](../03-skills/) | ⭐⭐ Trung cấp | 1 giờ | Level 2 | Lệnh Slash | Chuyên môn tự động | Khả năng tái sử dụng, nhất quán |
-| **6** | [Hooks](../06-hooks/) | ⭐⭐ Trung cấp | 1 giờ | Level 2 | Tools, Commands | Tự động hóa workflow (31 sự kiện, 5 types) | Xác thực, cổng chất lượng |
-| **7** | [MCP](../05-mcp/) | ⭐⭐⭐ Trung cấp+ | 1 giờ | Level 2 | Cấu hình | Truy cập dữ liệu trực tiếp | Tích hợp thời gian thực, APIs |
-| **8** | [Tác Nhân Con](../04-subagents/) | ⭐⭐⭐ Trung cấp+ | 1.5 giờ | Level 2 | Bộ Nhớ, Commands | Xử lý task phức tạp (6 built-in bao gồm Bash) | Ủy quyền, chuyên môn hóa |
-| **9** | [Tính Năng Nâng Cao](../09-advanced-features/) | ⭐⭐⭐⭐⭐ Nâng cao | 2-3 giờ | Level 3 | Tất cả trước | Công cụ power user | Planning, Auto Mode, Channels, Voice Dictation, permissions |
-| **10** | [Plugins](../07-plugins/) | ⭐⭐⭐⭐ Nâng cao | 2 giờ | Level 3 | Tất cả trước | Giải pháp hoàn chỉnh | Onboarding team, phân phối |
-| **11** | [CLI Mastery](../10-cli/) | ⭐⭐⭐ Nâng cao | 1 giờ | Level 3 | Khuyến nghị: Tất cả | Làm chủ usage command-line | Scripting, CI/CD, tự động hóa |
+| **1** | [Lệnh Slash](01-slash-commands/) | ⭐ Người mới | 30 phút | Level 1 | None | Gains năng suất nhanh (55+ built-in + 10 bundled skills) | Tự động hóa tức thì, tiêu chuẩn team |
+| **2** | [Bộ Nhớ](02-memory/) | ⭐⭐ Người mới+ | 45 phút | Level 1 | None | Thiết yếu cho tất cả tính năng | Ngữ cảnh lưu trữ, sở thích |
+| **3** | [Checkpoints](08-checkpoints/) | ⭐⭐ Trung cấp | 45 phút | Level 1 | Quản lý session | Khám phá an toàn | Thử nghiệm, phục hồi |
+| **4** | [CLI Cơ Bản](10-cli/) | ⭐⭐ Người mới+ | 30 phút | Level 1 | None | Sử dụng CLI cốt | Mode tương tác & print |
+| **5** | [Skills](03-skills/) | ⭐⭐ Trung cấp | 1 giờ | Level 2 | Lệnh Slash | Chuyên môn tự động | Khả năng tái sử dụng, nhất quán |
+| **6** | [Hooks](06-hooks/) | ⭐⭐ Trung cấp | 1 giờ | Level 2 | Tools, Commands | Tự động hóa workflow (31 sự kiện, 5 types) | Xác thực, cổng chất lượng |
+| **7** | [MCP](05-mcp/) | ⭐⭐⭐ Trung cấp+ | 1 giờ | Level 2 | Cấu hình | Truy cập dữ liệu trực tiếp | Tích hợp thời gian thực, APIs |
+| **8** | [Tác Nhân Con](04-subagents/) | ⭐⭐⭐ Trung cấp+ | 1.5 giờ | Level 2 | Bộ Nhớ, Commands | Xử lý task phức tạp (6 built-in bao gồm Bash) | Ủy quyền, chuyên môn hóa |
+| **9** | [Tính Năng Nâng Cao](09-advanced-features/) | ⭐⭐⭐⭐⭐ Nâng cao | 2-3 giờ | Level 3 | Tất cả trước | Công cụ power user | Planning, Auto Mode, Channels, Voice Dictation, permissions |
+| **10** | [Plugins](07-plugins/) | ⭐⭐⭐⭐ Nâng cao | 2 giờ | Level 3 | Tất cả trước | Giải pháp hoàn chỉnh | Onboarding team, phân phối |
+| **11** | [CLI Mastery](10-cli/) | ⭐⭐⭐ Nâng cao | 1 giờ | Level 3 | Khuyến nghị: Tất cả | Làm chủ usage command-line | Scripting, CI/CD, tự động hóa |

 **Tổng Thời Gian Học**: ~11-13 giờ (hoặc nhảy đến cấp độ của bạn và tiết kiệm thời gian)

@@ -149,8 +149,8 @@ cp ../02-memory/project-CLAUDE.md ./CLAUDE.md

 #### Các Bước Tiếp Theo
 Khi thoải mái, đọc:
- [../01-slash-commands/README.md](../01-slash-commands/README.md)
- [../02-memory/README.md](../02-memory/README.md)
+- [../01-slash-commands/README.md](01-slash-commands/README.md)
+- [../02-memory/README.md](02-memory/README.md)

 > **Kiểm tra sự hiểu của bạn**: Chạy `/lesson-quiz slash-commands` hoặc `/lesson-quiz memory` trong Claude Code để kiểm tra những gì bạn đã học.

@@ -193,8 +193,8 @@ cat error.log | claude -p "giải thích lỗi này"
 - [ ] Hiểu khi nào dùng checkpoints để thử nghiệm an toàn

 #### Các Bước Tiếp Theo
- Đọc: [../08-checkpoints/README.md](../08-checkpoints/README.md)
- Đọc: [../10-cli/README.md](../10-cli/README.md)
+- Đọc: [../08-checkpoints/README.md](08-checkpoints/README.md)
+- Đọc: [../10-cli/README.md](10-cli/README.md)
 - **Sẵn Sàng Cho Level 2!** Tiếp tục [Milestone 2A](#milestone-2a-tự-động-hóa-skills--hooks)

 > **Kiểm tra sự hiểu của bạn**: Chạy `/lesson-quiz checkpoints` hoặc `/lesson-quiz cli` để xác nhận bạn sẵn sàng cho Level 2.
@@ -212,10 +212,10 @@ cat error.log | claude -p "giải thích lỗi này"

 Trước khi bắt đầu Level 2, đảm bảo bạn thoải mái với các khái niệm Level 1 này:

- [ ] Có thể tạo và sử dụng slash commands ([../01-slash-commands/](../01-slash-commands/))
- [ ] Đã thiết lập bộ nhớ dự án qua CLAUDE.md ([../02-memory/](../02-memory/))
- [ ] Biết cách tạo và khôi phục checkpoints ([../08-checkpoints/](../08-checkpoints/))
- [ ] Có thể sử dụng `claude` và `claude -p` từ command line ([../10-cli/](../10-cli/))
+- [ ] Có thể tạo và sử dụng slash commands ([../01-slash-commands/](01-slash-commands/))
+- [ ] Đã thiết lập bộ nhớ dự án qua CLAUDE.md ([../02-memory/](02-memory/))
+- [ ] Biết cách tạo và khôi phục checkpoints ([../08-checkpoints/](08-checkpoints/))
+- [ ] Có thể sử dụng `claude` và `claude -p` từ command line ([../10-cli/](10-cli/))

 > **Thiếu?** Xem lại các tutorials được liên kết ở trên trước khi tiếp tục.

@@ -273,8 +273,8 @@ chmod +x ~/.claude/hooks/pre-tool-check.sh
 #### Các Bước Tiếp Theo
 - Tạo skill tùy chỉnh của riêng bạn
 - Thiết lập additional hooks cho workflow của bạn
- Đọc: [../03-skills/README.md](../03-skills/README.md)
- Đọc: [../06-hooks/README.md](../06-hooks/README.md)
+- Đọc: [../03-skills/README.md](03-skills/README.md)
+- Đọc: [../06-hooks/README.md](06-hooks/README.md)

 > **Kiểm tra sự hiểu của bạn**: Chạy `/lesson-quiz skills` hoặc `/lesson-quiz hooks` để kiểm tra kiến thức trước khi chuyển tiếp.

@@ -323,8 +323,8 @@ Thử workflow hoàn chỉnh này:
 #### Các Bước Tiếp Theo
 - Thiết lập additional MCP servers (database, Slack, v.v.)
 - Tạo custom subagents cho domain của bạn
- Đọc: [../05-mcp/README.md](../05-mcp/README.md)
- Đọc: [../04-subagents/README.md](../04-subagents/README.md)
+- Đọc: [../05-mcp/README.md](05-mcp/README.md)
+- Đọc: [../04-subagents/README.md](04-subagents/README.md)
 - **Sẵn Sàng Cho Level 3!** Tiếp tục [Milestone 3A](#milestone-3a-tính-năng-nâng-cao)

 > **Kiểm tra sự hiểu của bạn**: Chạy `/lesson-quiz mcp` hoặc `/lesson-quiz subagents` để xác nhận bạn sẵn sàng cho Level 3.
@@ -342,10 +342,10 @@ Thử workflow hoàn chỉnh này:

 Trước khi bắt đầu Level 3, đảm bảo bạn thoải mái với các khái niệm Level 2 này:

- [ ] Có thể tạo và sử dụng skills với auto-invocation ([../03-skills/](../03-skills/))
- [ ] Đã thiết lập hooks cho tự động hóa dựa trên sự kiện ([../06-hooks/](../06-hooks/))
- [ ] Có thể cấu hình MCP servers cho dữ liệu bên ngoài ([../05-mcp/](../05-mcp/))
- [ ] Biết cách sử dụng subagents để ủy quyền task ([../04-subagents/](../04-subagents/))
+- [ ] Có thể tạo và sử dụng skills với auto-invocation ([../03-skills/](03-skills/))
+- [ ] Đã thiết lập hooks cho tự động hóa dựa trên sự kiện ([../06-hooks/](06-hooks/))
+- [ ] Có thể cấu hình MCP servers cho dữ liệu bên ngoài ([../05-mcp/](05-mcp/))
+- [ ] Biết cách sử dụng subagents để ủy quyền task ([../04-subagents/](04-subagents/))

 > **Thiếu?** Xem lại các tutorials được liên kết ở trên trước khi tiếp tục.

@@ -423,7 +423,7 @@ export CLAUDE_AGENT_TEAMS=1
 - [ ] Đã sử dụng `/loop` cho tasks định kỳ hoặc monitoring theo lịch

 #### Các Bước Tiếp Theo
- Đọc: [../09-advanced-features/README.md](../09-advanced-features/README.md)
+- Đọc: [../09-advanced-features/README.md](09-advanced-features/README.md)

 > **Kiểm tra sự hiểu của bạn**: Chạy `/lesson-quiz advanced` để kiểm tra sự thành thạo của bạn về các tính năng power user.

@@ -492,8 +492,8 @@ Tạo một script CI/CD đơn giản:
 - **Xử Lý Dữ Liệu**: Chuyển đổi và phân tích files dữ liệu

 #### Các Bước Tiếp Theo
- Đọc: [../07-plugins/README.md](../07-plugins/README.md)
- Đọc: [../10-cli/README.md](../10-cli/README.md)
+- Đọc: [../07-plugins/README.md](07-plugins/README.md)
+- Đọc: [../10-cli/README.md](10-cli/README.md)
 - Tạo shortcuts CLI và plugins cho team
 - Thiết lập scripts xử lý hàng loạt

@@ -527,7 +527,7 @@ Repository này bao gồm hai skills tương tác bạn có thể sử dụng b

 1. Sao chép một slash command: `cp ../01-slash-commands/optimize.md .claude/commands/`
 2. Thử trong Claude Code: `/optimize`
-3. Đọc: [../01-slash-commands/README.md](../01-slash-commands/README.md)
+3. Đọc: [../01-slash-commands/README.md](01-slash-commands/README.md)

 **Kết Quả**: Bạn sẽ có một slash command đang hoạt động và hiểu những điều cơ bản

@@ -623,40 +623,40 @@ Repository này bao gồm hai skills tương tác bạn có thể sử dụng b
 Sử dụng các checklists này để theo dõi tiến độ của bạn theo level. Chạy `/self-assessment` bất cứ lúc nào để nhận profile kỹ năng cập nhật, hoặc `/lesson-quiz [lesson]` sau mỗi tutorial để xác nhận sự hiểu của bạn.

 ### 🟢 Level 1: Người Mới
- [ ] Hoàn thành [../01-slash-commands/](../01-slash-commands/)
- [ ] Hoàn thành [../02-memory/](../02-memory/)
+- [ ] Hoàn thành [../01-slash-commands/](01-slash-commands/)
+- [ ] Hoàn thành [../02-memory/](02-memory/)
 - [ ] Đã tạo slash command tùy chỉnh đầu tiên
 - [ ] Thiết lập bộ nhớ dự án
 - [ ] **Milestone 1A đạt được**
- [ ] Hoàn thành [../08-checkpoints/](../08-checkpoints/)
- [ ] Hoàn thành [../10-cli/](../10-cli/) cơ bản
+- [ ] Hoàn thành [../08-checkpoints/](08-checkpoints/)
+- [ ] Hoàn thành [../10-cli/](10-cli/) cơ bản
 - [ ] Đã tạo và hoàn nguyên về một checkpoint
 - [ ] Đã sử dụng mode tương tác và print mode
 - [ ] **Milestone 1B đạt được**

 ### 🔵 Level 2: Trung Cấp
- [ ] Hoàn thành [../03-skills/](../03-skills/)
- [ ] Hoàn thành [../06-hooks/](../06-hooks/)
+- [ ] Hoàn thành [../03-skills/](03-skills/)
+- [ ] Hoàn thành [../06-hooks/](06-hooks/)
 - [ ] Đã cài đặt skill đầu tiên
 - [ ] Thiết lập PreToolUse hook
 - [ ] **Milestone 2A đạt được**
- [ ] Hoàn thành [../05-mcp/](../05-mcp/)
- [ ] Hoàn thành [../04-subagents/](../04-subagents/)
+- [ ] Hoàn thành [../05-mcp/](05-mcp/)
+- [ ] Hoàn thành [../04-subagents/](04-subagents/)
 - [ ] Kết nối GitHub MCP
 - [ ] Đã tạo subagent tùy chỉnh
 - [ ] Kết hợp các tích hợp trong một workflow
 - [ ] **Milestone 2B đạt được**

 ### 🔴 Level 3: Nâng Cao
- [ ] Hoàn thành [../09-advanced-features/](../09-advanced-features/)
+- [ ] Hoàn thành [../09-advanced-features/](09-advanced-features/)
 - [ ] Đã sử dụng planning mode thành công
 - [ ] Đã cấu hình permission modes (6 modes bao gồm auto)
 - [ ] Đã sử dụng auto mode với safety classifier
 - [ ] Đã sử dụng extended thinking toggle
 - [ ] Đã khám phá Channels và Voice Dictation
 - [ ] **Milestone 3A đạt được**
- [ ] Hoàn thành [../07-plugins/](../07-plugins/)
- [ ] Hoàn thành [../10-cli/](../10-cli/) sử dụng nâng cao
+- [ ] Hoàn thành [../07-plugins/](07-plugins/)
+- [ ] Hoàn thành [../10-cli/](10-cli/) sử dụng nâng cao
 - [ ] Thiết lập print mode (`claude -p`) CI/CD
 - [ ] Đã tạo output JSON để tự động hóa
 - [ ] Tích hợp Claude vào pipeline CI/CD
@@ -124,7 +124,7 @@ Claude Code 提供 6 种权限模式，用来控制工具调用如何被授权
 | `bypassPermissions` | 跳过所有权限检查 | CI/CD、无头环境 |
 | `dontAsk` | 跳过需要权限的工具 | 非交互脚本 |

-> **注意**：`auto` 模式需要满足合格的套餐、模型和提供商条件 — 参见 [09-advanced-features/](../09-advanced-features/#auto-mode)。只有在可信且已隔离的环境中才使用 `bypassPermissions`。
+> **注意**：`auto` 模式需要满足合格的套餐、模型和提供商条件 — 参见 [09-advanced-features/](09-advanced-features/#auto-mode)。只有在可信且已隔离的环境中才使用 `bypassPermissions`。

 **参考**: [官方文档](https://code.claude.com/docs/en/permissions)

@@ -214,7 +214,9 @@ blog-draft/

 **使用方式**：在设置中配置后自动执行

-**Hook 类型**（5 类，31 个事件）：
+**Hook 类型**（5 种）：`command`、`http`、`prompt`、`mcp_tool`、`agent` — 决定 hook 如何运行。
+
+**Hook 事件**（31 个，分 4 类）— 决定 hook 何时运行：
 - 工具 Hook：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PostToolBatch`、`PermissionRequest`、`PermissionDenied`
 - 会话 Hook：`SessionStart`、`Setup`、`SessionEnd`、`Stop`、`StopFailure`、`SubagentStart`、`SubagentStop`
 - 任务 Hook：`UserPromptSubmit`、`UserPromptExpansion`、`MessageDisplay`、`TaskCompleted`、`TaskCreated`、`TeammateIdle`
@@ -478,7 +478,9 @@ chmod +x ~/.claude/hooks/*.sh

 **使用方法**: hooks 会在事件发生时自动执行

-**Hook 类型**（5 类，31 个事件）:
+**Hook 类型**（5 种）：`command`、`http`、`prompt`、`mcp_tool`、`agent` — 决定 hook 如何运行。
+
+**Hook 事件**（31 个，分 4 类）— 决定 hook 何时运行:
 - **工具 Hook**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `PermissionRequest`, `PermissionDenied`
 - **会话 Hook**: `SessionStart`, `Setup`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`
 - **任务 Hook**: `UserPromptSubmit`, `UserPromptExpansion`, `MessageDisplay`, `TaskCompleted`, `TaskCreated`, `TeammateIdle`