diff --git a/.cspell.json b/.cspell.json
index b7fb1b7..6d81ae5 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -123,9 +123,7 @@
     "asyncio",
     "beautifulsoup",
     "ebooklib",
-    "httpx",
     "pillow",
-    "tenacity",
     "cSpell",
     "markdownlint",
     "Kroki",
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 70352ce..5c30d85 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -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: |
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 8be75aa..cb77d32 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -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)$
diff --git a/CLAUDE.md b/CLAUDE.md
index 2b137d6..332fb33 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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.
 
diff --git a/INDEX.md b/INDEX.md
index 75eaa12..924c0cb 100644
--- a/INDEX.md
+++ b/INDEX.md
@@ -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
diff --git a/README.md b/README.md
index 174d392..7946f1a 100644
--- a/README.md
+++ b/README.md
@@ -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`
diff --git a/ja/CATALOG.md b/ja/CATALOG.md
index 1a345f3..af27645 100644
--- a/ja/CATALOG.md
+++ b/ja/CATALOG.md
@@ -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)
 
diff --git a/ja/CLAUDE.md b/ja/CLAUDE.md
index ddf7493..2f6998f 100644
--- a/ja/CLAUDE.md
+++ b/ja/CLAUDE.md
@@ -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. **これはチュートリアルでありライブラリではない** — コンテンツを追加する際は、明快な解説、コピー＆ペースト可能な例、視覚的な図を重視する。価値は概念を教えることにあり、再利用可能なコードを提供することではない。
 
diff --git a/ja/INDEX.md b/ja/INDEX.md
index 16b5098..a59077b 100644
--- a/ja/INDEX.md
+++ b/ja/INDEX.md
@@ -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
diff --git a/ja/README.md b/ja/README.md
index 67d4711..ad5d8dd 100644
--- a/ja/README.md
+++ b/ja/README.md
@@ -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`
diff --git a/ja/claude_concepts_guide.md b/ja/claude_concepts_guide.md
index 4ea3c06..10f4007 100644
--- a/ja/claude_concepts_guide.md
+++ b/ja/claude_concepts_guide.md
@@ -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/)
 
 ---
 
diff --git a/ja/scripts/README.md b/ja/scripts/README.md
index 2d4f377..3779ac9 100644
--- a/ja/scripts/README.md
+++ b/ja/scripts/README.md
@@ -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` が見つからない場合、スクリプトはテキストのみの表紙を生成する。
diff --git a/scripts/README.md b/scripts/README.md
index 6016fb4..1492d6b 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -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.
 
diff --git a/scripts/pyproject.toml b/scripts/pyproject.toml
index b8bcef3..2de9f92 100644
--- a/scripts/pyproject.toml
+++ b/scripts/pyproject.toml
@@ -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"]
diff --git a/scripts/requirements-dev.txt b/scripts/requirements-dev.txt
index 63ea204..2a1bc9b 100644
--- a/scripts/requirements-dev.txt
+++ b/scripts/requirements-dev.txt
@@ -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
diff --git a/scripts/requirements.txt b/scripts/requirements.txt
index 1b36857..c8a8be3 100644
--- a/scripts/requirements.txt
+++ b/scripts/requirements.txt
@@ -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
diff --git a/scripts/tests/test_build_website.py b/scripts/tests/test_build_website.py
index 5abad84..102f3d5 100644
--- a/scripts/tests/test_build_website.py
+++ b/scripts/tests/test_build_website.py
@@ -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"
+            )
 
 
 # =============================================================================
diff --git a/scripts/tests/test_check_markdown_rendering.py b/scripts/tests/test_check_markdown_rendering.py
index c20dbbe..b18fbc7 100644
--- a/scripts/tests/test_check_markdown_rendering.py
+++ b/scripts/tests/test_check_markdown_rendering.py
@@ -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 == []
 
diff --git a/uk/CATALOG.md b/uk/CATALOG.md
index 96621c6..3379891 100644
--- a/uk/CATALOG.md
+++ b/uk/CATALOG.md
@@ -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)
 
 **Швидке встановлення**:
 
diff --git a/uk/CLAUDE.md b/uk/CLAUDE.md
index fbdd141..b3ccf54 100644
--- a/uk/CLAUDE.md
+++ b/uk/CLAUDE.md
@@ -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. **Це туторіал, а не бібліотека** — При додаванні контенту зосереджуйтесь на чітких поясненнях, готових прикладах та візуальних діаграмах. Цінність — у навчанні концепцій, а не у наданні повторно використовуваного коду.
 
diff --git a/uk/INDEX.md b/uk/INDEX.md
index ca592aa..97b5405 100644
--- a/uk/INDEX.md
+++ b/uk/INDEX.md
@@ -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
diff --git a/uk/LEARNING-ROADMAP.md b/uk/LEARNING-ROADMAP.md
index 41298e5..5698ac6 100644
--- a/uk/LEARNING-ROADMAP.md
+++ b/uk/LEARNING-ROADMAP.md
@@ -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-пайплайн
diff --git a/uk/README.md b/uk/README.md
index 77862ec..8a4afb0 100644
--- a/uk/README.md
+++ b/uk/README.md
@@ -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`
diff --git a/uk/scripts/README.md b/uk/scripts/README.md
index 903f75f..9693848 100644
--- a/uk/scripts/README.md
+++ b/uk/scripts/README.md
@@ -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` не знайдено.
diff --git a/vi/CATALOG.md b/vi/CATALOG.md
index f63852f..4ee6991 100644
--- a/vi/CATALOG.md
+++ b/vi/CATALOG.md
@@ -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
diff --git a/vi/CLAUDE.md b/vi/CLAUDE.md
index 073405a..0118bbf 100644
--- a/vi/CLAUDE.md
+++ b/vi/CLAUDE.md
@@ -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.
 
diff --git a/vi/INDEX.md b/vi/INDEX.md
index 71ee426..ca10b38 100644
--- a/vi/INDEX.md
+++ b/vi/INDEX.md
@@ -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
diff --git a/vi/LEARNING-ROADMAP.md b/vi/LEARNING-ROADMAP.md
index 493d558..29e941c 100644
--- a/vi/LEARNING-ROADMAP.md
+++ b/vi/LEARNING-ROADMAP.md
@@ -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
diff --git a/zh/CATALOG.md b/zh/CATALOG.md
index 214b148..1c4b2e4 100644
--- a/zh/CATALOG.md
+++ b/zh/CATALOG.md
@@ -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)
 
diff --git a/zh/INDEX.md b/zh/INDEX.md
index ac1666a..4a94430 100644
--- a/zh/INDEX.md
+++ b/zh/INDEX.md
@@ -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`
diff --git a/zh/README.md b/zh/README.md
index 84568bb..b65ec8f 100644
--- a/zh/README.md
+++ b/zh/README.md
@@ -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`