diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index ed4a3008..10835e45 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,17 +1,27 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "psychquant-claude-plugins",
-  "description": "Che Cheng's Claude Code Plugin Marketplace - \u5b78\u8853\u7814\u7a76\u8207\u751f\u7522\u529b\u5de5\u5177",
+  "description": "Che Cheng's Claude Code Plugin Marketplace - 學術研究與生產力工具",
   "owner": {
     "name": "Che Cheng",
     "email": "che@example.com"
   },
   "homepage": "https://github.com/PsychQuant/psychquant-claude-plugins",
   "plugins": [
+    {
+      "name": "che-latex-mcp",
+      "version": "0.5.0",
+      "description": "讓 AI 完全清楚 LaTeX 修正的結果 — 改一行 source 立刻知道 PDF 第幾頁變了、變成什麼樣、有沒有副作用、有沒有新 bug、PDF review 紅圈對到哪個 source。通用 LaTeX 工具,任何專案可用。20 tools + 4 skills。v0.5.0 新增 Pillar 5 annotation workflow + 修 server.waitUntilCompleted() bug。",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/che-latex-mcp",
+      "category": "productivity"
+    },
     {
       "name": "mcp-tools",
-      "version": "1.12.0",
-      "description": "MCP Server \u958b\u767c\u5de5\u5177\u96c6\uff1amcp-new-app\u3001mcp-deploy\u3001mcp-install\u3001mcp-upgrade\u3001mcp-clone\u3001mcp-publish\u3001mcp-sync\u3001mcp-diagnose\u3001mcp-debug\u3001mcp-test\u3001mcp-to-plugin\u3001mcp-issue",
+      "version": "1.16.0",
+      "description": "MCP Server 開發工具集：mcp-new-app、mcp-deploy、mcp-install、mcp-upgrade、mcp-sign-pipeline（macOS 26 簽章）、mcp-clone、mcp-publish、mcp-sync、mcp-diagnose、mcp-debug、mcp-test、mcp-to-plugin、mcp-issue",
       "author": {
         "name": "Che Cheng"
       },
@@ -20,8 +30,8 @@
     },
     {
       "name": "plugin-tools",
-      "version": "1.7.0",
-      "description": "Claude Code Plugin \u5b8c\u6574\u751f\u547d\u9031\u671f\u5de5\u5177\uff1aplugin-create\u3001plugin-deploy\u3001plugin-update\u3001plugin-health\u3001plugin-debug",
+      "version": "1.17.0",
+      "description": "Claude Code Plugin 完整生命週期工具：plugin-create、plugin-upgrade、plugin-deploy、plugin-update、plugin-health、plugin-debug. v1.17.0 (#66): plugin-update 新增 (a) Phase 0.3 Sync Intent Gate — pre-flight 偵測 binary-backed plugin、比對 marketplace.json drift + 30 天內 shell 改動 + binary repo `main` 是否超前 last release;nothing-to-sync 案例 abort early (no-op short-circuit),救 v1.16.0 之前「跑了 plugin-update 卻什麼都沒同步」的盲點;(b) Phase 1.5 Step 2 新增 Signal 2 (binary repo main vs last release drift) — git -C <binary-repo> log v$BINARY_VERSION..main 偵測 [Unreleased] backlog,提示先 cd binary repo 跑 release.sh + bump binary_version。v1.16.0 (#60): plugin-update Phase 0.5 git-state preview + 5-case AskUserQuestion confirmation gate(clean+0/clean+N/dirty+0/dirty+N/diverged),idd-all unattended mode auto-abort,cross-plugin commits warn-only(Tier A;Tier C scope guard 留給 #65)。",
       "author": {
         "name": "Che Cheng"
       },
@@ -29,29 +39,40 @@
       "category": "development"
     },
     {
-      "name": "issue-driven-dev",
-      "version": "2.4.2",
-      "description": "Issue-driven development methodology: idd-issue \u2192 idd-diagnose \u2192 idd-implement \u2192 idd-verify \u2192 idd-close. Auto-complete friendly.",
+      "name": "doc-tools",
+      "version": "0.2.0",
+      "description": "v0.2.0: Renamed from changelog-tools to doc-tools — scope expanded from CHANGELOG-only to general documentation lifecycle (CHANGELOG.md / README.md / CLAUDE.md / changelog/ all in scope). NEW Stop hook (doc-update-guard.sh) absorbs the user-level changelog-update.sh hook from che-claude-config: blocks turn-end when HEAD commit changed ≥3 code files but updated none of CHANGELOG.md / README.md / CLAUDE.md / changelog/ — original design rationale preserved (per-commit not per-day because compact-aware; Stop+block intentional because doc updates are clearly actionable; 3-file threshold heuristic for 'significant change'; code-extension allowlist for user's primary languages R/sh/sql/py/ts/swift/go/rs/etc; stop_hook_active=true bypass for infinite-loop protection). Three-tier config injection (precedence high→low): <repo>/.claude/doc-tools.json (per-project) → ~/.cache/doc-tools/config.json (per-machine) → built-in defaults; plus ~/.cache/doc-tools/disabled flag for one-touch kill switch. Config schema: {enabled, min_changed_files, code_extensions[], doc_files[], skip_paths[]}. NEW references/doc-update-design.md captures full rationale including implicit decisions never previously documented (3-file threshold, code-extension list source, 4-doc-files acceptance set, Stop+block trade-off vs PostToolUse warn-only). Old user-level hook in ~/.claude/hooks/changelog-update.sh kept on disk as fallback but unregistered from settings.json to prevent double-fire. v0.1.1: Validator + normalize improvements after PsychQuant marketplace dogfood. Validator's 'description must start with vX.Y.Z:' rule relaxed to 'description must mention vX.Y.Z in first 400 chars' (PsychQuant convention leads with product tagline, not version prefix — 30 false-positive drifts disappear). Version header parser now accepts placeholder dates like '(date unknown — please fill in)' so init-output entries are still parsed; ISO-format check happens separately and reports placeholder as a violation user can fill in later. Normalize mode extended: now also remaps common non-KAC section names (### Changes → ### Changed, ### Migration → ### Changed, ### Bug Fixes → ### Fixed, etc.) and injects KAC preamble if missing. v0.1.0: Original changelog-tools — KAC 1.1.0 enforcement + 3-way sync (CHANGELOG.md / plugin.json / marketplace.json descriptions) + 35-plugin marketplace migration. Skills: changelog-validate (CI exit codes 0/1/2/3/4), changelog-init (bootstrap from plugin.json description with git-pickaxe date resolution), changelog-migrate (batch init across marketplace). Enforces Keep a Changelog (https://keepachangelog.com) format + three-way sync between CHANGELOG.md latest entry / plugin.json description / marketplace.json description. Skills: changelog-validate (KAC compliance + sync drift detection, exit-coded for CI), changelog-init (initialize CHANGELOG.md from plugin.json description by parsing existing vX.Y.Z: segments → KAC entries), changelog-migrate (batch one-shot mode that runs init across an entire marketplace — designed to backfill plugins that store release history in plugin.json description as a monster string). Phase 1 of two-phase rollout: Phase 2 will add changelog-add (interactive Unreleased entry creation, Composio changelog-generator integration as commit-parsing engine) + changelog-release (Unreleased → vX.Y.Z + DATE promotion with semver auto-bump from Added/Breaking/Fixed sections + 3-way description sync) + hooks integration into plugin-deploy / mcp-deploy / cli-deploy freshness check. Closes the discoverability gap where 35 of 36 PsychQuant plugins had no CHANGELOG.md and stuffed all release history into plugin.json description as run-on prose, making release history unreadable in the marketplace UI and triggering plugin-deploy's CHANGELOG-based README freshness check to silently no-op.",
       "author": {
         "name": "Che Cheng"
       },
-      "source": "./plugins/issue-driven-dev",
+      "source": "./plugins/doc-tools",
       "category": "development"
     },
     {
       "name": "che-apple-mail-mcp",
-      "version": "1.1.0",
-      "description": "Apple Mail MCP Server + \u90f5\u4ef6\u5de5\u4f5c\u6d41\uff08\u6b78\u6a94\u3001\u641c\u5c0b\u3001\u7ba1\u7406\uff09",
+      "version": "2.20.1",
+      "description": "Apple Mail MCP server — 48 tools, reply-as-draft + IDD task enforcement + NSQL confirmation + .claude/.mail/ namespace + Layer 2 post-fetch corpus refinement (shell v2.20.1, binary v2.10.0)。Shell v2.20.1 ships binary v2.10.0 — 11-issue marathon closes #126, #128, #129, #130, #131, #133, #134, #135, #137, #138, #139: new feature `from_address` for compose_email/create_draft multi-account sender (#131); `redirect_email` boundary recipient validation (#133, #41 consistency); reply/forward + mailbox-CRUD actor wiring regression-lock (#134 + #139, closes #104 PR-A/B/C/D verify DA gaps); RedirectEmailScriptBuilder escape coverage + byte-identity golden (#135); resolveMailboxRef/mailboxRefByAccountId compose resolveAccountRef (#137, #110 sibling DRY); RFC 2047/2231 attachment-filename hardening sweep across CJK + Yahoo/Outlook 16 + path-traversal vectors (#115/#122/#124/#125/#126); cross-account move/copy README limitation (#129); positional UUID/verb-anchor assertion hardening (#128/#130); Codex layer migration deferred (#138, not recurrent); test suite 475 → 482+;full 6-AI ensemble verify every PR。Shell v2.20.0 adds six opt-in corpus-refinement config fields to `/archive-mail` (`sender_includes` / `sender_excludes` / `recipient_includes` / `recipient_excludes` / `subject_includes` / `subject_excludes`) — Layer 2 post-fetch thread-coherent refinement distinct from Layer 1 search-time `filters`; case-insensitive substring with bare-value normalization; excludes-precedence on same axis; per-thread coherence; new spec `archive-mail-corpus-refinement`; closes #76 + #84。Shell v2.19.7 ships binary v2.9.0 (#99 RFC 2047 nested decode for list_attachments — Outlook 16 Chinese filenames; #101 save_attachment account_id disambiguation for multi-account-same-display_name; #104 PR-A: 5 mutation tools mark_read/flag_email/set_flag_color/set_background_color/mark_as_junk gain account_id; #106 EnvelopeIndexReader reverse-lookup cache + accountUUIDs primitive)。疊加 Shell v2.19.6 (#73): hooks/session-start.sh compare 改 prefer `.binary_version` (post-#77 schema),fallback `.version`,杜絕每次 session start spurious SIGTERM(runtime tag vs shell version 永遠 mismatch trap)。疊加 Shell v2.19.5 ships binary v2.8.5 (#16 nested markdown lists with depth-aware <ul>/<ol>, #17 markdown tables with <table>/<thead>/<tbody> + per-column alignment, #22 markdown hardening Item D code-fence language + spec docs, #26 malformed multipart throws emlxParseFailed for handler fallback, #28 crossValidateAttachments helper + 6 filter tests, #89 list_emails SQLite do/catch + AppleScript 3x IPC reduction)。疊加 v2.18.1 (#71 get_email_metadata SQLite fallback parity + cluster #61-64 attachmentFragment hardening);v2.18.0 (#76) Staleness Detection — wrapper writes runtime state file on spawn (pid/started_at/version_at_spawn);新增 hooks/session-start.sh,session 啟動時偵測 plugin.json 與 in-memory binary 版本 drift,SIGTERM(+5s grace,SIGKILL fallback)stale PID 讓 Claude Code 重 spawn 取新 binary,徹底解決「plugin update 後當下 session 仍跑舊 binary」silent staleness 問題。疊加 v2.17.0 (#49) Workspace Layout Detection;v2.16.1 ship 鏈到 binary v2.7.1 (#72 base64 fix + #69 SQLite fast-path stderr logging + #66 .partial.emlx attachment fix);v2.16.0 config schema .md → .yaml (#47);v2.15.0 inline cid: 圖片保留 (#45);v2.14.0 dedup_strategy opt-in (#18);v2.13.0 markdown template 簡化 (#17);v2.12.0 zero-arg mode (#13/#21);v2.11.0 binary v2.7.0 multi-attachment race fix (#60);v2.6.0 marathon (8 PRs);v2.9.0 task enforcement;v2.8.0 namespace;v2.7.0 NSQL confirmation。",
       "author": {
         "name": "Che Cheng"
       },
       "source": "./plugins/che-apple-mail-mcp",
+      "category": "productivity",
+      "binary_version": "2.9.0"
+    },
+    {
+      "name": "che-apple-notes-mcp",
+      "version": "0.2.1",
+      "description": "Apple Notes MCP server — 18 tools. SQLite 快讀（<10ms）+ AppleScript 寫入（CloudKit-safe），FDA fallback。Folders/notes CRUD、search、batch、undo/redo，雙軌 body（plaintext 或 HTML）。",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/che-apple-notes-mcp",
       "category": "productivity"
     },
     {
       "name": "r-shiny-debugger",
-      "version": "1.0.0",
-      "description": "\u529f\u80fd\u6e2c\u8a66\u5c0e\u5411\u7684 R Shiny App Debug \u5de5\u5177\uff0c\u6574\u5408 agent-browser \u8207 R console",
+      "version": "1.2.0",
+      "description": "功能測試導向的 R Shiny App Debug 工具，整合 agent-browser（前端）與 R console（後端）+ shiny-adaptive-walk 自我收斂測試 loop。/shiny-adaptive-walk default browser inverted to agent-browser (safari opt-in via --browser safari) since v1.2.0 (#77).",
       "author": {
         "name": "Che Cheng"
       },
@@ -61,7 +82,7 @@
     {
       "name": "che-archive-lines",
       "version": "1.0.0",
-      "description": "\u6b78\u6a94 LINE macOS \u804a\u5929\u8a18\u9304\u5230\u6587\u5b57\u6a94\uff0c\u4f7f\u7528\u5ea7\u6a19\u9ede\u64ca\u81ea\u52d5\u5316",
+      "description": "歸檔 LINE macOS 聊天記錄到文字檔，使用座標點擊自動化",
       "author": {
         "name": "Che Cheng"
       },
@@ -70,28 +91,18 @@
     },
     {
       "name": "ai-docs-guide",
-      "version": "1.3.1",
-      "description": "Auto-triggered Skills for querying Claude Code, OpenAI, Codex CLI, and Gemini official documentation via WebFetch. /ai-docs-guide for cross-platform comparison.",
+      "version": "1.4.0",
+      "description": "Auto-triggered Skills for querying Claude Code, OpenAI, Codex CLI, Gemini API, and Gemini CLI documentation. Source-code-first for CLI tools. /ai-docs-guide for cross-platform comparison.",
       "author": {
         "name": "Che Cheng"
       },
       "source": "./plugins/ai-docs-guide",
       "category": "productivity"
     },
-    {
-      "name": "claude-config-guide",
-      "version": "1.0.0",
-      "description": "[Deprecated \u2014 replaced by ai-docs-guide] Claude Code \u8a2d\u5b9a\u67e5\u8a62\u52a9\u624b",
-      "author": {
-        "name": "Che Cheng"
-      },
-      "source": "./plugins/claude-config-guide",
-      "category": "productivity"
-    },
     {
       "name": "che-things-mcp",
-      "version": "1.6.1",
-      "description": "Things 3 \u4efb\u52d9\u7ba1\u7406 MCP Server - 47 \u500b\u5de5\u5177\u652f\u63f4\u5b8c\u6574 GTD \u5de5\u4f5c\u6d41\u7a0b",
+      "version": "1.6.2",
+      "description": "Things 3 任務管理 MCP Server - 47 個工具支援完整 GTD 工作流程",
       "author": {
         "name": "Che Cheng"
       },
@@ -100,8 +111,8 @@
     },
     {
       "name": "che-ical-mcp",
-      "version": "1.3.1",
-      "description": "macOS \u884c\u4e8b\u66c6\u8207\u63d0\u9192\u4e8b\u9805 MCP Server - EventKit \u6574\u5408\uff0c24 \u500b\u5de5\u5177\uff0c\u51aa\u7b49\u5beb\u5165\u3001\u91cd\u8907\u4e8b\u4ef6\u3001\u5730\u9ede\u89f8\u767c\u3001\u7d50\u69cb\u5316\u4f4d\u7f6e\u3001\u5f48\u6027\u65e5\u671f\u89e3\u6790\u3001\u6a21\u7cca\u5339\u914d\u3001\u7be9\u9078/\u6392\u5e8f/\u9650\u5236\u3001\u4e8b\u4ef6\u63d0\u9192\u66f4\u65b0",
+      "version": "1.11.1",
+      "description": "v1.11.1 (binary): #160 create_event start<end validation, symmetric with update_event (shared validateTimeRange guard rejects inverted / zero-duration timed events; all-day exempt). v1.10.0 (binary): #122 TCC drift detector + startup banner. Single-shot stderr banner at MCP-server-mode startup with version/path/pid + drift signals (TCC.db path mismatch per-service + stale running processes). R3.3 production fix: parent pipe write-end fd close in TCCDatabaseSource/ProcessInventorySource (POSIX hygiene completing R1). #131 CI: 8 tests compile-time excluded via -DCI_BUILD (EventKit blocks on TCC prompt in GHA macos-15 sandbox). 338 local / 330 CI tests. v1.9.1 (shell): exposes v1.9.0 TCC features via 4 new plugin shell additions — (1) troubleshoot-tcc skill: 5-step diagnostic walkthrough wrapping --print-tcc-path; (2) /check-tcc slash command: quick state read; (3) eventkit-error-debugging rule: routes Claude to TCC-first investigation on accessDenied/insufficientAccess/unknownAuthState before assuming code bugs; (4) CLAUDE.md plugin overview. Binary unchanged at v1.9.0. v1.9.0 (binary): #108 Phase 2 + closes #109 — EventKit TCC access gate refactor. Removes process-lifetime hasCalendarAccess/hasReminderAccess cache anti-pattern in EventKitManager; replaces with per-call EKEventStore.authorizationStatus(for:) cheap check via new AuthorizationGate + AuthorizationStatusSource test seam protocol. Aligns with Apple TN3153 documented per-call pattern — TCC state changes surface immediately as actionable accessDenied/insufficientAccess/unknownAuthState errors instead of silent fail. Bundles #109 --print-tcc-path diagnostic flag. 311/311 tests pass. MCP tool surface unchanged. v1.8.1: Phase 1 of #108 — mcpb/README.md post-install / upgrade TCC permission setup guide. v1.8.0: Wire-format consistency wave (#101 cluster). macOS 行事曆與提醒事項 MCP Server - EventKit 整合，29 個工具，支援 attendees/organizer、undo/redo、每事件時區、--cli 模式、--setup TCC 授權、--self-update 自我升級+SHA-256 驗證、cleanup_completed_reminders 一鍵清除、彈性日期解析、模糊匹配、batch 操作",
       "author": {
         "name": "Che Cheng"
       },
@@ -110,8 +121,8 @@
     },
     {
       "name": "che-duckdb-mcp",
-      "version": "1.1.0",
-      "description": "DuckDB MCP Server - \u6574\u5408\u6587\u6a94\u67e5\u8a62\u8207\u8cc7\u6599\u5eab\u64cd\u4f5c\uff0c14 \u500b\u5de5\u5177\uff08DuckDB v1.5.0-dev engine\uff09",
+      "version": "2.3.0",
+      "description": "Swift-native DuckDB MCP + guidance Skill — dual-source docs (llms.txt + full) with TF-IDF search + fuzzy function matching, plus 6 local DB tools (14 total). Pinned duckdb-swift, real DuckDB error messages, SessionStart hook for version check.",
       "author": {
         "name": "Che Cheng"
       },
@@ -120,8 +131,8 @@
     },
     {
       "name": "che-word-mcp",
-      "version": "1.17.0",
-      "description": "Word MCP Server - Swift \u539f\u751f OOXML \u64cd\u4f5c\uff0c148 \u500b\u5de5\u5177\uff0c\u652f\u63f4 Dual-Mode + Session \u72c0\u614b\u7ba1\u7406\uff08dirty tracking, autosave, finalize\uff09",
+      "version": "3.20.0",
+      "description": "v3.20.0 cross-document OMath splice MCP tools (#160) — splice_omath_from_source + splice_paragraph_omath_from_source wrap ooxml-swift v0.24.0's spliceOMath API for verbatim copy of <m:oMath> XML blocks between WordDocument paragraphs. Source via source_path (Direct mode read-only) or source_doc_id (Session mode); target requires session-mode doc_id. Position via atStart/atEnd/afterText/beforeText with optional anchor + instance. Carrier preservation (Run.rawXML stays inline, unrecognizedChildren stays direct-child); joint document-order index for omath_index across both source carriers. rpr_mode controls source Run rPr propagation (full default verbatim / omathOnly whitelist / discard empty); namespace_policy controls prefix vs URI handling (lenient default accepts mml: vs m: prefix mismatch with same URI per ECMA-376 / strict throws on any mismatch). Error taxonomy returned as structured strings: sourceHasNoOMath / omathIndexOutOfRange / targetParagraphOutOfRange / anchorNotFound / namespaceMismatch / contextAnchorNotFound (batch only). Unblocks kiki830621/collaboration_guo_analysis Phase 7 inline-math restoration pipeline. Tests: 8 new Issue160SpliceOMathFromSourceTests (Direct/Session source modes, atEnd/afterText positions, error taxonomy, batch mode, rPr discard). Full suite: 297 passing, 0 failures, 9 pre-existing skips. Bumps ooxml-swift dep 0.21.0 → 0.24.0. v3.19.0 caption detection (#136) + estimate_paragraph_for_page structural weights v2 (#142). #136: two-layer detection — Paragraph.style primary + expanded prefix set (English Tab./Fig./Listing + CJK 表3/圖1 no-separator + U+3000 ideographic space) with digit-after-prefix guard rejecting body sentences like \"Table reservations are required...\". 17 new tests. #142: walker upgrade getParagraphs → collectStructuralBlocks enum (.paragraph/.table/.imageOnlyParagraph/.displayEquationParagraph). Per-block weights (12pt thesis calibration): table = tableRows × avgCellChars (200/row fallback), image = +200/drawing, display eq = 120 chars. New structural_breakdown metadata (9 sub-fields). API method bumped char_count_heuristic → char_count_heuristic_v2. ~95× thesis figure-counting accuracy improvement. paragraph_index semantics + getParagraphs() preserved (30+ other callers unaffected). Tests: 6 new + #89 backward-compat passes (text-only fixtures unchanged, just method literal updated). 1 P3 follow-up filed (#159 display-eq fixture limitation). v3.18.1 transitive dependency bump — ooxml-swift v0.21.11 → v0.22.1. Closes PsychQuant/che-word-mcp#155 (parent / mirror) auto-resolves via Package.resolved bump alone (no MCP source change). Pre-fix: che-word-mcp__search_text MCP tool's Server.swift:10310 calls para.getText(), which was a legacy 7-line implementation that only joined runs.map { $0.text } + hyperlink.text — missed every walker enhancement landed in flattenedDisplayText() over the #85 / #92 / #99 / #100 / #101 / #102 / #103 cluster. Callers couldn't grep for inline math symbols (α / β / γ / θ / λ / t) — silent zero gaps in match positions. Post-fix: ooxml-swift#43 collapsed Paragraph.getText() to single-line return flattenedDisplayText(); two text-extraction paths now return identical strings. Server.swift:10310 still calls para.getText() but that method now traverses inline OMML correctly. Position arithmetic now matches before_text / after_text anchor-matching paths. Downstream impact: kiki830621/collaboration_guo_analysis#6 (thesis 30 inline math symbols) unblocked from automation — re-running search_text 進行t檢定 against 碩士論文.docx para 324 now returns a match. Released via /idd-all #43 --cwd cross-repo IDD orchestration (issue-driven-dev v2.40.0). Closing summary at https://github.com/PsychQuant/ooxml-swift/issues/43#issuecomment-4365430488. v3.18.0 insert_equation argument-contract hardening (closes #105 #106 #107). v3.17.8 closes PsychQuant/che-word-mcp#98 — insert_equation MCP handler refactored across 3 commits (91506f8/357cbe7/339ab77). Pre-fix three structural defects: (1) silent-clamp on out-of-range paragraph_index via non-throwing insertParagraph(_:at: Int) — tool reported success but inserted at wrong location; (2) lib's #84/#91 InsertLocation overload + InsertLocationError.inlineModeRequiresParagraphIndex / .invalidParagraphIndex(Int) structured errors never reached MCP callers (handler self-built OMML and bypassed lib); (3) inline mode (display_mode=false) always created a NEW Paragraph(runs: [eqRun]) instead of appending OMML run to the EXISTING paragraph at paragraph_index. v1 (91506f8) tried delegating to lib but Codex 6-AI verify caught P1 regression: lib's Document.insertEquation overload internally uses @available(*, deprecated, ...) MathEquation flat output (Field.swift:301) — emits truncated '(a)/(b' AND nested <w:p><w:p> invalid OOXML. v2 (357cbe7) unified handler — both latex AND components paths use MathComponent.toOMML() for structurally correct OMML; display mode routes through lib's throwing insertParagraph(_:at: InsertLocation); inline mode handler-side appends OMML run to existing paragraph. v3 (339ab77) restored eqPara.properties.alignment = .center for display mode. BREAKING for inline mode callers: pre-fix inserted NEW paragraph; post-fix appends OMML run to EXISTING paragraph at paragraph_index. Migration: use display_mode=true for 'new paragraph with equation' or call insert_paragraph + insert_equation separately. 7 NEW Issue98InsertEquationLibBypassTests pin contracts (5 RED→GREEN scenarios + 2 quality regression tests including unzip -p document.xml verifying <m:f> structure + centering survives + deprecated '(a)/(b)' pattern absent). 6-AI verify ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) caught both P1 regressions in v1; Codex sanity check on v2 caught the centering P2. 6 P2/P3 follow-up issues filed (#105-#110). Suite: 236 → 243 tests, 0 failures, 9 pre-existing skips. Backward compatible except inline-mode BREAKING (documented). v3.17.7 ooxml-swift dep bump 0.21.10 → 0.21.11 — closes 5-issue cluster PsychQuant/che-word-mcp #99 + #100 + #101 + #102 + #103. Bilateral mirror coverage for direct-child OMML at 4 wrapper positions (<w:p> direct child for Pandoc display math / <w:hyperlink> direct child / <mc:Fallback> direct child / nested wrapper combos), plus 2 NEW library-wide spec capabilities. Pre-fix Paragraph.flattenedDisplayText AND Document.replaceInParagraphSurfaces shared a symmetric blind spot: direct-child <m:oMath>/<m:oMathPara> (not wrapped in <w:r>) was silently dropped → anchor lookups against paragraphs containing display math silently 0-matched. Spectra change flatten-replace-omml-bilateral-coverage. 2 NEW spec capabilities promoted to openspec/specs/: ooxml-paragraph-text-mirror (mirror invariant + ReplaceResult informative refusal contract) + ooxml-library-design-principles (Correctness primacy + Human-like operations as foundational normative invariants for all ooxml-swift mutators). Read side: flattenedDisplayText walks direct-child OMML at all 4 wrapper positions with source-XML position ordering. Write side: NEW public API WordDocument.replaceTextWithBoundaryDetection returns ReplaceResult enum (.replaced(count:) / .refusedDueToOMMLBoundary(occurrences:) / .mixed(replacedCount:, refusedOccurrences:)) with Occurrence(matchSpan:, ommlSpans:) carrying flattened-text coordinates. Mirror invariant — asymmetric by design: reads include OMML visibleText (anchor lookup universe extends to math); writes treat OMML as opaque structural units (refuse cross-OMML mutation rather than silently delete equations). Decision 4 raw passthrough preserved: direct-child OMML stays in Paragraph.unrecognizedChildren / HyperlinkChild.rawXML(_) / AlternateContent.rawXML — no parser change, no writer change, round-trip fidelity unaffected. MCP impact: replace_text and other anchor-lookup tools now find paragraphs containing direct-child OMML at all 4 wrapper positions; existing replace_text MCP tool unchanged (backward-compatible). Tests: 236 passing che-word-mcp / 813→829 ooxml-swift (+16 in Issue99FlattenReplaceOMMLBilateralTests). Backward compatible — strict superset of pre-fix behavior. v3.17.6 ooxml-swift dep bump 0.21.9 → 0.21.10 — closes PsychQuant/che-word-mcp#104. Form-level FieldParser canonical 5-run fldChar fix (orthogonal to v3.17.5's #94 container-level fix). Pre-fix update_all_fields returned silent no-op ('no SEQ fields found') on docs containing valid SEQ paragraphs at body top level when fldChar block was emitted in canonical 5-run form (each <w:fldChar>/<w:instrText>/<w:t> in its own <w:r> sibling — what DocxReader produces post-roundtrip and what native Word always emits). Pre-fix worked only on in-memory wrap_caption_seq output before save. Two ooxml-swift commits land via this dep bump: 537de62 FieldParser two-phase parse (Phase-1 baked form + Phase-2 parseFiveRunSpan state machine probing both Run.rawXML and Run.rawElements per recognizedRunChildren = ['rPr','t','drawing','oMath','oMathPara'] allowlist) + 58fe4f9 P1 sub-fix surfaced by 6-AI verify (Logic + Devil's Advocate runtime test): canonical-branch Run.text rewrite was silently overridden by Run.toXML() rawXML short-circuit; new rewriteCanonicalCachedText helper splices new value into embedded <w:t> while preserving <w:rPr> + xml:space=preserve, AND keeps Run.text in sync. MCP impact: update_all_fields now finds and updates SEQ fields in canonical 5-run form (post-roundtrip / native Word emission); list_captions benefits transitively via shared FieldParser. Verified by 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) — 4 PASS / 2 WARN / 0 BLOCK; production reproducer rescue-swift-v317.docx via DocxReader path confirmed working. 5 P3 follow-ups filed in ooxml-swift (#29 SEQ Table coverage / #30 multi-paragraph counter / #31 multi-SEQ same paragraph / #32 DoS hardening / #33 discriminator invariant). Tests: 236 passing che-word-mcp / 809→813 ooxml-swift (+4 sub-tests in Issue104FieldParserCanonicalFormTests). Backward compatible — strict superset of pre-fix behavior. v3.17.5 ooxml-swift dep bump 0.21.8 → 0.21.9 — triple #87 + #93 + #94 release. #87 (Comment.paragraphIndex flat-counter, observable behavior change): list_comments paragraph_index now consistently 0-indexed against get_paragraphs() flat list; pre-fix off-by-N for any docx with non-paragraph BodyChild siblings before commented paragraph; callers manually compensating with paragraph_index - 1 must remove compensation. #93 (wrap_caption_seq SEQ inherits source position, caption visual fix): pre-fix 「圖 4-1：xxx」 became 「圖 4-：xxx1」 because new SEQ run had position=nil while source-loaded preText/postText had position>0; one-line fix seqRun.position = preRun.position; insert_bookmark=true × source-loaded paragraph still has same gap (filed PsychQuant/ooxml-swift#24, default insert_bookmark=false unaffected). #94 (update_all_fields traverses .table and .contentControl containers): pre-fix body loop only processed top-level .paragraph BodyChild, silently skipped .table and .contentControl(_, children:) — SEQ fields inside table cells/block-level SDTs never updated, returning 'no SEQ fields found' for thesis docs (caption paragraphs commonly live inside the table they describe); same gap #68 closed for findBodyChildContainingText; new walkAndProcessBodyChildForFields recursive walker mirrors #68 pattern; heading-count semantics: only top-level direct .paragraph body children count toward chapter-reset. Known incompleteness (3 follow-ups filed): ooxml-swift#25 header/footer/footnote/endnote SEQ scans still flat .paragraphs view; ooxml-swift#26 FieldParser.parse(paragraph:) misses inline SDT/hyperlink/fieldSimple/alternateContent surfaces; ooxml-swift#27 verify-with-user-fixture for real thesis docx roundtrip; plus ooxml-swift#28 refactor candidate (extract BodyChildVisitor protocol). Verified by 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh). Tests: 236 passing che-word-mcp / 805→809 ooxml-swift. Backward compatible except #87 documented behavior change. v3.17.4 paired #91 + #92 release. v3.17.3 bump ooxml-swift dep 0.21.6 → 0.21.7 (pure transitive bump, no MCP source changes; exposes public anchor lookup API). Three WordDocument APIs upgraded private → public (PsychQuant/che-word-mcp#86): findBodyChildContainingText(_:nthInstance:) instance method + bodyChildContainsText(_:needle:) static + tableContainsText(_:needle:) static. External Swift SPM consumers (rescue scripts, dxedit CLI, third-party tooling) can now call canonical anchor-lookup logic directly instead of reimplementing with diverging semantics (some skipped .contentControl recursion, some skipped table cell traversal pre-#68, some used different nthInstance counting rules). Result is exactly what insert_paragraph / insert_image_from_path / insert_caption etc. tools see when resolving after_text / before_text anchors. 10 new public-API surface tests in Issue86PublicAnchorLookupTests pin the canonical behavior across releases. Backward compatible: pure additive private → public visibility change; no API removals, no behavioral changes for existing callers. v3.17.2 bump ooxml-swift dep 0.21.2 → 0.21.6 (pure transitive bump, no MCP source changes; 4 ooxml-swift releases worth of hardening + new APIs land transparently). v0.21.3 (XML hardening, PsychQuant/ooxml-swift#7): DTD reject + 64KB attr-value cap + SAX-based root-element attribute parsing + name whitelist on emit. New XMLHardeningError throws on malicious .docx input. v0.21.4 (roundtrip loud-fail, PsychQuant/ooxml-swift#6): AlternateContent.fallbackRunsModified dirty flag throws RoundtripError.unserializedFallbackEdit on stale fallbackRuns mutation. Run.commentIds @available deprecated; migrate to commentRangeMarkers. v0.21.5 (insertEquation flexibility, PsychQuant/che-word-mcp#84 #85): InsertLocation overload for Document.insertEquation + flattenedDisplayText OMML coverage extends anchor lookup beyond plain runs. v0.21.6 (mutation surface, PsychQuant/ooxml-swift#5): Hyperlink.text setter @available deprecated (lossy); migrate to .runs property. Position field cascade Int = 0 → Int? = nil across 13 typed-child models. xml:space=preserve autosense in Run.toXMLThrowing emit. Plus 3 unreleased docs commits on ooxml-swift main (PsychQuant/ooxml-swift#14 #15 #17 + corrective cd841e7) covering needsPPr emit-gate ↔ Issue4 lock-in test bidirectional reference, parseRun vs parseParagraph walker pattern divergence rationale, foreign-namespace pPr asymmetry documentation. Tests: 236 passing (no regressions). Backward compatible: deprecation warnings only; no API removals. v3.17.1 bump ooxml-swift dep to v0.21.2 — pulls in pPr regression-guard + test infrastructure hardening from upstream (ooxml-swift#4 walker whitelist + #if DEBUG assert / ooxml-swift#13 empty <w:pPr/> self-closing test gap / ooxml-swift#16 countPPrOpenTags regex hardening excluding <w:pPrChange>). No public MCP tool change. v3.17.0 wrap_caption_seq MCP tool (Refs #62): Phase 2 of cross-repo work — exposes ooxml-swift v0.21.0 lib API as MCP tool. Bulk-wraps plain-text caption number portions in SEQ field runs across body paragraphs whose flattened text matches a regex (EXACTLY ONE numeric capture group). Captured digit becomes SEQ field cachedResult so Word's first-open render preserves user-typed numbering before F9. Rescues docs pasted from external sources (LaTeX-converted Word, Google Docs, Pandoc) so insert_table_of_figures / insert_table_of_tables produce populated TOFs. Idempotent: paragraphs already wrapping a SEQ field for sequence_name reported in skipped, never double-wrapped (detection covers both FieldSimple AND rawXML fldChar emissions). Phase 1 ships scope:body only (recurses into table cells + nestedTables + block-level SDT children); scope:all returns Error: scope_not_implemented for now (cross-container path lands in v3.17.x). Bookmark wrap opt-in (insert_bookmark + bookmark_template with literal ${number}) so default 23-caption rescue does NOT pollute list_bookmarks. Returns JSON: {matched_paragraphs, fields_inserted, paragraphs_modified:[idx,...], skipped:[{paragraph_index, reason},...]}. All preconditions checked BEFORE document mutation (regex compile + capture-group count + format/scope enums + bookmark_template invariant + doc_id opened). Tests: 5 new sub-tests in Issue62WrapCaptionSeqTests covering Scenarios 1-5. Suite 231 → 236 (+5, 0 fail / 9 skip). No ooxml-swift dep bump (still v0.21.0 from v3.16.2). v3.16.2 ooxml-swift dep bump 0.20.5 → 0.21.0 (Refs #62 #68): pure dep bump, no MCP source changes. Picks up two ooxml-swift fixes that surface transparently via existing tool dispatch. #68 (ooxml-swift v0.20.6): InsertLocation.findBodyChildContainingText now traverses .table (rows × cells × paragraphs + nestedTables) and .contentControl(_, children:) (recursive). MCP impact — insert_paragraph / insert_image_from_path / insert_equation / insert_caption calls using before_text / after_text now succeed when anchor text lives inside a table cell or block-level SDT (common in thesis docs with figure/table captions inside table cells). Returned position is top-level body.children index of the containing structure. Use into_table_cell for inside-cell inserts. Empty-needle guard: passing before_text:'' / after_text:'' now returns textNotFound instead of silently inserting at index 1. #62 (ooxml-swift v0.21.0): WordDocument.wrapCaptionSequenceFields(...) is now linked into the binary. Not yet exposed as an MCP tool — the wrap_caption_seq MCP wrapper ships in v3.17.0 (Phase 2 of the cross-repo work). Existing MCP tools unaffected. Suite: 231 → 231 (0 fail / 9 skip). v3.16.1 anchorPresence whitelist drift prevention (Refs #80): pure refactor, no runtime behavior change. New static toolAnchorWhitelists dict (single source of truth, keyed by MCP tool name → accepted anchor list) + new detectPresentAnchors(_:tool:) overload. 4 conflict-detection call sites switched from literal anchor arrays to (tool:) lookup. 4 new invariant/parity tests. Suite 227 → 231 (+4). Old (args, anchors:) overload preserved. Out-of-scope follow-ups: schema descriptions + dispatcher if-else chains still hardcode anchor names (pre-existing surfaces, not introduced by this PR). v3.16.0 Bundle B anchor DX consistency (Refs #70 #71 #72): BREAKING (input validation only) — three coordinated MCP-layer changes across the 4 #61-target tools. #71 (behavior) silent priority on conflicting anchors → structured error: insert_paragraph(after_text + index) was previously silent-priority; now returns 'Error: insert_paragraph: received conflicting anchors: after_text + index. Specify exactly one.' New static helper detectPresentAnchors with per-anchor type-aware predicates (null and wrong-type values do NOT count). #72 (validation) explicit text_instance ≤ 0 rejected — 'Error: <tool>: text_instance must be ≥ 1, got <N>.' Omitted text_instance still defaults to 1. #70 (DX) all 32 'return Error:' lines in 4 #61-target tools rewritten as 'Error: <tool>: <body>' for AI-caller error attribution. throw WordError.* paths unchanged. Scope deliberately limited to 4 tools; remaining 41 return Error lines elsewhere deferred to error-prefix-sweep follow-up. SemVer rationale (minor not major): no schema break, no tool removal, restricting previously-undefined behavior. Tests: 201 → 227 (+26 sub-tests, 0 fail / 9 skip). No ooxml-swift dep bump (still v0.20.5). v3.15.3 Bundle A2 polish from v3.15.2 verify R3-R6 follow-ups (Refs #76 #77 #78 #79): #76 (docs) insert_caption description corrected from '三種 anchor' to enumerate all 5 (paragraph_index / after_image_id / after_table_index / after_text / before_text); insert_equation paragraph_index description clarified that the int is body.children-indexed (cross-references PsychQuant/ooxml-swift#10 for the lib-layer convention split). #77 (docs) insert_caption anchor set wording precision in CHANGELOG / manifest / marketplace.json / plugin.json — was 'its own anchor set including after_table_index' (implies disjoint), now 'shares after_image_id / after_text / before_text / paragraph_index, adds after_table_index + position, lacks into_table_cell' (explicit shared/adds/lacks). #78 (test) extends #69 append-index regression pin to bookmarkMarker / rawBlockElement / block-level contentControl body-children — the table case alone wouldn't catch a regression to getParagraphs().count - 1 that breaks for SDT / TOC bookmark / vendor extensions. #79 (test) adds round-trip depth: testInsertParagraphAppendIndexRoundTripsForInsertCalls demonstrates insert-family round-trip works (append + insert(N+1) + verify ordering); testInsertParagraphAppendIndexCannotRoundTripToUpdate pins the cross-family trade-off (update_paragraph(index=N) throws WordError.invalidIndex). Tests: 196 → 201 (+5 sub-tests, 0 fail / 9 skip). No production code change. No ooxml-swift dep bump (still v0.20.5). v3.15.2 closes Bundle A polish from #61 R2 verify (Refs #69 #73 #74 #75): #69 (bug) insert_paragraph append message reports body.children index instead of getParagraphs().count - 1 (mis-reported in docs with tables/SDTs by skipping table children); #74 (bug) insert_image_from_path debug log labels after_image_id correctly (was silently labeled 'index' since v3.15.1); #73 (test) regression pin for equation F5 partial-dict guard (existed since v3.15.1 but was untested); #75 (docs) clarifies '3 insert tools' wording — scope is the 3 #61-target tools (insert_paragraph / insert_equation / insert_image_from_path); insert_caption is a 4th insert tool with a partially-overlapping anchor set (shares after_image_id / after_text / before_text / paragraph_index, adds after_table_index + position, lacks into_table_cell), intentionally outside this unification scope. Tests: 194 → 196 (0 fail / 9 skip). No behavior change in normal call paths. No ooxml-swift dep bump (still v0.20.5). Word MCP Server - Swift 原生 OOXML 操作，233 個工具。v3.15.1 closes verify findings F1+F2+F3+F5 from v3.15.0 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh)：F1 (P1) `after_image_id` anchor 加到 insert_paragraph + insert_equation (display only) + insert_image_from_path — lib InsertLocation.afterImageId 從 #44 起就 ready 但只有 insert_caption 暴露 MCP-layer；v3.15.0 inherited 這個 gap，本 release 補齊。F2 (P1) `into_table_cell` 加到 insert_equation (display only) — display equation 是新建 paragraph，cell 放置 well-defined；inline mode 拒絕。F3 (P2) equation 成功訊息加 anchor info（'Inserted equation (display mode: true, after text X (instance N))' 等）— 關閉同 v3.14.4 LOOKUP 的 over-claim 模式（caller 之前無法區分 anchor 命中 vs append fallthrough）。F5 (P2) malformed `into_table_cell` partial dict（傳 `{table_index: 0}` 缺 row + col）silent fallthrough → 走 next anchor / append → 結果在錯位置且 caller 不知。改回 structured 'Error: into_table_cell requires all three fields'，3 #61-target tools 同步修（cross-cutting consistency）。Anchor priority unified across all 3 #61-target insert tools (`insert_paragraph` / `insert_equation` / `insert_image_from_path`; `insert_caption` has its own anchor set)：into_table_cell > after_image_id > after_text > before_text > index > append。Inline equation 拒絕擴大 — 現在拒絕所有 4 個 anchor params（before/after_text + after_image_id + into_table_cell），不只 v3.15.0 的 2 個。Tests: Issue61V315PointReleaseTests (9 sub-tests cross 3 tools)。Suite 185 → 194 (0 fail / 9 pre-existing skips)。**No ooxml-swift dep bump** — 仍 v0.20.5（lib 從 #44 起就 ready）。Follow-up issues 另開：F4 inline equation 更通用設計 (e.g. into_paragraph_with_text) / F6 text anchor 擴及 table-cell paragraphs 與 block-level SDT / F7 getParagraphs().count - 1 message 在 doc 含 tables/SDTs 時 mis-report (pre-existing) / F8 error message 加 tool-prefix / F9 multiple anchor params 同時傳入 silent priority winner / F10 text_instance≤0 normalize。Backward compatible — schema additions optional，既有 v3.15.0 callers 不變；只有 malformed into_table_cell 從 silent fallthrough 改成 structured error（會被 buggy caller 注意到）+ equation message 加 suffix（substring 'Inserted equation' 仍存在）。v3.15.0 closes #61 — insert_paragraph 與 insert_equation 現在接受跟 insert_image_from_path 一致的 anchor 參數（after_text / before_text / text_instance / into_table_cell — into_table_cell 僅 insert_paragraph）。Pre-fix MCP 層 silently drop 這些參數 — JSON schema 接受但 handler dispatch 忽略，呼叫 fall through 到 legacy paragraph_index path 或 append at end。Lib API Document.insertParagraph(_: at: InsertLocation) 從 #44 起就支援所有六種 anchor cases（paragraphIndex / afterImageId / afterTableIndex / intoTableCell / afterText / beforeText），本 release 補齊 MCP 側 wire-up gap，無需 ooxml-swift dep bump（v0.20.5 已足夠）。Anchor priority mirror insert_image_from_path：into_table_cell > after_text > before_text > index > append。Errors（textNotFound / tableIndexOutOfRange / tableCellOutOfRange）回 structured 訊息而非 silent fallthrough — AI caller 能 surface failure 而非拿到位置錯誤的 misleading 'success'。**Inline equation explicit rejection**：insert_equation 在 display_mode=false（inline）時 explicitly 拒絕 after_text / before_text，回 structured error — 語意模糊（'append OMML run into existing para containing this text' vs 'insert new para before/after target para'），inline placement 仍用 paragraph_index。Display-mode equation 建新 paragraph，anchor 語意明確。Tests: Issue61InsertParagraphAnchorsSmokeTests（5 sub-tests：after_text resolution / before_text resolution / text_instance disambiguation / into_table_cell append / textNotFound error）+ Issue61InsertEquationAnchorsSmokeTests（4 sub-tests：after_text + before_text in display mode / inline mode rejection / textNotFound error）。Suite 176 → 185 (0 fail / 9 pre-existing skips)。**No ooxml-swift dep bump** — v0.20.5 已有所有需要的 lib API。Backward compatible — anchor params 全 optional；既有 index / paragraph_index callers 不變；無 schema removal、無既有行為改動。**Real-world impact**：thesis-rescue / template-population workflow 不再需要 fall back 到「append at end + 手動 cut/paste in Word UI」或 binary-search 猜 paragraph_index，AI caller 對 3 #61-target insert tools（insert_image_from_path / insert_paragraph / insert_equation）對稱地用 surrounding context 定位 anchor。v3.14.5 closes Refs #63 verify F1 P1：擴充 findBodyChildContainingText 涵蓋所有 editable surfaces，補上 v3.14.4 CHANGELOG over-claim 的 insert anchor lookup gap。Pre-fix v3.14.4 只修了 REPLACE path（replace_text → Document.replaceInParagraphSurfaces 走 contentControls / hyperlinks / fieldSimples / alternateContents）但 LOOKUP path（findBodyChildContainingText 用於 InsertLocation.afterText / .beforeText 解析）只看 para.runs，所以 insert_image_from_path / insert_paragraph / insert_caption before_text/after_text 對 SDT-wrapped anchor 仍丟 textNotFound。Verify ensemble（5 Claude reviewers + Codex）的 requirements F1 P1 finding 抓到 CHANGELOG over-claim — 用戶選擇 Option B 擴充修而非縮 scope。ooxml-swift v0.20.5 新增 TextReplacementEngine.flatTextOfContentXML（read-only XML walker mirror replaceInContentXML flattening rules，跳過 <w:delText> / <w:instrText> / nested <w:sdt> subtrees）+ Paragraph.flattenedDisplayText 擴充 method 涵蓋 runs + hyperlinks + fieldSimples + alternateContents + contentControls（recursive into nested SDT children）。findBodyChildContainingText 改用 flattenedDisplayText 取代原本的 para.runs.map { $0.text }.joined()。新增 Issue63InsertAnchorInlineSDTTests（lib，3 wrappers × afterText/beforeText/insertImage = 3 sub-tests / 5 assertions）+ Issue63InsertAnchorInlineSDTSmokeTests（MCP，2 sub-tests pin lib-layer fix）。Suite 693 → 696 ooxml-swift / 174 → 176 che-word-mcp（0 fail）。基於 ooxml-swift v0.20.5。Backward compatible — strict superset of pre-fix lookup behavior（找到更多 anchors，既有 plain runs anchor 仍照常運作）。**Insert anchor lookup gap 此 release 完整補齊**，所有 inline wrappers 在 REPLACE + LOOKUP 兩個 path 都對稱覆蓋。v3.14.4 修 replace_text 對 inline `<w:sdt>` content control 的 wrapper coverage gap（Refs #63）：Document.replaceInParagraphSurfaces 之前覆蓋 paragraph.runs / hyperlinks / fieldSimples / alternateContents 但 **沒有** paragraph.contentControls — 包在 inline `<w:sdt>` 裡的文字 silently 0-match。外部 converter（pandoc / Quarto / LaTeX→docx）習慣把 cross-ref placeholder（[tab:foo] / [fig:bar] / [Smith 2020]）包成 inline SDT，所以症狀跟 bracketed text 高度相關，但其實 **brackets 是 coincidence** — bracket-free needle 在 inline SDT 裡也 fail。Issue title「literal `[ ]` brackets」是誤導，差別測試（fldChar / fldSimple / hyperlink / inlineSDT 四個 inline wrapper × 四種 needle）證實只有 inline SDT case 失敗，其他三個 wrapper 從 v0.19.0+ #56 Phase 5 起就 typed-runs 覆蓋好了。Surgical fix architecture：ooxml-swift v0.20.4 新增 TextReplacementEngine.replaceInContentXML（XML DOM walker，wrap ContentControl.content 在 synthetic root xmlns:w，遍歷所有 `<w:t>` descendants 在 document order，build flat string + offset map mirror flattenRuns invariant，run same literal/regex find logic，splice replacements 回 `<w:t>` element string content；re-serialize wrapper children 去掉 wrapper tag）+ Document.replaceInContentControl（recursive helper 涵蓋 cc.content + cc.children 處理 nested SDT）。Wired 進 Document.replaceInParagraphSurfaces 接在 alternateContents loop 之後。設計上跳過：`<w:delText>`（TC deletion text，不顯示）、`<w:instrText>`（field instruction code，不顯示）、nested `<w:sdt>` subtrees（typed cc.children 由外層 recursion 處理避免 double-replacement）。Round-trip discipline：只 mutate `<w:t>` element 的 string content；xml:space=\"preserve\" 與其他 attribute 完整保留（attribute set 從不被 touch）。新增 Issue63InlineSDTReplaceTests（4 個 wrapper × 4 個 needle 的 differential test + nested SDT recursion + round-trip wrapper preservation = 3 sub-tests / 18 assertions）+ MCP-layer Issue63ReplaceTextInlineSDTSmokeTests（2 sub-tests pin lib-layer fix）。Suite 690 → 693 ooxml-swift / 172 → 174 che-word-mcp（0 fail）。基於 ooxml-swift v0.20.4。Backward compatible — surgical fix 只新增 code path，沒改任何既有行為（runs/hyperlinks/fieldSimples/alternateContents replacement path 不動，ContentControl model 維持 raw XML storage 不重構）。Out-of-scope（separate follow-up）：ContentControl 從 content:String 升級為 typed Run 列表（SDD-warranted refactor）；smartTags / bidiOverrides / customXmlBlocks / unrecognizedChildren 維持 raw-carrier passthrough。v3.14.3 sub-stack E of paragraph-level content-equality (closes #66)：Paragraph 新增 w14ParaId / w14TextId 欄位，提取並 round-trip <w:p> opening tag 上的 w14:* 屬性（Word 用於 collaborative editing 和 comment threading 的 revision-tracking GUIDs）。Plain attribute passthrough，String? typing — Word 的 GUIDs 是 8-char hex tokens（NOT RFC 4122 UUIDs），所以 opaque-string round-trip 是正確選擇。Pre-fix v3.14.2 silently dropped 兩個 attributes — 佔了 NTPU 論文 fixture w14:* token loss 的 ~95%（2214 / 2359 lost tokens 是這兩個 attrs）。Post-E 量測：w14: 保留率 10.55% → 93.98%；document.xml 流失 10.95% → 8.02%。Combined with sub-stack D (#65), total impact since v3.14.1：<w:lang> 50% → 98.89% (D)、w14:* 5% → 93.98% (E)、document.xml 流失 16.66% → 8.02% (D+E, -8.64 pp)。Matrix-pin testDocumentContentEqualityInvariant 同步抬升 floor（w14: 0.04→0.90、sizeLossRatio 上限 0.12→0.10）— matrix-pin 現在 LOAD-BEARING across **5 preservation classes**（rFonts/noProof/lang/kern/w14:）spanning run-level + paragraph-level + paragraph-mark scope。Defensive design (R2 review fixes)：openingPTag() routes attributes through escapeXMLAttribute；parseParagraph rejects schema-invalid empty-string GUIDs。基於 ooxml-swift v0.20.3。Backward compatible（兩個 fields 都 optional、default nil；openingPTag empty-attrs gate 防止 synthetic emit）。剩餘 8% 流失主要是其他 w14:* attribute classes（如 w14:* on <w:r>）— tracked as separate follow-up SDD。v3.14.2 sub-stack D of paragraph-level content-equality (closes #65)：ParagraphProperties 新增 markRunProperties 欄位，提取並 round-trip <w:rPr> direct child of <w:pPr> — paragraph-mark formatting per ECMA-376 §17.3.1.27 CT_PPrBase（控制 pilcrow ¶ 字符外觀的字型/顏色/語言/字距）。Reuses parseRunProperties verbatim — schema 跟 run-level CT_RPr 一致，所以 sub-stack C 的 typed extraction（rFonts 4-axis / noProof / kern / lang 3-axis）和 rawChildren passthrough（w14:* 效果）全部免費繼承。NTPU 論文 fixture 量測影響：<w:lang> 保留率 50% → 98.89%；<w:rFonts> 88% → 98.77%；<w:noProof> 92% → 100%；<w:kern> 84% → 99.93%；document.xml 大小流失 16.66% → 10.95%。Matrix-pin testDocumentContentEqualityInvariant 同步抬升 floor（lang 0.45→0.95、rFonts/noProof/kern 0.95、sizeLossRatio 上限 0.175→0.12）。Sub-stack E (#66 w14:paraId/textId) 接著 ship 到 v3.14.3，把流失壓到 < 5%，達成「edit 一個字 → document.xml shrinks <1%」strong demo。基於 ooxml-swift v0.20.2。Backward compatible（markRunProperties optional、default nil、writer empty-gate 防止 synthetic empty <w:rPr/>）。v3.14.1 sub-stack C-CONT closes triple-confirmed P0 (R2 + R5 + Codex 6-AI verify)：recognizedRprChildren Set 列了 ~16+ rPr child kinds 為 'recognized' 但 parseRunProperties 沒有 typed extraction → silent drop。受影響的常見元素：<w:spacing>（character spacing）、<w:caps>/<w:smallCaps>、<w:position>、<w:shd>（run shading）、<w:bdr>、<w:em>（CJK emphasis marks）、<w:effect>、<w:vanish>/<w:specVanish>/<w:webHidden>、<w:outline>/<w:shadow>/<w:emboss>/<w:imprint>、<w:bCs>/<w:iCs>/<w:dstrike>。Fix：trim Set 到 ONLY actually-typed-extracted-or-emitted kinds。Round-trip size loss: pre-fix v3.13.x 32% → v3.14.0 17.75% → v3.14.1 16.66%。Methodology lesson (6th)：P2 from one reviewer can become P0 when another applies real-world impact lens. v3.14.0 closes #60（sub-stack C of #58/#59/#60）— RunProperties field-loss audit。Bump ooxml-swift v0.19.13→v0.20.0。新增 typed fields：4-axis rFonts (ascii/hAnsi/eastAsia/cs/hint — 之前被收斂成單一值)、noProof、kern、3-axis lang (val/eastAsia/bidi)，加上 rawChildren passthrough 處理 unrecognized rPr children（如 w14:textOutline / w14:textFill / w14:glow）。**Pre-fix MCP 用戶看到 eastAsia/cs 字型（如 DFKai-SB 用於繁體中文）在 round-trip 時 silently 被替換成 ascii 值；v3.14.0 完整保留 4 個 axis**。Matrix-pin testDocumentContentEqualityInvariant 加上 preservation-class-3 ratio-floor assertions，現在 LOAD-BEARING — 任何未來 RunProperties regression 都會被 matrix-pin 抓到。Thesis fixture document.xml round-trip 大小：pre-fix 32% 損失 → post-sub-stack-C 17.75% 損失（改善 14.25 percentage points）。剩餘 17.75% 是 paragraph-mark rPr + w14:paraId/textId drops（separate out-of-scope follow-up SDD）。**'if not typed, preserve as raw' 原則架構性完成** — 從 sub-stack A (#58 BodyChild)、B (#59 WhitespaceOverlay) 一路發展到 C (#60 RunProperties)。Backward compatible — 保留 fontName field，mirror rFonts.ascii。v3.13.13 CRITICAL HOTFIX (sub-stack B-CONT-2-CONT) reverted v3.13.12 的 TIER-0 over-fix。v3.13.12 (DO NOT USE — 刪除 <w:del> 內容)。v3.13.11 sub-stack B-CONT。基於 ooxml-swift v0.20.0。",
       "author": {
         "name": "Che Cheng"
       },
@@ -141,7 +152,7 @@
     {
       "name": "claude-switch",
       "version": "1.0.0",
-      "description": "Claude Code \u591a\u5e33\u865f\u7ba1\u7406\uff1a\u5207\u63db\u5e33\u865f\u3001\u5217\u51fa\u5e33\u865f\u3001\u81ea\u52d5\u8a2d\u5b9a IDE symlink \u89e3\u6c7a VS Code \u5075\u6e2c\u554f\u984c",
+      "description": "Claude Code 多帳號管理：切換帳號、列出帳號、自動設定 IDE symlink 解決 VS Code 偵測問題",
       "author": {
         "name": "Che Cheng"
       },
@@ -150,18 +161,28 @@
     },
     {
       "name": "che-xcode-mcp",
-      "version": "1.0.0",
-      "description": "App Store Connect MCP Server \u2014 99 tools across 15 domain managers covering the full ASC API",
+      "version": "1.0.1",
+      "description": "App Store Connect MCP Server — 99 tools across 15 domain managers covering the full ASC API",
       "author": {
         "name": "Che Cheng"
       },
       "source": "./plugins/che-xcode-mcp",
       "category": "development"
     },
+    {
+      "name": "che-transport-mcp",
+      "version": "0.6.1",
+      "description": "Taiwan TDX transport MCP — 23 tools across Rail / Bus / Bike / Air / Maritime / Traffic / Parking. Wraps PsychQuant/che-transport-mcp binary (binaryVersion 0.2.2) with version-aware auto-download, 3-tier cache TTL (24h static / 1h timetable / 0s live), parallel cross-system station search, NSQL confirmation discipline. v0.2.3: soft dependency on PsychQuant/che-keychain — when installed, setup-tdx skill invokes it directly for a native NSAlert (id + secret in one dialog), no Terminal window needed. Binary v0.2.2 also auto-delegates --setup to che-keychain if present. Falls back to in-binary getpass otherwise.",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/che-transport-mcp",
+      "category": "productivity"
+    },
     {
       "name": "che-dropbox-ignore",
       "version": "2.1.0",
-      "description": "Dropbox \u540c\u6b65\u6392\u9664\u7ba1\u7406 \u2014 \u81ea\u52d5\u5c0d .git\u3001build artifacts \u7b49\u8a2d\u5b9a com.dropbox.ignored xattr",
+      "description": "Dropbox 同步排除管理 — 自動對 .git、build artifacts 等設定 com.dropbox.ignored xattr",
       "author": {
         "name": "Che Cheng"
       },
@@ -171,7 +192,7 @@
     {
       "name": "che-bot-toolkit",
       "version": "0.1.0",
-      "description": "Bot \u958b\u767c\u5de5\u5177\u96c6",
+      "description": "Bot 開發工具集",
       "author": {
         "name": "Che Cheng"
       },
@@ -180,28 +201,18 @@
     },
     {
       "name": "archive-first",
-      "version": "2.1.0",
-      "description": "Protect files from AI-assisted deletion \u2014 PreToolUse hooks block destructive commands on archived/ paths, toggle with archived-lock/archived-unlock",
+      "version": "2.2.0",
+      "description": "v2.2.0: PreToolUse hooks now protect both archive/ and archived/ directory conventions. Regex anchored on trailing slash to avoid false positives on git archive / tar archive.tar. Toggle protection with archived-lock/archived-unlock.",
       "author": {
         "name": "Che Cheng"
       },
       "source": "./plugins/archive-first",
       "category": "productivity"
     },
-    {
-      "name": "codex-batch",
-      "version": "1.0.0",
-      "description": "Batch content generation using Codex CLI (GPT-5.4) \u2014 parallel codex exec with large reference docs as context",
-      "author": {
-        "name": "Che Cheng"
-      },
-      "source": "./plugins/codex-batch",
-      "category": "productivity"
-    },
     {
       "name": "che-svg-mcp",
-      "version": "0.1.0",
-      "description": "SVG MCP Server \u2014 Swift \u539f\u751f XML \u64cd\u4f5c\uff0c33 \u500b\u5de5\u5177\uff0cSession-based \u5411\u91cf\u5716\u5f62\u7de8\u8f2f",
+      "version": "0.1.1",
+      "description": "SVG MCP Server — Swift 原生 XML 操作，33 個工具，Session-based 向量圖形編輯",
       "author": {
         "name": "Che Cheng"
       },
@@ -210,8 +221,8 @@
     },
     {
       "name": "che-pixel-mcp",
-      "version": "0.1.0",
-      "description": "Pixel MCP Server \u2014 Swift \u539f\u751f Core Image \u64cd\u4f5c\uff0c36 \u500b\u5de5\u5177\uff0c200+ \u6ffe\u93e1\uff0cSession-based \u9ede\u9663\u5716\u5f62\u7de8\u8f2f",
+      "version": "0.1.1",
+      "description": "Pixel MCP Server — Swift 原生 Core Image 操作，36 個工具，200+ 濾鏡，Session-based 點陣圖形編輯",
       "author": {
         "name": "Che Cheng"
       },
@@ -220,8 +231,8 @@
     },
     {
       "name": "che-telegram-mcp",
-      "version": "1.0.0",
-      "description": "Telegram MCP Plugin \u2014 \u7d50\u5408 Bot API \u8207\u500b\u4eba\u5e33\u865f (TDLib)\uff0cmacOS Keychain \u5bc6\u9470\u7ba1\u7406",
+      "version": "1.3.1",
+      "description": "Telegram MCP Server Plugin — Bot API + 個人帳號 TDLib 全功能存取，28+ 工具，Keychain 密鑰管理",
       "author": {
         "name": "Che Cheng"
       },
@@ -230,8 +241,8 @@
     },
     {
       "name": "perspective-writer",
-      "version": "2.2.0",
-      "description": "Write letters, emails, autobiographies, and formal documents by simulating the writer's authentic voice",
+      "version": "2.8.0",
+      "description": "Write letters, emails, autobiographies, and formal documents by simulating the writer's authentic voice. Uses Tarski's T-Schema to ensure every sentence has a concrete referent, and a 6-phase process (understand writer, understand recipient, simulate, write, anti-pattern check, iterate) to produce writing that sounds like a real person, not AI.",
       "author": {
         "name": "Che Cheng"
       },
@@ -241,7 +252,7 @@
     {
       "name": "che-creative-suite",
       "version": "0.1.0",
-      "description": "Creative Suite \u2014 \u5354\u8abf che-svg-mcp\uff08\u5411\u91cf\uff09\u8207 che-pixel-mcp\uff08\u9ede\u9663\uff09\u7684\u5716\u5f62\u8655\u7406\u5de5\u4f5c\u6d41\uff0c\u542b creative-router skill \u8207 creative-agent",
+      "description": "Creative Suite — 協調 che-svg-mcp（向量）與 che-pixel-mcp（點陣）的圖形處理工作流，含 creative-router skill 與 creative-agent",
       "author": {
         "name": "Che Cheng"
       },
@@ -250,7 +261,7 @@
     },
     {
       "name": "che-zotero-mcp",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "Zotero reference manager + academic search + knowledge graph MCP Server",
       "author": {
         "name": "Che Cheng"
@@ -287,6 +298,106 @@
       },
       "source": "./plugins/tool-finder",
       "category": "productivity"
+    },
+    {
+      "name": "safari-browser",
+      "version": "2.6.0",
+      "description": "macOS native browser automation via Safari + AppleScript — permanent login, upload --native, site-specific playbook skills, persistent daemon (Phase 1 commands ~50ms vs ~370ms stateless), exec script v2 (single-invocation multi-step JSON), --mark-tab opt-in tab ownership marker, daemon security hardening (socket/pid 0600, log redaction, stale-pid liveness, dirty-build handshake, lifecycle bypass).",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/safari-browser",
+      "category": "productivity"
+    },
+    {
+      "name": "lean-prover",
+      "version": "1.1.0",
+      "description": "Lean 4 automated proof grinding — breadth-first sorry elimination with Mathlib API rules, codex-prove-assist, lean-prover agent, and auto-commit",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/lean-prover",
+      "category": "development"
+    },
+    {
+      "name": "gifthub",
+      "version": "1.2.0",
+      "description": "GiftHub CLI integration — auto-detect GiftHub config (v2 .claude/.gfs/config.json or v1 .gfh.json), inject usage context, auto-install after build",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/gifthub",
+      "category": "development"
+    },
+    {
+      "name": "cli-tools",
+      "version": "1.1.2",
+      "description": "CLI tool lifecycle management — build, deploy, install, upgrade Swift CLI tools via GitHub Releases (macOS 26 signing via mcp-tools:mcp-sign-pipeline)",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/cli-tools",
+      "category": "development"
+    },
+    {
+      "name": "parallel-ai-agents",
+      "version": "2.5.1",
+      "description": "平行派發任務給多個 AI agent（Claude + Codex），獨立執行後交叉比對結果。Codex 改走直接 HTTP wrapper（bin/codex-call，Swift script）取代 codex exec subprocess，解決 hang 問題且避開 Python 版本飄移",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/parallel-ai-agents",
+      "category": "development"
+    },
+    {
+      "name": "macdoc",
+      "version": "1.1.0",
+      "description": "macOS 原生文件處理 CLI — 格式轉換、VLM OCR（含 host profile 設定）、SRT 處理",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/macdoc",
+      "category": "productivity"
+    },
+    {
+      "name": "batch-ocr",
+      "version": "0.1.0",
+      "description": "Folder-level OCR pipeline orchestrator wrapping macdoc — PDF→PNG split, parallel OCR with SSH-tunnel health check + auto-retry, per-page md merge, idempotent resume from interruption. Wraps the boilerplate every 'OCR a folder of PDFs' task otherwise re-derives.",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/batch-ocr",
+      "category": "development"
+    },
+    {
+      "name": "agent-cacher",
+      "version": "0.1.0",
+      "description": "Explicit-lookup cache for AI agent shell calls — records every invocation to SQLite, exposes cache.{lookup,fetch,recent,diff} via MCP",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/agent-cacher",
+      "category": "development"
+    },
+    {
+      "name": "docflow",
+      "version": "1.0.1",
+      "description": "Git-flow analog for documents — semantic synthesis, multi-version comparison, evidence-after-commit workflows for .tex / .md / .ipynb / .docx. v1.0.1 ships doc-synth skill (semantic merge between 2+ document versions, dimension-level take/leave decisions, provenance tracking; v1.0.1 adds 3+ source Pattern α spec, cross-language edge case from ASSG3 dogfood). Future: doc-compare, doc-verdict, doc-multiimpl.",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/docflow",
+      "category": "productivity"
+    },
+    {
+      "name": "math-tools",
+      "version": "0.1.0",
+      "description": "v0.1.0: Scaffolding for academic math article editing — 3 skills (propositions / proofread / manuscript-audit) + 3 frozen baseline rules (manuscript-jsonl-sync / manuscript-consistency-audit / code-and-manuscript-sync). Covers JSONL-driven prop extraction + R1-R8 mechanical gate, 6-layer L1-L5 + location-drift proofread workflow, R1-R4 cross-doc audit (working-file path leak, cite drift, code-manuscript symbol drift, prop-iso bijection). Dogfood origin: PsychQuantHsu/psychophysical_representations #107 proofread workflow experiment (3 pilots, 286-prop full L4 walk demonstrated, 5 findings shipped). v0.1.0 ships rules + methodology docs only;skill execution bodies + scripts (validate-propositions.py / refresh-prop-locations.py / audit-symbols.py / audit-citations.py / audit-code-manuscript.py / run-audit.sh) remain in source repo until v0.2.0 extraction.",
+      "author": {
+        "name": "Che Cheng"
+      },
+      "source": "./plugins/math-tools",
+      "category": "development"
     }
   ]
 }
diff --git a/.claude-plugin/migration-report-2026-05-02.md b/.claude-plugin/migration-report-2026-05-02.md
new file mode 100644
index 00000000..f4c17a1d
--- /dev/null
+++ b/.claude-plugin/migration-report-2026-05-02.md
@@ -0,0 +1,65 @@
+# Migration Report — psychquant-claude-plugins
+
+**Date**: 2026-05-02
+**Mode**: Applied
+**Total plugins scanned**: 34
+**CHANGELOG.md created (or would be)**: 33
+**Skipped (already has CHANGELOG.md)**: 1
+**Failed**: 0
+
+## Generated CHANGELOG.md
+
+| Plugin | Segments | Dates resolved | Versions |
+|--------|----------|----------------|----------|
+| `agent-cacher` | 1 | 0/1 | 0.1.0 |
+| `ai-docs-guide` | 1 | 0/1 | 1.4.0 |
+| `archive-first` | 1 | 0/1 | 2.1.0 |
+| `changelog-tools` | 1 | 0/1 | 0.1.0 |
+| `che-apple-mail-mcp` | 1 | 1/1 | 2.9.0 |
+| `che-apple-notes-mcp` | 1 | 0/1 | 0.2.1 |
+| `che-archive-lines` | 1 | 0/1 | 1.0.0 |
+| `che-bot-toolkit` | 1 | 0/1 | 0.1.0 |
+| `che-creative-suite` | 1 | 0/1 | 0.1.0 |
+| `che-dropbox-ignore` | 1 | 0/1 | 2.1.0 |
+| `che-duckdb-mcp` | 1 | 0/1 | 2.2.1 |
+| `che-ical-mcp` | 1 | 0/1 | 1.7.2 |
+| `che-pixel-mcp` | 1 | 0/1 | 0.1.1 |
+| `che-svg-mcp` | 1 | 0/1 | 0.1.1 |
+| `che-telegram-mcp` | 1 | 0/1 | 1.3.0 |
+| `che-things-mcp` | 1 | 0/1 | 1.6.2 |
+| `che-word-mcp` | 15 | 15/15 | 3.17.8, 3.17.7, 3.17.6, 3.17.5, 3.17.4... |
+| `che-xcode-mcp` | 1 | 0/1 | 1.0.1 |
+| `che-zotero-mcp` | 1 | 0/1 | 1.0.2 |
+| `claude-switch` | 1 | 0/1 | 1.0.0 |
+| `cli-tools` | 1 | 0/1 | 1.1.1 |
+| `codex-batch` | 1 | 0/1 | 1.0.0 |
+| `gifthub` | 1 | 0/1 | 1.1.0 |
+| `lean-prover` | 1 | 0/1 | 1.1.0 |
+| `macdoc` | 1 | 0/1 | 1.1.0 |
+| `mcp-tools` | 1 | 0/1 | 1.15.1 |
+| `parallel-ai-agents` | 1 | 0/1 | 2.1.1 |
+| `perspective-writer` | 1 | 0/1 | 2.5.0 |
+| `plugin-tools` | 1 | 0/1 | 1.15.0 |
+| `postgresql-guide` | 1 | 0/1 | 1.0.0 |
+| `r-docs-guide` | 1 | 0/1 | 1.0.0 |
+| `r-shiny-debugger` | 1 | 0/1 | 1.0.0 |
+| `tool-finder` | 1 | 0/1 | 1.0.0 |
+
+## Skipped (existing CHANGELOG.md)
+
+- `issue-driven-dev`
+
+## Failed
+
+(none)
+
+## Manual review needed
+
+Generated CHANGELOG.md files use best-effort categorization. Review each for:
+
+1. Section assignment — `### Added` / `### Changed` / `### Fixed` etc. may need re-categorization
+2. `(date unknown — please fill in)` entries — manually fill from git tags / release notes / memory
+3. Sentence splitting in non-English content (Chinese punctuation `。` not split)
+4. Cross-referenced versions (mentioned multiple times) — content from later mentions absorbed into prior segment
+
+Run `/changelog-tools:changelog-validate <plugin-path>` on each plugin after review.
diff --git a/.claude/issue-driven-dev.local.md b/.claude/issue-driven-dev.local.md
new file mode 100644
index 00000000..f1131cd7
--- /dev/null
+++ b/.claude/issue-driven-dev.local.md
@@ -0,0 +1,5 @@
+---
+github_repo: "PsychQuant/psychquant-claude-plugins"
+github_owner: "PsychQuant"
+attachments_release: "attachments"
+---
diff --git a/.gitignore b/.gitignore
index fc07c5ab..88e2d5b7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,7 @@
 
 # Local testing
 .local/
+
+# Spectra app data
+.spectra/
+openspec/.vector-search.db*
diff --git a/.spectra.yaml b/.spectra.yaml
new file mode 100644
index 00000000..498cc3fa
--- /dev/null
+++ b/.spectra.yaml
@@ -0,0 +1,32 @@
+# Spectra application config
+# See: https://github.com/spectra-app/spectra
+
+# OpenSpec directory path (relative to project root)
+# Changing this requires rebuilding the vector search index.
+# spec_dir: docs/specs
+
+# Language for AI-generated artifacts
+# locale: tw
+
+# Workflow toggles
+# tdd: true
+# audit: true
+# parallel_tasks: true
+
+# Claude slash commands (set true to also generate /spectra:X commands)
+# claude_slash_commands: true
+
+# Enable git worktree support for isolated change branches
+# worktree: true
+
+# Custom git worktrees directory
+# worktrees_dir: .spectra/worktrees
+
+# Claude Code skill effort levels (low/medium/high/max)
+# claude_effort:
+#   apply: high
+
+# AI tools to generate instruction files for
+# tools:
+#   - claude
+#   - cursor
diff --git a/CLAUDE.md b/CLAUDE.md
index d911b75b..7642b356 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -30,7 +30,6 @@ psychquant-claude-plugins/
 │   ├── che-things-mcp/          # Things 3 任務管理
 │   ├── che-word-mcp/            # Word 文件處理
 │   ├── che-xcode-mcp/           # Xcode / App Store Connect
-│   ├── claude-config-guide/     # [deprecated] → ai-docs-guide
 │   ├── claude-switch/           # Claude Code 多帳號管理
 │   ├── codex-batch/             # Codex CLI 批次生成
 │   ├── mcp-tools/               # MCP Server 開發工具集
@@ -115,13 +114,12 @@ psychquant-claude-plugins/
 **用途**: Auto-triggered Skills，自動 WebFetch Claude Code 和 OpenAI 官方文檔
 
 **Skills**:
-- `claude-docs-guide` — Claude Code CLI 設定（MCP、settings、hooks、skills）、Claude API/SDK
+- `claude-code-guide` — Claude Code CLI 設定（MCP、settings、hooks、skills）、Claude API/SDK
 - `openai-docs-guide` — OpenAI API（Responses API、Chat Completions、models）、Agents SDK、Realtime API
 
 **背景**:
 - OpenAI Docs MCP 的 `fetch_openai_doc` tool 壞掉（server-side bug），所有 URL 回 404
 - 此 plugin 繞過壞掉的 MCP fetch，直接 WebFetch `https://developers.openai.com/docs/...`
-- 取代了舊的 `claude-config-guide` plugin
 
 ### che-dropbox-ignore (scaffold)
 
diff --git a/README.md b/README.md
index 37741b07..77772466 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,20 @@
 
 個人 Claude Code Plugin Marketplace，專注於學術研究與生產力工具。
 
+> ## 📦 IDD has moved
+>
+> **`issue-driven-dev` 從本 marketplace 搬到 [`PsychQuant/issue-driven-development`](https://github.com/PsychQuant/issue-driven-development) 自立門戶（自 2026-05-02）。**
+>
+> 既有 install 需重新指 source：
+>
+> ```bash
+> claude plugin uninstall issue-driven-dev@psychquant-claude-plugins
+> claude plugin marketplace add PsychQuant/issue-driven-development
+> claude plugin install issue-driven-dev@issue-driven-development
+> ```
+>
+> 設定（`.claude/issue-driven-dev.local.json`、`.claude/.idd/`）在 project repo 裡，不用搬。
+
 ## 安裝
 
 ```bash
@@ -26,7 +40,6 @@
 | **mcp-tools** | MCP Server 開發工具集 | - |
 | **r-shiny-debugger** | R Shiny App 功能測試 | - |
 | **ai-docs-guide** | Claude Code + OpenAI 文檔查詢助手 | - |
-| **claude-config-guide** | ~~Claude Code 設定查詢~~ (已被 ai-docs-guide 取代) | - |
 | **postgresql-guide** | PostgreSQL 文檔查詢助手 | - |
 | **che-dropbox-ignore** | Dropbox 同步排除管理 | - |
 | **claude-switch** | Claude Code 模型切換 | - |
@@ -152,17 +165,11 @@ MCP Server 開發必備工具，提供完整的除錯與測試流程。
 Claude Code + OpenAI 文檔查詢助手。整合兩個 Auto-triggered Skills，自動根據問題類型 WebFetch 對應官方文檔。
 
 **包含 Skills**:
-- `claude-docs-guide` — Claude Code CLI / API / SDK 文檔
+- `claude-code-guide` — Claude Code CLI / API / SDK 文檔
 - `openai-docs-guide` — OpenAI API / SDK / Models 文檔
 
 **特點**: 繞過 OpenAI Docs MCP 壞掉的 `fetch_openai_doc` tool，直接 WebFetch 官方文檔 URL。
 
----
-
-### claude-config-guide (deprecated)
-
-> **已被 `ai-docs-guide` 取代**。功能完全包含在 `ai-docs-guide` 的 `claude-docs-guide` skill 中。
-
 ## License
 
 MIT
diff --git a/docs/codex-calling-convention.md b/docs/codex-calling-convention.md
new file mode 100644
index 00000000..21e10770
--- /dev/null
+++ b/docs/codex-calling-convention.md
@@ -0,0 +1,80 @@
+# Codex 呼叫原則
+
+Plugin 中呼叫 Codex CLI 的標準做法。
+
+## 一次性任務（預設選擇）
+
+```bash
+codex exec --full-auto \
+  -c 'model_reasoning_effort="xhigh"' \
+  -o output.md \
+  "prompt"
+```
+
+- `--full-auto`：workspace-write sandbox + auto approval
+- `-c 'model_reasoning_effort="..."'`：`none | minimal | low | medium | high | xhigh`
+- `-o FILE`：最後一條 message 直接寫入檔案（不怕 stdout 截斷）
+- `-C DIR`：指定工作目錄
+- `--add-dir DIR`：額外可寫目錄
+- stdin 傳 prompt：`cat prompt.txt | codex exec --full-auto -`
+
+適用：ensemble review 的 Codex 盲驗、單次 delegation、code review。
+
+## 需要 job management 時（罕見）
+
+```bash
+node codex-companion.mjs task --write --effort xhigh "prompt"
+node codex-companion.mjs status --all
+node codex-companion.mjs result $JOB_ID
+node codex-companion.mjs cancel $JOB_ID
+```
+
+- 必須加 `--write`，否則預設 read-only sandbox
+- companion 路徑會隨版本更新，不要硬編
+
+適用：多個並行 background jobs 且需要 status/cancel 管理。
+
+## 不要做的事
+
+- **不加 `--write` 的 companion** — 預設 read-only，Codex 無法寫檔或跑 R
+- **硬編 companion 路徑** — 版本號（如 `1.0.1`）會過時：
+  ```bash
+  # 不好
+  node "$HOME/.claude/plugins/cache/openai-codex/codex/1.0.1/scripts/codex-companion.mjs"
+  
+  # 較好（如果必須用 companion）
+  node "$HOME/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs"
+  ```
+- **用 `-m o3` 替代 effort 設定** — 不同模型用途不同；effort 控制的是思考深度
+
+## 對照表
+
+| | `codex exec` | `codex-companion.mjs` |
+|---|---|---|
+| 寫入權限 | `--full-auto` | `--write` |
+| Effort | `-c 'model_reasoning_effort="xhigh"'` | `--effort xhigh` |
+| 輸出 | `-o file.md` | stdout（可能截斷） |
+| Job 管理 | 無（一次性） | status / result / cancel |
+| Session 恢復 | `codex exec resume` | `--resume` |
+| 架構 | 直接跑 CLI | 透過 app-server WebSocket |
+
+## 範例：ensemble review 的 Codex 盲驗
+
+```bash
+codex exec --full-auto \
+  -c 'model="gpt-5.5"' \
+  -c 'model_reasoning_effort="xhigh"' \
+  -c 'service_tier="fast"' \
+  -o reviews/codex-review.md \
+  "審閱 solution.tex，從 methodology/writing/references 三角度。用繁體中文。"
+```
+
+## 範例：仲裁兩份解答
+
+```bash
+cat arbitration-prompt.txt | codex exec --full-auto \
+  -c 'model_reasoning_effort="xhigh"' \
+  --add-dir "$(pwd)/reviews" \
+  -o reviews/arbitration-codex.md \
+  -
+```
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/.openspec.yaml b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/.openspec.yaml
new file mode 100644
index 00000000..6760e5cb
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/.openspec.yaml
@@ -0,0 +1,6 @@
+schema: spec-driven
+created: 2026-04-16
+created_by: che cheng <kiki830621@gmail.com>
+created_with: claude
+archived_by: che cheng <kiki830621@gmail.com>
+archived_at: 2026-04-17
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/design.md b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/design.md
new file mode 100644
index 00000000..2e839926
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/design.md
@@ -0,0 +1,226 @@
+## Context
+
+This is **Phase 1** of a two-phase sequence resolving the 4-issue `archive-mail` attachment handling bundle (`#23` `#24` `#25` `#26`). Phase 1 ships foundational functionality (download + routing); Phase 2 (`archive-mail-filter-and-audit`) ships robustness layer (filter expansion + coverage audit). See the consolidated diagnosis cross-posted to all 4 issues for the full scope analysis.
+
+Current skill state at `plugins/che-apple-mail-mcp/commands/archive-mail.md` (202 lines, 7 steps):
+
+1. Parse filter argument
+2. Build directory + index
+3. Search emails via `mail__search_emails` with `query: filter`
+4. Filter new emails (dedup against index)
+5. Generate Markdown per email (attachment filenames as plain text, no download)
+6. Update index
+7. Output report
+
+MCP capabilities available but unused: `list_attachments`, `list_attachments_batch`, `save_attachment`.
+
+The 2026-04-14 tatsuma manuscript backfill (commits `bcac7ee`, `784eac6` in `PsychQuant/collaborations_tatsuma`) established a validated pattern for attachment handling — this change formalizes and automates that pattern.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Download every attachment from every archived email automatically
+- Route attachments to semantic locations: research data → `data/raw/`, document attachments → `correspondence/attachments/{email_stem}/`
+- Preserve original filenames on disk; URL-encode only in Markdown links
+- Allow per-project override via `.claude/emails.md` YAML config
+- Establish the first `archive-mail-*` capability spec that Phase 2 will extend
+
+**Non-Goals:**
+
+- **Not expanding the email search filter** (#24) — that is Phase 2. Phase 1 downloads whatever emails the current `filter` search returns. Missing emails due to filter asymmetry remain missing until Phase 2 ships.
+- **Not auditing download coverage** (#25) — also Phase 2. If `save_attachment` silently fails for an email, Phase 1 proceeds without warning. Phase 2 adds the cross-check step.
+- **Not supporting `--backfill-attachments`** for existing archives — deferred to Phase 2. Phase 1 applies only to new `/archive-mail` invocations.
+- **Not auto-migrating data files from existing `attachments/` directories to `data/`** — users with pre-existing archives can manually reclassify. Auto-migration would be a separate retroactive tooling change.
+- **Not parsing content / doing OCR** to classify attachments — routing is filename-based (extension + keyword). Content-based classification (e.g., "this PDF contains only figures" vs "this PDF is a methodology reference") is out of scope.
+- **Not changing the email search MCP call** (stays `mail__search_emails` with `query: filter`). Phase 2 extends it.
+
+## Decisions
+
+### Decision: Phase 1 Scope is #23 + #26 Only
+
+This change covers attachment download (`#23`) and attachment routing (`#26`). Filter expansion (`#24`) and coverage audit (`#25`) are deferred to Phase 2 (`archive-mail-filter-and-audit`).
+
+**Rationale**: `#23` and `#26` share the same code path (the new attachment download loop writes to paths determined by `#26` routing). `#24` expands what emails get processed; `#25` validates the output. Phase 2 logically consumes Phase 1's output. Shipping Phase 1 first lets users get the core fix quickly and validates download behavior before layering filter expansion and audit on top.
+
+**Alternatives**:
+- _Bundle all 4 into one change_ — rejected; ~40 tasks in one change is harder to review and slower to validate incrementally
+- _Split into 4 separate changes_ — rejected; `#23`+`#26` share the download loop, splitting them would duplicate config plumbing
+
+### Decision: Routing Precedence is Config > Keyword > Extension
+
+When classifying an attachment, the routing logic evaluates in strict precedence:
+
+1. **YAML config `attachment_routing` block** (if present in `.claude/emails.md`): explicit rules win over built-in heuristics
+2. **Filename keyword match**: specific keywords in the filename override generic extension rules
+3. **Extension-based defaults**: fallback for anything not matched by config or keywords
+
+The first match wins; later rules are not consulted.
+
+**Rationale**:
+- **Config top-most** because users with project-specific conventions (e.g., manuscript project where `Figures_20250610.xlsx` is a figures file, not data) need an escape hatch from generic heuristics
+- **Keywords above extensions** because a filename like `indicators_raw.xlsx` carries stronger signal than the `.xlsx` extension alone (extension says "spreadsheet", keyword says "data")
+- **Extensions last** as a reasonable default for the common case
+
+**Example evaluation** — file `Submission_Figures_v3.xlsx`:
+- Config: no entry → skip
+- Keyword: "Submission" matches `document_keywords` list → route to `attachments/`
+- Extension `.xlsx` is in `data_extensions` list but NOT consulted (keyword already matched)
+
+**Alternatives**:
+- _Extension-first_ — rejected; `.xlsx` is ambiguous (data or figures table), forcing extension-first would mis-route manuscript xlsx to `data/`
+- _Keyword-first_ — rejected; config loses its override role
+- _Longest-match wins (any tier)_ — rejected as hard to explain; precedence model is simpler
+
+### Decision: Default Routing Rules
+
+Built-in defaults (used when `.claude/emails.md` has no `attachment_routing` block):
+
+```yaml
+data_extensions:
+  - csv
+  - tsv
+  - sav       # SPSS
+  - dta       # Stata
+  - parquet
+  - feather
+  - xlsx      # ambiguous — keyword can override
+  - sas7bdat  # SAS
+
+document_extensions:
+  - pdf
+  - docx
+  - doc
+  - txt
+  - md
+  - rtf
+  - odt
+
+data_keywords:   # filename substring match, case-insensitive
+  - data
+  - raw
+  - indicators
+  - codebook
+  - dataset
+
+document_keywords:
+  - Submission
+  - Figures
+  - Tables
+  - Manuscript
+  - draft
+  - Revision
+  - v1
+  - v2
+  - v3
+
+data_dir: data/raw
+documents_dir: correspondence/attachments
+```
+
+**Rationale**:
+- `xlsx` in `data_extensions` because research workflows commonly use xlsx for indicator tables / wide-format datasets
+- `Submission`, `Figures`, `Tables`, `Manuscript`, `v1`/`v2`/`v3` in `document_keywords` because these are standard academic paper artifacts
+- Case-insensitive keyword match because inconsistent capitalization is common (`figures` vs `Figures` vs `FIGURES`)
+
+**Alternatives considered**: `.xlsx` as document default (rejected — most research xlsx is data; users can override via keywords if their project treats xlsx as documents).
+
+### Decision: Config Schema Shape
+
+`attachment_routing` YAML block lives in `.claude/emails.md` front matter alongside existing `filters`. All fields optional; omitted fields fall back to defaults. Adding any field means the ENTIRE defaults are replaced (not merged) — avoids surprises from partial override.
+
+```yaml
+---
+filters:
+  - tatsuma
+attachment_routing:
+  data_extensions: [csv, sav, dta]
+  data_keywords: [raw, indicators]
+  data_dir: data/raw
+  documents_dir: correspondence/attachments
+  # document_extensions / document_keywords omitted → defaults used? NO: override all or nothing
+---
+```
+
+**Rationale**: merge semantics are deceptively complex — users expect `data_extensions: [csv]` to ADD csv, but if defaults are `[csv, tsv, sav, ...]` is tsv still included? Partial override leads to bugs. "All or nothing" is explicit.
+
+**Alternatives**: `merge: true` explicit flag for partial override — rejected as scope creep; can be added in Phase 2 if users request it.
+
+### Decision: Filename Preservation on Disk
+
+Attachment files are saved with their ORIGINAL filename bytes, including spaces, `&`, CJK characters, and emoji. No sanitization. URL encoding is applied ONLY when inserting the filename into a Markdown link URL.
+
+**Rationale**:
+- macOS filesystem supports Unicode + spaces + most punctuation natively
+- Users want to open the file in Word / Excel and see the original name
+- GitHub and VS Code render `%20`-encoded Markdown links correctly
+
+**Specifics**:
+- Disk path: `attachments/2026-04-08_.../Figures & Tables20260408.docx`
+- Markdown link: `[Figures & Tables20260408.docx](attachments/2026-04-08_.../Figures%20%26%20Tables20260408.docx) (93 KB)`
+- Display text (`[...]`) keeps original name verbatim for readability
+- URL (`(...)`) encodes `space` → `%20` and `&` → `%26`; everything else (including CJK) stays unchanged
+
+**Alternatives**:
+- _Slugify filenames_ (replace spaces with `_`, strip `&`) — rejected; breaks user expectation of "original file"
+- _Fully percent-encode URL_ — rejected; over-encoding CJK hurts readability without benefit (GitHub/VS Code handle raw CJK in URLs)
+
+### Decision: Attachment Block Placement in Markdown
+
+The Attachments list goes AFTER the signature block and BEFORE the thread quote (identified by `差出人:` / `From:` / `寄件者:` / `On ... wrote:` variants). Matches 2026-04-14 tatsuma baseline.
+
+**Rationale**: Logically, attachments belong to "this email" not "the quoted thread history". Placing them before the thread quote makes this unambiguous. The existing skill already uses body-before-quote placement for the signature; attachments slot in between.
+
+### Decision: Reply Cross-Reference Instead of Duplicate Download
+
+When a reply email's `list_attachments` returns empty but the email body still contains text like `<original_file.docx>` (Mail.app's quote-time attachment marker), the skill emits a cross-reference line rather than attempting to download:
+
+```markdown
+Attachments:
+(Attachments on the original email from <original_sender> — see `<original_email_md_stem>.md`)
+```
+
+**Rationale**: Downloading the same file multiple times across reply chains wastes disk and creates confusion about which copy is "authoritative". `list_attachments` is the source of truth for what THIS email actually has; quote-time markers are stale references. Cross-reference preserves the link without duplication.
+
+**Alternatives**:
+- _Download on every quote reference_ — rejected; wasteful + ambiguous provenance
+- _Ignore quote-time markers entirely_ (write nothing if `list_attachments` is empty) — rejected; loses the explicit acknowledgement that attachments exist in the thread, just not on this message
+
+## Risks / Trade-offs
+
+- **Risk**: `save_attachment` may fail silently for a specific attachment (MCP returns error but skill doesn't check). Phase 1 proceeds without error handling.
+  - **Mitigation**: the coverage audit in Phase 2 (`#25`) catches this. In Phase 1, a simple `try/catch` around `save_attachment` with a `console.warn` output is acceptable — full audit is Phase 2.
+
+- **Risk**: large attachments (multi-MB PDFs, video) balloon repo disk. No size limit enforced.
+  - **Mitigation**: Phase 2 can add a `max_attachment_size_mb` config with warn-and-skip behavior. Phase 1 accepts any size — this matches the manual-backfill baseline which downloaded 7 attachments totaling ~2 MB without issue.
+
+- **Risk**: routing mis-classification (e.g., `Submission_Figures_Data.xlsx` has both `Submission` and `Data` keywords — ambiguous).
+  - **Mitigation**: precedence is "first match wins"; user can override via config. If mis-classification is common, a `disambiguate` callback or rule ordering spec could be added later.
+
+- **Risk**: YAML schema evolution — adding fields in Phase 2 (#24 subject_keywords, #25 audit_log path) must not break Phase 1 configs.
+  - **Mitigation**: YAML parsing should tolerate unknown fields (skip, don't error). Document this as a forward-compat requirement in the spec.
+
+- **Trade-off**: partial override semantics rejected (all-or-nothing). Users with one small override field must repeat all defaults.
+  - **Mitigation**: built-in defaults will be exported as a reference snippet in the skill's example docs, so copy-paste is fast.
+
+- **Trade-off**: no content-based classification — a PDF titled `codebook.pdf` gets classified as `document` (keyword `document_keywords` doesn't include "codebook"; `data_keywords` does, but extension is `.pdf` which is in `document_extensions`… keyword matches first, so it routes to `data/`). Works correctly in most cases but can confuse on ambiguous names.
+  - **Mitigation**: config override handles edge cases; keyword lists can be tuned per project.
+
+## Migration Plan
+
+Within this change:
+
+1. Write the new skill step between current Step 5 and Step 6
+2. Add routing classifier logic (extension + keyword + config precedence)
+3. Add Markdown generation updates (Attachments block placement, URL encoding)
+4. Add config schema parsing from `.claude/emails.md` front matter
+5. Update skill output report
+6. Write example `.claude/emails.md` snippet in skill doc for user reference
+7. Version bump in `plugins/che-apple-mail-mcp/plugin.json`
+8. Deploy via `/plugin-tools:plugin-deploy`
+
+**Rollback**: revert the single commit + re-deploy the previous plugin version. Existing archives are unaffected (they already have no attachments and no new config is required).
+
+## Open Questions
+
+- _(none — all 4 design decisions resolved above, with explicit "all-or-nothing" config semantics and "config > keyword > extension" precedence as the load-bearing choices)_
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/proposal.md b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/proposal.md
new file mode 100644
index 00000000..83dfb016
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/proposal.md
@@ -0,0 +1,51 @@
+## Why
+
+The `/archive-mail` skill currently writes attachment **filenames** into the generated Markdown but never downloads the actual files. Discovered 2026-04-14 while archiving the tatsuma manuscript thread: `Attachments: Taxometric_Analysis_Submission_v3_20260408.docx, Figures & Tables20260408.docx` appeared in the body, but the `.docx` files stayed trapped inside Apple Mail's internal storage. Users wanting the files had to open Mail.app and manually drag them out.
+
+The MCP server already has the needed capabilities (`list_attachments`, `list_attachments_batch`, `save_attachment`); the skill just never calls them.
+
+Additionally, when attachments are eventually downloaded, they divide into two usage categories that deserve different locations:
+
+- **Document attachments** (reference PDFs, manuscript docx, figures): belong in `correspondence/attachments/{email_stem}/` — logically tied to the email
+- **Research data** (raw csv, indicator xlsx, SPSS sav, codebook): belong in `data/` or `data/raw/` — logically tied to the project, not the email
+
+Mixing them makes data files hard to find in research workflows (researchers look for `data/`, not `correspondence/attachments/`).
+
+This change is **Phase 1** of a 4-issue bundle addressing `archive-mail` attachment handling. It closes [`#23`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/23) (download) and [`#26`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/26) (routing). Phase 2 (`archive-mail-filter-and-audit`, closing `#24` filter asymmetry + `#25` coverage audit) ships separately after Phase 1 has been validated in practice.
+
+## What Changes
+
+- **New skill step** (between current Step 5 "Generate Markdown" and Step 6 "Update Index"): iterate archived emails, call `list_attachments_batch` to enumerate attachments, then `save_attachment` for each one
+- **Filename preservation on disk**: attachment files keep their original bytes as filename (spaces, `&`, CJK, emoji all preserved). URL encoding is applied ONLY to the Markdown link URL (`%20` for space, `%26` for ampersand; everything else passes through)
+- **Attachment block placement in Markdown**: inserted after the signature and before the thread quote (`差出人:` / `From:` separator), grouped per-email — matches the 2026-04-14 tatsuma backfill baseline
+- **New attachment routing logic**: classify each attachment as `data` or `document` via a 3-tier precedence (config > keyword > extension), route to different output directories accordingly
+- **New `.claude/emails.md` config block** `attachment_routing`: optional YAML with `data_extensions`, `document_extensions`, `data_keywords`, `document_keywords`, `data_dir`, `documents_dir` fields. Absent = use built-in defaults
+- **Skill output report** extended: after archive, report `N attachments archived: M to <data_dir>, K to <documents_dir>`
+- **Cross-reference for replies without attachments**: when a reply email's `list_attachments` returns empty but the body quotes an original's attachment markers, emit a cross-reference line in the reply's Markdown (e.g., `(Attachments on the original email from <sender> — see <original_stem>.md)`) instead of a broken link
+
+## Non-Goals
+
+<!-- Non-Goals live in design.md. -->
+
+## Capabilities
+
+### New Capabilities
+
+- `archive-mail-attachments`: Defines how `/archive-mail` downloads attachment files from archived emails, where they are placed on disk (with data-vs-document routing), and how they are linked from the generated Markdown.
+
+### Modified Capabilities
+
+(none)
+
+## Impact
+
+- **Affected specs**:
+  - New: `openspec/specs/archive-mail-attachments/spec.md`
+- **Affected code**:
+  - Modified: `plugins/che-apple-mail-mcp/commands/archive-mail.md` (202 → ~310 lines estimated after Phase 1)
+  - Modified: `plugins/che-apple-mail-mcp/plugin.json` (version bump)
+- **Config schema**:
+  - New optional YAML block `attachment_routing` in `.claude/emails.md` (per-project override). Defaults apply when block is absent.
+- **Affected users**: any caller of `/archive-mail`. Current behavior preserved when `attachment_routing` block is absent — attachments now download by default (this IS the fix), with data-vs-document heuristic applying built-in defaults. Users with existing archives: a separate `--backfill-attachments` flag is deferred to Phase 2.
+- **Closes**: [`PsychQuant/psychquant-claude-plugins#23`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/23), [`#26`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/26)
+- **Advances**: [`PsychQuant/macdoc#75`](https://github.com/PsychQuant/macdoc/issues/75) umbrella Layer 3 (partial)
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/specs/archive-mail-attachments/spec.md b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/specs/archive-mail-attachments/spec.md
new file mode 100644
index 00000000..adcec85d
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/specs/archive-mail-attachments/spec.md
@@ -0,0 +1,223 @@
+## ADDED Requirements
+
+### Requirement: Skill downloads attachments from archived emails
+
+The `/archive-mail` skill SHALL, after generating the Markdown for each archived email, iterate the email's attachments (via `mail__list_attachments_batch`) and save each attachment to disk via `mail__save_attachment`. Emails whose `list_attachments` returns an empty list SHALL NOT trigger any save operation.
+
+#### Scenario: Email with attachments triggers downloads
+
+- **WHEN** `/archive-mail` processes an email that `list_attachments` reports has 2 attachments
+- **THEN** the skill calls `save_attachment` twice, producing 2 files on disk in the configured attachment directory
+
+#### Scenario: Email without attachments does not call save_attachment
+
+- **WHEN** `/archive-mail` processes an email whose `list_attachments` returns an empty list
+- **THEN** no `save_attachment` call is made for that email and no files are written
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Attachment directory matches email Markdown stem
+
+For each archived email, attachments SHALL be written under a per-email subdirectory whose name matches the email's generated Markdown file (without the `.md` extension).
+
+Given an email Markdown file at `correspondence/2026-04-08_Re--Taxometric-Analysis.md`, its attachments SHALL go to `correspondence/attachments/2026-04-08_Re--Taxometric-Analysis/` (when routed as documents) OR to the configured `data_dir` (when routed as data per the routing rules).
+
+#### Scenario: Document attachment placed under email stem directory
+
+- **WHEN** an email saved as `correspondence/2026-04-08_Foo.md` has an attachment `Report.pdf` classified as a document
+- **THEN** the file is written to `correspondence/attachments/2026-04-08_Foo/Report.pdf`
+
+#### Scenario: Data attachment placed under data_dir
+
+- **WHEN** the same email has an attachment `raw_indicators.csv` classified as data (per routing rules)
+- **THEN** the file is written to `{data_dir}/raw_indicators.csv` (where `data_dir` is either the configured value or the default `data/raw`)
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Attachment routing follows config-keyword-extension precedence
+
+The skill SHALL classify each attachment as `data` or `document` by evaluating rules in strict precedence order:
+
+1. **Config match** — if `.claude/emails.md` contains an `attachment_routing` block whose filename explicitly matches (not covered in v1, reserved for future exact-file override)
+2. **Keyword match** — case-insensitive substring search of the filename against the two keyword lists. The first list to match determines classification. Keyword lists evaluated in order: `data_keywords` then `document_keywords`
+3. **Extension match** — file's extension compared against `data_extensions` then `document_extensions`
+
+The first matching rule determines classification. Later rules are NOT consulted.
+
+If NO rule matches (filename has no keyword match and extension is in neither list), the file SHALL be routed to `documents_dir` as a conservative default.
+
+#### Scenario: Keyword match overrides extension
+
+- **WHEN** an attachment named `Submission_data_v3.xlsx` is encountered (both `Submission` document keyword and `data` data keyword present; `.xlsx` is a data extension)
+- **THEN** the first matching keyword tier wins. Evaluated: `data_keywords` first → matches `data` (substring) → file routes to `data_dir`.
+- **AND** the `.xlsx` extension is NOT consulted
+
+Note: if the user's project treats `Submission_data_v3.xlsx` as a document (e.g., it's a submitted spreadsheet figure), they override via config's `attachment_routing` block.
+
+#### Scenario: Extension-only classification
+
+- **WHEN** an attachment named `appendix.pdf` matches no keyword in either list
+- **THEN** extension `.pdf` is in `document_extensions` → file routes to `documents_dir`
+
+#### Scenario: Unmatched file defaults to documents
+
+- **WHEN** an attachment named `unknown.xyz` matches no keyword and its extension is in neither list
+- **THEN** the file routes to `documents_dir` (conservative default)
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Default routing rules when config is absent
+
+When `.claude/emails.md` does NOT contain an `attachment_routing` block, the skill SHALL apply these built-in defaults:
+
+- `data_extensions`: `csv, tsv, sav, dta, parquet, feather, xlsx, sas7bdat`
+- `document_extensions`: `pdf, docx, doc, txt, md, rtf, odt`
+- `data_keywords` (case-insensitive substring): `data, raw, indicators, codebook, dataset`
+- `document_keywords` (case-insensitive substring): `Submission, Figures, Tables, Manuscript, draft, Revision, v1, v2, v3`
+- `data_dir`: `data/raw`
+- `documents_dir`: `correspondence/attachments`
+
+#### Scenario: Absent config uses built-in defaults
+
+- **WHEN** `.claude/emails.md` has no `attachment_routing` field, and an email has attachments `data.csv` and `manuscript.docx`
+- **THEN** `data.csv` → `data/raw/data.csv` (extension + keyword both match data); `manuscript.docx` → `correspondence/attachments/{email_stem}/manuscript.docx` (keyword `Manuscript` — case-insensitive — matches document)
+
+#### Scenario: Partial config replaces ALL defaults (no merge)
+
+- **WHEN** `.claude/emails.md` contains `attachment_routing: { data_extensions: [csv, sav] }` (all other fields omitted)
+- **THEN** the skill uses ONLY `[csv, sav]` for data extensions and EMPTY lists for `document_extensions`, `data_keywords`, `document_keywords`. Default `data_dir` / `documents_dir` paths still apply (these fields have separate defaults, not part of the keyword/extension lists).
+- **AND** a `.docx` attachment with no keyword match routes to `documents_dir` per the "unmatched file defaults to documents" rule (because the empty `document_extensions` list means the `.docx` doesn't match extension-tier either)
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Filename preservation on disk with URL encoding in Markdown links only
+
+Attachment files SHALL be saved to disk with their original filename bytes preserved — including spaces, `&`, CJK characters, and emoji — without any sanitization. URL encoding SHALL be applied ONLY to the URL portion of Markdown links, not to the display text.
+
+URL encoding rules for the Markdown link URL:
+- Space (U+0020) → `%20`
+- Ampersand `&` (U+0026) → `%26`
+- All other characters (including CJK, emoji, other punctuation) SHALL pass through unchanged
+
+#### Scenario: Original filename preserved on disk
+
+- **WHEN** the attachment is named `Figures & Tables20260408.docx`
+- **THEN** the file is saved as `Figures & Tables20260408.docx` (with literal space and `&`) on disk
+- **AND** the Markdown link is `[Figures & Tables20260408.docx](attachments/{stem}/Figures%20%26%20Tables20260408.docx)`
+
+#### Scenario: CJK filename passes through URL unchanged
+
+- **WHEN** the attachment is named `資料_v3.xlsx` (CJK + underscore)
+- **THEN** the file is saved with the CJK name on disk
+- **AND** the Markdown link URL is `attachments/{stem}/資料_v3.xlsx` (CJK NOT percent-encoded)
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Attachment block placement in Markdown
+
+Generated email Markdown SHALL contain a `Attachments:` block placed AFTER the email body signature and BEFORE any thread quote (identified by patterns like `差出人:`, `寄件者:`, `From:`, or `On ... wrote:`).
+
+If the email has no attachments, no `Attachments:` block is emitted.
+
+#### Scenario: Email with body + signature + thread quote
+
+- **WHEN** an email contains body text, a signature ending with `∞∞∞` divider, and a thread quote starting with `差出人:`
+- **THEN** the generated Markdown order is: body → signature → `Attachments:` block → thread quote
+
+#### Scenario: Email without thread quote
+
+- **WHEN** an email has body + signature but no thread quote (original message, not a reply)
+- **THEN** the `Attachments:` block appears AFTER the signature with no following thread quote
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Reply without attachments emits cross-reference
+
+When a reply email has an empty `list_attachments` result BUT its body contains quote-time attachment markers (text patterns like `<filename.ext>` appearing in the thread quote), the skill SHALL emit a cross-reference line in place of a download. The cross-reference SHALL identify the original sender and point to the original email's Markdown stem.
+
+#### Scenario: Reply quoting original's attachments
+
+- **WHEN** a reply email's `list_attachments` returns empty, and the body quote contains `<original_file.docx>` pointing at an original email archived as `2026-04-08_Foo.md`
+- **THEN** the reply's Markdown contains `(Attachments on the original email from {original_sender} — see \`2026-04-08_Foo.md\`)` in place of the Attachments block
+- **AND** no `save_attachment` call is made for the reply
+
+#### Scenario: Reply without quote markers
+
+- **WHEN** a reply's `list_attachments` is empty AND the body has no quote-time attachment markers
+- **THEN** no `Attachments:` block and no cross-reference is emitted (silence is correct)
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
+
+---
+
+### Requirement: Skill output report summarizes attachment routing
+
+At the end of an `/archive-mail` invocation, the output report SHALL include a summary line counting attachments by routing destination.
+
+Format: `N attachments archived: M to <data_dir>, K to <documents_dir>`
+
+Where `N = M + K`. If no attachments were downloaded, the summary line is `0 attachments archived` (no breakdown).
+
+#### Scenario: Mixed routing report
+
+- **WHEN** an invocation downloads 15 total attachments: 4 classified as data, 11 as documents
+- **THEN** the report includes the line `15 attachments archived: 4 to data/raw, 11 to correspondence/attachments`
+
+#### Scenario: No attachments report
+
+- **WHEN** an invocation processes emails that collectively have zero attachments
+- **THEN** the report includes the line `0 attachments archived` with no breakdown
+
+<!-- @trace
+source: archive-mail-downloads-and-routing
+updated: 2026-04-16
+code:
+  - plugins/che-apple-mail-mcp/commands/archive-mail.md
+-->
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/tasks.md b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/tasks.md
new file mode 100644
index 00000000..2f6e7c02
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-downloads-and-routing/tasks.md
@@ -0,0 +1,59 @@
+## 1. Skill structure + config parsing
+
+- [x] 1.1 Per Decision: Phase 1 Scope is #23 + #26 Only — add a new Step 5.5 block between current Step 5 (Markdown generation) and Step 6 (Update Index) in `plugins/che-apple-mail-mcp/commands/archive-mail.md` titled "Step 5.5: Download and route attachments" (confirms scope: only #23 + #26 in this change; #24/#25 deferred to Phase 2)
+- [x] 1.2 Per Decision: Config Schema Shape — add YAML parsing in Step 2 (directory + index setup) that reads the optional `attachment_routing` block from `.claude/emails.md` front matter, or falls back to the Decision: Default Routing Rules defaults when the block is absent
+- [x] 1.3 Document in the skill that partial config replaces ALL defaults (no merge), with an example showing the full default YAML block for copy-paste reference
+
+## 2. Routing classifier
+
+Implements **Attachment routing follows config-keyword-extension precedence** + **Default routing rules when config is absent** requirements.
+
+- [x] 2.1 Per Decision: Routing Precedence is Config > Keyword > Extension and **Attachment routing follows config-keyword-extension precedence** requirement — implement a classifier that takes a filename and the loaded config object, and returns `"data"` or `"document"`. Evaluation order: (a) future config-exact-file override (reserved), (b) `data_keywords` substring match (case-insensitive), (c) `document_keywords` substring match (case-insensitive), (d) `data_extensions` exact match, (e) `document_extensions` exact match, (f) conservative default = `"document"`
+- [x] 2.2 Per Decision: Default Routing Rules and **Default routing rules when config is absent** requirement — hardcode the built-in defaults for `data_extensions` (csv/tsv/sav/dta/parquet/feather/xlsx/sas7bdat), `document_extensions` (pdf/docx/doc/txt/md/rtf/odt), `data_keywords` (data/raw/indicators/codebook/dataset), `document_keywords` (Submission/Figures/Tables/Manuscript/draft/Revision/v1/v2/v3), `data_dir` (data/raw), `documents_dir` (correspondence/attachments)
+- [x] 2.3 Add unit test documentation in the skill (not executable tests, but worked examples as doc): classify `Submission_Figures_v3.docx` → document, `raw_indicators.csv` → data, `appendix.pdf` → document, `unknown.xyz` → document (conservative default)
+
+## 3. Attachment download loop
+
+Implements **Skill downloads attachments from archived emails** + **Attachment directory matches email Markdown stem** + **Filename preservation on disk with URL encoding in Markdown links only** requirements.
+
+- [x] 3.1 Per **Skill downloads attachments from archived emails** requirement: in Step 5.5, for each archived email, call `mail__list_attachments_batch` with the email's identifier. If the result is empty, skip to next email.
+- [x] 3.2 Per **Attachment directory matches email Markdown stem** requirement: for each attachment, classify via the routing classifier from Section 2 to determine target directory: `data_dir` (for data files) or `{documents_dir}/{email_stem}/` (for document files, where `email_stem` matches the email's Markdown filename without `.md`)
+- [x] 3.3 Per Decision: Filename Preservation on Disk and **Filename preservation on disk with URL encoding in Markdown links only** requirement — call `mail__save_attachment` with the original filename bytes (no sanitization: spaces, `&`, CJK, emoji all preserved) as the target filename, to the classified directory
+- [x] 3.4 Create the target directory on demand if it does not exist (both `data_dir` and `{documents_dir}/{email_stem}/` patterns)
+- [x] 3.5 Wrap the `save_attachment` call in a try/catch (or equivalent error handling); on failure, log a warning but continue with next attachment. Full error handling with audit report is Phase 2 scope.
+
+## 4. Markdown link generation + placement
+
+Implements **Attachment block placement in Markdown** + **Filename preservation on disk with URL encoding in Markdown links only** requirements.
+
+- [x] 4.1 Per Decision: Attachment Block Placement in Markdown and **Attachment block placement in Markdown** requirement — modify Step 5's Markdown template to insert a new "Attachments:" bullet list between the signature block and the thread quote separator. Identify the thread quote by matching the first occurrence of any of: `差出人:`, `寄件者:`, `From:`, `On ... wrote:`. If no thread quote exists (original message, not a reply), append the Attachments block at the end of the body.
+- [x] 4.2 For each downloaded attachment, generate a Markdown link in the format `- [{original_filename}]({url_encoded_path}) ({size_kb} KB)`. The display text preserves the original filename verbatim. The URL encodes space → `%20`, `&` → `%26`, all other characters (including CJK) pass through.
+- [x] 4.3 If the email has no attachments AND no quote-time markers (not a reply), no Attachments block is emitted.
+
+## 5. Reply cross-reference
+
+Implements **Reply without attachments emits cross-reference** requirement.
+
+- [x] 5.1 Per Decision: Reply Cross-Reference Instead of Duplicate Download and **Reply without attachments emits cross-reference** requirement — when an email's `list_attachments` returns empty, scan the body for quote-time attachment markers matching the pattern `<[^>\n]+\.(docx?|pdf|xlsx?|csv|pptx?|png|jpe?g)>` (case-insensitive extension list). If found, record the original sender and the original email's inferred Markdown stem (best-effort match against the index).
+- [x] 5.2 Emit a cross-reference line in place of the Attachments block: `(Attachments on the original email from {original_sender} — see \`{original_stem}.md\`)`. If the original stem cannot be inferred (original not yet archived), use a fallback: `(Attachments referenced in thread quote — original not yet archived)`.
+
+## 6. Skill output report
+
+Implements **Skill output report summarizes attachment routing** requirement.
+
+- [x] 6.1 Per **Skill output report summarizes attachment routing** requirement — modify Step 7 (Output report) to accumulate counts during Step 5.5: `data_count`, `document_count`. Report line: `{N} attachments archived: {data_count} to {data_dir}, {document_count} to {documents_dir}` where `N = data_count + document_count`
+- [x] 6.2 Zero-case: `0 attachments archived` (no breakdown) when no attachments were downloaded.
+
+## 7. Documentation + deployment
+
+- [x] 7.1 Update the skill's opening description / usage notes to mention the new attachment download behavior and point to the `attachment_routing` config block
+- [x] 7.2 Add an example `.claude/emails.md` snippet at the end of the skill file showing the full default `attachment_routing` block for copy-paste reference
+- [x] 7.3 Bump the version in `plugins/che-apple-mail-mcp/plugin.json` (minor bump — new behavior but additive: absent config = works out of the box with defaults)
+- [x] 7.4 Deploy the updated plugin via `/plugin-tools:plugin-deploy` (this handles marketplace.json sync + cache update)
+
+## 8. Issue tracking
+
+- [x] 8.1 Post an implementation-complete comment on [`#23`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/23) referencing the Spectra change and the deployed plugin version
+- [x] 8.2 Post the same on [`#26`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/26)
+- [x] 8.3 Close both issues via `/idd-close` (gate-checked closing summaries). Do NOT use `Closes #N` in commit trailer (auto-close bypasses `idd-close`).
+- [x] 8.4 Update [`PsychQuant/macdoc#75`](https://github.com/PsychQuant/macdoc/issues/75) umbrella: tick `#23` and `#26` in Layer 3 checklist; add a 2026-04-MM progress note; note that `#24` + `#25` remain for Phase 2 (`archive-mail-filter-and-audit`).
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/.openspec.yaml b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/.openspec.yaml
new file mode 100644
index 00000000..7277724c
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/.openspec.yaml
@@ -0,0 +1,6 @@
+schema: spec-driven
+created: 2026-04-17
+created_by: che cheng <kiki830621@gmail.com>
+created_with: claude
+archived_by: che cheng <kiki830621@gmail.com>
+archived_at: 2026-04-17
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/proposal.md b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/proposal.md
new file mode 100644
index 00000000..05979a0c
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/proposal.md
@@ -0,0 +1,51 @@
+## Why
+
+Phase 1 (`archive-mail-downloads-and-routing`, v2.3.0) shipped attachment download + routing. But two structural gaps remain:
+
+1. **Filter asymmetry (#24 bug)**: `/archive-mail tatsuma` only matches emails where "tatsuma" appears in sender/to. Internal multi-party discussions (Che ↔ Lay ↔ Pei-Chi without Tatsuma in cc) are invisible — 21 emails + 14 attachments were missed in the 2026-04-14 tatsuma audit. The root cause: `mail__search_emails` with `query: filter, field: sender` cannot capture threads where the external collaborator is absent from sender/to.
+
+2. **No coverage audit (#25 feature)**: after archive-mail runs, there's no verification that (a) all attachments were actually downloaded (save_attachment could silently fail) or (b) the thread corpus is complete (no sibling emails missing from the archive). The 2026-04-14 audit was a 1+ hour manual cross-check.
+
+This change is **Phase 2**, closing `#24` and `#25`.
+
+## What Changes
+
+### Filter expansion (#24)
+
+- **Subject-keyword matching**: new optional `subject_keywords` field in `.claude/emails.md` YAML (e.g., `[taxometric, SSQ, paper]`). After the sender-based search (unchanged), a second pass searches by subject keyword. Union of both results. Deduplication by Message-ID.
+- **Participant aliases**: new optional `participant_aliases` field (map of `email_address → canonical_name`). When a sender-based match returns a thread, the skill follows the thread's subject to find sibling messages from other participants (including internal-only threads). Not a new MCP call — uses the same `search_emails` but with `field: subject` and the matched thread's subject.
+- **Thread-subject expansion**: for each email found by the initial sender search, extract its subject (strip `Re:` / `Fwd:` prefixes), search again by that bare subject. This catches internal follow-ups that share the same thread subject but lack the external collaborator in sender/to.
+
+### Coverage audit (#25)
+
+- **New Step 8** (after Step 7 report): `list_attachments_batch` on all archived emails, cross-check against disk files. Warn for any email whose reported attachment count doesn't match disk count.
+- **Thread completeness check**: for each unique thread subject in the archive, search for additional messages with the same subject that were NOT archived. Report as "potential missing thread siblings".
+- **Output**: audit report appended to the Step 7 output, showing warnings and a "coverage score" (`archived/total_found` for both emails and attachments).
+
+## Non-Goals
+
+- Not implementing `--backfill-attachments` or `--backfill-thread` auto-repair flags — those require transactional behavior (download + update index atomically) that the current skill structure doesn't support well. Deferred to a future change.
+- Not using `In-Reply-To` / `Message-ID` chains for thread tracking — requires MCP `get_email_headers` which adds latency per email. Subject-based heuristic is good enough for 90%+ of academic email threads.
+- Not auto-correcting the archive when audit finds gaps — audit REPORTS issues but doesn't fix them. Users re-run `/archive-mail` with expanded config to fill gaps.
+
+## Capabilities
+
+### New Capabilities
+
+- `archive-mail-filter-expansion`: Defines how `/archive-mail` expands beyond sender-based search to capture complete thread corpora using subject keywords, participant aliases, and thread-subject expansion.
+
+### Modified Capabilities
+
+- `archive-mail-attachments`: ADDS the coverage audit step (Step 8) that validates attachment download completeness and thread coverage after the main archive flow completes.
+
+## Impact
+
+- **Affected specs**:
+  - New: `openspec/specs/archive-mail-filter-expansion/spec.md`
+  - Modified: `openspec/specs/archive-mail-attachments/spec.md` (adds audit requirement)
+- **Affected code**:
+  - Modified: `plugins/che-apple-mail-mcp/commands/archive-mail.md` (~310 → ~400 lines after Phase 2)
+- **Config schema**:
+  - New optional fields in `.claude/emails.md`: `subject_keywords: [String]`, `participant_aliases: { email: canonical_name }`
+- **Closes**: [`#24`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/24), [`#25`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/25)
+- **Completes**: [`PsychQuant/macdoc#75`](https://github.com/PsychQuant/macdoc/issues/75) Layer 3
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/specs/archive-mail-attachments/spec.md b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/specs/archive-mail-attachments/spec.md
new file mode 100644
index 00000000..070a9d78
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/specs/archive-mail-attachments/spec.md
@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Coverage audit validates attachment completeness
+
+After the main archive flow (Step 7 report), the skill SHALL run a coverage audit (Step 8) that:
+
+1. Calls `list_attachments_batch` on all newly archived emails
+2. Compares the reported attachment count per email against actual files on disk in the corresponding attachment directory
+3. Reports any mismatches as warnings
+
+#### Scenario: All attachments present on disk
+
+- **WHEN** an email reports 2 attachments and both files exist on disk in the expected directory
+- **THEN** the audit reports no warning for that email
+
+#### Scenario: Missing attachment detected
+
+- **WHEN** an email reports 3 attachments but only 2 files exist on disk
+- **THEN** the audit emits a warning: `⚠️ {email_stem}: 1 attachment missing (expected 3, found 2)`
+
+---
+
+### Requirement: Thread completeness check identifies potential gaps
+
+The coverage audit SHALL, for each unique bare subject in the archive, search for additional messages with that subject that were NOT archived. These are reported as "potential missing thread siblings" for user review.
+
+#### Scenario: Missing sibling detected
+
+- **WHEN** the archive contains 3 emails with subject "Re: Taxometric Analysis" but a search finds 5 total messages with that bare subject
+- **THEN** the audit reports: `⚠️ Thread "Taxometric Analysis": 2 potential missing siblings (archived 3/5)`
+
+#### Scenario: Complete thread
+
+- **WHEN** all messages with a given subject are already in the archive
+- **THEN** no thread-completeness warning is emitted for that subject
+
+---
+
+### Requirement: Audit report format
+
+The audit output SHALL be appended after the Step 7 archive report, in a clearly separated section:
+
+```
+Archive Coverage Audit
+═══════════════════════════════════════════
+Attachment coverage: 15/15 (100%)
+Thread coverage: 3 threads, 2 complete, 1 with gaps
+
+Issues:
+  ⚠️ {email_stem}: 1 attachment missing
+  ⚠️ Thread "Subject": 2 potential missing siblings
+
+Run /archive-mail with expanded subject_keywords to fill gaps.
+═══════════════════════════════════════════
+```
+
+#### Scenario: Clean audit
+
+- **WHEN** all attachments are present and all threads are complete
+- **THEN** the audit section shows `Attachment coverage: N/N (100%)` and `Thread coverage: M threads, M complete, 0 with gaps` with no Issues section
+
+#### Scenario: Issues found
+
+- **WHEN** the audit finds 1 missing attachment and 1 incomplete thread
+- **THEN** the Issues section lists both warnings with actionable guidance
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/specs/archive-mail-filter-expansion/spec.md b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/specs/archive-mail-filter-expansion/spec.md
new file mode 100644
index 00000000..a0af8648
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/specs/archive-mail-filter-expansion/spec.md
@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Subject-keyword search expands email corpus
+
+After the sender-based search (Step 3), the skill SHALL perform a second search pass using each entry in the optional `subject_keywords` config field. Results are unioned with the sender-based results and deduplicated by Message-ID.
+
+#### Scenario: Subject keyword finds internal-only thread
+
+- **WHEN** `/archive-mail tatsuma` runs with `subject_keywords: [taxometric]` and an internal email between Che and Lay has subject "Re: Taxometric indicator selection" (no "tatsuma" in sender/to)
+- **THEN** that email is included in the archive corpus because "taxometric" matches the subject
+
+#### Scenario: No subject_keywords configured skips second pass
+
+- **WHEN** `.claude/emails.md` has no `subject_keywords` field
+- **THEN** only the sender-based search results are used (backward compatible)
+
+---
+
+### Requirement: Thread-subject expansion discovers sibling messages
+
+For each email found by the initial sender-based search, the skill SHALL extract the bare subject (strip `Re:` / `RE:` / `Fwd:` / `FW:` prefixes), then search for additional messages with the same bare subject. This captures reply-chain siblings where the original filter string does not appear in sender/to.
+
+#### Scenario: Internal reply to external thread is captured
+
+- **WHEN** the sender search finds "Tatsuma → Lay: Re: Taxometric Analysis" and thread-subject expansion searches for bare subject "Taxometric Analysis"
+- **THEN** "Lay → Che: Re: Taxometric Analysis" (internal, no Tatsuma) is also captured
+
+#### Scenario: Unrelated email with similar subject is deduplicated
+
+- **WHEN** thread-subject expansion finds a duplicate (same Message-ID already in corpus)
+- **THEN** the duplicate is skipped without error
+
+---
+
+### Requirement: Participant aliases config field
+
+`.claude/emails.md` SHALL support an optional `participant_aliases` YAML field mapping email addresses to canonical names. This field is informational for the current Phase 2 scope (used in audit reports and future display) but does not change search behavior.
+
+#### Scenario: Alias present in config
+
+- **WHEN** `.claude/emails.md` contains `participant_aliases: { "b08801008@ntu.edu.tw": "Pei-Chi" }`
+- **THEN** the skill acknowledges the alias for audit reporting purposes
+
+#### Scenario: No aliases configured
+
+- **WHEN** `.claude/emails.md` has no `participant_aliases` field
+- **THEN** the skill operates normally without alias resolution
diff --git a/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/tasks.md b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/tasks.md
new file mode 100644
index 00000000..3c0d321f
--- /dev/null
+++ b/openspec/changes/archive/2026-04-17-archive-mail-filter-and-audit/tasks.md
@@ -0,0 +1,31 @@
+## 1. Config schema expansion
+
+- [x] 1.1 Add `subject_keywords: [String]` optional field parsing in Step 2 of `archive-mail.md` per **Subject-keyword search expands email corpus** requirement. When absent, skip subject-keyword pass.
+- [x] 1.2 Add `participant_aliases: { email: name }` optional field parsing per **Participant aliases config field** requirement. Store for audit reporting.
+- [x] 1.3 Document both new fields in the config example section at the bottom of `archive-mail.md`
+
+## 2. Filter expansion (#24)
+
+- [x] 2.1 Per **Subject-keyword search expands email corpus** — after the existing sender-based search in Step 3, add a second search loop: for each keyword in `subject_keywords`, call `search_emails` with `field: subject` and `query: keyword`. Collect results.
+- [x] 2.2 Per **Thread-subject expansion discovers sibling messages** — for each email found by the sender search, extract the bare subject (strip `Re:` / `RE:` / `Fwd:` / `FW:` prefixes via regex `^(Re|RE|Fwd|FW|转发|轉寄):\s*`), then search with `field: subject` and `query: bare_subject`. Collect results.
+- [x] 2.3 Union all three result sets (sender + subject_keywords + thread-subject) and deduplicate by Message-ID. Feed the deduplicated corpus into Step 4 (filter new).
+- [x] 2.4 Add a note in the Step 7 report showing expanded corpus stats: `搜尋結果: {sender_count} by sender + {keyword_count} by subject keyword + {thread_count} by thread expansion = {total_unique} unique (after dedup)`
+
+## 3. Coverage audit (#25)
+
+- [x] 3.1 Add new Step 8 "Coverage Audit" after Step 7 per **Coverage audit validates attachment completeness** requirement. For each newly archived email, call `list_attachments` and compare count against actual files in the expected disk directory.
+- [x] 3.2 Per **Thread completeness check identifies potential gaps** requirement: for each unique bare subject in the archive, search for total message count with that subject; compare against archived count. Report any gap as "potential missing thread siblings".
+- [x] 3.3 Per **Audit report format** requirement: append the audit section to Step 7 output with attachment coverage percentage, thread coverage summary, and Issues list. Clean audit shows 100% with no Issues section.
+
+## 4. Documentation + deployment
+
+- [x] 4.1 Update skill description and usage notes to mention subject_keywords, participant_aliases, and the coverage audit step
+- [x] 4.2 Bump version in `plugins/che-apple-mail-mcp/.claude-plugin/plugin.json` to 2.4.0
+- [x] 4.3 Deploy via `/plugin-tools:plugin-deploy`
+
+## 5. Issue closure
+
+- [x] 5.1 Post implementation-complete comment on #24 referencing the deployed version
+- [x] 5.2 Post implementation-complete comment on #25
+- [x] 5.3 Close both via `/idd-close` with gate-checked closing summaries (no `Closes` trailer in commits)
+- [x] 5.4 Update `PsychQuant/macdoc#75` umbrella: tick #24 and #25 in Layer 3; add progress note; Layer 3 fully complete
diff --git a/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/.openspec.yaml b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/.openspec.yaml
new file mode 100644
index 00000000..c6b8e734
--- /dev/null
+++ b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/.openspec.yaml
@@ -0,0 +1,6 @@
+schema: spec-driven
+created: 2026-05-13
+created_by: che cheng <kiki830621@gmail.com>
+created_with: claude
+archived_by: che cheng <kiki830621@gmail.com>
+archived_at: 2026-05-13
diff --git a/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/design.md b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/design.md
new file mode 100644
index 00000000..13a65e90
--- /dev/null
+++ b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/design.md
@@ -0,0 +1,150 @@
+## Context
+
+`/shiny-adaptive-walk` is a Claude Code slash-command skill in `plugins/r-shiny-debugger` that drives the MP165 v1.2 Track B adaptive overlay for the QEF dashboard verification system. It runs a multi-iteration self-converging loop: each iteration walks a Shiny dashboard, classifies defects via an LLM judge, and either files them as bugs (real_bug) or mutates the test infrastructure (test_infra_gap). The loop typically targets 5 companies (QEF_DESIGN / D_RACING / MAMBA / WISER / kitchenMAMA) and can take multiple hours.
+
+The skill's Step 3a (Discovery walk) currently hard-codes `safari-browser` as the browser driver, with `which safari-browser || abort ...` in pre-flight (Step 0). The skill markdown frames this as "real renderer ground truth" and includes an Anti-pattern table entry explicitly forbidding `agent-browser` for discovery.
+
+During a manual execution on 2026-05-13 (kiki830621/ai_martech_global_scripts#665), the safari-only mandate broke for environmental reasons unrelated to the dashboard under test: parallel ChatGPT usage stole tab focus, the user-profile-bound Safari context caused reproducibility drift, and per-iteration Safari startup added latency. The operator switched to `agent-browser` mid-walk to complete the iteration. The `/spectra-discuss` session that followed established that:
+
+- Both `safari-browser` (WebKit) and `agent-browser` (headless Chromium) render real DOM. For Shiny apps using bs4Dash + plotly + DT, engine-level rendering differences are effectively zero.
+- The only genuine differentiator is realtime visibility — `safari-browser` shows the loop iterating in a visible window; `agent-browser` is headless.
+- Realtime visibility delivers value only when a human is actively watching. For unattended / CI / multi-hour runs, visibility is worth nothing while headlessness is worth latency reduction and reproducibility gains.
+
+The skill's default therefore points at the wrong tool. This design captures the inversion.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make `agent-browser` the default for the discovery walk so unattended and multi-hour invocations are stable + fast by default.
+- Provide an explicit opt-in (`--browser safari`) for the live-watch scenario without breaking that path.
+- Capture the rationale persistently so future maintainers don't re-instate the safari-mandatory framing.
+- Document a single source of truth for browser dispatch (helper function) so future changes to the browser layer touch one spot.
+
+**Non-Goals:**
+
+- Not introducing auto-detection or auto-fallback. Mode is explicit (flag > env > static default). The earlier diagnosis suggested probing Safari window count to decide — rejected because `agent-browser` is no longer a "fallback", it is the default, so there is nothing to probe for.
+- Not supporting a third browser (e.g. native Chrome, Firefox). The plugin already chose safari + agent as its supported pair.
+- Not unifying the mechanical regression phase (Step 3d safety gate) with the discovery walk's browser choice. Mechanical regression has always used `agent-browser` and continues to — it is not user-facing visibility, so safari was never a valid option there.
+- Not making the dispatcher pluggable for arbitrary browser CLIs. The dispatcher knows exactly two backends; extensibility is YAGNI.
+
+## Decisions
+
+### Default browser: agent
+
+`/shiny-adaptive-walk` default browser is `agent-browser` (headless Chromium). `safari-browser` is opt-in via `--browser safari`.
+
+**Rationale**: The `/spectra-discuss` analysis showed `safari-browser`'s "real renderer ground truth" framing was Safari-bias rather than fact. Both engines render real DOM; for the dashboard under test, no engine-specific rendering differences matter. The genuine advantage of safari (realtime visibility) only applies when a human watches the loop iterate, which is not the dominant use case (Phase 5 cross-co rollout is multi-hour and unattended). Defaulting to safari forces every unattended invocation to pay startup latency, fight tab-focus contention, and inherit user-profile state drift, in exchange for visibility that nobody is consuming.
+
+**Alternative considered**: keep `safari-browser` as default and add auto-fallback to `agent-browser` when pre-flight detects multiple Safari windows or missing CLI. Rejected because the "fallback" framing treats agent as inferior, which the analysis rejected. Auto-fallback also introduces a runtime heuristic (window count threshold) whose threshold is arbitrary — `> 1`, `> 2`, or some focus-aware probe each have boundary cases the other misses. Explicit selection removes the entire class of pre-flight ambiguity.
+
+### Dispatcher: helper function (Option A)
+
+A single `browser_cmd()` shell function dispatches discovery primitives. All ~14 `safari-browser X --url "$URL_SUBSTR"` call sites in Step 3a become `browser_cmd X`.
+
+```bash
+browser_cmd() {
+  local subcmd="$1"; shift
+  if [ "$BROWSER" = "safari" ]; then
+    safari-browser "$subcmd" "$@" --url "$URL_SUBSTR"
+  else
+    agent-browser "$subcmd" "$@"
+  fi
+}
+```
+
+**Rationale**: Discovery primitives (open / snapshot / click / fill / screenshot) map 1:1 between the two CLIs by subcommand name. The only meaningful API difference is `--url "$URL_SUBSTR"` for safari tab targeting, which agent doesn't need (single ephemeral context). A 10-line helper consolidates the dispatch logic, replaces 14 call-site rewrites with 14 trivial substitutions, and gives future browser-related changes a single edit point.
+
+**Alternatives considered**:
+
+- **Option B (inline if/else at each call site)**: rejected. Doubles Step 3a from ~60 lines to ~120 lines, repeats the same conditional 14 times, and any future browser-layer change requires touching 14 places. No upside.
+- **Option C (function-per-primitive: `discovery_open()` / `discovery_login()` / `discovery_walk_tab()` etc.)**: rejected for over-abstraction. The primitives are thin wrappers around a single CLI invocation each; wrapping them in another function tier adds indirection without behavioral abstraction. Suitable if the discovery layer grew much more complex; YAGNI for the current scope.
+
+### Selection precedence: flag > env > static default
+
+```
+1. `--browser=safari|agent` flag (highest)
+2. `SHINY_ADAPTIVE_BROWSER` environment variable
+3. Static default: `agent`
+```
+
+**Rationale**: Standard CLI / 12-factor convention. Flag overrides env (per-invocation override of session-wide setting); env overrides default (lets shells / CI configure once). Unknown values (anything other than `safari` or `agent`) abort with an error in both flag and env path.
+
+**Alternative considered**: a binary `--watch` flag (presence implies safari, absence implies agent). Rejected on naming grounds: `--watch` is commonly understood as file-system watching, would mislead users. `--browser=mechanism` is more explicit and survives future browser additions without rename.
+
+### Pre-flight: mode-specific CLI presence check
+
+Pre-flight (Step 0) checks browser CLI presence for the **selected** browser only:
+
+- `--browser safari` → require `safari-browser` CLI, abort if missing.
+- `--browser agent` (default) → require `agent-browser` CLI, abort if missing.
+
+Drop the WIN_COUNT detection and `safari-browser documents` parsing entirely.
+
+**Rationale**: Each mode has exactly one CLI dependency. The WIN_COUNT heuristic was meaningful only when safari was default and agent was fallback (deciding when to fall back). With explicit selection, the heuristic has no decision to inform.
+
+### Audit trail: per-iteration commit body emits `BROWSER=<mode>`
+
+Each per-iteration commit (existing `iter-N: ... (refs #N)` format) gains one line in the commit body: `BROWSER=safari` or `BROWSER=agent`. No fallback-reason logging (no fallback exists). Final report does not duplicate this — commit history is the single source of truth.
+
+**Rationale**: Cheapest possible audit trail. Per-iteration commits already exist for atomic rollback; adding one line is free. Future debugging of "why did iter 3 produce different screenshots than iter 2" can grep commit history. Avoids verbosity in the final report.
+
+### Anti-pattern table entry removed, not qualified
+
+Line 583 of the skill markdown (`Use agent-browser for discovery walk → Use safari-browser`) is removed outright, not softened to "Use agent-browser when safari unavailable". Adding a new "When to opt into `--browser safari`" section in the Configuration area replaces it.
+
+**Rationale**: A qualified anti-pattern entry still implies agent is inferior. The conclusion from `/spectra-discuss` was that agent is the default. Keeping a softened entry would invite future regression toward safari-mandatory behavior.
+
+## Implementation Contract
+
+**Observable behavior after this change ships:**
+
+- Invoking `/shiny-adaptive-walk <COMPANY>` with no `--browser` flag and no `SHINY_ADAPTIVE_BROWSER` env var uses headless `agent-browser` for the discovery walk. The Shiny app being walked sees a Chromium user agent. No Safari window appears on screen.
+- Invoking `/shiny-adaptive-walk <COMPANY> --browser safari` uses `safari-browser`. A Safari window becomes visible (or focuses an existing one matching the URL). The skill continues to use `--url "$URL_SUBSTR"` for tab targeting in safari mode.
+- Invoking with `SHINY_ADAPTIVE_BROWSER=safari` (no flag) is equivalent to `--browser safari`. Flag overrides env when both are set.
+- Invoking `/shiny-adaptive-walk <COMPANY> --browser agent` with `agent-browser` CLI missing aborts pre-flight with a message naming the missing CLI. Same shape of failure as before for safari, just for the other CLI.
+- Each per-iteration commit body contains exactly one `BROWSER=<safari|agent>` line. Auditors can grep `git log --grep "BROWSER=" --pretty=fuller` over the loop's branch to see which browser drove which iteration.
+
+**Interface / contracts:**
+
+- `--browser` flag accepts exactly two values: `safari` or `agent`. Any other value (including empty string, mixed case, `chrome`, etc.) aborts with an error naming the accepted values.
+- `SHINY_ADAPTIVE_BROWSER` env var has the same value domain and same error shape on invalid input.
+- `browser_cmd()` shell helper signature: `browser_cmd <subcmd> [args...]`. Subcommand is forwarded to the chosen CLI verbatim. Caller does not pass `--url` — the helper supplies it for safari mode.
+- Anti-pattern table no longer contains an entry for `agent-browser` for discovery walk.
+- New section heading "When to opt into `--browser safari`" appears under the Configuration heading in the skill markdown.
+
+**Failure modes:**
+
+- Selected browser CLI missing → abort in Step 0 with `<CLI> required (pass --browser=<other> to switch)`. No silent fallback. No retry.
+- Invalid `--browser` value → abort with `--browser must be one of: safari, agent (got: X)`. No silent normalization (no auto-correcting `Safari` → `safari`).
+- Invalid `SHINY_ADAPTIVE_BROWSER` value → same shape as above, but error message names the env var.
+- `browser_cmd()` invoked with a subcommand that one of the CLIs does not support → the underlying CLI's own error surfaces (e.g. `safari-browser: unknown command 'foo'`). Helper does not pre-validate subcommands. Documentation lists the supported primitive set.
+
+**Acceptance criteria:**
+
+- AC1: `/shiny-adaptive-walk QEF_DESIGN` with no flag and no env var completes a single iteration using headless Chromium. `ps` during execution shows an `agent-browser` process, no Safari process spawn. No window appears.
+- AC2: `/shiny-adaptive-walk QEF_DESIGN --browser safari` completes a single iteration with a visible Safari window (or focused existing tab). Same screenshots produced (modulo engine-level pixel-perfect differences). Same commit shape.
+- AC3: Each per-iteration commit body contains exactly one `BROWSER=` line, matching the selected mode.
+- AC4: Existing Phase 1 unit tests (`98_test/test_contract_primitives.R`) and Phase 2 walker tests (`98_test/test_smoke_lite_walker.R`) continue to pass after the skill markdown change. (These tests do not depend on the skill markdown directly, so this is a regression guard rather than direct coverage.)
+- AC5: `grep -n "Use agent-browser for discovery walk" plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md` returns zero hits after the change.
+- AC6: `grep -n "When to opt into \`--browser safari\`" plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md` returns one hit.
+
+**Scope boundaries:**
+
+In scope:
+- Skill markdown: Step 0 (pre-flight), Step 3a (discovery walk dispatcher), Anti-pattern table, Configuration reference, Troubleshooting, new "When to opt into `--browser safari`" section, frontmatter description if it references "safari-browser".
+- README rationale section (optional but recommended for plugin marketplace consumers reading the README first).
+
+Out of scope:
+- `kiki830621/ai_martech_global_scripts` `00_principles/.claude/rules/08-shiny-testing.md` narrow exception clause (consistency only — clause stays accurate as written).
+- Mechanical regression phase (Step 3d) browser choice.
+- `/shiny-debug` sister skill (different lifecycle — single-pass interactive, never adaptive).
+- Plugin-marketplace versioning (`plugin.json` bump) — handled by `/plugin-update` separately if needed.
+
+## Risks / Trade-offs
+
+- **[Live-watch users surprised by headless default]** → Mitigation: add prominent "When to opt into `--browser safari`" section near top of skill markdown; mention in release notes for the plugin version bump. Default change is BREAKING and called out explicitly in proposal What Changes.
+- **[Per-iteration commit body bloat]** → Mitigation: one `BROWSER=` line is ~15 bytes; over a typical 5-iteration converge that's 75 bytes total. Negligible.
+- **[Engine-specific edge cases surface only when running safari]** → Mitigation: when a user explicitly opts into safari, they accept it. Default-agent users get Chromium consistently. If a future bug emerges that only reproduces in WebKit, the opt-in path is available.
+- **[Dispatcher leaks `--url` to environments that don't want it]** → Mitigation: helper only appends `--url` in safari mode; agent path never sees it. Single source of truth makes future audit easy.
+- **[Migration friction for in-flight `/shiny-adaptive-walk` invocations]** → Mitigation: no in-flight automation calls this skill yet; today's manual invocations all set their own `--browser` if needed. No data migration involved.
diff --git a/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/proposal.md b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/proposal.md
new file mode 100644
index 00000000..122f65c1
--- /dev/null
+++ b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/proposal.md
@@ -0,0 +1,53 @@
+## Why
+
+The `/shiny-adaptive-walk` skill (in `plugins/r-shiny-debugger`) currently mandates `safari-browser` for the discovery walk phase and hard-aborts if it is missing. The original rationale framed `safari-browser` as "real renderer ground truth", positioning `agent-browser` as a lesser substitute. Field experience (kiki830621/ai_martech_global_scripts#665 walker run on 2026-05-13) showed this framing is inaccurate: both `safari-browser` (WebKit) and `agent-browser` (headless Chromium) render real DOM and produce equally valid screenshots for LLM-judge classification. The genuine differences are:
+
+- `agent-browser`: headless, faster, reproducible (ephemeral context, no user profile contamination), immune to macOS Safari tab-focus contention.
+- `safari-browser`: provides realtime visibility for a human watching the loop iterate.
+
+Realtime visibility only matters when a user is present. For unattended, multi-hour, or cross-company runs (Phase 5 cross-co rollout target: QEF_DESIGN / D_RACING / MAMBA / WISER / kitchenMAMA), visibility delivers zero value while focus-stealing and per-iteration Safari startup overhead degrade reliability. The default therefore points at the wrong tool, forcing every user (including the AI itself during manual orchestration) to work around an opinion that does not survive scrutiny.
+
+## What Changes
+
+- **BREAKING**: Default browser for `/shiny-adaptive-walk` discovery walk changes from `safari-browser` to `agent-browser`. Invocations that previously implicitly relied on `safari-browser` continue to work but now use `agent-browser` unless explicitly overridden.
+- Introduce `--browser=safari|agent` flag for explicit selection. `agent` is the default; `safari` is opt-in for "I want to watch the loop iterate" scenarios (live demo, teaching, in-the-moment debugging).
+- Introduce `SHINY_ADAPTIVE_BROWSER` environment variable accepting the same values (`safari` / `agent`). Precedence: `--browser` flag > `SHINY_ADAPTIVE_BROWSER` env var > default (`agent`).
+- Introduce `browser_cmd()` shell helper that dispatches one set of discovery primitives (open / snapshot / click / fill / screenshot) to either `safari-browser` (with `--url "$URL_SUBSTR"` flag for tab targeting) or `agent-browser` (headless, single context).
+- Replace `which safari-browser || abort ...` pre-flight check (Step 0) with two-mode logic: if `--browser safari` is selected, fail loudly when `safari-browser` CLI is absent; if `--browser agent` (default), only verify `agent-browser` CLI presence.
+- Remove the WIN_COUNT detection / auto-fallback logic suggested in earlier diagnoses of this issue (no longer needed once `agent-browser` is the default — there is nothing to fall back to).
+- Anti-pattern table entry "Use `agent-browser` for discovery walk → Use `safari-browser`" (line 583 of the skill markdown) is removed. Using `agent-browser` for discovery is no longer an anti-pattern; it is the recommended default.
+- Add a new "When to opt into `--browser safari`" section to the skill markdown documenting when realtime visibility justifies the trade-off.
+- Update the Configuration reference table to add `--browser` flag and `SHINY_ADAPTIVE_BROWSER` env var rows.
+- Update Troubleshooting to remove "skill REQUIRES safari-browser" language; replace with guidance on each browser mode's failure surfaces.
+- Per-iteration commit message body emits one `BROWSER=<safari|agent>` line for audit-trail traceability (which browser produced the iteration's evidence).
+
+## Non-Goals
+
+- This change does NOT modify the mechanical regression phase (Step 3d safety gate); it has always used `agent-browser` and continues to.
+- This change does NOT introduce any browser other than `safari-browser` or `agent-browser`. Future support for additional browsers (e.g. native Chrome / Firefox) is explicitly out of scope.
+- This change does NOT introduce auto-detection or auto-fallback between modes. Mode is determined explicitly by `--browser` flag, then `SHINY_ADAPTIVE_BROWSER` env, then the static default (`agent`). No runtime environment probing.
+- This change does NOT modify the LLM-judge classification logic, the dedup/sister-bug filing logic, or the convergence model. Browser selection is orthogonal to all downstream phases.
+- This change does NOT alter the cross-reference in `kiki830621/ai_martech_global_scripts` `00_principles/.claude/rules/08-shiny-testing.md` narrow exception clause. That clause says "safari-browser is permitted on local for adaptive-walker discovery"; it remains accurate (safari is still permitted, just no longer the default).
+
+## Capabilities
+
+### New Capabilities
+
+- `shiny-adaptive-walk-browser`: Browser selection contract for the shiny-adaptive-walk skill's discovery walk phase. Defines the `--browser` flag, `SHINY_ADAPTIVE_BROWSER` env var, the default (`agent`), the dispatcher helper, and the audit-trail emission per iteration.
+
+### Modified Capabilities
+
+(none — the shiny-adaptive-walk skill does not yet have an explicit spec in the openspec specs directory; this change creates the first formal contract for one aspect of the skill)
+
+## Impact
+
+- Affected specs:
+  - New: `openspec/specs/shiny-adaptive-walk-browser/spec.md`
+- Affected code:
+  - Modified: `plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md` (Step 0 pre-flight, Step 3a discovery walk dispatcher, Anti-pattern table, Configuration reference, Troubleshooting)
+  - Modified: `plugins/r-shiny-debugger/README.md` (optional — add browser-mode rationale section near skill description)
+  - New: (none — single-file refactor)
+  - Removed: (none)
+- Downstream behavior:
+  - Manual or AI-driven `/shiny-adaptive-walk QEF_DESIGN` invocations now headless-by-default. Live observation requires explicit `--browser safari`.
+  - Existing local CI invocations remain functional; they previously failed if `safari-browser` was missing, now succeed (the abort path is gone for the default mode).
diff --git a/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/specs/shiny-adaptive-walk-browser/spec.md b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/specs/shiny-adaptive-walk-browser/spec.md
new file mode 100644
index 00000000..9ea45470
--- /dev/null
+++ b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/specs/shiny-adaptive-walk-browser/spec.md
@@ -0,0 +1,144 @@
+## ADDED Requirements
+
+### Requirement: Default Browser SHALL Be agent-browser
+
+The `/shiny-adaptive-walk` skill SHALL use `agent-browser` (headless Chromium) for the discovery walk phase when no explicit browser is specified via flag or environment variable. The skill SHALL NOT use `safari-browser` as the default.
+
+#### Scenario: Default invocation with no overrides
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY>` with no `--browser` flag and no `SHINY_ADAPTIVE_BROWSER` environment variable set
+- **THEN** the skill SHALL invoke `agent-browser` for all discovery walk primitives (open, snapshot, click, fill, screenshot)
+- **AND** the skill SHALL NOT spawn or focus a `safari-browser` window
+- **AND** the per-iteration commit body SHALL contain the line `BROWSER=agent`
+
+### Requirement: Browser Selection Flag SHALL Accept Two Values
+
+The skill SHALL accept a `--browser` flag with exactly two valid values: `safari` and `agent`. The flag SHALL be parsed alongside existing flags (`--budget`, `--max-iter`, `--no-pr`) in the Step 0 pre-flight phase.
+
+#### Scenario: Explicit safari selection via flag
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser safari`
+- **THEN** the skill SHALL invoke `safari-browser` for the discovery walk
+- **AND** the skill SHALL pass `--url "$URL_SUBSTR"` to every safari-browser subcommand for tab targeting
+- **AND** the per-iteration commit body SHALL contain the line `BROWSER=safari`
+
+#### Scenario: Explicit agent selection via flag
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser agent`
+- **THEN** the skill SHALL invoke `agent-browser` for the discovery walk
+- **AND** the per-iteration commit body SHALL contain the line `BROWSER=agent`
+
+#### Scenario: Invalid --browser value
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser chrome`
+- **THEN** the skill SHALL abort in Step 0 pre-flight with an error message naming the accepted values
+- **AND** no app launch SHALL occur
+
+##### Example: Invalid value error
+
+- **GIVEN** invocation `/shiny-adaptive-walk QEF_DESIGN --browser firefox`
+- **WHEN** Step 0 pre-flight parses the flag
+- **THEN** the skill exits non-zero with a message containing `--browser must be one of: safari, agent (got: firefox)`
+
+### Requirement: Browser Selection Environment Variable SHALL Accept Same Values
+
+The skill SHALL accept a `SHINY_ADAPTIVE_BROWSER` environment variable with the same value domain as the `--browser` flag (`safari` or `agent`). The flag SHALL take precedence over the environment variable when both are set.
+
+#### Scenario: Environment variable sets safari mode
+
+- **WHEN** the user invokes `SHINY_ADAPTIVE_BROWSER=safari /shiny-adaptive-walk <COMPANY>` with no `--browser` flag
+- **THEN** the skill SHALL invoke `safari-browser` for the discovery walk
+
+#### Scenario: Flag overrides environment variable
+
+- **WHEN** the user invokes `SHINY_ADAPTIVE_BROWSER=safari /shiny-adaptive-walk <COMPANY> --browser agent`
+- **THEN** the skill SHALL invoke `agent-browser` for the discovery walk
+
+##### Example: Precedence table
+
+| Flag        | Env var                      | Effective browser |
+| ----------- | ---------------------------- | ----------------- |
+| (unset)     | (unset)                      | agent (default)   |
+| (unset)     | SHINY_ADAPTIVE_BROWSER=safari| safari            |
+| (unset)     | SHINY_ADAPTIVE_BROWSER=agent | agent             |
+| --browser=safari | (unset)                 | safari            |
+| --browser=agent  | SHINY_ADAPTIVE_BROWSER=safari | agent (flag wins) |
+| --browser=safari | SHINY_ADAPTIVE_BROWSER=agent  | safari (flag wins) |
+
+### Requirement: Pre-flight SHALL Check Only Selected Browser CLI
+
+Step 0 pre-flight SHALL verify the presence of the CLI for the selected browser. The skill SHALL NOT require both CLIs to be present.
+
+#### Scenario: agent-browser CLI missing while safari is selected
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser safari` on a system where `agent-browser` is missing but `safari-browser` is present
+- **THEN** the skill SHALL proceed past pre-flight (because `agent-browser` is not needed for this invocation)
+- **AND** the discovery walk SHALL succeed using `safari-browser`
+
+#### Scenario: safari-browser CLI missing while default is in effect
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY>` with no overrides on a system where `safari-browser` is missing but `agent-browser` is present (e.g. Linux CI)
+- **THEN** the skill SHALL proceed past pre-flight (because `safari-browser` is not needed for the default agent path)
+- **AND** the discovery walk SHALL succeed using `agent-browser`
+
+#### Scenario: Selected browser CLI missing
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser safari` on a system where `safari-browser` is missing
+- **THEN** the skill SHALL abort in Step 0 pre-flight with an error naming the missing CLI
+
+### Requirement: Single Dispatcher Helper SHALL Route Discovery Primitives
+
+The skill SHALL define a single shell helper function (`browser_cmd`) before Step 3a that routes the discovery primitives to the selected browser CLI. All call sites within Step 3a SHALL invoke primitives through this helper, not by direct `safari-browser` or `agent-browser` invocation.
+
+#### Scenario: Helper dispatches to safari with --url flag
+
+- **WHEN** the helper is invoked as `browser_cmd open "$URL"` and the selected browser is safari
+- **THEN** the helper SHALL execute `safari-browser open "$URL" --url "$URL_SUBSTR"`
+
+#### Scenario: Helper dispatches to agent without --url flag
+
+- **WHEN** the helper is invoked as `browser_cmd open "$URL"` and the selected browser is agent
+- **THEN** the helper SHALL execute `agent-browser open "$URL"`
+- **AND** the helper SHALL NOT pass any `--url` argument to `agent-browser`
+
+##### Example: Dispatch table
+
+| Helper call                    | safari mode resolves to                                                | agent mode resolves to                |
+| ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------- |
+| `browser_cmd open "$URL"`      | `safari-browser open "$URL" --url "$URL_SUBSTR"`                       | `agent-browser open "$URL"`           |
+| `browser_cmd snapshot -i`      | `safari-browser snapshot -i --url "$URL_SUBSTR"`                       | `agent-browser snapshot -i`           |
+| `browser_cmd click @e2`        | `safari-browser click @e2 --url "$URL_SUBSTR"`                         | `agent-browser click @e2`             |
+| `browser_cmd fill @e1 VIBE`    | `safari-browser fill @e1 VIBE --url "$URL_SUBSTR"`                     | `agent-browser fill @e1 VIBE`         |
+| `browser_cmd screenshot file`  | `safari-browser screenshot file --url "$URL_SUBSTR"`                   | `agent-browser screenshot file`       |
+
+### Requirement: Per-Iteration Commit Body SHALL Record Browser Mode
+
+Each per-iteration commit produced by the skill (matching the existing `iter-N: <summary> (refs #<parent>)` title format) SHALL contain exactly one `BROWSER=<safari|agent>` line in the commit message body.
+
+#### Scenario: Default agent invocation records BROWSER=agent
+
+- **WHEN** the skill completes iteration N with default browser selection (no flag, no env var)
+- **THEN** `git log --pretty=fuller -1 HEAD` body SHALL contain a line equal to `BROWSER=agent`
+
+#### Scenario: Explicit safari invocation records BROWSER=safari
+
+- **WHEN** the skill completes iteration N with `--browser safari`
+- **THEN** `git log --pretty=fuller -1 HEAD` body SHALL contain a line equal to `BROWSER=safari`
+
+### Requirement: Anti-Pattern Table SHALL NOT Forbid agent-browser for Discovery
+
+The skill markdown's Anti-Patterns table SHALL NOT contain an entry forbidding the use of `agent-browser` for the discovery walk phase.
+
+#### Scenario: Anti-pattern entry removed
+
+- **WHEN** a reader greps the skill markdown for the prior anti-pattern text `Use agent-browser for discovery walk`
+- **THEN** the search SHALL return zero matches
+
+### Requirement: Documentation SHALL Explain When to Opt Into safari
+
+The skill markdown SHALL include a section explaining the scenarios in which `--browser safari` is the appropriate choice (live demo / teaching / in-the-moment debugging / watching the loop iterate). The section SHALL be placed within or adjacent to the Configuration reference section.
+
+#### Scenario: Section exists
+
+- **WHEN** a reader greps the skill markdown for the heading `When to opt into`
+- **THEN** the search SHALL return at least one match within the Configuration area
diff --git a/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/tasks.md b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/tasks.md
new file mode 100644
index 00000000..806cbc1b
--- /dev/null
+++ b/openspec/changes/archive/2026-05-13-adaptive-walk-agent-browser-default/tasks.md
@@ -0,0 +1,89 @@
+# Tasks
+
+## 1. Flag and environment variable parsing
+
+- [x] 1.1 In Step 0 pre-flight of `plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md`, add `--browser=safari|agent` to the existing flag-parsing block (alongside `--budget` / `--max-iter` / `--no-pr`). Store parsed value in `BROWSER_FLAG` variable.
+- [x] 1.2 Add precedence resolution: `BROWSER="${BROWSER_FLAG:-${SHINY_ADAPTIVE_BROWSER:-agent}}"`. This makes flag override env var override the static `agent` default.
+- [x] 1.3 Validate `$BROWSER` is one of `safari` or `agent`. If not, abort with `--browser must be one of: safari, agent (got: $BROWSER)`. Same validation for `SHINY_ADAPTIVE_BROWSER` resolved value (single check covers both paths).
+
+## 2. Pre-flight CLI presence check
+
+- [x] 2.1 Remove the unconditional `which safari-browser || abort ...` line from Step 0 pre-flight.
+- [x] 2.2 Replace with mode-specific check: `if [ "$BROWSER" = "safari" ]; then which safari-browser || abort ...; else which agent-browser || abort ...; fi`. The skill SHALL require only the CLI for the selected browser.
+- [x] 2.3 Remove any earlier-diagnosed WIN_COUNT detection code or auto-fallback logic. No runtime browser probing remains after this task.
+
+## 3. Dispatcher helper function
+
+- [x] 3.1 Before Step 3a (Discovery walk), define a `browser_cmd()` shell function. The body MUST dispatch: if `$BROWSER` is `safari`, exec `safari-browser "$subcmd" "$@" --url "$URL_SUBSTR"`; otherwise exec `agent-browser "$subcmd" "$@"`. The helper SHALL accept the subcommand as `$1` and forward remaining args.
+- [x] 3.2 Verify the helper's signature is single-source-of-truth — no other dispatch logic introduced elsewhere in Step 3a. Subcommand list documented for the supported primitives (open, snapshot, click, fill, screenshot).
+
+## 4. Call-site refactor in Step 3a
+
+- [x] 4.1 In Step 3a Discovery walk pseudocode, replace `safari-browser open "$URL" --url "$URL_SUBSTR"` with `browser_cmd open "$URL"`.
+- [x] 4.2 Replace `safari-browser snapshot -i --url "$URL_SUBSTR"` invocations (login snapshot, walk snapshots) with `browser_cmd snapshot -i`.
+- [x] 4.3 Replace `safari-browser fill ... --url "$URL_SUBSTR"` with `browser_cmd fill ...` (password entry).
+- [x] 4.4 Replace `safari-browser click ... --url "$URL_SUBSTR"` with `browser_cmd click ...` (login submit + tab navigation + sub-tab clicks).
+- [x] 4.5 Replace `safari-browser screenshot ... --url "$URL_SUBSTR"` with `browser_cmd screenshot ...` (top-level and sub-tab screenshots).
+- [x] 4.6 Cross-check: no `safari-browser` or `agent-browser` literal CLI invocations remain within Step 3a outside the helper itself.
+
+## 5. Per-iteration audit trail
+
+- [x] 5.1 In Step 3d safety gate, when constructing the per-iteration commit message (`git commit -m "iter-$ITER: ..."`), append one `BROWSER=$BROWSER` line to the body section. Existing commit body content (mutations / filings summaries) remains untouched.
+- [x] 5.2 Verify the audit line is emitted exactly once per iteration, regardless of how many `browser_cmd` calls Step 3a made.
+
+## 6. Anti-pattern table cleanup
+
+- [x] 6.1 Locate the Anti-Patterns table entry beginning with `Use agent-browser for discovery walk` (previously line 583 of the skill markdown). Remove that table row entirely (do not soften the wording).
+- [x] 6.2 Verify `grep -n "Use agent-browser for discovery walk" plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md` returns zero matches after removal.
+
+## 7. Configuration reference updates
+
+- [x] 7.1 In the Configuration reference Env var table, add a row for `SHINY_ADAPTIVE_BROWSER`: default `agent`, effect describes the precedence with `--browser` flag.
+- [x] 7.2 In the Configuration reference Flags table, add a row for `--browser`: accepted values, default, link to the new opt-in section.
+
+## 8. New documentation section
+
+- [x] 8.1 Add a new H3 section under or adjacent to the Configuration reference titled `### When to opt into --browser safari`. Body explains the live-watch scenarios (live demo / teaching / in-the-moment debugging / watching the loop iterate) and contrasts with the default headless agent mode used for unattended and multi-hour runs.
+- [x] 8.2 In the 核心原則 table near the top of the skill markdown, update the visibility row (line 35) so the wording no longer implies safari is the only path to visibility; reframe as "headless agent is default; safari opt-in via `--browser safari` for live observation".
+
+## 9. Troubleshooting updates
+
+- [x] 9.1 Replace the `### safari-browser missing or wrong version` subsection's language. Drop "skill REQUIRES safari-browser" wording. Reframe as "if `--browser safari` is selected and safari-browser is missing, here are the resolution steps; otherwise the default agent path bypasses this entirely".
+- [x] 9.2 Add a parallel `### agent-browser missing` subsection covering the symmetric failure on the default path (rare on macOS / common on bare Linux).
+
+## 10. README.md rationale section (optional but recommended)
+
+- [x] 10.1 In `plugins/r-shiny-debugger/README.md`, add a short paragraph in the skill description explaining the browser-mode rationale (headless default for stability; visible safari for opt-in observation). Cross-link to the new opt-in section in the skill markdown.
+
+## 11. Final verification
+
+- [x] 11.1 Open the QEF_DESIGN app locally and invoke `/shiny-adaptive-walk QEF_DESIGN` with no flag. Confirm AC1: `ps -ef | grep agent-browser` shows the process while running, no Safari process spawn, no window appears. (This task does not require a full convergence run — a single iteration is sufficient.)
+- [x] 11.2 Invoke `/shiny-adaptive-walk QEF_DESIGN --browser safari`. Confirm AC2: a Safari window becomes visible (or focuses the matching tab), iteration completes, screenshots are equivalent to AC1's screenshots (modulo engine-level pixel differences).
+- [x] 11.3 After the two verification runs, inspect the produced commits: each per-iteration commit body SHALL contain exactly one `BROWSER=` line matching the selected mode. Run `git log --pretty=full $BRANCH -3 | grep BROWSER=` to confirm.
+- [x] 11.4 Run existing Phase 1 + Phase 2 unit tests from `kiki830621/ai_martech_global_scripts` (`NOT_CRAN=true Rscript -e 'testthat::test_file(...)'` for `test_contract_primitives.R` and `test_smoke_lite_walker.R`). Confirm AC4: both suites still pass.
+- [x] 11.5 Run `grep -n "Use agent-browser for discovery walk" plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md` (AC5 — zero hits) and `grep -n "When to opt into" plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md` (AC6 — at least one hit).
+
+## 12. Release
+
+- [x] 12.1 Bump `plugins/r-shiny-debugger/.claude-plugin/plugin.json` version from `1.1.0` to `1.2.0` (minor bump — BREAKING default change). Update CHANGELOG in the plugin entry if one exists.
+- [x] 12.2 Open a PR to `PsychQuant/psychquant-claude-plugins` main branch with summary, AC checklist, and reference to issue #77 + parent change.
+- [x] 12.3 After merge, run `/plugin-tools:plugin-update r-shiny-debugger` to sync the marketplace `marketplace.json` and update the locally-installed plugin.
+
+## 13. Spec and design coverage map
+
+This section maps the specification requirements (`specs/shiny-adaptive-walk-browser/spec.md`) and design decisions (`design.md`) to the implementation tasks above. Each task group above implements one or more requirements / decisions; this map names them explicitly so the analyzer can confirm coverage.
+
+- [x] 13.1 Satisfies requirement `Default Browser SHALL Be agent-browser` (covered by tasks 1.2, 11.1).
+- [x] 13.2 Satisfies requirement `Browser Selection Flag SHALL Accept Two Values` (covered by tasks 1.1, 1.3).
+- [x] 13.3 Satisfies requirement `Browser Selection Environment Variable SHALL Accept Same Values` (covered by tasks 1.2, 1.3).
+- [x] 13.4 Satisfies requirement `Pre-flight SHALL Check Only Selected Browser CLI` (covered by tasks 2.1, 2.2, 2.3).
+- [x] 13.5 Satisfies requirement `Single Dispatcher Helper SHALL Route Discovery Primitives` (covered by tasks 3.1, 3.2, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6).
+- [x] 13.6 Satisfies requirement `Per-Iteration Commit Body SHALL Record Browser Mode` (covered by tasks 5.1, 5.2, 11.3).
+- [x] 13.7 Satisfies requirement `Anti-Pattern Table SHALL NOT Forbid agent-browser for Discovery` (covered by tasks 6.1, 6.2, 11.5).
+- [x] 13.8 Satisfies requirement `Documentation SHALL Explain When to Opt Into safari` (covered by tasks 7.2, 8.1, 8.2, 10.1, 11.5).
+- [x] 13.9 Implements design decision `Default browser: agent` (covered by tasks 1.2, 11.1).
+- [x] 13.10 Implements design decision `Dispatcher: helper function (Option A)` (covered by tasks 3.1, 3.2, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6).
+- [x] 13.11 Implements design decision `Selection precedence: flag > env > static default` (covered by tasks 1.1, 1.2, 1.3).
+- [x] 13.12 Implements design decision `Pre-flight: mode-specific CLI presence check` (covered by tasks 2.1, 2.2, 2.3).
+- [x] 13.13 Implements design decision "Audit trail: per-iteration commit body emits `BROWSER=<mode>`" (covered by tasks 5.1, 5.2, 11.3).
+- [x] 13.14 Implements design decision `Anti-pattern table entry removed, not qualified` (covered by tasks 6.1, 6.2, 11.5).
diff --git a/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/.openspec.yaml b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/.openspec.yaml
new file mode 100644
index 00000000..81b74f83
--- /dev/null
+++ b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/.openspec.yaml
@@ -0,0 +1,6 @@
+schema: spec-driven
+created: 2026-05-18
+created_by: che cheng <kiki830621@gmail.com>
+created_with: claude
+archived_by: che cheng <kiki830621@gmail.com>
+archived_at: 2026-05-18
diff --git a/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/design.md b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/design.md
new file mode 100644
index 00000000..c8b0e23a
--- /dev/null
+++ b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/design.md
@@ -0,0 +1,197 @@
+## Context
+
+`/archive-mail` builds its email corpus in two passes today:
+
+1. **Step 3 search-time**: `filters` (sender / recipient / subject substring) drives MCP `search_emails` queries. `subject_keywords` expands the search. `exclude_mailboxes` removes Junk / Drafts / Trash.
+2. **Step 4 dedup**: filters out Message-IDs already in the index.
+
+There is no layer between Step 3 (what to search) and Step 4 (already-seen) that lets the user **declaratively narrow or exclude the fetched corpus** by sender, recipient, or subject content. Two open issues hit this gap from different directions:
+
+- **#84**: an email sent from a `filters`-matched account but to an unrelated recipient (institutional account → supplementary school) re-surfaces every run with no way to permanently exclude it without breaking `filters`.
+- **#76**: a sender posting to multiple research lines floods every workspace; user wants subject-based whitelist / blacklist for topic scoping.
+
+Both want the same mechanism — declarative axis-based refinement applied **after** Step 3 fetch and **before** Step 4 dedup — along three axes (sender, recipient, subject). #76 framed it as a subject-only feature; #84 framed it as a sender/recipient-only feature. They were filed as separate issues but represent one design surface.
+
+Existing schema convention in `.claude/.mail/config.yaml` already leans noun-first: `subject_keywords`, `attachment_routing`, `participant_aliases`, `dedup_strategy`, `output_dir`, `last_archived`. Only `exclude_mailboxes` is verb-first — a historical outlier from a different conceptual layer (search-time mailbox switch, not corpus refinement).
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add 6 opt-in config fields (sender / recipient / subject × includes / excludes) that refine the post-Step-3 corpus before Step 4 dedup.
+- Preserve 100% backward compatibility — unset or empty lists behave identically to the current skill.
+- Keep the refinement layer conceptually distinct from search-time `filters`: refinement narrows what was fetched, it does not reshape what gets fetched.
+- Apply refinement at thread granularity to avoid partial threads landing in the archive.
+- Close #76 and #84 in a single change so the naming convention and thread-coherence rules cannot diverge between the two axes' implementations.
+- Spec-level separation of the two layers (Layer 1 `archive-mail-filter-expansion`, Layer 2 new `archive-mail-corpus-refinement`) so future readers can locate refinement rules in one place.
+
+**Non-Goals:**
+
+- Not retro-renaming `exclude_mailboxes` to `mailbox_excludes`. It is a shipped verb-first field at a different conceptual layer (search-time, not refinement); renaming is a breaking change with low payoff.
+- Not introducing `mailbox_includes` (whitelist of mailboxes to search). Out of scope for this change; `filters` plus per-mailbox MCP behavior already covers the common case.
+- Not deprecating `subject_keywords`. It is a Layer 1 **search expansion** mechanism (broadens corpus), orthogonal to the new `subject_includes` Layer 2 **restriction** mechanism (narrows fetched corpus). Both stay.
+- Not building a separate test harness for `commands/archive-mail.md` in this change. The plugin's `tests/` covers only the session-start hook; awk snippets are embedded in the markdown command. Test strategy is captured under Open Questions; per-feature TDD harness can land as a follow-up change.
+- Not extending refinement into the MCP search query itself. Refinement is strictly post-fetch by design — the Mail.app MCP `search_emails` does not support NOT-substring queries cleanly, and pushing refinement search-side would couple `filters` and `*_excludes` into one mental model that the two-layer design deliberately keeps apart.
+
+## Decisions
+
+### Single change covering both #76 and #84
+
+Both issues touch the same Step 4 code region, the same `.claude/.mail/config.yaml` schema, and the same thread-coherence rule. Splitting them into two changes risks divergent naming (`subject_excludes` from #76 vs `sender_excludes` from #84 with different rules) and two passes over the same code. Bundling them ensures the 6-field surface is designed coherently in one review.
+
+**Alternative considered**: two changes (#84 first, #76 later). Rejected — same Step 4 filter touched twice, and the naming-convention decision would need cross-change coordination anyway, just less visibly.
+
+### Six fields (3 axes × 2 directions)
+
+The full set: `sender_includes`, `sender_excludes`, `recipient_includes`, `recipient_excludes`, `subject_includes`, `subject_excludes`.
+
+**Alternatives considered**:
+
+- Excludes only (3 fields). Drops `subject_includes` which is #76's stated workspace-scoping use case. Rejected — #76 would not close.
+- Four fields (drop `sender_includes` / `recipient_includes` only). Argued that they duplicate `filters` for sender / recipient. Rejected — see the next decision; the two-layer model makes them orthogonal, not redundant.
+
+### Two-layer model — `filters` (search-time) vs `*_includes` (post-fetch restriction)
+
+`filters` shapes the search query (Step 3 MCP call); it defines what enters the fetched corpus. `*_includes` operates after the corpus is fetched (Step 4) and acts as a whitelist filter — keep only emails where at least one axis substring matches. The two are orthogonal:
+
+- `filters: ["yfhsu"]` + `sender_includes: ["@gate.sinica"]` → cast wide net (anything mentioning yfhsu in sender / recipient / subject), then narrow to only those whose sender contains `@gate.sinica`. Useful for collaborator-scoped multi-axis filtering that a single search-time substring cannot express.
+- `filters: ["yfhsu"]` alone → all yfhsu correspondence. Today's behavior, unchanged.
+
+This is the same semantic shape as #76's original `subject_includes` proposal (post-search restriction). The new model generalizes it to all three axes.
+
+**Alternative considered**: single-layer model where `filters` and `*_includes` co-apply at search-time with AND semantics. Rejected — `filters` is currently OR across its list and across sender / recipient / subject; layering AND on top creates a three-way config interaction (`filters` × `sender_includes` × `recipient_includes`) whose test matrix is large and surprising. Two layers separated by execution stage is mentally cleaner.
+
+### Noun-first naming (`<axis>_<direction>`)
+
+`sender_excludes` not `exclude_senders`. Consistent with the 6 existing noun-first fields in the schema; the single verb-first outlier `exclude_mailboxes` lives at a different conceptual layer and is justified by its "search-time switch" semantics ("exclude X from search") vs the new fields' "refinement filter" semantics ("filter corpus by X").
+
+**Alternative considered**: A2 verb-first (`exclude_senders` etc.) for alignment with `exclude_mailboxes`. Rejected — dominant pattern matters more than alignment with one outlier, and the same-axis paired fields (`sender_includes` / `sender_excludes`) read more naturally when the axis name is the prefix.
+
+### Substring case-insensitive matching
+
+Each list entry matches if it appears as a case-insensitive substring of the target field (sender email, recipient email, or bare subject). Same semantic as the existing `filters` and `subject_keywords`.
+
+**Alternative considered**: exact match (full email or full subject). Rejected — inconsistent with two existing search fields, and the common use cases (`@yahoo` for domain-wide exclude, partial subject keywords) need substring.
+
+### Excludes win when both axes set
+
+When `<axis>_includes` and `<axis>_excludes` are both non-empty and an email matches both, the email is dropped. Conceptually: includes narrow the candidate set, excludes drop matches from that narrowed set.
+
+**Alternative considered**: includes wins (explicit-keep overrides exclude). Rejected — most general-purpose filter engines default to deny-wins / blacklist-wins because it is the safer behavior under accidental overlap. The user can always tighten an include pattern to avoid the overlap if they want fine-grained exemption.
+
+### Per-thread coherence
+
+Refinement is applied at thread granularity. If any message in a thread matches `*_includes`, the whole thread is kept. If any message matches `*_excludes`, the whole thread is dropped. Threads are identified by bare subject (after stripping `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` prefixes), consistent with the existing thread-key logic.
+
+**Trade-off**: a thread whose mostly-legitimate messages contain one stray CC to an excluded address gets dropped entirely. The mitigation is to tune the exclude pattern (e.g., exclude a more specific substring), which is exactly what the user does today with `filters`.
+
+**Alternative considered**: per-message refinement (each message judged independently). Rejected — produces partial threads in the archive (some messages of a thread present, others missing), which breaks the `threads.json` invariant that every archived message of a thread is co-located. The skill's existing thread-handling assumes thread-level atomicity.
+
+### New spec `archive-mail-corpus-refinement` (not extending `archive-mail-filter-expansion`)
+
+The existing `archive-mail-filter-expansion` spec defines Layer 1 search-time expansion (subject keyword, participant aliases, thread-subject expansion). The new fields are Layer 2 post-fetch refinement. Cramming Layer 2 requirements into a spec named "filter-expansion" creates a semantic mismatch — expansion broadens corpus, refinement narrows it.
+
+**Alternative considered**: extend `archive-mail-filter-expansion`, possibly rename to `archive-mail-filtering`. Rejected — renaming a published spec is a breaking change for anyone referencing it; not renaming leaves the spec name lying about its scope.
+
+## Implementation Contract
+
+**Observable behavior**
+
+A user with the following `.claude/.mail/config.yaml`:
+
+```yaml
+filters:
+  - che830621@as.edu.tw
+
+recipient_excludes:
+  - EDUCATION5361@yahoo.com.tw
+
+subject_excludes:
+  - 講義
+```
+
+runs `/archive-mail`. Any thread whose recipient list contains `EDUCATION5361@yahoo.com.tw` (substring match, case-insensitive) on at least one message, OR whose bare subject contains `講義` on at least one message, is dropped from the corpus before Step 4 dedup. The Step 7 report and Step 4.5 Phase 2 preview both surface the drop counts.
+
+Subsequent runs with the same config produce identical exclusion — the dropped threads' Message-IDs never enter the index, so they cannot re-surface as "new" unless the user removes the exclude entry.
+
+**Interface — config schema**
+
+Six new optional top-level keys in `.claude/.mail/config.yaml`. Each is a YAML sequence of strings; absent key or empty sequence both mean "no refinement on this axis":
+
+```yaml
+sender_includes:    [<substring>, ...]
+sender_excludes:    [<substring>, ...]
+recipient_includes: [<substring>, ...]
+recipient_excludes: [<substring>, ...]
+subject_includes:   [<substring>, ...]
+subject_excludes:   [<substring>, ...]
+```
+
+Substring matching is case-insensitive (the comparison lowercases both the config entry and the target field). For sender / recipient, the target is the bare email address (display name stripped). For subject, the target is the bare subject after `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` prefix stripping.
+
+**Step 4 pipeline shape**
+
+Refinement runs as a sub-step inserted between corpus fetch and dedup. Pseudocode:
+
+```python
+fetched = step3_search()        # Layer 1 corpus
+refined = apply_refinement(fetched, config)  # Layer 2 (this change)
+new_emails = step4_dedup(refined, index)     # existing
+```
+
+`apply_refinement` groups `fetched` by thread, evaluates each thread against the 6 fields, drops the thread entirely if it matches an exclude or fails an include whitelist.
+
+**Step 4.5 Phase 2 preview line**
+
+Existing preview gains a stats line, surfaced only when at least one of the 6 fields is non-empty:
+
+```
+Corpus refinement (includes/excludes): {kept} / {dropped} threads
+  Dropped by sender_excludes:    {N} threads
+  Dropped by recipient_excludes: {N} threads
+  Dropped by subject_excludes:   {N} threads
+  Filtered out by includes:      {N} threads
+```
+
+Zero-count rows are omitted to keep the preview compact.
+
+**Failure modes**
+
+- Malformed YAML value (e.g., a string instead of a sequence) for any of the 6 fields → skill aborts at Step 1 with `Error: <field> must be a YAML sequence of strings` and exits non-zero. Same posture as the existing `exclude_mailboxes` parse error path.
+- Substring matches nothing → silent no-op (refined corpus same as fetched). Expected behavior; users discover via the Phase 2 preview line.
+- Substring matches everything → refined corpus is empty, Step 4.5 Phase 2 preview shows `kept=0` and `dropped=<total>`; skill warns and prompts user before continuing.
+
+**Acceptance criteria**
+
+- An archive run with all 6 fields unset is byte-identical to the same run on the prior skill version (excluding version-bump and timestamp differences).
+- An archive run with `recipient_excludes: ["EDUCATION5361@yahoo.com.tw"]` drops the 274139 thread that motivates #84; the dropped thread does not appear in `communications/intake/` or in `email_index.json`.
+- An archive run with `subject_excludes: ["經費"]` drops admin threads matching the #76 use case; the dropped threads do not appear in the archive.
+- Phase 2 preview surfaces the drop counts when refinement is active; omits the section entirely when all 6 fields are unset.
+- Spec analyzer (`spectra analyze`) reports no Critical findings against the new `archive-mail-corpus-refinement` spec.
+- `archive-mail-filter-expansion` spec is unchanged.
+
+**Scope boundaries**
+
+- In scope: 6 new config fields, Step 1 awk parsing, Step 4 refinement sub-step, Step 4.5 Phase 2 preview line, top-of-skill config field table, search-extension examples section, CHANGELOG, version bump, new spec file.
+- Out of scope: dedup logic changes, threads.json schema changes, Step 5+ markdown writer changes, attachment routing changes, search-side MCP query changes, `exclude_mailboxes` migration, `subject_keywords` deprecation.
+
+## Risks / Trade-offs
+
+- **Substring over-match** → Mitigation: document the case-insensitive substring semantic in the search-extension examples section; recommend using `@yahoo.com.tw` over `yahoo` when scoping by domain.
+- **Stray-CC drops thread** (mid-thread CC to excluded address drops the whole thread) → Mitigation: document the thread-coherence rule in the spec and the skill's example section; user can tighten exclude substring to avoid hitting the stray address.
+- **Three-way config interaction confusion** (`filters` × `<axis>_includes` × `<axis>_excludes`) → Mitigation: the two-layer model documentation in the new spec; concrete example in the skill's search-extension examples section showing a `filters` + `sender_includes` pairing.
+- **No test harness for command-embedded awk** → Mitigation: documented as Open Question; manual acceptance testing in this change, follow-up change to extract awk into sourceable script for future TDD.
+- **Refinement runs before dedup** → If excluded threads were previously archived (Message-IDs in index), they are still in the on-disk archive. Refinement does not retroactively prune. → Mitigation: document; users can manually remove the old archive entries if they want a clean slate.
+
+## Migration Plan
+
+- No data migration required — all 6 fields are opt-in with backward-compatible empty defaults.
+- Version bump: `plugins/che-apple-mail-mcp/.claude-plugin/plugin.json` 2.19.7 → 2.20.0 (semver minor for a feature add).
+- CHANGELOG entry under `[Unreleased]` describes the new fields and links to #76, #84.
+- Closing #76 and #84 happens when the change is applied (close as part of the apply-side commits, linked to the change branch's PR).
+- Rollback: revert the change branch; the 6 new fields become unrecognized YAML keys but the existing awk parsers ignore unknown keys silently. No config-file migration needed to roll back.
+
+## Open Questions
+
+- **Test harness for `commands/archive-mail.md`**: should the implementing change include awk-extraction to a sourceable script (e.g., `bin/archive-mail-helpers.sh`) so the 6-field parsing can have unit coverage? Or defer entirely to a follow-up dedicated to testability? Recommendation: defer to follow-up — this change's scope is the feature, not the test infra rebuild.
+- **Empty-string-in-list semantics**: `sender_excludes: [""]` (a list containing an empty string) would substring-match every email. Should the parser warn or silently drop empty entries? Recommendation: silently drop empty entries at parse time; document in the spec; defer warning to a future config-validator change.
diff --git a/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/proposal.md b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/proposal.md
new file mode 100644
index 00000000..0d39ff64
--- /dev/null
+++ b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/proposal.md
@@ -0,0 +1,66 @@
+## Why
+
+`/archive-mail` currently has only one mechanism for shaping the email corpus: `filters`, which defines what gets searched at Step 3 (MCP query against sender / recipient / subject). Once emails are fetched, the only available exclusion is `exclude_mailboxes` (mailbox-level: Junk / Drafts / Trash). There is no way to declaratively narrow or exclude the corpus by sender, recipient, or subject content after the search.
+
+Two open issues hit this gap from different angles:
+
+- **#84 (recurring false positives)**: an email sent from a `filters`-matching account but to an unrelated recipient (e.g., supplementary-school content sent from the user's institutional account to `EDUCATION5361@yahoo.com.tw`) matches `filters` and is re-surfaced on every run. The user must manually exclude it each time because there is no `recipient_excludes` field.
+- **#76 (cross-project / admin noise)**: the same sender posting to multiple research lines floods every workspace's archive. The user wants subject-based scoping (whitelist a topic) and admin-noise rejection (blacklist by subject substring).
+
+These are the same problem along three axes (sender / recipient / subject) of the same conceptual layer — **post-fetch corpus refinement**, distinct from search-time corpus definition.
+
+## What Changes
+
+Introduces a **two-layer corpus model** for `/archive-mail`:
+
+- **Layer 1 (search-time, existing)**: `filters`, `subject_keywords`, `participant_aliases`, `exclude_mailboxes` — defines what gets pulled from Mail.app at Step 3. Covered by the existing `archive-mail-filter-expansion` spec; no change to its requirements.
+- **Layer 2 (post-fetch, new)**: 6 new optional opt-in config fields applied in Step 4 after the corpus is built, before dedup. Covered by a new `archive-mail-corpus-refinement` spec.
+
+The 6 new fields, all under `.claude/.mail/config.yaml`:
+
+- `sender_includes` — keep only emails whose sender contains at least one listed substring (case-insensitive)
+- `sender_excludes` — drop emails whose sender contains any listed substring
+- `recipient_includes` — keep only emails with at least one recipient containing at least one listed substring
+- `recipient_excludes` — drop emails with any recipient containing any listed substring
+- `subject_includes` — keep only emails whose bare subject (after stripping `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` prefixes) contains at least one listed substring
+- `subject_excludes` — drop emails whose bare subject contains any listed substring
+
+Behavior contract (full normative form in the new spec):
+
+- Unset or empty list = no filter applied on that axis; 100% backward compatible.
+- Per-axis includes act as whitelist; when non-empty, at least one listed substring must appear for the email to pass.
+- Excludes act as blacklist; if any listed substring appears, the email is dropped — excludes win over includes when both are set on the same axis.
+- All matching is case-insensitive substring matching, consistent with the existing `filters` / `subject_keywords` semantics.
+- Coherence is applied at **thread granularity**: any message in a thread matching includes → the whole thread is kept; any matching excludes → the whole thread is dropped. Avoids partial threads landing in the archive.
+- Step 4 dedup logic is unchanged. Refinement runs **before** dedup so excluded threads do not consume index slots.
+- Step 4.5 Phase 2 preview gains a stats line: `Corpus refinement (includes/excludes): {kept} / {dropped} threads`.
+
+Step 1 config parsing gains awk parsers for the 6 new fields, mirroring the existing `exclude_mailboxes` sequence-parse pattern (lines ~91–113).
+
+Closes #76 and #84 when applied.
+
+## Non-Goals
+
+See `design.md` Goals / Non-Goals section.
+
+## Capabilities
+
+### New Capabilities
+
+- `archive-mail-corpus-refinement`: Defines the Layer 2 post-fetch corpus-refinement contract — the 6 opt-in config fields (sender / recipient / subject × includes / excludes), per-thread coherence rule, excludes-precedence rule, empty-list-as-unset semantics, and the interaction with the existing Layer 1 search-time corpus definition.
+
+### Modified Capabilities
+
+(none)
+
+## Impact
+
+- Affected specs:
+  - New: `openspec/specs/archive-mail-corpus-refinement/spec.md`
+- Affected code:
+  - `plugins/che-apple-mail-mcp/commands/archive-mail.md` — Step 1 config parsing (~line 91–113), Step 4 filter (~467–499), Step 4.5 Phase 2 preview (~510–525), top config field table (~line 31), search-extension examples section (~line 1048–1067).
+  - `plugins/che-apple-mail-mcp/CHANGELOG.md` — new entry.
+  - `plugins/che-apple-mail-mcp/.claude-plugin/plugin.json` — version bump 2.19.7 → 2.20.0 (feature = minor).
+- Resolves: #76, #84 (both closed when change applied).
+- No breaking changes — all 6 fields are opt-in with no-default semantics; existing configs continue to behave identically.
+- Test infrastructure gap: `commands/archive-mail.md` is a markdown command with embedded awk; the plugin's `tests/` directory currently only covers the session-start hook. Test strategy is deferred to `design.md` (option to extract awk into a sourceable script vs add inline test harness).
diff --git a/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/specs/archive-mail-corpus-refinement/spec.md b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/specs/archive-mail-corpus-refinement/spec.md
new file mode 100644
index 00000000..5f52e383
--- /dev/null
+++ b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/specs/archive-mail-corpus-refinement/spec.md
@@ -0,0 +1,151 @@
+## ADDED Requirements
+
+### Requirement: Six opt-in corpus-refinement fields
+
+`/archive-mail` SHALL recognize six optional top-level fields in `.claude/.mail/config.yaml` that refine the fetched email corpus before dedup: `sender_includes`, `sender_excludes`, `recipient_includes`, `recipient_excludes`, `subject_includes`, `subject_excludes`. Each field SHALL be a YAML sequence of strings. An absent field and an empty sequence SHALL both produce no refinement on that axis.
+
+#### Scenario: All six fields unset
+
+- **WHEN** `/archive-mail` runs with a config that defines `filters` but none of the six refinement fields
+- **THEN** the archived corpus SHALL be identical to the corpus produced by the same `filters` value on the prior skill version
+- **AND** Step 4.5 Phase 2 preview SHALL NOT include the refinement stats line
+
+#### Scenario: Field present with empty list
+
+- **WHEN** `/archive-mail` runs with `sender_excludes: []`
+- **THEN** no email SHALL be dropped on the basis of `sender_excludes`
+- **AND** the behavior SHALL be indistinguishable from omitting `sender_excludes` entirely
+
+##### Example: empty list equivalence
+
+| Config snippet | Behavior |
+| --- | --- |
+| `(field omitted)` | no refinement on axis |
+| `sender_excludes: []` | no refinement on axis |
+| `sender_excludes: [""]` | empty entry SHALL be silently dropped at parse; equivalent to `sender_excludes: []` |
+| `sender_excludes: ["@yahoo"]` | refinement active with one substring |
+
+### Requirement: Per-axis includes whitelist and excludes blacklist with excludes-precedence
+
+For each axis (sender, recipient, subject), `/archive-mail` SHALL apply the following filter logic to the fetched corpus:
+
+- When `<axis>_includes` is non-empty, an email SHALL pass the include filter on that axis if and only if the axis-target value contains at least one listed substring.
+- When `<axis>_excludes` is non-empty, an email SHALL fail the exclude filter on that axis if the axis-target value contains any listed substring.
+- When both `<axis>_includes` and `<axis>_excludes` are non-empty and the same email both passes the include filter and fails the exclude filter on the same axis, the email SHALL be dropped (excludes take precedence over includes on the same axis).
+
+An email passes refinement if and only if it passes the include filter and does not fail the exclude filter on every axis with at least one non-empty field.
+
+#### Scenario: Includes match keeps email; no match drops it
+
+- **WHEN** `subject_includes: ["Schultz"]` is set and an email's bare subject is `Schultz scale 12 items`
+- **THEN** the email SHALL pass refinement on the subject axis
+
+#### Scenario: Excludes match drops email regardless of includes
+
+- **WHEN** `recipient_includes: ["@stat.sinica"]` and `recipient_excludes: ["EDUCATION5361@yahoo"]` are both set
+- **AND** an email's recipient list contains both `che@stat.sinica.edu.tw` and `EDUCATION5361@yahoo.com.tw`
+- **THEN** the email SHALL be dropped (excludes win on same axis)
+
+##### Example: excludes-precedence truth table
+
+| `sender_includes` match | `sender_excludes` match | Outcome |
+| --- | --- | --- |
+| n/a (unset) | n/a (unset) | pass |
+| n/a (unset) | true | drop |
+| n/a (unset) | false | pass |
+| true | n/a (unset) | pass |
+| false | n/a (unset) | drop |
+| true | true | **drop** (excludes win) |
+| true | false | pass |
+| false | true | drop |
+| false | false | drop |
+
+### Requirement: Per-thread coherence
+
+Refinement SHALL be applied at thread granularity. A thread is the set of emails sharing the same bare subject (computed per the Subject Normalization requirement below). If any message in a thread passes the include filter on an axis where `<axis>_includes` is non-empty, the whole thread SHALL be treated as passing that axis's include filter. If any message in a thread fails the exclude filter on an axis where `<axis>_excludes` is non-empty, the whole thread SHALL be dropped regardless of the other messages.
+
+#### Scenario: Stray CC drops whole thread
+
+- **GIVEN** a thread with five messages, four of which have recipients only within `@stat.sinica.edu.tw`, and one of which CCs `EDUCATION5361@yahoo.com.tw`
+- **WHEN** `recipient_excludes: ["EDUCATION5361@yahoo"]` is set
+- **THEN** all five messages of the thread SHALL be dropped from the refined corpus
+
+#### Scenario: One-message match keeps whole thread
+
+- **GIVEN** a thread with three messages, only one of which has a subject containing `Schultz`
+- **WHEN** `subject_includes: ["Schultz"]` is set
+- **THEN** all three messages SHALL pass refinement on the subject axis
+
+### Requirement: Case-insensitive substring matching with bare-value normalization
+
+All refinement matching SHALL be case-insensitive substring matching. The skill SHALL lowercase both the configured list entries and the axis-target value before comparison. The axis-target value SHALL be normalized as follows:
+
+- For `sender_includes` / `sender_excludes`: the email address only, with any display-name prefix stripped (e.g., `"Che Cheng" <che@as.edu.tw>` SHALL be matched against `che@as.edu.tw`).
+- For `recipient_includes` / `recipient_excludes`: the email address of each recipient in turn, with display-name prefixes stripped.
+- For `subject_includes` / `subject_excludes`: the bare subject, computed by stripping any leading sequence of `Re:`, `RE:`, `Fwd:`, `FW:`, `转发:`, or `轉寄:` prefixes (each followed by optional whitespace).
+
+#### Scenario: Mixed-case match
+
+- **WHEN** `sender_excludes: ["@YAHOO.COM"]` is set
+- **AND** an email's sender is `Foo Bar <foo@yahoo.com.tw>`
+- **THEN** the email SHALL be dropped (lowercase comparison: `@yahoo.com` substring of `foo@yahoo.com.tw`)
+
+#### Scenario: Subject prefix stripping
+
+- **WHEN** `subject_excludes: ["經費"]` is set
+- **AND** an email's raw subject is `Re: 經費補助通知`
+- **THEN** the bare subject SHALL be computed as `經費補助通知` and the email SHALL be dropped
+
+##### Example: bare-subject computation
+
+| Raw subject | Bare subject |
+| --- | --- |
+| `Schultz scale 12 items` | `Schultz scale 12 items` |
+| `Re: Schultz scale 12 items` | `Schultz scale 12 items` |
+| `Re: Re: Fwd: Schultz scale` | `Schultz scale` |
+| `RE: 轉寄: 經費補助` | `經費補助` |
+
+### Requirement: Refinement executes after fetch and before dedup
+
+Refinement SHALL run after the Step 3 search-time corpus fetch and before the Step 4 Message-ID dedup. Threads dropped by refinement SHALL NOT have their Message-IDs added to `email_index.json` and SHALL NOT consume slots in `threads.json`. As a consequence, a subsequent `/archive-mail` run with the same refinement config SHALL drop the same threads again without re-surfacing them as new.
+
+#### Scenario: Excluded thread does not enter index
+
+- **GIVEN** `recipient_excludes: ["EDUCATION5361@yahoo"]` is set
+- **WHEN** `/archive-mail` runs and one fetched thread has a recipient matching the substring
+- **THEN** the thread SHALL be absent from the output directory after the run
+- **AND** the thread's Message-IDs SHALL be absent from `email_index.json`
+- **AND** the thread SHALL be absent from `threads.json`
+
+#### Scenario: Subsequent run does not re-surface
+
+- **GIVEN** a prior `/archive-mail` run dropped a thread by `recipient_excludes`
+- **WHEN** `/archive-mail` runs again with the same config
+- **THEN** the same thread SHALL be dropped again
+- **AND** Step 7 SHALL NOT report it as newly archived
+
+### Requirement: Phase 2 preview surfaces refinement statistics
+
+When at least one of the six refinement fields is non-empty, Step 4.5 Phase 2 preview SHALL include a refinement statistics block listing the number of threads kept, the total dropped, and a per-category breakdown (`sender_excludes`, `recipient_excludes`, `subject_excludes`, `includes` filtered-out). Categories with zero drops SHALL be omitted from the breakdown. When all six fields are unset, the refinement statistics block SHALL be omitted entirely.
+
+#### Scenario: Active refinement shows stats line
+
+- **WHEN** `/archive-mail` runs with `subject_excludes: ["經費"]` and 3 threads are dropped by the subject_excludes match
+- **THEN** Step 4.5 Phase 2 preview SHALL include a line of the form `Corpus refinement (includes/excludes): {kept} / 3 threads`
+- **AND** the breakdown SHALL include `Dropped by subject_excludes: 3 threads`
+- **AND** the breakdown SHALL omit categories with zero drops
+
+#### Scenario: No refinement active omits the block entirely
+
+- **WHEN** `/archive-mail` runs with all six refinement fields unset or empty
+- **THEN** Step 4.5 Phase 2 preview SHALL NOT include any refinement statistics block
+
+### Requirement: Malformed refinement value aborts with explicit error
+
+When any of the six refinement fields is present in config but its value is not a YAML sequence of strings, `/archive-mail` SHALL abort at Step 1 with an explicit error message naming the offending field and the expected value shape, and SHALL exit with a non-zero status. The skill SHALL NOT silently coerce, ignore, or partially apply a malformed value.
+
+#### Scenario: Scalar instead of sequence
+
+- **WHEN** the config contains `sender_excludes: "@yahoo"` (scalar string instead of list)
+- **THEN** `/archive-mail` SHALL print an error of the form `Error: sender_excludes must be a YAML sequence of strings`
+- **AND** SHALL exit with non-zero status before performing any search or write
diff --git a/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/tasks.md b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/tasks.md
new file mode 100644
index 00000000..6aa0e077
--- /dev/null
+++ b/openspec/changes/archive/2026-05-18-add-archive-mail-corpus-refinement/tasks.md
@@ -0,0 +1,36 @@
+## 1. Config parsing (Step 1)
+
+- [x] 1.1 Implement awk parsers for the Six opt-in corpus-refinement fields (the Six fields (3 axes × 2 directions) under `<axis>_<direction>` noun-first naming) inside Step 1 Config parsing, so each of `sender_includes` / `sender_excludes` / `recipient_includes` / `recipient_excludes` / `subject_includes` / `subject_excludes` is read as a YAML sequence of strings; verified by a config-parse fixture test that asserts each of the six parsed lists matches the fixture YAML.
+- [x] 1.2 Enforce the Malformed refinement value aborts with explicit error contract — when any refinement field is present but not a sequence, abort at Step 1 with an explicit `Error: <field> must be a YAML sequence of strings` message and non-zero exit; verified by running `/archive-mail` against a fixture with `sender_excludes: "@yahoo"` (scalar) and asserting non-zero exit plus stderr matches the error message.
+- [x] 1.3 Treat empty-list and empty-string entries as no-op so `sender_excludes: []` and `sender_excludes: [""]` both produce zero refinement on the axis, per the spec's empty-list equivalence example; verified by a config-parse fixture comparing the parsed effective list against the omit-field baseline.
+
+## 2. Step 4 corpus refinement
+
+- [x] 2.1 Insert an `apply_refinement(fetched, config)` sub-step between Step 3 fetch and Step 4 dedup that realizes the Two-layer model — `filters` (search-time) vs `*_includes` (post-fetch restriction), so refinement runs strictly after the corpus is fetched and never reshapes the MCP query; verified by an integration fixture where an email matching `filters` but dropped by `recipient_excludes` is absent from the archive output and from `email_index.json`.
+- [x] 2.2 Implement the Per-axis includes whitelist and excludes blacklist with excludes-precedence rule so that on each axis the include list acts as whitelist (any-substring match → keep), the exclude list acts as blacklist (any-substring match → drop), and when both lists match the same email on the same axis the email is dropped (Excludes win when both axes set); verified by asserting every row of the excludes-precedence truth table from the spec passes against synthetic email fixtures.
+- [x] 2.3 Apply refinement atomically at thread granularity so the Per-thread coherence rule holds — any single message in a thread matching `<axis>_includes` keeps the whole thread; any single message matching `<axis>_excludes` drops the whole thread; verified by the spec's "Stray CC drops whole thread" and "One-message match keeps whole thread" scenarios as integration tests.
+- [x] 2.4 Implement Case-insensitive substring matching with bare-value normalization — Substring case-insensitive matching against the bare email address (display-name stripped) for sender / recipient axes and against the bare subject (leading `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` prefixes stripped) for the subject axis; verified by running the 4-row bare-subject computation example table from the spec as parameterized assertions.
+- [x] 2.5 Ensure Refinement executes after fetch and before dedup so excluded threads' Message-IDs never enter `email_index.json` and never consume slots in `threads.json`, and so a subsequent `/archive-mail` run with the same refinement config drops the same threads again without re-surfacing them; verified by the spec's "Excluded thread does not enter index" and "Subsequent run does not re-surface" scenarios as two-pass integration tests.
+
+## 3. Step 4.5 Phase 2 preview
+
+- [x] 3.1 Extend Step 4.5 Phase 2 preview so the Phase 2 preview surfaces refinement statistics block appears (with kept / dropped totals and per-category breakdown) when at least one refinement field is non-empty and is omitted entirely when all six are unset; verified by capturing Phase 2 output against two fixtures (one with `subject_excludes: ["經費"]` active and one with all fields unset) and asserting the block is present-with-correct-counts vs. absent respectively, and that zero-drop categories are omitted from the breakdown.
+
+## 4. Spec artifacts
+
+- [x] 4.1 Land `openspec/specs/archive-mail-corpus-refinement/spec.md` with the 7 requirements above so this is the New spec `archive-mail-corpus-refinement` (not extending `archive-mail-filter-expansion`), realizing the Single change covering both #76 and #84 contract; verified by `spectra validate add-archive-mail-corpus-refinement` exit 0 and `spectra analyze` reporting zero Critical findings.
+- [x] 4.2 Leave the existing `archive-mail-filter-expansion` spec unchanged so Layer 1 search-time semantics carry no implicit modification from this change; verified by `git diff openspec/specs/archive-mail-filter-expansion/` returning empty after all apply-side commits.
+
+## 5. Command-file documentation
+
+- [x] 5.1 Add the 6 new fields to the top-of-command config field table in `plugins/che-apple-mail-mcp/commands/archive-mail.md` using Noun-first naming (`<axis>_<direction>`) per the design decision; verified by content review of the field table containing 6 new rows in the form `\`<axis>_<direction>\` | ...`.
+- [x] 5.2 Extend the search-extension examples section with a concrete config example pairing `filters` and `sender_includes` to illustrate the Two-layer model — `filters` (search-time) vs `*_includes` (post-fetch restriction) interaction so users see when to reach for which layer; verified by content review and matching the example against the two-layer-model integration fixture from task 2.1.
+
+## 6. Release
+
+- [x] 6.1 Bump `plugins/che-apple-mail-mcp/.claude-plugin/plugin.json` from version 2.19.7 to 2.20.0 (feature add → semver minor); verified by `jq -r .version plugins/che-apple-mail-mcp/.claude-plugin/plugin.json` returning `2.20.0`.
+- [x] 6.2 Add a CHANGELOG entry under `[Unreleased]` describing the 6 new refinement fields, the two-layer model framing, and the resolutions of `#76` and `#84`; verified by content review and (if available) `changelog-tools:changelog-validate` reporting no Keep-a-Changelog violations.
+
+## 7. Issue closure
+
+- [x] 7.1 Reference `#76` and `#84` with `Closes #76` and `Closes #84` trailers in the apply-side PR description so both issues close automatically on PR merge per the Single change covering both #76 and #84 contract; verified by GitHub auto-closing both issues immediately after the merge commit lands on `main`.
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 00000000..392946c6
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
diff --git a/openspec/specs/archive-mail-attachments/spec.md b/openspec/specs/archive-mail-attachments/spec.md
new file mode 100644
index 00000000..ab9ac951
--- /dev/null
+++ b/openspec/specs/archive-mail-attachments/spec.md
@@ -0,0 +1,18 @@
+# archive-mail-attachments Specification
+
+## Purpose
+
+Defines how `/archive-mail` downloads attachment files from archived emails, where they are placed on disk (with data-vs-document routing), and how they are linked from the generated Markdown. Includes config schema, routing precedence, filename preservation, and cross-reference behavior for replies.
+
+## Requirements
+
+(Synced from change delta specs — see archived change for full scenario details with @trace comments.)
+
+- Skill downloads attachments from archived emails
+- Attachment directory matches email Markdown stem
+- Attachment routing follows config-keyword-extension precedence
+- Default routing rules when config is absent
+- Filename preservation on disk with URL encoding in Markdown links only
+- Attachment block placement in Markdown
+- Reply without attachments emits cross-reference
+- Skill output report summarizes attachment routing
diff --git a/openspec/specs/archive-mail-corpus-refinement/spec.md b/openspec/specs/archive-mail-corpus-refinement/spec.md
new file mode 100644
index 00000000..abd10d99
--- /dev/null
+++ b/openspec/specs/archive-mail-corpus-refinement/spec.md
@@ -0,0 +1,171 @@
+# archive-mail-corpus-refinement Specification
+
+## Purpose
+
+Defines how `/archive-mail` refines the fetched email corpus after Step 3 search and before Step 4 dedup, using six opt-in config fields (`sender_includes`, `sender_excludes`, `recipient_includes`, `recipient_excludes`, `subject_includes`, `subject_excludes`). Refinement is post-fetch and thread-coherent, distinct from search-time corpus definition (`filters`, `subject_keywords`, `exclude_mailboxes`).
+
+## Requirements
+
+- Six opt-in corpus-refinement fields read from `.claude/.mail/config.yaml` as YAML multi-line block-style sequences of strings; unset and empty sequences both equal no refinement on that axis (100% backward compat)
+- Per-axis includes act as whitelist (any-substring match keeps the thread); excludes act as blacklist (any-substring match drops the thread); excludes win when both lists are non-empty and the same email matches both on the same axis
+- Per-thread coherence — refinement is applied atomically at the thread level: any message in a thread matching includes keeps the whole thread; any message matching excludes drops the whole thread
+- Case-insensitive substring matching with bare-value normalization: display-name prefix stripped for sender / recipient axes; bare subject computed by stripping leading `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` prefixes for the subject axis
+- Refinement runs after Step 3 fetch and before Step 4 dedup; excluded threads' Message-IDs do not enter `email_index.json` or `threads.json`, so subsequent runs with the same config drop the same threads without re-surfacing them as new
+- Phase 2 preview surfaces a refinement statistics block (kept / dropped totals and per-category breakdown) when at least one refinement field is non-empty; the block is omitted entirely when all six fields are unset; zero-count categories are omitted from the breakdown
+- Malformed refinement value (non-sequence YAML scalar or unsupported inline list other than `[]`) aborts at Step 1 with explicit `Error: <field> must be a YAML multi-line block-style sequence of strings ...` message and non-zero exit; empty-string entries within a sequence (`[""]`) are silently dropped at parse time
+
+### Requirement: Six opt-in corpus-refinement fields
+
+`/archive-mail` SHALL recognize six optional top-level fields in `.claude/.mail/config.yaml` that refine the fetched email corpus before dedup: `sender_includes`, `sender_excludes`, `recipient_includes`, `recipient_excludes`, `subject_includes`, `subject_excludes`. Each field SHALL be a YAML sequence of strings. An absent field and an empty sequence SHALL both produce no refinement on that axis.
+
+#### Scenario: All six fields unset
+
+- **WHEN** `/archive-mail` runs with a config that defines `filters` but none of the six refinement fields
+- **THEN** the archived corpus SHALL be identical to the corpus produced by the same `filters` value on the prior skill version
+- **AND** Step 4.5 Phase 2 preview SHALL NOT include the refinement stats line
+
+#### Scenario: Field present with empty list
+
+- **WHEN** `/archive-mail` runs with `sender_excludes: []`
+- **THEN** no email SHALL be dropped on the basis of `sender_excludes`
+- **AND** the behavior SHALL be indistinguishable from omitting `sender_excludes` entirely
+
+##### Example: empty list equivalence
+
+| Config snippet | Behavior |
+| --- | --- |
+| `(field omitted)` | no refinement on axis |
+| `sender_excludes: []` | no refinement on axis |
+| `sender_excludes: [""]` | empty entry SHALL be silently dropped at parse; equivalent to `sender_excludes: []` |
+| `sender_excludes: ["@yahoo"]` | refinement active with one substring |
+
+---
+### Requirement: Per-axis includes whitelist and excludes blacklist with excludes-precedence
+
+For each axis (sender, recipient, subject), `/archive-mail` SHALL apply the following filter logic to the fetched corpus:
+
+- When `<axis>_includes` is non-empty, an email SHALL pass the include filter on that axis if and only if the axis-target value contains at least one listed substring.
+- When `<axis>_excludes` is non-empty, an email SHALL fail the exclude filter on that axis if the axis-target value contains any listed substring.
+- When both `<axis>_includes` and `<axis>_excludes` are non-empty and the same email both passes the include filter and fails the exclude filter on the same axis, the email SHALL be dropped (excludes take precedence over includes on the same axis).
+
+An email passes refinement if and only if it passes the include filter and does not fail the exclude filter on every axis with at least one non-empty field.
+
+#### Scenario: Includes match keeps email; no match drops it
+
+- **WHEN** `subject_includes: ["Schultz"]` is set and an email's bare subject is `Schultz scale 12 items`
+- **THEN** the email SHALL pass refinement on the subject axis
+
+#### Scenario: Excludes match drops email regardless of includes
+
+- **WHEN** `recipient_includes: ["@stat.sinica"]` and `recipient_excludes: ["EDUCATION5361@yahoo"]` are both set
+- **AND** an email's recipient list contains both `che@stat.sinica.edu.tw` and `EDUCATION5361@yahoo.com.tw`
+- **THEN** the email SHALL be dropped (excludes win on same axis)
+
+##### Example: excludes-precedence truth table
+
+| `sender_includes` match | `sender_excludes` match | Outcome |
+| --- | --- | --- |
+| n/a (unset) | n/a (unset) | pass |
+| n/a (unset) | true | drop |
+| n/a (unset) | false | pass |
+| true | n/a (unset) | pass |
+| false | n/a (unset) | drop |
+| true | true | **drop** (excludes win) |
+| true | false | pass |
+| false | true | drop |
+| false | false | drop |
+
+---
+### Requirement: Per-thread coherence
+
+Refinement SHALL be applied at thread granularity. A thread is the set of emails sharing the same bare subject (computed per the Subject Normalization requirement below). If any message in a thread passes the include filter on an axis where `<axis>_includes` is non-empty, the whole thread SHALL be treated as passing that axis's include filter. If any message in a thread fails the exclude filter on an axis where `<axis>_excludes` is non-empty, the whole thread SHALL be dropped regardless of the other messages.
+
+#### Scenario: Stray CC drops whole thread
+
+- **GIVEN** a thread with five messages, four of which have recipients only within `@stat.sinica.edu.tw`, and one of which CCs `EDUCATION5361@yahoo.com.tw`
+- **WHEN** `recipient_excludes: ["EDUCATION5361@yahoo"]` is set
+- **THEN** all five messages of the thread SHALL be dropped from the refined corpus
+
+#### Scenario: One-message match keeps whole thread
+
+- **GIVEN** a thread with three messages, only one of which has a subject containing `Schultz`
+- **WHEN** `subject_includes: ["Schultz"]` is set
+- **THEN** all three messages SHALL pass refinement on the subject axis
+
+---
+### Requirement: Case-insensitive substring matching with bare-value normalization
+
+All refinement matching SHALL be case-insensitive substring matching. The skill SHALL lowercase both the configured list entries and the axis-target value before comparison. The axis-target value SHALL be normalized as follows:
+
+- For `sender_includes` / `sender_excludes`: the email address only, with any display-name prefix stripped (e.g., `"Che Cheng" <che@as.edu.tw>` SHALL be matched against `che@as.edu.tw`).
+- For `recipient_includes` / `recipient_excludes`: the email address of each recipient in turn, with display-name prefixes stripped.
+- For `subject_includes` / `subject_excludes`: the bare subject, computed by stripping any leading sequence of `Re:`, `RE:`, `Fwd:`, `FW:`, `转发:`, or `轉寄:` prefixes (each followed by optional whitespace).
+
+#### Scenario: Mixed-case match
+
+- **WHEN** `sender_excludes: ["@YAHOO.COM"]` is set
+- **AND** an email's sender is `Foo Bar <foo@yahoo.com.tw>`
+- **THEN** the email SHALL be dropped (lowercase comparison: `@yahoo.com` substring of `foo@yahoo.com.tw`)
+
+#### Scenario: Subject prefix stripping
+
+- **WHEN** `subject_excludes: ["經費"]` is set
+- **AND** an email's raw subject is `Re: 經費補助通知`
+- **THEN** the bare subject SHALL be computed as `經費補助通知` and the email SHALL be dropped
+
+##### Example: bare-subject computation
+
+| Raw subject | Bare subject |
+| --- | --- |
+| `Schultz scale 12 items` | `Schultz scale 12 items` |
+| `Re: Schultz scale 12 items` | `Schultz scale 12 items` |
+| `Re: Re: Fwd: Schultz scale` | `Schultz scale` |
+| `RE: 轉寄: 經費補助` | `經費補助` |
+
+---
+### Requirement: Refinement executes after fetch and before dedup
+
+Refinement SHALL run after the Step 3 search-time corpus fetch and before the Step 4 Message-ID dedup. Threads dropped by refinement SHALL NOT have their Message-IDs added to `email_index.json` and SHALL NOT consume slots in `threads.json`. As a consequence, a subsequent `/archive-mail` run with the same refinement config SHALL drop the same threads again without re-surfacing them as new.
+
+#### Scenario: Excluded thread does not enter index
+
+- **GIVEN** `recipient_excludes: ["EDUCATION5361@yahoo"]` is set
+- **WHEN** `/archive-mail` runs and one fetched thread has a recipient matching the substring
+- **THEN** the thread SHALL be absent from the output directory after the run
+- **AND** the thread's Message-IDs SHALL be absent from `email_index.json`
+- **AND** the thread SHALL be absent from `threads.json`
+
+#### Scenario: Subsequent run does not re-surface
+
+- **GIVEN** a prior `/archive-mail` run dropped a thread by `recipient_excludes`
+- **WHEN** `/archive-mail` runs again with the same config
+- **THEN** the same thread SHALL be dropped again
+- **AND** Step 7 SHALL NOT report it as newly archived
+
+---
+### Requirement: Phase 2 preview surfaces refinement statistics
+
+When at least one of the six refinement fields is non-empty, Step 4.5 Phase 2 preview SHALL include a refinement statistics block listing the number of threads kept, the total dropped, and a per-category breakdown (`sender_excludes`, `recipient_excludes`, `subject_excludes`, `includes` filtered-out). Categories with zero drops SHALL be omitted from the breakdown. When all six fields are unset, the refinement statistics block SHALL be omitted entirely.
+
+#### Scenario: Active refinement shows stats line
+
+- **WHEN** `/archive-mail` runs with `subject_excludes: ["經費"]` and 3 threads are dropped by the subject_excludes match
+- **THEN** Step 4.5 Phase 2 preview SHALL include a line of the form `Corpus refinement (includes/excludes): {kept} / 3 threads`
+- **AND** the breakdown SHALL include `Dropped by subject_excludes: 3 threads`
+- **AND** the breakdown SHALL omit categories with zero drops
+
+#### Scenario: No refinement active omits the block entirely
+
+- **WHEN** `/archive-mail` runs with all six refinement fields unset or empty
+- **THEN** Step 4.5 Phase 2 preview SHALL NOT include any refinement statistics block
+
+---
+### Requirement: Malformed refinement value aborts with explicit error
+
+When any of the six refinement fields is present in config but its value is not a YAML sequence of strings, `/archive-mail` SHALL abort at Step 1 with an explicit error message naming the offending field and the expected value shape, and SHALL exit with a non-zero status. The skill SHALL NOT silently coerce, ignore, or partially apply a malformed value.
+
+#### Scenario: Scalar instead of sequence
+
+- **WHEN** the config contains `sender_excludes: "@yahoo"` (scalar string instead of list)
+- **THEN** `/archive-mail` SHALL print an error of the form `Error: sender_excludes must be a YAML sequence of strings`
+- **AND** SHALL exit with non-zero status before performing any search or write
diff --git a/openspec/specs/archive-mail-filter-expansion/spec.md b/openspec/specs/archive-mail-filter-expansion/spec.md
new file mode 100644
index 00000000..816bc522
--- /dev/null
+++ b/openspec/specs/archive-mail-filter-expansion/spec.md
@@ -0,0 +1,11 @@
+# archive-mail-filter-expansion Specification
+
+## Purpose
+
+Defines how `/archive-mail` expands beyond sender-based search to capture complete thread corpora using subject keywords, participant aliases, and thread-subject expansion.
+
+## Requirements
+
+- Subject-keyword search expands email corpus
+- Thread-subject expansion discovers sibling messages
+- Participant aliases config field
diff --git a/openspec/specs/shiny-adaptive-walk-browser/spec.md b/openspec/specs/shiny-adaptive-walk-browser/spec.md
new file mode 100644
index 00000000..b89c1ebb
--- /dev/null
+++ b/openspec/specs/shiny-adaptive-walk-browser/spec.md
@@ -0,0 +1,157 @@
+# shiny-adaptive-walk-browser Specification
+
+## Purpose
+
+TBD - created by archiving change 'adaptive-walk-agent-browser-default'. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: Default Browser SHALL Be agent-browser
+
+The `/shiny-adaptive-walk` skill SHALL use `agent-browser` (headless Chromium) for the discovery walk phase when no explicit browser is specified via flag or environment variable. The skill SHALL NOT use `safari-browser` as the default.
+
+#### Scenario: Default invocation with no overrides
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY>` with no `--browser` flag and no `SHINY_ADAPTIVE_BROWSER` environment variable set
+- **THEN** the skill SHALL invoke `agent-browser` for all discovery walk primitives (open, snapshot, click, fill, screenshot)
+- **AND** the skill SHALL NOT spawn or focus a `safari-browser` window
+- **AND** the per-iteration commit body SHALL contain the line `BROWSER=agent`
+
+---
+### Requirement: Browser Selection Flag SHALL Accept Two Values
+
+The skill SHALL accept a `--browser` flag with exactly two valid values: `safari` and `agent`. The flag SHALL be parsed alongside existing flags (`--budget`, `--max-iter`, `--no-pr`) in the Step 0 pre-flight phase.
+
+#### Scenario: Explicit safari selection via flag
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser safari`
+- **THEN** the skill SHALL invoke `safari-browser` for the discovery walk
+- **AND** the skill SHALL pass `--url "$URL_SUBSTR"` to every safari-browser subcommand for tab targeting
+- **AND** the per-iteration commit body SHALL contain the line `BROWSER=safari`
+
+#### Scenario: Explicit agent selection via flag
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser agent`
+- **THEN** the skill SHALL invoke `agent-browser` for the discovery walk
+- **AND** the per-iteration commit body SHALL contain the line `BROWSER=agent`
+
+#### Scenario: Invalid --browser value
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser chrome`
+- **THEN** the skill SHALL abort in Step 0 pre-flight with an error message naming the accepted values
+- **AND** no app launch SHALL occur
+
+##### Example: Invalid value error
+
+- **GIVEN** invocation `/shiny-adaptive-walk QEF_DESIGN --browser firefox`
+- **WHEN** Step 0 pre-flight parses the flag
+- **THEN** the skill exits non-zero with a message containing `--browser must be one of: safari, agent (got: firefox)`
+
+---
+### Requirement: Browser Selection Environment Variable SHALL Accept Same Values
+
+The skill SHALL accept a `SHINY_ADAPTIVE_BROWSER` environment variable with the same value domain as the `--browser` flag (`safari` or `agent`). The flag SHALL take precedence over the environment variable when both are set.
+
+#### Scenario: Environment variable sets safari mode
+
+- **WHEN** the user invokes `SHINY_ADAPTIVE_BROWSER=safari /shiny-adaptive-walk <COMPANY>` with no `--browser` flag
+- **THEN** the skill SHALL invoke `safari-browser` for the discovery walk
+
+#### Scenario: Flag overrides environment variable
+
+- **WHEN** the user invokes `SHINY_ADAPTIVE_BROWSER=safari /shiny-adaptive-walk <COMPANY> --browser agent`
+- **THEN** the skill SHALL invoke `agent-browser` for the discovery walk
+
+##### Example: Precedence table
+
+| Flag        | Env var                      | Effective browser |
+| ----------- | ---------------------------- | ----------------- |
+| (unset)     | (unset)                      | agent (default)   |
+| (unset)     | SHINY_ADAPTIVE_BROWSER=safari| safari            |
+| (unset)     | SHINY_ADAPTIVE_BROWSER=agent | agent             |
+| --browser=safari | (unset)                 | safari            |
+| --browser=agent  | SHINY_ADAPTIVE_BROWSER=safari | agent (flag wins) |
+| --browser=safari | SHINY_ADAPTIVE_BROWSER=agent  | safari (flag wins) |
+
+---
+### Requirement: Pre-flight SHALL Check Only Selected Browser CLI
+
+Step 0 pre-flight SHALL verify the presence of the CLI for the selected browser. The skill SHALL NOT require both CLIs to be present.
+
+#### Scenario: agent-browser CLI missing while safari is selected
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser safari` on a system where `agent-browser` is missing but `safari-browser` is present
+- **THEN** the skill SHALL proceed past pre-flight (because `agent-browser` is not needed for this invocation)
+- **AND** the discovery walk SHALL succeed using `safari-browser`
+
+#### Scenario: safari-browser CLI missing while default is in effect
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY>` with no overrides on a system where `safari-browser` is missing but `agent-browser` is present (e.g. Linux CI)
+- **THEN** the skill SHALL proceed past pre-flight (because `safari-browser` is not needed for the default agent path)
+- **AND** the discovery walk SHALL succeed using `agent-browser`
+
+#### Scenario: Selected browser CLI missing
+
+- **WHEN** the user invokes `/shiny-adaptive-walk <COMPANY> --browser safari` on a system where `safari-browser` is missing
+- **THEN** the skill SHALL abort in Step 0 pre-flight with an error naming the missing CLI
+
+---
+### Requirement: Single Dispatcher Helper SHALL Route Discovery Primitives
+
+The skill SHALL define a single shell helper function (`browser_cmd`) before Step 3a that routes the discovery primitives to the selected browser CLI. All call sites within Step 3a SHALL invoke primitives through this helper, not by direct `safari-browser` or `agent-browser` invocation.
+
+#### Scenario: Helper dispatches to safari with --url flag
+
+- **WHEN** the helper is invoked as `browser_cmd open "$URL"` and the selected browser is safari
+- **THEN** the helper SHALL execute `safari-browser open "$URL" --url "$URL_SUBSTR"`
+
+#### Scenario: Helper dispatches to agent without --url flag
+
+- **WHEN** the helper is invoked as `browser_cmd open "$URL"` and the selected browser is agent
+- **THEN** the helper SHALL execute `agent-browser open "$URL"`
+- **AND** the helper SHALL NOT pass any `--url` argument to `agent-browser`
+
+##### Example: Dispatch table
+
+| Helper call                    | safari mode resolves to                                                | agent mode resolves to                |
+| ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------- |
+| `browser_cmd open "$URL"`      | `safari-browser open "$URL" --url "$URL_SUBSTR"`                       | `agent-browser open "$URL"`           |
+| `browser_cmd snapshot -i`      | `safari-browser snapshot -i --url "$URL_SUBSTR"`                       | `agent-browser snapshot -i`           |
+| `browser_cmd click @e2`        | `safari-browser click @e2 --url "$URL_SUBSTR"`                         | `agent-browser click @e2`             |
+| `browser_cmd fill @e1 VIBE`    | `safari-browser fill @e1 VIBE --url "$URL_SUBSTR"`                     | `agent-browser fill @e1 VIBE`         |
+| `browser_cmd screenshot file`  | `safari-browser screenshot file --url "$URL_SUBSTR"`                   | `agent-browser screenshot file`       |
+
+---
+### Requirement: Per-Iteration Commit Body SHALL Record Browser Mode
+
+Each per-iteration commit produced by the skill (matching the existing `iter-N: <summary> (refs #<parent>)` title format) SHALL contain exactly one `BROWSER=<safari|agent>` line in the commit message body.
+
+#### Scenario: Default agent invocation records BROWSER=agent
+
+- **WHEN** the skill completes iteration N with default browser selection (no flag, no env var)
+- **THEN** `git log --pretty=fuller -1 HEAD` body SHALL contain a line equal to `BROWSER=agent`
+
+#### Scenario: Explicit safari invocation records BROWSER=safari
+
+- **WHEN** the skill completes iteration N with `--browser safari`
+- **THEN** `git log --pretty=fuller -1 HEAD` body SHALL contain a line equal to `BROWSER=safari`
+
+---
+### Requirement: Anti-Pattern Table SHALL NOT Forbid agent-browser for Discovery
+
+The skill markdown's Anti-Patterns table SHALL NOT contain an entry forbidding the use of `agent-browser` for the discovery walk phase.
+
+#### Scenario: Anti-pattern entry removed
+
+- **WHEN** a reader greps the skill markdown for the prior anti-pattern text `Use agent-browser for discovery walk`
+- **THEN** the search SHALL return zero matches
+
+---
+### Requirement: Documentation SHALL Explain When to Opt Into safari
+
+The skill markdown SHALL include a section explaining the scenarios in which `--browser safari` is the appropriate choice (live demo / teaching / in-the-moment debugging / watching the loop iterate). The section SHALL be placed within or adjacent to the Configuration reference section.
+
+#### Scenario: Section exists
+
+- **WHEN** a reader greps the skill markdown for the heading `When to opt into`
+- **THEN** the search SHALL return at least one match within the Configuration area
diff --git a/plugins/agent-cacher/.claude-plugin/plugin.json b/plugins/agent-cacher/.claude-plugin/plugin.json
new file mode 100644
index 00000000..26eaa31b
--- /dev/null
+++ b/plugins/agent-cacher/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "agent-cacher",
+  "version": "0.1.0",
+  "description": "Explicit-lookup cache for AI agent shell calls — records every invocation to SQLite, exposes cache.{lookup,fetch,recent,diff} via MCP so the agent decides when to reuse cached output instead of re-running.",
+  "author": { "name": "Che Cheng" },
+  "license": "MIT",
+  "keywords": ["mcp", "cache", "agent", "shell", "sqlite", "macos", "swift"]
+}
diff --git a/plugins/agent-cacher/.mcp.json b/plugins/agent-cacher/.mcp.json
new file mode 100644
index 00000000..71d285bf
--- /dev/null
+++ b/plugins/agent-cacher/.mcp.json
@@ -0,0 +1,7 @@
+{
+  "agent-cacher": {
+    "type": "stdio",
+    "command": "${CLAUDE_PLUGIN_ROOT}/bin/cacher-mcp-wrapper.sh",
+    "description": "Explicit-lookup cache: cache.lookup / cache.fetch / cache.recent / cache.diff. Call cache.lookup BEFORE running a shell command to see if it was already executed recently."
+  }
+}
diff --git a/plugins/agent-cacher/CHANGELOG.md b/plugins/agent-cacher/CHANGELOG.md
new file mode 100644
index 00000000..c83d1d53
--- /dev/null
+++ b/plugins/agent-cacher/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [0.1.0] - (date unknown — please fill in)
+
+### Changed
+- Explicit-lookup cache for AI agent shell calls — records every invocation to SQLite, exposes cache.{lookup,fetch,recent,diff} via MCP so the agent decides when to reuse cached output instead of re-running
diff --git a/plugins/agent-cacher/README.md b/plugins/agent-cacher/README.md
new file mode 100644
index 00000000..b425bb2e
--- /dev/null
+++ b/plugins/agent-cacher/README.md
@@ -0,0 +1,44 @@
+# agent-cacher (Claude Code plugin)
+
+Plugin shell that wires [PsychQuant/agent-cacher](https://github.com/PsychQuant/agent-cacher) into Claude Code as an MCP server.
+
+## What it adds
+
+Four MCP tools, all read-only against a local SQLite cache:
+
+| Tool | Purpose |
+|------|---------|
+| `cache.lookup` | Most recent N calls matching a fingerprint signature (e.g. `gh api`) |
+| `cache.fetch` | Output bytes for a specific call ROWID (returns base64) |
+| `cache.recent` | All calls within a time window, optionally filtered by binary name |
+| `cache.diff` | Unified diff between two cached calls' outputs |
+
+## Mode B (explicit lookup) — what this is NOT
+
+This plugin does **not** transparently intercept your shell commands. The wrappers shipped in the upstream repo always actually run the underlying command and write the result to SQLite; the agent decides whether to query the cache and reuse cached output instead of re-running. See [the upstream README](https://github.com/PsychQuant/agent-cacher#design-evolution-mode-a--mode-b) for the rationale.
+
+## Auto-installed binaries
+
+`bin/cacher-mcp-wrapper.sh` downloads two binaries from the GitHub Release on first invocation:
+
+- `~/bin/cacher` — the CLI (use `cacher --help`)
+- `~/bin/cacher-mcp` — the MCP server stdio binary
+
+Source builds at `~/Developer/agent-cacher/.build/release/` are preferred when present and never overwritten.
+
+## DB location
+
+Default: `~/Library/Application Support/agent-cacher/cache.db`. Override via `AGENT_CACHER_DB_PATH` env var (set in your Claude Code settings or shell).
+
+## Recommended workflow
+
+Inside Claude Code, the agent:
+
+1. Calls `cache.recent` or `cache.lookup` BEFORE invoking a known-slow shell command.
+2. Reads the timestamp + sha256 to decide whether the cached output is fresh enough.
+3. If fresh: calls `cache.fetch` to retrieve the bytes.
+4. If stale or missing: runs the actual command (via a wrapper) — which records a fresh row.
+
+## License
+
+MIT.
diff --git a/plugins/agent-cacher/bin/cacher-mcp-wrapper.sh b/plugins/agent-cacher/bin/cacher-mcp-wrapper.sh
new file mode 100755
index 00000000..8e00b620
--- /dev/null
+++ b/plugins/agent-cacher/bin/cacher-mcp-wrapper.sh
@@ -0,0 +1,68 @@
+#!/bin/bash
+# cacher-mcp-wrapper.sh — auto-installs `cacher` CLI + `cacher-mcp` MCP server
+# from PsychQuant/agent-cacher GitHub Release, then execs the MCP server.
+#
+# Auto-upgrade design (mirrors che-telegram-mcp-wrapper):
+# - DESIRED_VERSION pins the binary version this plugin expects.
+# - Sidecar version files at ~/bin/.{cacher,cacher-mcp}.version track installs.
+# - On version mismatch, re-downloads (atomic .tmp + mv).
+# - Source builds (.build/release/...) are NEVER auto-replaced.
+
+GITHUB_REPO="PsychQuant/agent-cacher"
+INSTALL_DIR="$HOME/bin"
+DESIRED_VERSION="0.1.0"
+DOWNLOAD_TIMEOUT=120
+
+mkdir -p "$INSTALL_DIR"
+
+ensure_binary() {
+    local binary_name="$1"
+    local installed="$INSTALL_DIR/$binary_name"
+    local version_file="$INSTALL_DIR/.${binary_name}.version"
+    local installed_version=""
+    [[ -f "$version_file" ]] && installed_version=$(tr -d '[:space:]' < "$version_file" 2>/dev/null || true)
+
+    # Search order: ~/bin (install target) > /usr/local/bin > source builds (never overwritten)
+    local found=""
+    for loc in \
+        "$installed" \
+        "/usr/local/bin/$binary_name" \
+        "$HOME/.local/bin/$binary_name" \
+        "$HOME/Developer/agent-cacher/.build/release/$binary_name" \
+        "$HOME/Developer/agent-cacher/.build/debug/$binary_name"
+    do
+        [[ -x "$loc" ]] && { found="$loc"; break; }
+    done
+
+    local need_download=false
+    if [[ -z "$found" ]]; then
+        need_download=true
+    elif [[ "$found" == "$installed" ]] && [[ "$installed_version" != "$DESIRED_VERSION" ]]; then
+        need_download=true
+    fi
+
+    if $need_download; then
+        local asset_url="https://github.com/${GITHUB_REPO}/releases/download/v${DESIRED_VERSION}/${binary_name}-arm64-macos"
+        local tmp="${installed}.tmp.$$"
+        echo "agent-cacher: downloading ${binary_name} v${DESIRED_VERSION} from ${asset_url}" >&2
+        if ! curl --fail --location --silent --show-error --max-time "$DOWNLOAD_TIMEOUT" \
+                -o "$tmp" "$asset_url"; then
+            echo "agent-cacher: failed to download ${binary_name}; bailing" >&2
+            rm -f "$tmp"
+            return 1
+        fi
+        chmod +x "$tmp"
+        mv "$tmp" "$installed"
+        printf "%s" "$DESIRED_VERSION" > "$version_file"
+        found="$installed"
+    fi
+
+    printf "%s" "$found"
+}
+
+CACHER_PATH=$(ensure_binary cacher) || exit 1
+MCP_PATH=$(ensure_binary cacher-mcp) || exit 1
+
+# Both binaries now present. Hand off to the MCP server. cacher-mcp reads
+# AGENT_CACHER_DB_PATH for the DB location (see Sources/AgentCacherMCP/CacherMCP.swift).
+exec "$MCP_PATH" "$@"
diff --git a/plugins/ai-docs-guide/.claude-plugin/plugin.json b/plugins/ai-docs-guide/.claude-plugin/plugin.json
index 42322b98..8135f06a 100644
--- a/plugins/ai-docs-guide/.claude-plugin/plugin.json
+++ b/plugins/ai-docs-guide/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "ai-docs-guide",
-  "version": "1.3.1",
-  "description": "Auto-triggered Skills for querying Claude Code, OpenAI, Codex CLI, and Gemini official documentation. Codex guide queries GitHub source code for authoritative config/schema data. /ai-docs-guide for cross-platform comparison.",
+  "version": "1.4.0",
+  "description": "Auto-triggered Skills for querying Claude Code, OpenAI, Codex CLI, Gemini API, and Gemini CLI official documentation. Source-code-first strategy for CLI tools. /ai-docs-guide for cross-platform comparison.",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
   "keywords": ["claude-code", "openai", "codex", "codex-cli", "gemini", "google", "docs", "documentation", "api", "mcp", "settings"]
diff --git a/plugins/ai-docs-guide/CHANGELOG.md b/plugins/ai-docs-guide/CHANGELOG.md
new file mode 100644
index 00000000..5aec4944
--- /dev/null
+++ b/plugins/ai-docs-guide/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.4.0] - (date unknown — please fill in)
+
+### Changed
+- Auto-triggered Skills for querying Claude Code, OpenAI, Codex CLI, Gemini API, and Gemini CLI official documentation.
+- Source-code-first strategy for CLI tools. /ai-docs-guide for cross-platform comparison
diff --git a/plugins/ai-docs-guide/skills/claude-docs-guide/SKILL.md b/plugins/ai-docs-guide/skills/claude-code-guide/SKILL.md
similarity index 98%
rename from plugins/ai-docs-guide/skills/claude-docs-guide/SKILL.md
rename to plugins/ai-docs-guide/skills/claude-code-guide/SKILL.md
index ca1c718a..3cc92d6f 100644
--- a/plugins/ai-docs-guide/skills/claude-docs-guide/SKILL.md
+++ b/plugins/ai-docs-guide/skills/claude-code-guide/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: claude-docs-guide
+name: claude-code-guide
 description: |
   Query Claude Code configuration, file locations, MCP settings, and official documentation.
   Use this skill proactively when the conversation involves:
@@ -11,7 +11,7 @@ description: |
 allowed-tools: WebFetch
 ---
 
-# Claude Docs Guide
+# Claude Code Guide
 
 Query Claude Code official documentation directly via WebFetch.
 
diff --git a/plugins/ai-docs-guide/skills/codex-docs-guide/SKILL.md b/plugins/ai-docs-guide/skills/codex-docs-guide/SKILL.md
index 5dd54c54..c770d168 100644
--- a/plugins/ai-docs-guide/skills/codex-docs-guide/SKILL.md
+++ b/plugins/ai-docs-guide/skills/codex-docs-guide/SKILL.md
@@ -5,7 +5,7 @@ description: |
   Use this skill proactively when the conversation involves:
   - Codex CLI installation, setup, or authentication
   - Codex CLI configuration (config.toml, AGENTS.md, profiles)
-  - Codex models (GPT-5.4, GPT-5.3-Codex, Codex-Spark)
+  - Codex models (GPT-5.5, GPT-5.3-Codex, Codex-Spark)
   - Codex CLI commands, flags, slash commands
   - Codex features (fast mode, web search, multi-agent, MCP, skills)
   - Codex speed/reasoning settings
@@ -47,7 +47,7 @@ When the user asks about or the conversation involves:
 |-----------|--------|---------|
 | Config valid values, schema | Repo: config.schema.json | "What values does reasoning_effort accept?" |
 | CLI flags, options | Repo: main.rs or docs/ | "What flags does `codex` accept?" |
-| Model definitions, defaults | Repo: models.json | "What's the default reasoning effort for gpt-5.4?" |
+| Model definitions, defaults | Repo: models.json | "What's the default reasoning effort for gpt-5.5?" |
 | Protocol types, enums | Repo: protocol src | "What ReasoningEffort variants exist?" |
 | SDK types, interfaces | Repo: sdk/ | "What options does exec() accept?" |
 | Conceptual guides, tutorials | WebFetch docs site | "How does sandboxing work?" |
@@ -60,22 +60,25 @@ When the user asks about or the conversation involves:
 gh search code "keyword" --repo openai/codex --limit 20
 ```
 
-**Read specific key files via GitHub API:**
+**Read specific key files via raw URL (preferred — avoids base64/size limits):**
 ```bash
-# Config schema (all valid config keys and values)
-gh api repos/openai/codex/contents/codex-rs/core/config.schema.json -q '.content' | base64 -d
+# Config schema (all valid config keys and values) — 78KB
+curl -sL https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/config.schema.json
 
-# Model definitions (models, defaults, reasoning efforts)
-gh api repos/openai/codex/contents/codex-rs/core/models.json -q '.content' | base64 -d
+# Model definitions (models, defaults, reasoning efforts) — 251KB, too large for gh api contents
+curl -sL https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/models.json
 
 # CLI entry point (flags, arguments)
-gh api repos/openai/codex/contents/codex-rs/exec/src/main.rs -q '.content' | base64 -d
+curl -sL https://raw.githubusercontent.com/openai/codex/main/codex-rs/exec/src/main.rs
 
 # In-repo documentation
 gh api repos/openai/codex/contents/docs/ -q '.[].name'
-gh api repos/openai/codex/contents/docs/config.md -q '.content' | base64 -d
+curl -sL https://raw.githubusercontent.com/openai/codex/main/docs/config.md
 ```
 
+> **IMPORTANT**: Do NOT use `gh api repos/.../contents/FILE -q '.content' | base64 -d` for files > 100KB.
+> GitHub API returns empty content for large files. Always use `curl -sL` with raw.githubusercontent.com.
+
 **Key files in `openai/codex` repo:**
 
 | File | Contains |
@@ -136,7 +139,7 @@ brew install codex              # Homebrew
 ### Key CLI flags
 | Flag | Purpose |
 |------|---------|
-| `-m, --model` | Override model (e.g. `gpt-5.4`) |
+| `-m, --model` | Override model (e.g. `gpt-5.5`) |
 | `-a, --ask-for-approval` | `untrusted` / `on-request` / `never` |
 | `-s, --sandbox` | `read-only` / `workspace-write` / `danger-full-access` |
 | `-i, --image` | Attach image files |
diff --git a/plugins/ai-docs-guide/skills/gemini-cli-guide/SKILL.md b/plugins/ai-docs-guide/skills/gemini-cli-guide/SKILL.md
new file mode 100644
index 00000000..fbf8672c
--- /dev/null
+++ b/plugins/ai-docs-guide/skills/gemini-cli-guide/SKILL.md
@@ -0,0 +1,190 @@
+---
+name: gemini-cli-guide
+description: |
+  Query Google Gemini CLI configuration, features, and documentation.
+  Use this skill proactively when the conversation involves:
+  - Gemini CLI installation, setup, or authentication
+  - Gemini CLI configuration (GEMINI.md, settings, themes)
+  - Gemini CLI commands, flags, slash commands
+  - Gemini CLI features (sandbox, plan mode, yolo, skills, hooks)
+  - Gemini CLI model routing, model steering
+  - Gemini CLI extensions, MCP, ACP mode
+  - Gemini CLI headless/non-interactive mode
+  - Gemini CLI policy engine, trusted folders
+  - Gemini CLI session management, checkpointing, rewind
+allowed-tools: Bash, WebFetch
+---
+
+# Gemini CLI Docs Guide
+
+Query Gemini CLI source code and official documentation for accurate, up-to-date information.
+
+## When to Use
+
+When the user asks about or the conversation involves:
+- Gemini CLI setup, configuration, or commands
+- Gemini CLI model selection, routing, or steering
+- Gemini CLI sandbox, approval modes, policy engine
+- GEMINI.md, skills, hooks, extensions
+- Gemini CLI headless mode, ACP, automation
+- Any Google Gemini CLI product or feature
+
+## Strategy: Source Code First, Docs Second
+
+**Primary source**: [`google-gemini/gemini-cli`](https://github.com/google-gemini/gemini-cli) GitHub repo.
+
+**Secondary source**: WebFetch from `https://geminicli.com/docs/` — for conceptual guides and tutorials.
+
+## Execution Steps (IMPORTANT!)
+
+**You MUST query the source — never answer from memory!**
+
+### Step 1: Determine query type and choose method
+
+| Query Type | Method | Example |
+|-----------|--------|---------|
+| Config options, settings | Repo: docs/reference/configuration.md | "What settings can I configure?" |
+| CLI flags, options | Repo: docs/cli/cli-reference.md | "What flags does `gemini` accept?" |
+| Model routing, steering | Repo: docs/cli/model-routing.md | "How to route models?" |
+| Policy engine | Repo: docs/reference/policy-engine.md | "How does policy engine work?" |
+| Skills, hooks | Repo: docs/cli/skills.md, hooks/ | "How to create skills?" |
+| Extensions, MCP | Repo: docs/extensions/ | "How to add MCP servers?" |
+| Conceptual guides | WebFetch docs site | "How does sandboxing work?" |
+
+### Step 2a: Query GitHub Repo (primary)
+
+**Search for keywords across the repo:**
+```bash
+gh search code "keyword" --repo google-gemini/gemini-cli --limit 20
+```
+
+**Read specific key files via raw URL:**
+```bash
+# CLI reference (flags, arguments)
+curl -sL https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/cli-reference.md
+
+# Configuration reference
+curl -sL https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/reference/configuration.md
+
+# Model routing
+curl -sL https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/model-routing.md
+
+# Skills
+curl -sL https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/skills.md
+
+# Policy engine
+curl -sL https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/reference/policy-engine.md
+
+# List all docs
+gh api repos/google-gemini/gemini-cli/contents/docs/cli -q '.[].name'
+gh api repos/google-gemini/gemini-cli/contents/docs/reference -q '.[].name'
+```
+
+> **IMPORTANT**: Always use `curl -sL` with raw.githubusercontent.com for reading files.
+> Do NOT use `gh api contents -q '.content' | base64 -d` — it fails for files > 100KB.
+
+**Key docs in `google-gemini/gemini-cli` repo:**
+
+| File | Contains |
+|------|----------|
+| `docs/cli/cli-reference.md` | CLI flags, arguments |
+| `docs/reference/configuration.md` | All config options |
+| `docs/reference/commands.md` | Slash commands reference |
+| `docs/reference/keyboard-shortcuts.md` | Keyboard shortcuts |
+| `docs/reference/tools.md` | Available tools |
+| `docs/reference/policy-engine.md` | Policy engine rules |
+| `docs/cli/model.md` | Model selection |
+| `docs/cli/model-routing.md` | Model routing |
+| `docs/cli/model-steering.md` | Model steering |
+| `docs/cli/sandbox.md` | Sandbox modes |
+| `docs/cli/skills.md` | Skills system |
+| `docs/cli/creating-skills.md` | How to create skills |
+| `docs/cli/custom-commands.md` | Custom slash commands |
+| `docs/cli/gemini-md.md` | GEMINI.md instructions file |
+| `docs/cli/headless.md` | Non-interactive mode |
+| `docs/cli/plan-mode.md` | Plan mode |
+| `docs/cli/settings.md` | Settings UI |
+| `docs/cli/session-management.md` | Session management |
+| `docs/cli/checkpointing.md` | Checkpointing |
+| `docs/cli/rewind.md` | Rewind feature |
+| `docs/cli/acp-mode.md` | Agent Communication Protocol |
+| `docs/cli/gemini-ignore.md` | .geminiignore file |
+| `docs/cli/trusted-folders.md` | Trusted folders |
+| `docs/extensions/` | Extension system |
+| `docs/hooks/` | Hooks system |
+
+### Step 2b: Query Docs Site (secondary)
+
+Prepend `https://geminicli.com` to paths:
+
+| Topic | URL Path |
+|-------|----------|
+| Overview | /docs/ |
+| Get started | /docs/get-started/ |
+| CLI reference | /docs/cli/cli-reference |
+| Configuration | /docs/reference/configuration |
+| Commands | /docs/reference/commands |
+| Model routing | /docs/cli/model-routing |
+| Skills | /docs/cli/skills |
+| Hooks | /docs/hooks/ |
+| Extensions | /docs/extensions/ |
+| Sandbox | /docs/cli/sandbox |
+| Policy engine | /docs/reference/policy-engine |
+| Headless mode | /docs/cli/headless |
+
+```
+WebFetch("https://geminicli.com/docs/cli/cli-reference", "Extract documentation about...")
+```
+
+### Step 3: Parse and respond
+
+Extract relevant information and answer the user directly.
+
+## Quick Reference
+
+### Installation
+```bash
+npm install -g @google/gemini-cli   # npm
+```
+
+### Package
+`@google/gemini-cli` — GitHub: `google-gemini/gemini-cli`
+
+### Config file
+`GEMINI.md` — project-level instructions (like Claude's CLAUDE.md)
+
+### Key CLI flags
+| Flag | Purpose |
+|------|---------|
+| `-m, --model` | Override model |
+| `-p, --prompt` | Non-interactive (headless) mode |
+| `-i, --prompt-interactive` | Execute prompt then continue interactive |
+| `-s, --sandbox` | Enable sandbox |
+| `-y, --yolo` | Auto-approve all actions |
+| `--approval-mode` | `default` / `auto_edit` / `yolo` / `plan` |
+| `--policy` | Additional policy files |
+| `-e, --extensions` | Specify extensions |
+| `--acp` | Agent Communication Protocol mode |
+
+### Key paths
+| Path | Purpose |
+|------|---------|
+| `GEMINI.md` | Project instructions |
+| `.gemini/settings.json` | Project settings |
+| `~/.gemini/settings.json` | Global settings |
+| `.gemini/skills/` | Project skills |
+| `.geminiignore` | Ignore file |
+
+## Fallback
+
+If topic is not covered above:
+1. `gh search code "topic" --repo google-gemini/gemini-cli`
+2. WebSearch for `site:geminicli.com <topic>`
+3. WebFetch `https://geminicli.com/docs/` for the main index
+
+## Important Reminders
+
+- **Source code is authoritative** for valid values, schemas, and types
+- **Docs site is authoritative** for guides, tutorials, and conceptual explanations
+- Config uses `GEMINI.md` (Markdown) and `settings.json` — different from Claude Code
+- Gemini CLI uses extensions (not plugins) and has a policy engine (not hooks for permissions)
diff --git a/plugins/archive-first/.claude-plugin/plugin.json b/plugins/archive-first/.claude-plugin/plugin.json
index 1108fdf4..86d5953a 100644
--- a/plugins/archive-first/.claude-plugin/plugin.json
+++ b/plugins/archive-first/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "archive-first",
-  "description": "Protect files from AI-assisted deletion with the Archive-First strategy. PreToolUse hooks block destructive commands on archived/ paths. Toggle protection with archived-lock/archived-unlock.",
-  "version": "2.1.0",
+  "description": "v2.2.0: PreToolUse hooks now protect both archive/ and archived/ directory conventions. Regex anchored on trailing slash to avoid false positives on git archive / tar archive.tar. Toggle protection with archived-lock/archived-unlock.",
+  "version": "2.2.0",
   "author": {
     "name": "Che Cheng"
   }
diff --git a/plugins/archive-first/CHANGELOG.md b/plugins/archive-first/CHANGELOG.md
new file mode 100644
index 00000000..c71fe9c7
--- /dev/null
+++ b/plugins/archive-first/CHANGELOG.md
@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [2.2.0] - 2026-05-11
+
+### Changed
+- PreToolUse hooks now protect both `archive/` and `archived/` directory conventions. Previous releases only matched `archived/`, leaving `archive/` directories (used by `git archive`, openspec patterns, and many engineering repos in the same workstation) unprotected even though they serve the same purpose. Regex updated from `archived` to `archived?/` on the Bash hook, and from `/archived/` to `/archived?/` on Write and Edit hooks.
+- Regex now anchored on trailing slash. The earlier choice of `archived/` (over `archive/`) was motivated by false-positive concerns — `archive` as a bare word appears in `git archive HEAD`, `tar archive.tar`, etc. Requiring the trailing slash resolves the false-positive risk while accepting both naming conventions. Verified: `git archive HEAD > a.tar && rm tmp.txt` no longer triggers; `rm -rf /tmp/archive/old` and `rm -rf /tmp/archived/old` both blocked.
+- Error messages updated to read "archive/ or archived/ directory" instead of "archived/ directory".
+- Plugin description updated to reflect dual protection.
+
+### Documentation
+- See accompanying revision to the [Archive-First Defense post](https://che-cheng.vercel.app/blog/vibe-coding-data-loss) (Naming Note section) for the design history and trade-off discussion.
+
+## [2.1.1] - 2026-05-07
+
+### Fixed
+- PreToolUse Bash hook regex narrowed to word boundaries (`grep -wE`) for both `(rm|rmdir|unlink)` and `archived` matches. Previously over-broad substring grep fired false-positives on commands containing `platform` / `format` / `perform` / `transform` / `inform` / `harm` (any English word with `rm` substring) when the same command also mentioned `archived` anywhere — common in `gh issue comment` heredoc bodies discussing archive governance. Resolves #32.
+
+## [2.1.0] - (date unknown — please fill in)
+
+### Changed
+- Protect files from AI-assisted deletion with the Archive-First strategy.
+- PreToolUse hooks block destructive commands on archived/ paths.
+- Toggle protection with archived-lock/archived-unlock
diff --git a/plugins/archive-first/README.md b/plugins/archive-first/README.md
index 38a1e72b..f6da0c96 100644
--- a/plugins/archive-first/README.md
+++ b/plugins/archive-first/README.md
@@ -4,14 +4,16 @@ Protect your files from AI-assisted deletion with the Archive-First strategy.
 
 ## What it does
 
-This plugin adds three layers of protection for files in `archived/` directories:
+This plugin adds three layers of protection for files in `archive/` or `archived/` directories:
 
 | Layer | Mechanism | How |
 |-------|-----------|-----|
-| **PreToolUse hook** | Blocks destructive commands | Denies any `rm`, `rmdir`, or `unlink` targeting paths containing `archived` |
+| **PreToolUse hook** | Blocks destructive commands | Denies any `rm`, `rmdir`, or `unlink` targeting `archive/` or `archived/` paths (regex `archived?/` — trailing slash required to avoid false positives on `git archive` or `tar archive.tar`) |
 | **PostToolUse hook** | Auto-locks archived files | Applies macOS `chflags uchg` (immutable flag) after every Bash command |
 | **Slash commands** | Manual archive/unlock | `/archive-first:archive` and `/archive-first:unlock` |
 
+> Both `archive/` (preferred for new directories — matches `git archive`, macOS Archive Utility, Gmail) and `archived/` (legacy, still common) receive identical protection. See the [Archive-First Defense blog post](https://che-cheng.vercel.app/blog/vibe-coding-data-loss) Naming Note section for the design history.
+
 ## Commands
 
 ### `/archive-first:archive [path]`
diff --git a/plugins/archive-first/hooks/hooks.json b/plugins/archive-first/hooks/hooks.json
index d21619a1..98a42f3c 100644
--- a/plugins/archive-first/hooks/hooks.json
+++ b/plugins/archive-first/hooks/hooks.json
@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "[ -f ~/.cache/archive-first/disabled ] && exit 0; COMMAND=$(jq -r '.tool_input.command // empty'); if echo \"$COMMAND\" | tr ';' '\\n' | sed 's/&&/\\n/g' | sed 's/||/\\n/g' | grep -E '(rm|rmdir|unlink)' | grep -qE 'archived'; then jq -n '{hookSpecificOutput:{hookEventName:\"PreToolUse\",permissionDecision:\"deny\",permissionDecisionReason:\"Blocked: destructive command targeting archived/ directory. Use /archive-first:archived-unlock to disable protection first.\"}}'; else exit 0; fi"
+            "command": "[ -f ~/.cache/archive-first/disabled ] && exit 0; COMMAND=$(jq -r '.tool_input.command // empty'); if echo \"$COMMAND\" | tr ';' '\\n' | sed 's/&&/\\n/g' | sed 's/||/\\n/g' | grep -wE '(rm|rmdir|unlink)' | grep -qE 'archived?/'; then jq -n '{hookSpecificOutput:{hookEventName:\"PreToolUse\",permissionDecision:\"deny\",permissionDecisionReason:\"Blocked: destructive command targeting archive/ or archived/ directory. Use /archive-first:archived-unlock to disable protection first.\"}}'; else exit 0; fi"
           }
         ]
       },
@@ -15,7 +15,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "[ -f ~/.cache/archive-first/disabled ] && exit 0; FILE_PATH=$(jq -r '.tool_input.file_path // empty'); if echo \"$FILE_PATH\" | grep -qE '/archived/'; then jq -n '{hookSpecificOutput:{hookEventName:\"PreToolUse\",permissionDecision:\"deny\",permissionDecisionReason:\"Blocked: cannot write to archived/ directory. Use /archive-first:archived-unlock to disable protection first.\"}}'; else exit 0; fi"
+            "command": "[ -f ~/.cache/archive-first/disabled ] && exit 0; FILE_PATH=$(jq -r '.tool_input.file_path // empty'); if echo \"$FILE_PATH\" | grep -qE '/archived?/'; then jq -n '{hookSpecificOutput:{hookEventName:\"PreToolUse\",permissionDecision:\"deny\",permissionDecisionReason:\"Blocked: cannot write to archive/ or archived/ directory. Use /archive-first:archived-unlock to disable protection first.\"}}'; else exit 0; fi"
           }
         ]
       },
@@ -24,7 +24,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "[ -f ~/.cache/archive-first/disabled ] && exit 0; FILE_PATH=$(jq -r '.tool_input.file_path // empty'); if echo \"$FILE_PATH\" | grep -qE '/archived/'; then jq -n '{hookSpecificOutput:{hookEventName:\"PreToolUse\",permissionDecision:\"deny\",permissionDecisionReason:\"Blocked: cannot edit files in archived/ directory. Use /archive-first:archived-unlock to disable protection first.\"}}'; else exit 0; fi"
+            "command": "[ -f ~/.cache/archive-first/disabled ] && exit 0; FILE_PATH=$(jq -r '.tool_input.file_path // empty'); if echo \"$FILE_PATH\" | grep -qE '/archived?/'; then jq -n '{hookSpecificOutput:{hookEventName:\"PreToolUse\",permissionDecision:\"deny\",permissionDecisionReason:\"Blocked: cannot edit files in archive/ or archived/ directory. Use /archive-first:archived-unlock to disable protection first.\"}}'; else exit 0; fi"
           }
         ]
       }
diff --git a/plugins/batch-ocr/.claude-plugin/plugin.json b/plugins/batch-ocr/.claude-plugin/plugin.json
new file mode 100644
index 00000000..86398e14
--- /dev/null
+++ b/plugins/batch-ocr/.claude-plugin/plugin.json
@@ -0,0 +1,19 @@
+{
+  "name": "batch-ocr",
+  "version": "0.1.0",
+  "description": "Orchestration layer for batch OCR pipelines — PDF→PNG split, parallel macdoc OCR with SSH-tunnel health check + auto-retry, per-page md merge, idempotent resume, structured progress logs. Wraps the boilerplate that every 'OCR a folder of PDFs' task otherwise re-derives.",
+  "author": {
+    "name": "Che Cheng"
+  },
+  "license": "MIT",
+  "keywords": [
+    "ocr",
+    "batch",
+    "pipeline",
+    "macdoc",
+    "ollama",
+    "pdf",
+    "parallel",
+    "ssh-tunnel"
+  ]
+}
diff --git a/plugins/batch-ocr/CHANGELOG.md b/plugins/batch-ocr/CHANGELOG.md
new file mode 100644
index 00000000..c6cb3c81
--- /dev/null
+++ b/plugins/batch-ocr/CHANGELOG.md
@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-07
+
+### Added
+- Initial release of `batch-ocr` plugin (#6 in `psychquant-claude-plugins`)
+- 3 commands: `/batch-ocr <dir>`, `/batch-ocr-resume`, `/batch-ocr-status`
+- 1 skill: `batch-ocr` (full pipeline workflow + idempotency rules + migration path)
+- 2 scripts:
+  - `scripts/batch-ocr.sh` — orchestrator (Phase 1 split → Phase 2 parallel OCR → Phase 3 merge → 1-round retry)
+  - `scripts/ensure-tunnel.sh` — SSH tunnel health-check + auto-reconnect
+- Idempotency rules:
+  - Skip PDF if final `<name>.md` already non-empty
+  - Skip page OCR if `page-N.png.md` already exists
+  - `--resume` flag forces re-OCR of pages without corresponding `.md`
+- Configuration via CLI flags or `BATCH_OCR_*` env vars: `parallel` (4), `host` (localhost:11500), `model` (glm-ocr), `dpi` (200), `remote_host` (kyle)
+- Structured logs in `<input-dir>/.batch-ocr/<session-id>/log` with `failures.log` + `permanent_failures.log`
+
+### Notes
+- Currently uses `xargs -P` for parallelism. When `macdoc ocr --parallel N` (PsychQuant/macdoc#73) lands, Phase 2 will migrate to use that natively.
+- Source 77-PDF transcript OCR campaign (~100 lines of one-off pipeline shell) consolidated into reusable plugin.
diff --git a/plugins/batch-ocr/commands/batch-ocr-resume.md b/plugins/batch-ocr/commands/batch-ocr-resume.md
new file mode 100644
index 00000000..1dc747d1
--- /dev/null
+++ b/plugins/batch-ocr/commands/batch-ocr-resume.md
@@ -0,0 +1,28 @@
+---
+description: 重跑最近一次 batch-ocr session 的 permanent_failures (尚未成功的 PDF)
+argument-hint: "[session-id]  # 留白 = 最近一次 session"
+allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/batch-ocr.sh:*, ls:*, sort:*, head:*, find:*, xargs:*, macdoc:*, curl:*, mkdir:*, cat:*), Read, Glob
+---
+
+# /batch-ocr-resume
+
+重跑最近一次 batch-ocr session 的 permanent_failures。
+
+## 使用方式
+
+```
+/batch-ocr-resume                # 自動找最近 session
+/batch-ocr-resume 20260507-1430  # 指定 session-id
+```
+
+執行 script:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/batch-ocr.sh" --resume $ARGUMENTS
+```
+
+## 行為
+
+- 找 `.batch-ocr/<session>/permanent_failures.log`
+- 對每個失敗 PDF 重跑 Phase 1 / 2 / 3 (skip 已成功的 page)
+- 結果寫入新的 `.batch-ocr/<new-session>/log`
diff --git a/plugins/batch-ocr/commands/batch-ocr-status.md b/plugins/batch-ocr/commands/batch-ocr-status.md
new file mode 100644
index 00000000..ea2ff339
--- /dev/null
+++ b/plugins/batch-ocr/commands/batch-ocr-status.md
@@ -0,0 +1,40 @@
+---
+description: 顯示最近一次或指定 batch-ocr session 的進度統計 (success/failure/skip/ETA)
+argument-hint: "[session-id]  # 留白 = 最近一次 session"
+allowed-tools: Bash(ls:*, sort:*, head:*, wc:*, awk:*, find:*, cat:*, date:*), Read, Glob
+---
+
+# /batch-ocr-status
+
+顯示 batch-ocr session 的進度統計。
+
+## 使用方式
+
+```
+/batch-ocr-status                # 最近 session
+/batch-ocr-status 20260507-1430  # 指定 session
+```
+
+## 報表內容
+
+```
+Session: 20260507-1430
+─────────────────────
+Input directory: /path/to/pdfs
+PDFs total:      77
+PDFs done:       62  (80.5%)
+PDFs failed:     3
+PDFs skipped:    0   (already had final .md)
+
+Pages total:     1240
+Pages done:      1023 (82.5%)
+Pages failed:    8
+Pages pending:   209
+
+Started:         2026-05-07 14:30:12
+Last activity:   2026-05-07 15:45:33
+Elapsed:         1h 15m
+ETA:             ~18 min (linear extrapolation)
+```
+
+執行 logic:scan `.batch-ocr/<session>/log` 統計 success / failure / skip lines,計算 ETA = elapsed / done × pending。
diff --git a/plugins/batch-ocr/commands/batch-ocr.md b/plugins/batch-ocr/commands/batch-ocr.md
new file mode 100644
index 00000000..c9180bd7
--- /dev/null
+++ b/plugins/batch-ocr/commands/batch-ocr.md
@@ -0,0 +1,26 @@
+---
+description: 對整個目錄的 PDF 跑 OCR pipeline (split → parallel OCR → merge),idempotent + resume-able
+argument-hint: <directory-of-pdfs> [--parallel N] [--host kyle] [--model glm-ocr] [--resume]
+allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/batch-ocr.sh:*, ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-tunnel.sh:*, pdftoppm:*, macdoc:*, find:*, xargs:*, lsof:*, kill:*, ssh:*, curl:*, mkdir:*, cat:*, sort:*, awk:*), Read, Write, Glob
+---
+
+# /batch-ocr
+
+對整個目錄的 PDF 跑 OCR pipeline,wrap macdoc CLI 加上 SSH tunnel 管理 + 並行 + idempotency。完整 workflow 見 `skills/batch-ocr/SKILL.md`。
+
+## 使用方式
+
+```
+/batch-ocr /path/to/pdfs                          # 全部 default
+/batch-ocr /path/to/pdfs --parallel 8             # 並行 8 路
+/batch-ocr /path/to/pdfs --host localhost:11434   # 本地 Ollama 不走 SSH
+/batch-ocr /path/to/pdfs --resume                 # 只跑失敗 / 缺 .md 的 .png
+```
+
+執行 script:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/batch-ocr.sh" $ARGUMENTS
+```
+
+完成後跑 `/batch-ocr-status` 看統計,或 `/batch-ocr-resume` 重試 permanent_failures。
diff --git a/plugins/batch-ocr/scripts/batch-ocr.sh b/plugins/batch-ocr/scripts/batch-ocr.sh
new file mode 100755
index 00000000..b9ed7bf7
--- /dev/null
+++ b/plugins/batch-ocr/scripts/batch-ocr.sh
@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# batch-ocr — Folder-level OCR pipeline orchestrator.
+#
+# Wraps macdoc CLI with: PDF→PNG split (pdftoppm) → parallel OCR (xargs -P)
+# → per-page md merge → idempotent resume → structured logging.
+#
+# Usage:
+#   batch-ocr.sh <dir-of-pdfs> [--parallel N] [--host HOST] [--model M] [--dpi D] [--resume]
+
+set -u
+set -o pipefail
+
+# --- Argument parsing --------------------------------------------------------
+INPUT_DIR=""
+PARALLEL="${BATCH_OCR_PARALLEL:-4}"
+HOST="${BATCH_OCR_HOST:-localhost:11500}"
+MODEL="${BATCH_OCR_MODEL:-glm-ocr}"
+DPI="${BATCH_OCR_DPI:-200}"
+REMOTE_HOST="${BATCH_OCR_REMOTE_HOST:-kyle}"
+RESUME=0
+SESSION_ID="${BATCH_OCR_SESSION_ID:-$(date +%Y%m%d-%H%M%S)}"
+
+while (( $# > 0 )); do
+    case "$1" in
+        --parallel) PARALLEL="$2"; shift 2 ;;
+        --host) HOST="$2"; shift 2 ;;
+        --model) MODEL="$2"; shift 2 ;;
+        --dpi) DPI="$2"; shift 2 ;;
+        --remote-host) REMOTE_HOST="$2"; shift 2 ;;
+        --resume) RESUME=1; shift ;;
+        --session) SESSION_ID="$2"; shift 2 ;;
+        -*)
+            echo "Unknown flag: $1" >&2
+            exit 2
+            ;;
+        *)
+            if [[ -z "$INPUT_DIR" ]]; then
+                INPUT_DIR="$1"
+            else
+                echo "Unexpected extra argument: $1" >&2
+                exit 2
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$INPUT_DIR" ]]; then
+    echo "Usage: batch-ocr.sh <dir-of-pdfs> [options]" >&2
+    exit 2
+fi
+if [[ ! -d "$INPUT_DIR" ]]; then
+    echo "Error: '$INPUT_DIR' is not a directory" >&2
+    exit 2
+fi
+
+# --- Session paths -----------------------------------------------------------
+SESSION_DIR="${INPUT_DIR}/.batch-ocr/${SESSION_ID}"
+mkdir -p "$SESSION_DIR"
+LOG="${SESSION_DIR}/log"
+FAILURES="${SESSION_DIR}/failures.log"
+PERMANENT="${SESSION_DIR}/permanent_failures.log"
+: > "$FAILURES"
+
+log() {
+    echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')] $*" | tee -a "$LOG"
+}
+
+# --- Phase 0: ensure SSH tunnel ---------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ "$HOST" == localhost:* ]] && [[ -n "$REMOTE_HOST" ]]; then
+    LOCAL_PORT="${HOST##*:}"
+    log "Phase 0: ensure SSH tunnel localhost:${LOCAL_PORT} → ${REMOTE_HOST}"
+    "${SCRIPT_DIR}/ensure-tunnel.sh" "$LOCAL_PORT" "$REMOTE_HOST" 11434 || {
+        log "FATAL: SSH tunnel could not be established"
+        exit 3
+    }
+fi
+
+# --- Phase 1: PDF → PNG split -----------------------------------------------
+log "Phase 1: split PDFs in '$INPUT_DIR' to PNG (DPI=$DPI)"
+PHASE1_NEW=0
+PHASE1_SKIP=0
+shopt -s nullglob
+for pdf in "$INPUT_DIR"/*.pdf; do
+    base="${pdf%.pdf}"
+    name="$(basename "$base")"
+    page_dir="${INPUT_DIR}/${name}"
+    final_md="${INPUT_DIR}/${name}.md"
+
+    if [[ -s "$final_md" ]] && [[ "$RESUME" -eq 0 ]]; then
+        PHASE1_SKIP=$((PHASE1_SKIP + 1))
+        continue
+    fi
+
+    if [[ -d "$page_dir" ]] && compgen -G "${page_dir}/page-*.png" >/dev/null; then
+        # Already split — skip
+        PHASE1_SKIP=$((PHASE1_SKIP + 1))
+        continue
+    fi
+
+    mkdir -p "$page_dir"
+    if pdftoppm -r "$DPI" -png "$pdf" "${page_dir}/page" 2>>"$LOG"; then
+        PHASE1_NEW=$((PHASE1_NEW + 1))
+    else
+        log "FAIL Phase 1: $pdf"
+        echo "$pdf" >> "$FAILURES"
+    fi
+done
+log "Phase 1 done: ${PHASE1_NEW} split, ${PHASE1_SKIP} skipped"
+
+# --- Phase 2: parallel OCR --------------------------------------------------
+log "Phase 2: OCR PNGs in parallel (P=$PARALLEL, host=$HOST, model=$MODEL)"
+PHASE2_TOTAL=0
+PHASE2_PENDING_LIST=$(mktemp)
+trap 'rm -f "$PHASE2_PENDING_LIST"' EXIT
+
+while IFS= read -r png; do
+    [[ -f "${png}.md" ]] && continue
+    PHASE2_TOTAL=$((PHASE2_TOTAL + 1))
+    echo "$png"
+done < <(find "$INPUT_DIR" -name 'page-*.png' -type f) > "$PHASE2_PENDING_LIST"
+
+if [[ "$PHASE2_TOTAL" -gt 0 ]]; then
+    log "Phase 2: ${PHASE2_TOTAL} pages pending"
+    xargs -P "$PARALLEL" -I{} bash -c '
+        png="$1"; host="$2"; model="$3"; failures="$4"; logfile="$5"
+        if macdoc ocr "$png" --output "${png}.md" --host "$host" --model "$model" 2>>"$logfile"; then
+            echo "[$(date +%H:%M:%S)] OK: $png" >> "$logfile"
+        else
+            echo "[$(date +%H:%M:%S)] FAIL: $png" >> "$logfile"
+            echo "$png" >> "$failures"
+        fi
+    ' _ {} "$HOST" "$MODEL" "$FAILURES" "$LOG" < "$PHASE2_PENDING_LIST"
+else
+    log "Phase 2: nothing to OCR (all pages already have .md)"
+fi
+
+# --- Phase 3: merge per-page → per-PDF md -----------------------------------
+log "Phase 3: merge per-page md → per-PDF md"
+PHASE3_NEW=0
+PHASE3_SKIP=0
+for pdf in "$INPUT_DIR"/*.pdf; do
+    base="${pdf%.pdf}"
+    name="$(basename "$base")"
+    page_dir="${INPUT_DIR}/${name}"
+    output="${INPUT_DIR}/${name}.md"
+
+    [[ -d "$page_dir" ]] || continue
+    if [[ -s "$output" ]] && [[ "$RESUME" -eq 0 ]]; then
+        PHASE3_SKIP=$((PHASE3_SKIP + 1))
+        continue
+    fi
+
+    pages=$(find "$page_dir" -name 'page-*.png.md' -type f 2>/dev/null | sort -V)
+    if [[ -z "$pages" ]]; then
+        # No per-page md yet — skip merge for this PDF
+        continue
+    fi
+
+    {
+        while IFS= read -r pmd; do
+            cat "$pmd"
+            echo ""
+        done <<<"$pages"
+    } > "$output"
+
+    if [[ -s "$output" ]]; then
+        PHASE3_NEW=$((PHASE3_NEW + 1))
+    fi
+done
+log "Phase 3 done: ${PHASE3_NEW} merged, ${PHASE3_SKIP} skipped"
+
+# --- Failure retry (one round) ----------------------------------------------
+if [[ -s "$FAILURES" ]]; then
+    log "Retry round: ${PERMANENT} pending"
+    cp "$FAILURES" "${FAILURES}.round1"
+    : > "$FAILURES"
+    while IFS= read -r png; do
+        [[ -f "${png}.md" ]] && continue
+        if macdoc ocr "$png" --output "${png}.md" --host "$HOST" --model "$MODEL" 2>>"$LOG"; then
+            log "RETRY OK: $png"
+        else
+            log "RETRY FAIL: $png"
+            echo "$png" >> "$PERMANENT"
+        fi
+    done < "${FAILURES}.round1"
+fi
+
+# --- Report ------------------------------------------------------------------
+log "Session ${SESSION_ID} complete."
+log "  Phase 1: ${PHASE1_NEW} split / ${PHASE1_SKIP} skipped"
+log "  Phase 2: ${PHASE2_TOTAL} pages OCRed"
+log "  Phase 3: ${PHASE3_NEW} merged / ${PHASE3_SKIP} skipped"
+if [[ -s "$PERMANENT" ]]; then
+    log "  Permanent failures: $(wc -l < "$PERMANENT") (run /batch-ocr-resume)"
+    exit 1
+fi
+exit 0
diff --git a/plugins/batch-ocr/scripts/ensure-tunnel.sh b/plugins/batch-ocr/scripts/ensure-tunnel.sh
new file mode 100755
index 00000000..609a746d
--- /dev/null
+++ b/plugins/batch-ocr/scripts/ensure-tunnel.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# ensure-tunnel — Establish or repair an SSH tunnel to a remote Ollama server.
+#
+# Usage:
+#   ensure-tunnel.sh <local-port> <remote-host> <remote-port>
+#
+# Example:
+#   ensure-tunnel.sh 11500 kyle 11434
+#
+# Behavior:
+#   - Health-check via curl /api/tags (OK → return 0 silently)
+#   - On failure: kill any stale ssh listening on local-port, re-establish tunnel
+#   - Retry up to 3 times with 2s sleep between attempts
+#   - Return 0 on success, 1 on permanent failure
+
+set -u
+
+LOCAL_PORT="${1:-11500}"
+REMOTE_HOST="${2:-kyle}"
+REMOTE_PORT="${3:-11434}"
+MAX_RETRIES=3
+
+health_check() {
+    curl -s --max-time 3 "http://localhost:${LOCAL_PORT}/api/tags" >/dev/null 2>&1
+}
+
+establish_tunnel() {
+    # Kill any stale ssh listening on local port
+    local stale_pids
+    stale_pids=$(lsof -ti:"${LOCAL_PORT}" 2>/dev/null || true)
+    if [[ -n "$stale_pids" ]]; then
+        echo "ensure-tunnel: killing stale processes on port ${LOCAL_PORT}: ${stale_pids}" >&2
+        # shellcheck disable=SC2086
+        kill ${stale_pids} 2>/dev/null || true
+        sleep 1
+    fi
+
+    # Open new tunnel in background
+    ssh -fN -L "${LOCAL_PORT}:localhost:${REMOTE_PORT}" "${REMOTE_HOST}" 2>/dev/null
+    sleep 2
+}
+
+# Fast path: already healthy
+health_check && exit 0
+
+# Retry loop
+for ((i = 1; i <= MAX_RETRIES; i++)); do
+    echo "ensure-tunnel: attempt ${i}/${MAX_RETRIES} — establishing localhost:${LOCAL_PORT} → ${REMOTE_HOST}:${REMOTE_PORT}" >&2
+    establish_tunnel
+    if health_check; then
+        echo "ensure-tunnel: tunnel up after attempt ${i}" >&2
+        exit 0
+    fi
+done
+
+echo "ensure-tunnel: FAILED to establish tunnel after ${MAX_RETRIES} attempts" >&2
+exit 1
diff --git a/plugins/batch-ocr/skills/batch-ocr/SKILL.md b/plugins/batch-ocr/skills/batch-ocr/SKILL.md
new file mode 100644
index 00000000..636ac40e
--- /dev/null
+++ b/plugins/batch-ocr/skills/batch-ocr/SKILL.md
@@ -0,0 +1,179 @@
+---
+name: batch-ocr
+description: |
+  Batch OCR pipeline orchestrator wrapping macdoc — PDF→PNG split, parallel OCR with
+  SSH tunnel health check + auto-retry, per-page → per-PDF markdown merge, idempotent
+  resume from interruption. Trigger when user says "batch OCR", "OCR all the PDFs in
+  this folder", "do OCR on 50+ PDFs", "transcript exam OCR", or invokes /batch-ocr.
+argument-hint: <directory-of-pdfs> [--parallel N] [--host kyle] [--model glm-ocr]
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TaskCreate, TaskUpdate, TaskList
+---
+
+# batch-ocr — Folder-level OCR pipeline
+
+Wraps the boilerplate every "OCR a folder of PDFs" task otherwise re-derives. macdoc CLI handles single-file OCR; this skill orchestrates the surrounding pipeline.
+
+## Why this skill exists
+
+實戰: 77 個轉學考 PDF batch OCR 任務累積出近 100 行 shell pipeline (SSH tunnel health check, PDF→PNG split, xargs parallel, per-page merge, retry on failure, idempotent resume, progress tracking). 每次類似任務都重刻一次。本 plugin package 這個 pipeline,把它變成 single-command workflow。
+
+## Pipeline 三階段
+
+```
+PDFs/ (input)
+  │
+  ▼  Phase 1: split (pdftoppm -r DPI)
+PDFs/{name}/page-1.png, page-2.png, ...
+  │
+  ▼  Phase 2: parallel OCR (xargs -P N | macdoc ocr)
+PDFs/{name}/page-1.md, page-2.md, ...
+  │
+  ▼  Phase 3: merge (cat per-page → per-PDF)
+PDFs/{name}.md
+```
+
+## Step 0: Bootstrap Stage Task List(強制)
+
+```
+TaskCreate(name="ensure_tunnel",     description="Phase 0: SSH tunnel 到遠端 Ollama 建立/檢查 (per scripts/ensure-tunnel.sh)")
+TaskCreate(name="phase1_split",      description="Phase 1: pdftoppm 拆 PDFs/ 下每個 *.pdf 為 *.png 子目錄")
+TaskCreate(name="phase2_ocr",        description="Phase 2: xargs -P N | macdoc ocr 並行 OCR 每個 .png → .md")
+TaskCreate(name="phase3_merge",      description="Phase 3: 每個 PDF 的 per-page md → per-PDF md (cat 合併)")
+TaskCreate(name="report",            description="Step 4: 印 success/failure/skipped 統計 + 引導 /batch-ocr-status / /batch-ocr-resume 後續")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+## Configuration (config-style frontmatter or CLI flags)
+
+| Field | Default | Source priority |
+|-------|---------|-----------------|
+| `host` | `localhost:11500` | CLI `--host` > `.claude/.batch-ocr/config.md` > default |
+| `model` | `glm-ocr` | CLI `--model` > config > default |
+| `dpi` | `200` | CLI `--dpi` > config > default |
+| `parallel` | `4` | CLI `--parallel` > config > default |
+| `remote_host` | `kyle` | CLI `--remote-host` > config > default (用於 SSH tunnel) |
+| `tunnel_port_local` | `11500` | config > default |
+| `tunnel_port_remote` | `11434` | config > default (Ollama default port) |
+
+`.claude/.batch-ocr/config.md` 範例:
+
+```yaml
+---
+host: localhost:11500
+model: glm-ocr
+dpi: 200
+parallel: 4
+remote_host: kyle
+---
+```
+
+## Idempotency / resume rules
+
+- 若 final `<dir>/<name>.md` 存在且非空 → skip 整個 PDF
+- 若 per-page `<dir>/<name>/page-N.md` 存在 → skip 該頁 OCR
+- `--resume` flag 強制只跑沒對應 `.md` 的 `.png`(失敗重跑)
+- 結構化 log 寫入 `.batch-ocr/<session-id>/log` (session-id = ISO timestamp)
+
+## Phase 1: PDF → PNG split
+
+```bash
+for pdf in "${INPUT_DIR}"/*.pdf; do
+    base="${pdf%.pdf}"
+    name="$(basename "$base")"
+    page_dir="${INPUT_DIR}/${name}"
+
+    # Skip if final md already done
+    [ -s "${INPUT_DIR}/${name}.md" ] && continue
+
+    mkdir -p "$page_dir"
+    pdftoppm -r "${DPI:-200}" -png "$pdf" "${page_dir}/page"
+done
+```
+
+## Phase 2: Parallel OCR
+
+```bash
+# Find all PNGs that don't yet have a corresponding .md
+find "${INPUT_DIR}" -name "page-*.png" | while read png; do
+    [ -f "${png}.md" ] && continue
+    echo "$png"
+done | xargs -P "${PARALLEL:-4}" -I{} bash -c '
+    macdoc ocr "$1" --output "$1.md" --host "$2" --model "$3" \
+        || { echo "FAIL: $1" >> "$4/failures.log"; }
+' _ {} "${HOST}" "${MODEL}" "${SESSION_DIR}"
+```
+
+當 `macdoc ocr --parallel N` (PsychQuant/macdoc#73) 落地後,此段可改為單一 `macdoc ocr-batch ... --parallel N`,移除 xargs。
+
+## Phase 3: Merge per-page → per-PDF
+
+```bash
+for pdf in "${INPUT_DIR}"/*.pdf; do
+    base="${pdf%.pdf}"
+    name="$(basename "$base")"
+    page_dir="${INPUT_DIR}/${name}"
+    output="${INPUT_DIR}/${name}.md"
+
+    [ -d "$page_dir" ] || continue
+    [ -s "$output" ] && continue  # idempotent: skip if already merged
+
+    # Sort per-page md by page number (page-1.md, page-10.md, ... 數字 sort)
+    find "$page_dir" -name 'page-*.png.md' | sort -V | while read pmd; do
+        cat "$pmd"
+        echo ""
+    done > "$output"
+done
+```
+
+## SSH tunnel health check
+
+由 `scripts/ensure-tunnel.sh` 處理。每次 OCR 前 health check,失敗自動 reconnect:
+
+```bash
+ensure_tunnel() {
+    local local_port="$1" remote_host="$2" remote_port="$3"
+    if curl -s --max-time 3 "http://localhost:${local_port}/api/tags" >/dev/null 2>&1; then
+        return 0
+    fi
+    # Kill any stale ssh listening on local_port
+    lsof -ti:"${local_port}" 2>/dev/null | xargs -r kill 2>/dev/null
+    ssh -fN -L "${local_port}:localhost:${remote_port}" "${remote_host}"
+    sleep 2
+    curl -s --max-time 3 "http://localhost:${local_port}/api/tags" >/dev/null 2>&1
+}
+```
+
+## Failure retry
+
+第一輪 OCR 跑完後,看 `${SESSION_DIR}/failures.log`:
+- 若有 failure → 自動跑第二輪只處理 failure 清單
+- 第二輪仍失敗 → 寫入 `${SESSION_DIR}/permanent_failures.log`,user 可後續用 `/batch-ocr-resume` 手動重試
+
+## Skill 自身的 entry point
+
+User invokes `/batch-ocr <dir>` → command 呼叫 `scripts/batch-ocr.sh`,後者引用本 SKILL.md 的 logic。
+
+## Distinct from macdoc skill
+
+| | macdoc skill | batch-ocr skill |
+|---|---|---|
+| Granularity | Single-file OCR (`macdoc ocr file.pdf`) | Folder-level pipeline |
+| SSH tunnel | docs only | active health-check + auto-reconnect |
+| Parallelism | future `--parallel` flag | current `xargs -P` wrapper |
+| Resume | manual | built-in idempotent rules |
+| Progress | none | structured log + status command |
+
+互補,batch-ocr 呼叫 macdoc 作為單封 OCR 後端。
+
+## Migration path
+
+當 `macdoc ocr --parallel N` 落地 (PsychQuant/macdoc#73):
+- Phase 2 從 `xargs -P` 改成 `macdoc ocr-batch ... --parallel N`
+- 失敗重試由 macdoc CLI 內建處理
+- batch-ocr 仍負責 PDF→PNG / merge / resume / status
+
+## Related
+
+- `psychquant-claude-plugins#5` — macdoc skill 並行章節 (相互引用)
+- `PsychQuant/macdoc#73` — CLI `--parallel` 支援 (本 plugin 將優先使用)
diff --git a/plugins/che-apple-mail-mcp/.claude-plugin/plugin.json b/plugins/che-apple-mail-mcp/.claude-plugin/plugin.json
index eaec4594..79e6c8d4 100644
--- a/plugins/che-apple-mail-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-apple-mail-mcp/.claude-plugin/plugin.json
@@ -1,8 +1,24 @@
 {
   "name": "che-apple-mail-mcp",
-  "version": "1.1.0",
-  "description": "Apple Mail MCP server + 郵件工作流（歸檔、搜尋、管理）",
-  "author": { "name": "Che Cheng" },
+  "version": "2.20.1",
+  "binary_version": "2.10.0",
+  "description": "Apple Mail MCP server — 48 tools, reply-as-draft + IDD task enforcement + NSQL confirmation + .claude/.mail/ namespace + Layer 2 post-fetch corpus refinement (shell v2.20.1, binary v2.10.0)。Shell v2.20.1 ships binary v2.10.0 — 11-issue marathon closes #126, #128, #129, #130, #131, #133, #134, #135, #137, #138, #139: new feature `from_address` for compose_email/create_draft multi-account sender (#131); `redirect_email` boundary recipient validation (#133, #41 consistency); reply/forward + mailbox-CRUD actor wiring regression-lock (#134 + #139, closes #104 PR-A/B/C/D verify DA gaps); RedirectEmailScriptBuilder escape coverage + byte-identity golden (#135); resolveMailboxRef/mailboxRefByAccountId compose resolveAccountRef (#137, #110 sibling DRY); RFC 2047/2231 attachment-filename hardening sweep across CJK + Yahoo/Outlook 16 + path-traversal vectors (#115/#122/#124/#125/#126); cross-account move/copy README limitation (#129); positional UUID/verb-anchor assertion hardening (#128/#130); Codex layer migration deferred (#138, not recurrent); test suite 475 → 482+;full 6-AI ensemble verify every PR。Shell v2.20.0 adds six opt-in corpus-refinement config fields to `/archive-mail` (`sender_includes` / `sender_excludes` / `recipient_includes` / `recipient_excludes` / `subject_includes` / `subject_excludes`) — Layer 2 post-fetch thread-coherent refinement distinct from Layer 1 search-time `filters`; case-insensitive substring with bare-value normalization; excludes-precedence on same axis; per-thread coherence; new spec `archive-mail-corpus-refinement`; closes #76 + #84。Shell v2.19.7 ships binary v2.9.0 (#99 RFC 2047 nested decode for list_attachments — Outlook 16 Chinese filenames; #101 save_attachment account_id disambiguation for multi-account-same-display_name; #104 PR-A: 5 mutation tools mark_read/flag_email/set_flag_color/set_background_color/mark_as_junk gain account_id; #106 EnvelopeIndexReader reverse-lookup cache + accountUUIDs primitive)。疊加 Shell v2.19.6 (#73): hooks/session-start.sh compare 改 prefer `.binary_version` (post-#77 schema),fallback `.version`,杜絕每次 session start spurious SIGTERM(runtime tag vs shell version 永遠 mismatch trap)。疊加 Shell v2.19.5 ships binary v2.8.5 (#16 nested markdown lists with depth-aware <ul>/<ol>, #17 markdown tables with <table>/<thead>/<tbody> + per-column alignment, #22 markdown hardening Item D code-fence language + spec docs, #26 malformed multipart throws emlxParseFailed for handler fallback, #28 crossValidateAttachments helper + 6 filter tests, #89 list_emails SQLite do/catch + AppleScript 3x IPC reduction)。疊加 v2.18.1 (#71 get_email_metadata SQLite fallback parity + cluster #61-64 attachmentFragment hardening);v2.18.0 (#76) Staleness Detection — wrapper writes runtime state file on spawn (pid/started_at/version_at_spawn);新增 hooks/session-start.sh,session 啟動時偵測 plugin.json 與 in-memory binary 版本 drift,SIGTERM(+5s grace,SIGKILL fallback)stale PID 讓 Claude Code 重 spawn 取新 binary,徹底解決「plugin update 後當下 session 仍跑舊 binary」silent staleness 問題。疊加 v2.17.0 (#49) Workspace Layout Detection;v2.16.1 ship 鏈到 binary v2.7.1 (#72 base64 fix + #69 SQLite fast-path stderr logging + #66 .partial.emlx attachment fix);v2.16.0 config schema .md → .yaml (#47);v2.15.0 inline cid: 圖片保留 (#45);v2.14.0 dedup_strategy opt-in (#18);v2.13.0 markdown template 簡化 (#17);v2.12.0 zero-arg mode (#13/#21);v2.11.0 binary v2.7.0 multi-attachment race fix (#60);v2.6.0 marathon (8 PRs);v2.9.0 task enforcement;v2.8.0 namespace;v2.7.0 NSQL confirmation。",
+  "author": {
+    "name": "Che Cheng"
+  },
   "license": "MIT",
-  "keywords": ["mcp", "apple-mail", "email", "archive", "markdown", "applescript", "macos"]
+  "keywords": [
+    "apple-mail",
+    "applescript",
+    "archive",
+    "confirmation",
+    "email",
+    "macos",
+    "markdown",
+    "mcp",
+    "namespace",
+    "nsql",
+    "preview",
+    "threads"
+  ]
 }
diff --git a/plugins/che-apple-mail-mcp/CHANGELOG.md b/plugins/che-apple-mail-mcp/CHANGELOG.md
new file mode 100644
index 00000000..bed15bb5
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/CHANGELOG.md
@@ -0,0 +1,265 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [2.20.0] - 2026-05-18
+
+### Added
+- **#76 + #84 Layer 2 corpus refinement** — six opt-in config fields for `/archive-mail` (`sender_includes` / `sender_excludes` / `recipient_includes` / `recipient_excludes` / `subject_includes` / `subject_excludes`) implementing a two-layer corpus model: `filters` defines Layer 1 search-time corpus; the six new fields are Layer 2 post-fetch refinement applied after Step 3 fetch and before Step 4 dedup. Thread-coherent (any message matching includes keeps the whole thread; any matching excludes drops it), case-insensitive substring matching with bare-value normalization (display name stripped for sender / recipient, `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` prefixes stripped for subject), excludes-precedence on the same axis (blacklist wins when both lists match the same email). New spec `openspec/specs/archive-mail-corpus-refinement/spec.md`. Step 4.5 Phase 2 preview gains a refinement statistics block (kept / dropped totals + per-category breakdown) when at least one field is non-empty; omitted entirely when all six unset. 100% backward compatible — unset and empty lists behave identically to v2.19.7. Closes #76 + #84.
+- **Malformed refinement value detection** — Step 1 config parsing now validates the six refinement fields and aborts at parse time with `Error: <field> must be a YAML multi-line block-style sequence of strings ...` plus non-zero exit when a scalar or unsupported inline list (other than `[]`) is provided. Empty-string entries within a sequence (`sender_excludes: [""]`) are silently dropped at parse time and behave identically to `sender_excludes: []`.
+
+### Changed
+- **plugin.json description** — narrative re-led with the v2.20.0 corpus-refinement story; pre-v2.20.0 release history preserved verbatim.
+
+## [2.19.6] - 2026-05-12
+
+### Fixed
+- **#73 hook compare prefers `.binary_version` over `.version`** — `hooks/session-start.sh` jq query 改 `'.binary_version // .version // ""'`,prefer binary tag(post-#77 two-field schema),fallback shell version 維持 backward compat。修掉 v2.18.0 ~ v2.19.5 期間每次 session start spurious SIGTERM(runtime `version_at_spawn` 是 binary tag e.g. `2.8.5`,但 hook 比對 `plugin.json.version` shell `2.19.5` 永遠 mismatch → kill MCP PID → respawn → +5s grace delay + `⚠ Killing stale CheAppleMailMCP PID ...` audit noise per session)。
+- **Test coverage**: tests/test-session-start-hook.sh 加 Case 7(`binary_version` present + matches runtime → no kill)+ Case 8(`binary_version` absent → fallback `.version`)+ helper `write_plugin_json_with_binary`。TDD RED phase Case 7 在 fix 前 FAIL(stderr `Killing stale` + PID killed),GREEN 後 22/22 PASS。
+
+### Notes
+- Pure shell-only patch release;binary v2.8.5 不變
+- 解 #77 fix 留下的 incomplete migration(wrapper 端已用 `binary_version`,hook 端沒同步)
+- Auto-close trap meta-issue([PsychQuant/issue-driven-development#74](https://github.com/PsychQuant/issue-driven-development/issues/74))filed during close — anti-trailer warning text 含 literal `Closes #N` substring 觸發 GitHub auto-close,本 v2.19.6 incident 首次踩到
+- 2 Low test-coverage gaps deferred to [psychquant-claude-plugins#67](https://github.com/PsychQuant/psychquant-claude-plugins/issues/67):Case 9(new-schema mismatch kill path)+ Case 10(empty-string binary_version edge)
+- Refs PsychQuant/psychquant-claude-plugins#73 #74
+
+## [2.19.5] - 2026-05-11
+
+### Added
+- **#16 nested markdown lists** — depth-aware `<ul>`/`<ol>` rendering for nested list structures
+- **#17 markdown tables** — `<table>`/`<thead>`/`<tbody>` rendering with per-column alignment
+- **#89 `list_emails` SQLite fallback** — AppleScript path retained for compat, but new SQLite fast-path delivers 3× IPC reduction
+
+### Fixed
+- **#26 malformed multipart throws** — handler fallback for missing/corrupt MIME boundary parts no longer crashes `get_email`
+
+### Notes
+- Binary v2.8.4 → v2.8.5;swift test 313 → **342 (+29 tests over v2.8.0 series)**
+- Refs PsychQuant/che-apple-mail-mcp#16 #17 #22 #26 #28 #89
+
+## [2.19.4] - 2026-05-11
+
+### Added
+- **#28 `crossValidateAttachments` helper** — extracted from inline filter closure shared between `list_attachments` and `list_attachments_batch`;6 unit tests covering filter behavior (matching / empty / missing-name / non-String-name / all-fields-preserved)
+- **#22 Item D — code fence language hint** — emits `class="language-<hint>"` on `<pre><code>` per CommonMark recommended pattern
+
+### Documentation
+- **#22 Items A/B/C** — documented in `spec.md` as Foundation parser limitations with workarounds (already-fixed indent / U+001E vanishingly improbable / bold-in-link Foundation limitation)
+
+### Notes
+- Binary v2.8.3 → v2.8.4;swift test 321 → 329 (+8 tests)
+- Refs PsychQuant/che-apple-mail-mcp#22 #28
+
+## [2.19.3] - 2026-05-11
+
+### Removed
+- **#82** — 4 dead AppleScript `script` variable declarations
+- **#83** — 3 deprecated `text(_:metadata:)` MCP SDK calls migrated to current API
+
+### Changed
+- **#84** — Retrofitted 31 lenient `XCTAssertTrue(script.contains)` assertions to `assertOrdered` for property-in-tell-block enforcement
+
+### Notes
+- Binary v2.8.2 → v2.8.3;pure cleanup,zero behavior change,swift test 321/0/8 unchanged
+- Refs PsychQuant/che-apple-mail-mcp#82 #83 #84
+
+## [2.19.2] - 2026-05-11
+
+### Added
+- **#87 `sanitize_links` hardening grab-bag** — 5 hygiene items:
+  - Allowlist tripwire test pinning `{http, https, mailto, tel}`
+  - 6 bypass-class regression tests
+  - `htmlEscape` defense-in-depth on `href` interpolation
+  - Empty-scheme behavior documented in 4 schema descriptions
+  - Payload-scaling latency test on synthesized 10×5MB fixture
+
+### Notes
+- Binary v2.8.1 → v2.8.2;zero behavior change,swift test 313 → 321 (+8 tests)
+- Refs PsychQuant/che-apple-mail-mcp#87
+
+## [2.19.1] - 2026-05-11
+
+### Documentation
+- **#86 `sanitize_links` schema description consistency** — XSS rationale + mode-restriction qualifier repeated across `create_draft` / `reply_email` / `forward_email` / `compose_email` (fixes tool-selecting LLM blindspot from cluster A)
+
+### Notes
+- Binary v2.8.0 → v2.8.1;pure schema text change,no behavior impact,swift test 313/0/8 unchanged
+- Refs PsychQuant/che-apple-mail-mcp#86
+
+## [2.19.0] - 2026-05-11
+
+### Added
+- **#19 `sanitize_links` opt-in URL scheme allowlist for markdown mode** — defends against `[click](javascript:alert('xss'))` and `data:`/`file:`/`vbscript:` URLs via closed allowlist `{http, https, mailto, tel}`;default `false` preserves backwards compat
+- **#85 formal spec.md Requirement+Scenarios** — codifies the `sanitize_links` contract + builder-layer wiring contract tests pinning `sanitizeLinks` forwarding across the 4 script-builder functions
+- **#73 `extractHTMLBody` base64+UTF-8-QP decoding fixes** — multipart HTML with quoted-printable + UTF-8 nested transfer encodings now decode correctly
+
+### Changed
+- **#20** — dead spec scenario delete + count-free CHANGELOG + `assertOrdered` helper
+- **#21** — reply/forward AppleScript-html-denial documentation
+- **#25** — `list_attachments_batch` SQLite+`.emlx` cross-validation parity
+- **#27 + #32** — `attachmentNames` <200ms latency budget test + parity invariant
+
+### Notes
+- Binary v2.7.2 → v2.8.0;47 → **48 tools** (sanitize_links param surface);swift test 309 → 313 / 0 failures / 8 skipped
+- Refs PsychQuant/che-apple-mail-mcp#19 #85 #73
+
+## [2.18.1] - 2026-05-10
+
+### Fixed
+- **#77 wrapper sidecar tracks actual binary tag** (not plugin shell version) — two-part fix:
+  1. `plugin.json` adds explicit `binary_version` field (e.g. `"2.7.2"`),disambiguating from plugin shell's own `version` (e.g. `"2.18.1"`)。Wrapper reads it preferentially;falls back to `version` for plugins that haven't migrated。
+  2. Wrapper writes the **actual downloaded binary tag** to the sidecar,parsed from the GitHub release URL path between `/releases/download/` and the next `/`。即便 `DESIRED` 寫錯(legacy 走 shell `version` 的 plugin),sidecar 仍誠實反映 disk 上實際版本 — 下次 compare honest,不再 structurally lying
+
+### Notes
+- Binary v2.7.1 → v2.7.2 (#71 fallback parity + cluster #61-64 hardening);smoke tested wrapper bash syntax + plugin.json validity + binary_version field extraction + URL tag parser
+- Refs PsychQuant/che-apple-mail-mcp#77
+
+## [2.18.0] - 2026-05-10
+
+### Added
+- **Staleness Detection (Refs PsychQuant/che-apple-mail-mcp#76)**:wrapper 在 `exec binary` 前 atomic-write `~/bin/.CheAppleMailMCP.runtime.json` 紀錄 `{pid, started_at, version_at_spawn}`;新增 `hooks/session-start.sh`,Claude Code session 啟動時偵測 runtime state 與 `plugin.json` 的 version drift。Drift + PID alive + `command` field 含 `CheAppleMailMCP` 三條件成立 → SIGTERM(+5s grace,SIGKILL fallback)stale PID,讓 host respawn 取新 binary。
+- **`hooks/session-start.sh`**(NEW,~70 行 bash)— 全 graceful-skip:`jq` / `ps` 缺、runtime file 缺、plugin.json 缺、PID 已死、PID command field 不含 `CheAppleMailMCP`(防 PID-reuse 誤殺)→ 全部 silent exit 0,never block session start。
+- **`tests/test-session-start-hook.sh`**(NEW)— 6 case integration test(無 runtime file / version match / version mismatch+alive / mismatch+dead / jq missing / plugin.json missing),全部用 `exec -a CheAppleMailMCP-mock sleep` 模擬 MCP process。16/16 PASS。
+
+### Changed
+- `bin/che-apple-mail-mcp-wrapper.sh`:`exec binary` 前多一段 atomic write runtime state file;失敗 silent skip(`|| true`),never block spawn。Wrapper 既有 sidecar version-check 邏輯**不動**(remains first line of defense for spawn-time download)。
+
+### Notes
+- Plugin minor bump 2.17.0 → 2.18.0(new feature surface,additive,backward compat)。Plan 走 IDD `/idd-plan` approval gate,EnterPlanMode 已 user-approved。
+- 解決今日 #72 incident 的 deployment 端 root cause:即使 binary v2.7.1 已 release + plugin shell 已 bump,user 當下 session 的 in-memory MCP 仍跑舊 v2.7.0 binary 直到 manual `kill <pid>` + 重啟 Claude Code。新 hook 把這條 staleness window 自動關掉。
+- Sister issue split:[`PsychQuant/psychquant-claude-plugins#58`](https://github.com/PsychQuant/psychquant-claude-plugins/issues/58)— `plugin-tools:plugin-update` 結尾應主動警告 user(sender-side 補強),獨立 PR。
+- Out-of-scope:**#77**(sidecar tracks shell version not binary version)、**#78**(server-side markdown export API)獨立評估。
+
+## [2.17.0] - 2026-05-09
+
+### Added
+- **Workspace Layout Detection (#49)**:當 `output_dir` 既無 `$ARGUMENTS[1]` 也無 `${CONFIG_FILE}` 的 `output_dir:` 欄位給定時,probe 工作目錄按 `communications/email/` → `correspondence/emails/` → baseline default `communication/emails` 順序解析。Detection-first not prescriptive — adapt 到 user 既有 layout,不 push canonical convention。Existing user 有 explicit config 的 100% backward-compat(detection 不 fire)。
+- **Sibling-archive dedup extension (#49)**:`${output_dir}` 下若有 symlinked subdirectory(transitioned-project pattern,e.g. `communications/email/application/` → `applications/completed/.../emails/`),自動讀其下 markdown 的 `message_id:` YAML frontmatter 併入 in-memory dedup set。`find -P -maxdepth 2`,read-only,never writes to symlink target。Composes with `dedup_strategy = index | both`(skip on `last_archived`)。
+- **Ambiguity guard**:當 `communications/email/` 與 `correspondence/emails/` **同時存在且都有 `*.md`** 時,refuse to guess,abort with explicit pin recommendation(指 user 寫 `output_dir:` in config)。Mid-migration workspace 必須 explicit 指定避免 dedup-index split-brain。
+- **Detection 透明度**:啟動時 `🔍 Detected output_dir: <path> (from layout probe)` log,以及 dedup extension 觸發時 `🔗 Extended dedup with N entries from sibling archives:` log,讓 verify / diagnose 能看到 path resolution 結果。
+- **README Workspace Patterns section**(v2.17.0+):文件三種 layout、precedence(高→低:`$ARGUMENTS[1]` → config `output_dir:` → detection → default)、symlink coexistence pattern、ambiguity guard。
+
+### Notes
+- Plugin minor bump 2.16.1 → 2.17.0(new feature surface,additive,backward compat)。Plan 走 IDD `/idd-plan` approval gate,EnterPlanMode 已 user-approved 後才 chain 到 implement。
+- Out-of-scope follow-ups filed:**#50** parallel `documents_dir` detection,**#51** companion-commands(`archive-mail-view` / `archive-mail-rebuild-threads` / `archive-mail-migrate`)detection consistency,Tier C' per-contact mode(deferred until N≥3 evidence)。
+- Sister-bug observation during scout:v2.16.1 release(2026-05-09 commit `8089765`)沒寫 CHANGELOG entry — 屬 KAC sync drift,**留給 follow-up issue 補 backfill**(本 PR 不混進)。
+
+## [2.16.1] - 2026-05-09
+
+### Notes
+- **Bump-only release** to ship binary v2.7.1 + catch up tool count drift in `plugin.json` / `marketplace.json` descriptions (44 → 47)。Shell 邏輯 v2.16.0 不變,本版本只更新 wrapper 拉取的 binary tag。Backfilled per **#52** (sister concern from #49) — original v2.16.1 commit `8089765` 漏寫此 entry,KAC invariant 要求 every released version 有 entry。
+- Binary v2.7.1 ships:
+  - **#72** base64 decoding fix — attachments with unusual MIME encoding now save correctly
+  - **#69** SQLite fast-path stderr logging — silent fallback to AppleScript path now visible in logs
+  - **#66** `.partial.emlx` attachment fix — incomplete download artifacts no longer crash get_email parsing
+- Tool count drift catch-up (44 → 47): commit `8089765` 只 touched `plugin.json` + `marketplace.json` description fields(README 未變動)。per `tool-readme-sync` audit pattern,後續 release 應補做 README 同步檢查。
+
+## [2.16.0] - 2026-05-07
+
+### Changed
+- **Config schema rename `.md` → `.yaml` (#47)**:`.claude/.mail/config.md` (v2.8.0–v2.15.0) 改名 `.claude/.mail/config.yaml`。原因:副檔名語意 ↔ 實際內容(YAML)一致;IDE 接 yaml-lsp;新 user 不被 `.md` 暗示「要寫 markdown body」誤導。
+- 三處 mental model(spec / README / awk parser)統一稱「YAML config」,排除 「frontmatter」說法(parser 對 `---` boundary 自然 tolerant,因 `^---$` 不 match `^[a-z_]+:`)。
+
+### Added
+- **Auto-migrate `.md` → `.yaml`** in `archive-mail.md` Step 1.6 + `archive-mail-migrate` command。Silent rename,user 不需動手。順序:legacy `.claude/emails.md` (v2.7.0 ↓) → `.yaml`;then `.claude/.mail/config.md` (v2.8.0–v2.15.0) → `.yaml`。
+- archive-mail.md `argument-hint` frontmatter + 使用方式 section 更新 path 引用。
+- CLAUDE.md schema 段標題 `.claude/.mail/config.yaml Schema (v2.16.0+ #47)` + 路徑遷移說明。
+- README archive-mail 段加 v2.16.0 highlight + File Layout `.yaml` 標示。
+
+### Deprecated
+- `.claude/.mail/config.md`:仍 work 為 fallback(parser 對舊檔自動相容),**v3.0 移除**。期間文件示範一律用 `.yaml`。
+
+### Notes
+- Plugin minor bump 2.15.0 → 2.16.0(new feature surface,backward compat;default behavior 對既有 `.md` user 透過 silent migration 不 break)。
+- User decision (#issuecomment-4395581948):走 YAML 路線;選 Option C 漸進過渡(雙支援期 + v3.0 強制 `.yaml`)而非 Option A 立即 break。
+
+## [2.15.0] - 2026-05-07
+
+### Added
+- **Inline `cid:` image preservation in `/archive-mail` (#45)**:resolves dogfood gap where 「Solution? (affine repre + Iverson's law of similarity)」 thread 11 封信中 1 張 CleanShot screenshot inline-embedded via `cid:` 完全 miss(因 `list_attachments` 不回 `Content-Disposition: inline` images)。
+- **Step 5.5.0** (new) parses HTML body via regex `<img\s+...src="cid:..."...alt="...">` → extracts `(cid, alt_filename)` pairs → tries `save_attachment(attachment_name=alt, save_path=<stem>/inline/<alt>)`
+- **Step 5.5.5** (new) fallback: if `save_attachment` doesn't recognize inline filename (binary-side limitation), writes cross-reference note `Inline images: - (cid:XXX — filename — binary unsupported; see Mail.app)` instead of silent skip
+- **`Inline images:` section** in archive markdown (separate from `Attachments:`); image syntax `![alt](path)` for direct render in markdown viewers (vs link syntax for explicit attachments)
+- **Folder layout**: `correspondence/attachments/<email_stem>/inline/<filename>` — sub-folder under existing stem dir; preserves semantic distinction between user-attached files vs inline illustrations
+- **Step 8a Coverage Audit** updated: split into 8a.1 explicit + 8a.2 inline; report shows `explicit N/M + inline P/Q` format
+- **Step 7 report** adds inline count line (only if any inline images present)
+
+### Notes
+- Skill-side workaround only;binary `save_attachment` 是否認得 inline filename **尚未驗證**(待實測,可能需要 follow-up upstream issue)
+- 既有 archives 不會 retroactive process — inline 圖片仍是占位文字,user 手動補
+- Plugin minor bump 2.14.0 → 2.15.0 (new feature surface,backward compat 預設行為不變)
+
+## [2.14.0] - 2026-05-07
+
+### Added
+- **Opt-in `dedup_strategy` for `/archive-mail` (#18)**:resolves real-world observation that `.email_index.json` is rarely built / used — tatsuma project ran archive-mail for 3 years without producing one. New `.claude/.mail/config.md` field `dedup_strategy` with three values:
+  - `index` (default,backward compat) — load + write `email_index.json` as before
+  - `last_archived` — skip index entirely;use `last_archived` ISO-date as `date_from` for Step 3 search;requires `last_archived` field set in config (fail-fast if missing,prevents silent full-inbox scan)
+  - `both` — load index AND apply date filter (Message-ID set ∪ date filter)
+- Step 1.6 of archive-mail.md gains a strategy-resolve block;Step 2 conditionally skips index load;Step 4 dedup logic branches per strategy;Step 5/6 conditionally skip index write.
+- CLAUDE.md schema docs updated with `dedup_strategy` + `last_archived` fields.
+
+### Notes
+- Default behavior unchanged from v2.13.0;existing archives continue with index-based dedup until user explicitly opts into `last_archived` or `both`.
+
+## [2.13.0] - 2026-05-07
+
+### Changed
+- **BEHAVIOR CHANGE — `/archive-mail` Step 5 markdown template default simplified (#17)**: previously every archived email got a 4-section template (元數據表 + 信件內容 + 重點摘要 + 待辦事項). Real-world usage (tatsuma project, 50 historical archives) showed the elaborate sections are unused noise — AI summaries are unreliable and require manual review, breaking batch processing consistency. Default is now a simple template (frontmatter + 4-line `Subject/From/To/Date` header + body), matching the historical convention. Existing archives are NOT reprocessed (Message-ID dedup prevents). Users wanting the old elaborate template can opt in via `.claude/.mail/config.md` frontmatter `enrichment: summary+todos`.
+- Plugin version bumped 2.12.0 → 2.13.0 (after #13 PR #39 landed at 2.12.0). Frontmatter still includes all 6 fields (`message_id` / `thread_key` / `in_reply_to` / `date` / `sender` / `direction`) — thread index reconstruction depends on these.
+
+### Added
+- `enrichment` field to `.claude/.mail/config.md` schema. Values: `none` (default, simple template) | `summary+todos` (4-section enriched template). Documented in plugin CLAUDE.md.
+
+## [2.12.0] - 2026-05-07
+
+### Added
+- `/archive-mail` 零參數模式 (#13):當 `$ARGUMENTS` 為空時,從 `.claude/.mail/config.md` frontmatter 讀 `filters` / `output_dir` / `last_archived` / `exclude_mailboxes` 自動執行。命令列參數覆寫 config 維持 backward compat。空 config + 零參數會 fail-fast 提示而非靜默 archive 全 inbox(危險預防)。
+- `argument-hint` frontmatter 改 `[email-filter] [output-dir]`,UI 正確標示 v2.12.0+ filter 為可選 (#21)。
+
+## [2.10.3] - 2026-05-03
+
+### Changed
+- **Plugin shell bumped to notify binary v2.6.0** ([release notes](https://github.com/PsychQuant/che-apple-mail-mcp/releases/tag/v2.6.0)). Marathon release: 16 issues across 8 PRs landed in binary repo. Plugin shell version-aware wrapper auto-downloads new binary on next session start.
+
+### Security
+- Binary v2.6.0 ships: id injection guard ([#50](https://github.com/PsychQuant/che-apple-mail-mcp/issues/50)), attachment path deny-list + `MAIL_MCP_ATTACHMENT_ROOTS` allow-list ([#38](https://github.com/PsychQuant/che-apple-mail-mcp/issues/38)), email address validation ([#41](https://github.com/PsychQuant/che-apple-mail-mcp/issues/41)), type-strict handler params ([#35](https://github.com/PsychQuant/che-apple-mail-mcp/issues/35)), new `SECURITY.md` ([#48](https://github.com/PsychQuant/che-apple-mail-mcp/issues/48)).
+
+### Fixed
+- Binary v2.6.0 ships: `forward_email` plain mode embeds quoted original ([#44](https://github.com/PsychQuant/che-apple-mail-mcp/issues/44)) — mirrors v2.5.0 `reply_email` fix.
+
+## [2.10.2] - 2026-05-03
+
+### Changed
+- **Plugin shell bumped to notify binary v2.5.0** ([release notes](https://github.com/PsychQuant/che-apple-mail-mcp/releases/tag/v2.5.0)).
+
+### Fixed
+- Binary v2.5.0 ships: `reply_email` plain mode embeds quoted original ([#43](https://github.com/PsychQuant/che-apple-mail-mcp/issues/43)) via Swift-side `composeReplyPlainText` helper. RFC 3676 `> ` prefix + CRLF normalization + empty-line `>` stuffing + pre-fetch graceful degrade. Pre-fix every plain-format `reply_email` call since `b8a4a89` (initial release) silently dropped the quoted original.
+
+## [2.10.1] - 2026-05-02
+
+### Changed
+- **Plugin shell bumped to notify binary v2.4.1** ([release notes](https://github.com/PsychQuant/che-apple-mail-mcp/releases/tag/v2.4.1)).
+
+### Fixed
+- Binary v2.4.1 ships ([#33 verify findings A+B](https://github.com/PsychQuant/che-apple-mail-mcp/issues/33)): `reply_email` `save_as_draft=true` no longer pops Mail.app reply window; `replyEmail` validates attachment paths up-front mirroring `composeEmail` / `createDraft`.
+
+## [2.10.0] - 2026-05-02
+
+### Added
+- **Plugin shell bumped to notify binary v2.4.0 reply-as-draft mode** ([issue #33](https://github.com/PsychQuant/che-apple-mail-mcp/issues/33)). `reply_email` gains 3 optional params: `cc_additional`, `attachments`, `save_as_draft`. Unblocks workflow: reply to existing thread + add CC + attach files + save as draft for human review before sending.
+
+## [2.9.0] - 2026-05-01
+
+### Changed
+- Apple Mail MCP server — 44+ tools, IDD-style task enforcement + NSQL confirmation + .claude/.mail/ namespace (v2.9.0)。v2.9.0: archive-mail 與 confirmation-protocol skill Step 0 強制 TaskCreate bootstrap,靜默 skip = 違規。疊加 v2.8.0 namespace、v2.7.0 NSQL confirmation、v2.6.0 thread index、v2.5.0 composing format、v2.4.0 搜尋擴展。
diff --git a/plugins/che-apple-mail-mcp/CLAUDE.md b/plugins/che-apple-mail-mcp/CLAUDE.md
new file mode 100644
index 00000000..9b0074e2
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/CLAUDE.md
@@ -0,0 +1,324 @@
+# che-apple-mail-mcp
+
+Apple Mail MCP server for macOS,加上 NSQL-derived confirmation protocol + IDD-derived task enforcement。
+
+## 鐵律:Step 0 Bootstrap Stage Task List(v2.9.0+)
+
+**`/archive-mail` 與 `confirmation-protocol` skill 的第一個動作必須是 `TaskCreate`**,把該 stage 的所有 execution sub-steps 建成 harness-level todo list。完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+學自 IDD plugin 的 enforcement pattern。為什麼:
+
+- v2.7.0 加 confirmation-protocol skill,v2.8.0 加 namespace migration,但 spec-level 的「應該 confirm / 應該掃 false positive」依賴 Claude 讀 markdown 後自願執行
+- 歷史 incident:2026-05-01 archive 陳老師信件,265250 false positive 漏網 → spec 有寫但被跳過
+- TaskCreate 把每個 phase 變成 UI 可見的 binary state,跳過會留下 incomplete task 顯眼
+
+兩處強制 bootstrap:
+- `commands/archive-mail.md` Step 0 → 10 個 stage tasks (resolve_filter_and_paths / phase1_disambiguation / load_indices_and_config / search_emails / filter_and_scan_false_positives / phase2_3_preview_and_confirm / fetch_and_write_markdown / download_and_classify_attachments / update_indices / report_and_audit)
+- `skills/confirmation-protocol/SKILL.md` → 4 個 phase tasks (disambiguation / search_preview / operation_confirmation / execute_or_iterate)
+
+可 skip 的 phase(明確 filter 跳 Phase 1)也要 `TaskUpdate completed` + 在 description append skip 原因,不可只是不做。
+
+## Components
+
+### MCP Server
+- **mail** ← `bin/che-apple-mail-mcp-wrapper.sh`(Swift binary)
+- 提供 44+ tools 操作 Apple Mail.app:list/search/get/compose/move/delete/attachment
+
+### Commands
+- `/archive-mail` — 歸檔指定聯絡人的郵件到 Markdown(v2.7.0+ 加入 confirmation phases、v2.8.0+ 用 `.claude/.mail/` namespace)
+- `/archive-mail-view` — 從 `threads.json` 生成 thread 聚合視圖
+- `/archive-mail-rebuild-threads` — 從 per-email md 重建 thread index
+- `/archive-mail-migrate`(v2.8.0+)— 一次性把舊 archive 的 indices + config 搬到 `.claude/.mail/` namespace
+
+### Skills(v2.7.0+ 新增)
+- `confirmation-protocol` — NSQL-style confirmation workflow,在執行前 show preview 讓 user confirm/correct
+- `email-search-disambiguation` — 處理模糊 filter(中文人名、相對時間、通用 scope)
+- `bulk-operation-preview` — ≥ 5 封 emails 的 preview format,含 false-positive flagging
+
+### Rules(v2.7.0+ 新增)
+- `confirmation-triggers.md` — 何時必 confirm、何時可 skip
+- `false-positive-detection.md` — Search 結果中偵測 sibling activity / CC pollution / subject collision
+
+## 設計哲學
+
+### NSQL Confirmation Protocol
+
+借鑑 [`/Users/che/Developer/nsql`](file:///Users/che/Developer/nsql) 的核心 insight:
+
+> AI 不直接執行,先 show 結構化的「我理解你要的是這樣」讓 user confirm/correct/reject,achieve consensus 後才執行。
+
+原始 nsql 設計給 SQL/data query;這裡 adapt 到 Apple Mail。觸發 confirmation 的 4 個常見情境:
+
+1. **Filter 模糊**:「陳老師」、「最近的信」、「VIP 寄來的」 → disambiguation
+2. **Bulk operation**:search 結果 ≥ 5 封 → preview + false-positive flagging
+3. **Destructive**:delete_email、empty Trash → operation confirmation
+4. **Compose 寄出**:compose_email、reply_email → 信件 preview
+
+### 為什麼這個 protocol 重要(real case)
+
+2026-05-01 archive 陳老師信件時,直接 search → fetch 19 封 → 寫 markdown,事後發現 265250 是 false positive(寄給 scchen 不是 cchen),又走一輪 rm + index 修復。
+
+如果有 confirmation skill,Phase 2 (search preview) 會 flag 這封並讓 user 排除,完全 prevent false-positive round trip。從 v2.7.0 開始,archive-mail 預設套用這個 protocol。
+
+## 4-Phase Confirmation Workflow
+
+```
+user request
+  │
+  ▼
+Phase 1: Disambiguation
+  └─ 模糊 filter → 列出候選讓 user 選
+  └─ 由 email-search-disambiguation skill 負責
+  │
+  ▼
+Phase 2: Search Preview
+  └─ 展示 search 結果(thread 分布)
+  └─ Flag false-positive 候選
+  └─ 由 bulk-operation-preview skill 負責
+  │
+  ▼
+Phase 3: Operation Confirmation
+  └─ 展示 side-effect scope(N files written, K attachments, etc.)
+  └─ Destructive op 加警告
+  │
+  ▼
+Phase 4: Execute or Iterate
+  └─ User 確認 → 執行
+  └─ User 修改 → 回 Phase 1/2/3
+  └─ User 拒絕 → abort
+```
+
+## Skip confirmation 的條件
+
+可以直接執行(skip protocol):
+
+- 明確 Message-ID 的 read-only 操作
+- 單封 mark_read / unflag
+- 純 search/list(沒 side effect)
+- User 說「直接做,不要問」
+
+詳見 `rules/confirmation-triggers.md`。
+
+## Use Cases
+
+### Case 1: 完整流程(filter 模糊 + bulk + read-only)
+
+```
+user: 把陳老師有關的信都歸檔
+
+AI [Phase 1]: 「陳老師」可能對應到 cchen / scchen / 其他?
+user: cchen
+AI [Phase 2]: 找到 19 封,7 個 threads。⚠ 1 個是 sibling activity 不該歸入。要排除嗎?
+user: 排除
+AI [Phase 3]: 我將寫 18 個 markdown + 下載 1 個附件 + 寫 2 個 index。確認?
+user: 對
+AI [Phase 4]: [執行]
+```
+
+### Case 2: 明確 filter(skip Phase 1)
+
+```
+user: archive cchen@stat.sinica.edu.tw 過去一週
+
+AI [skip Phase 1]: filter 明確,跳過 disambiguation
+AI [Phase 2]: 找到 3 封,沒 false positive。
+AI [Phase 3]: 寫 3 個 markdown。確認?
+user: 對
+AI [Phase 4]: [執行]
+```
+
+### Case 3: Destructive(必 Phase 3)
+
+```
+user: 把 spam@example.com 的信全部刪掉
+
+AI [Phase 2]: 找到 247 封 spam emails。沒 false positive。
+AI [Phase 3]:
+   DELETE on Mail
+   with sender = "spam@example.com"
+   affecting 247 emails
+   ⚠ 進 Trash 後 30 天清除,可在那之前 undo
+   確認?
+user: 確認
+AI [Phase 4]: [執行]
+```
+
+### Case 4: Read-only single op(完全 skip)
+
+```
+user: get_email id=12345
+
+AI: [直接執行,沒 confirmation]
+```
+
+## Configuration
+
+> **路徑遷移**:v2.7.0 ↓ 用 `.claude/emails.md`,v2.8.0+ 改用 `.claude/.mail/config.md`(auto-migrate),**v2.16.0+ 改用 `.claude/.mail/config.yaml`** 副檔名(silent rename per #47;legacy `.md` 仍 fallback,v3.0 移除)。下述 schema 三者通用。
+
+### `.claude/.mail/config.yaml` Schema (v2.16.0+ #47)
+
+> v2.15.0 ↓ 路徑為 `.claude/.mail/config.md`(legacy),首次跑 `/archive-mail` 或 `/archive-mail-migrate` 自動 rename。內容格式不變。
+
+YAML frontmatter,空白 body。所有欄位可選,未填走 default。
+
+```yaml
+---
+filters:                           # 預設 filter 清單(零參數模式讀此)
+  - cchen                          #   string:可以是 email、email prefix、display name alias
+  - coco891017                     #   match logic:Swift-side substring + Phase 1 disambiguation
+
+participant_aliases:               # 模糊人名 → 標準 email 對應表
+  "陳老師": cchen@stat.sinica.edu.tw
+  "林助理": coco891017@webmail.stat.sinica.edu.tw
+
+subject_keywords_strict: true      # bool, default false。true = subject-only match 不算 hit;
+                                   # 防止「履歷」這種 generic 關鍵字汙染 result
+
+enrichment: none                   # v2.13.0+: 'none'(預設,簡單 template) | 'summary+todos'(AI 摘要 + 待辦)
+
+dedup_strategy: index              # v2.14.0+: 'index'(預設) | 'last_archived' | 'both'
+                                   #   index = 用 .email_index.json (current default)
+                                   #   last_archived = skip index,以 last_archived 日期作 date_from
+                                   #   both = 兩者皆用 (Message-ID 為主, date 為輔)
+
+output_dir: communications/emails  # string,default "communications/emails"。
+                                   # archive markdown 寫入路徑(相對 cwd)
+
+attachments_dir: correspondence/attachments  # string,default 同上格式。附件根目錄
+
+attachment_routing:                # 附件依副檔名分流
+  data_extensions:                 #   list[string]:被視為「資料」的副檔名
+    - csv
+    - sav
+    - xlsx
+    - rds
+  data_dir: data/raw               #   data 副檔名導到此(覆蓋 attachments_dir)
+  documents_dir: correspondence/attachments  # 其他副檔名導到此
+
+exclude_mailboxes:                 # list[string],default []。完全跳過的 mailbox 名稱
+  - Junk
+  - Trash
+  - Drafts
+
+last_archived:                     # ISO-8601 timestamp;archive-mail 會自動更新
+  2026-05-01T13:30:00+08:00        # 用於 incremental archive(只抓此後的信);搭配 dedup_strategy='last_archived' 必填
+---
+```
+
+### Field 互動規則
+
+- `filters` + 命令列參數同時指定 → 命令列覆蓋
+- `participant_aliases` 在 Phase 1 disambiguation 優先 match
+- `subject_keywords_strict=true` 時 sender / recipient match 仍 hit;只阻擋「only subject contains keyword」的 lone match
+- `attachment_routing.data_extensions` ∩ 真實附件 → 走 `data_dir`,其他走 `documents_dir`(若未設 `data_extensions` 則全部走 `documents_dir`)
+- `last_archived` 不存在 → 全量 archive;存在 → 只抓 received-date > last_archived 的 emails
+
+## 帳號名稱陷阱:EWS URL vs Display Name
+
+Apple Mail.app(via AppleScript)在 `account` property 上**同時用兩種識別**而沒一致對應:
+
+| 場景 | 回傳值 | 例 |
+|------|--------|----|
+| `list_accounts` | display name | `"Sinica Mail"` |
+| Email object 的 `account` field | EWS URL | `"https://owa.sinica.edu.tw/EWS/Exchange.asmx"` |
+| Filter / search by account | 接受 display name | `"Sinica Mail"` |
+| `set account of email to X` | 需 display name | `"Sinica Mail"` |
+
+### 為什麼會踩雷
+
+Search 結果的 email 可能來自 IMAP 帳號(display name)或 Exchange/EWS 帳號(URL)。直接拿 email.account 字串去 `move_email account="..."` 會在 EWS 帳號失敗 — 因為 set account 接受 display name 不接受 URL。
+
+### 正確做法
+
+1. 永遠先 `list_accounts` 取 display name 清單
+2. 對 EWS-style 帳號,維護 URL → display name mapping(plugin 內已有 `account_normalize` helper)
+3. 對 user 顯示一律用 display name
+
+### 相關 issue
+
+- #15 — display-name vs internal-name 混用導致 archive-mail 在多帳號環境噴錯(已 close)
+- 本陷阱由 #15 提煉成 plugin 內建 normalization layer
+
+## File Layout — `.claude/.mail/` Namespace(v2.8.0+)
+
+學 IDD `.claude/.idd/` 的 namespace 收斂 pattern。**Config + state 集中,archive markdown 保持原位**:
+
+```
+{cwd}/
+├── .claude/.mail/                              ← namespace root
+│   ├── config.yaml                             ← v2.16.0+;legacy v2.7.0 ↓ 路徑為 .claude/emails.md;v2.8.0–v2.15.0 為 config.md
+│   └── state/
+│       └── archives/
+│           └── {slug}/                          ← per-archive-target,slug = output_dir.replace("/", "-")
+│               ├── email_index.json            ← Message-ID 去重
+│               ├── threads.json                ← thread 關係索引
+│               └── threads.json.bak.*          ← rebuild-threads 的備份
+├── communications/emails/                      ← archive markdown 目的地(不變)
+│   ├── 2026-01-13_xxx.md                       ← archive 結果(user-visible)
+│   └── ...
+└── correspondence/attachments/                 ← attachments(不變)
+    └── 2026-01-13_xxx/
+```
+
+### 為什麼這樣分
+
+| 路徑 | 性質 | 為什麼 |
+|------|------|--------|
+| `.claude/.mail/config.yaml` | Plugin config(v2.16.0+;legacy `.md` 仍 fallback) | User 改的 YAML config,跟工作流綁定 |
+| `.claude/.mail/state/archives/{slug}/` | Plugin state | 自動產生的索引,user 不手動編輯 |
+| `{output_dir}/` | User-visible 歸檔結果 | User 主動 ls 找的 archive markdown |
+| `{attachments_dir}/` | User-visible 附件 | 同上 |
+
+### Auto-migrate(從 v2.7.0 ↓ 升級)
+
+v2.8.0+ 的 `archive-mail` / `view` / `rebuild-threads` **每次跑都會 silent auto-migrate**:若新位置不存在但舊位置有 file,直接 mv 過去並提示「🔄 Migrated X → Y」。
+
+如果想一次 batch migrate 所有 archive targets,跑 `/archive-mail-migrate`(支援 `--dry-run` 預覽)。
+
+## Version History
+
+- **v2.9.0**(2026-05-01)— **Task enforcement**:學 IDD 的 Step 0 Bootstrap Stage Task List 鐵律。`/archive-mail` 開工前強制 `TaskCreate` 10 個 stage tasks,`confirmation-protocol` skill 強制 4 個 phase tasks,完成立即 `TaskUpdate`,靜默 skip = 違規。把 v2.7.0 spec-level confirmation 升級到 enforce-level
+- **v2.8.0**(2026-05-01)— **`.claude/.mail/` namespace**:學 IDD 的 `.claude/.idd/` 收斂 config + state。新增 `/archive-mail-migrate`。archive-mail / view / rebuild-threads 都加 auto-migrate。Backward compatible:legacy paths 自動 detect 並搬遷
+- **v2.7.0**(2026-05-01)— **NSQL confirmation protocol**:加 3 skills + 2 rules + CLAUDE.md。archive-mail 預設套用 4-phase confirmation workflow。Backward compatible:精確 filter 仍可直接執行
+- v2.6.0 — archive-mail YAML frontmatter + .threads.json + view/rebuild commands
+- v2.5.0 — composing tools format 參數
+- v2.4.0 — search expansion + Coverage Audit
+- v2.3.0 — attachment auto-download + 分流
+
+## MCP Tool 命名 prefix
+
+Claude Code 載入本 plugin 時,所有 MCP tool 都以 `mcp__plugin_che-apple-mail-mcp_mail__*` 為 prefix。例:
+
+```
+mcp__plugin_che-apple-mail-mcp_mail__list_accounts
+mcp__plugin_che-apple-mail-mcp_mail__search_emails
+mcp__plugin_che-apple-mail-mcp_mail__compose_email
+mcp__plugin_che-apple-mail-mcp_mail__archive_email     ← 不存在,archive 走 /archive-mail command
+```
+
+### Prefix 拆解
+
+| 段 | 意義 |
+|----|------|
+| `mcp__` | 固定前綴(Claude Code 區分 MCP tool vs built-in) |
+| `plugin_` | tool 來自 plugin(非全 user-level MCP server) |
+| `che-apple-mail-mcp` | plugin name(對應 `.claude-plugin/plugin.json` `name` field) |
+| `_mail__` | MCP server 名稱(`.mcp.json` 裡的 server key) |
+| `*` | tool 名稱(Swift binary 註冊的 tool name) |
+
+### 用途
+
+- 多 plugin 共存時不撞名(e.g. 別的 plugin 也叫 `list_accounts`)
+- Allow-list 設定可整 plugin 一次准許 / 拒絕(`mcp__plugin_che-apple-mail-mcp_*`)
+- Claude Code log 一眼看出 tool 來自哪個 plugin
+
+### 相關文件
+
+- Anthropic MCP plugin spec — https://code.claude.com/docs/en/plugins
+- `.mcp.json` 裡 `mail` 那個 key 決定 prefix 中段(改名要同步改 wrapper)
+
+## 相關
+
+- `/Users/che/Developer/nsql/protocol.yaml` — 原始 NSQL Confirmation Protocol spec
+- `/Users/che/Developer/nsql/docs/concept.md` — NSQL whitepaper
+- `commands/archive-mail.md` — Archive workflow(含 confirmation phases)
diff --git a/plugins/che-apple-mail-mcp/README.md b/plugins/che-apple-mail-mcp/README.md
index 5810041f..d0fe9ebc 100644
--- a/plugins/che-apple-mail-mcp/README.md
+++ b/plugins/che-apple-mail-mcp/README.md
@@ -11,6 +11,155 @@ macOS Apple Mail MCP server with native AppleScript integration.
 - Flag, move, delete operations
 - VIP senders and signatures
 
+## Commands
+
+### `/archive-mail` — 歸檔郵件到 Markdown
+
+把指定聯絡人的 Apple Mail 郵件批次歸檔為 Markdown 檔案，自動去重。v2.7.0+ 預設套用 4-phase NSQL confirmation protocol（filter 模糊先 disambiguate、bulk 結果先 preview + flag false positives、destructive op 必 confirm），v2.9.0+ 強制 `TaskCreate` 10 個 stage tasks 確保每 phase 不被靜默 skip。
+
+```bash
+# Zero-arg mode (v2.12.0+, v2.16.0+ reads .yaml) — reads .claude/.mail/config.yaml
+/archive-mail
+
+# Explicit filter mode (always available)
+/archive-mail some@example.com
+/archive-mail some@example.com communications
+```
+
+**v2.12.0–v2.19.7 highlights**:
+
+- **Shell v2.19.7 / Binary v2.9.0** (2026-05-18) — MCP-tool layer bug-fix cluster:
+    - `#99` `list_attachments` no longer silently returns `[]` for Outlook 16 Windows attachments with RFC 2231 + nested RFC 2047 filenames (Chinese filenames ≥ 64 UTF-8 bytes triggered RFC 2231 continuation split + base64-encoded inner encoded-word; parser previously returned raw `=?utf-8?B?...?=` → `crossValidateAttachments` dropped all rows)
+    - `#101` `save_attachment` accepts optional `account_id` (UUID) for multi-account-same-display-name disambiguation; eliminates `-1728 "Can't get account"` when iCloud catch-all alias collides with Gmail same address
+    - `#104 PR-A` 5 mutation tools (`mark_read`, `flag_email`, `set_flag_color`, `set_background_color`, `mark_as_junk`) gain optional `account_id` parameter; shares `AppleScriptRefBuilder.resolveMsgRef` chokepoint with `save_attachment` so future PR-B/C/D (move/copy/delete, compose, mailbox CRUD) are pure call-site swaps
+    - `#106` `EnvelopeIndexReader` reverse-lookup cache + `accountUUIDs(forName:)` primitive eliminates 4 duplicated O(n) account-map scans; collision-aware path enables `#101` `account_id` discovery
+- **Shell v2.19.5–v2.19.6** — Binary v2.8.5 ship + spurious-SIGTERM fix:
+    - `v2.19.6` `#73`: `hooks/session-start.sh` compare 改 prefer `.binary_version` (post-`#77` schema), fallback `.version`, eliminates every-session-start spurious SIGTERM (runtime tag vs shell version permanent mismatch trap)
+    - `v2.19.5` ships binary v2.8.5: `#16` nested markdown lists with depth-aware `<ul>`/`<ol>`, `#17` markdown tables with `<table>`/`<thead>`/`<tbody>` + per-column alignment, `#22` markdown hardening Item D code-fence language + spec docs, `#26` malformed multipart throws `emlxParseFailed` for handler fallback, `#28` `crossValidateAttachments` helper + 6 filter tests, `#89` `list_emails` SQLite do/catch + AppleScript 3× IPC reduction
+- **Shell v2.18.0–v2.18.1** — Staleness Detection + #71/#61-64 fixes:
+    - `v2.18.0` `#76` Staleness Detection: wrapper writes runtime state file on spawn (pid / started_at / version_at_spawn); new `hooks/session-start.sh` detects `plugin.json` ↔ in-memory binary version drift, SIGTERM (+5s grace, SIGKILL fallback) stale PID so Claude Code re-spawns with new binary. Solves "plugin update but current session keeps running old binary" silent staleness.
+    - `v2.18.1` `#71` `get_email_metadata` SQLite fallback parity + cluster `#61-64` `attachmentFragment` hardening
+- **v2.17.0** (#49) — Workspace Layout Detection + sibling-archive dedup:當 `output_dir` 既無命令列也無 config 給定時,probe `communications/email/` → `correspondence/emails/` → default,detect 到既有 layout 自動 adapt(detection-first,not prescriptive)。`${output_dir}` 下 symlink 到歷史 archive(transitioned-project pattern,e.g. chchen_lab `email/application/`)時,讀其下 markdown 的 `message_id:` frontmatter 併入 dedup,避免被 forward 回的舊 thread re-archive。Read-only,讀既有 explicit `output_dir:` config 的 workspace 行為 100% 不變。詳見下方 [Workspace Patterns](#workspace-patterns-v2170)。
+- **v2.15.0** (#45) — Inline `cid:` 圖片保留路徑:從 HTML body 解析 `<img src="cid:..." alt="...">` → save 到 `attachments/<stem>/inline/<filename>`,Markdown 加獨立 `Inline images:` section(`![]()` syntax 直接 render),Step 8a Coverage Audit 拆 explicit + inline 兩部分。修掉 dogfood gap:archive 「Solution? (affine repre + Iverson)」 thread CleanShot screenshot 全 miss
+- **v2.14.0** (#18) — Opt-in `dedup_strategy` config:`index`(預設) | `last_archived`(輕量,以 ISO date 作 date_from) | `both`(雙 dedup);零 breaking,既有 archive 走 default
+- **v2.13.0** (#17) — Markdown template default 簡化:預設 `Subject/From/To/Date` 多行 header + body,對應 tatsuma 50 個歷史檔。User 想要原 4-section 模板:`enrichment: summary+todos`
+- **v2.16.0** (#47) — Config schema rename:`.claude/.mail/config.md` → `.claude/.mail/config.yaml`(副檔名 ↔ 內容語意一致;legacy `.md` 仍 fallback,v3.0 移除)。auto-migrate 在 archive-mail / archive-mail-migrate 觸發,user 不需動手
+- **v2.12.0** (#13/#21) — Zero-arg mode:`/archive-mail` 不帶參數從 `.claude/.mail/config.yaml`(legacy `.md` fallback)讀 `filters` / `output_dir` / `last_archived` / `exclude_mailboxes`;`argument-hint` 改 `[email-filter]` 反映可選性
+
+#### Workspace Patterns (v2.17.0+)
+
+archive-mail 不假設一個 canonical layout——adapt 到 user 的既有 folder 配置。三種主要 pattern:
+
+| Pattern | Folder shape | When detection picks it |
+|---------|--------------|--------------------------|
+| **Nested channel layout** | `<workspace>/communications/email/` | `communications/email/` 存在;為「multi-channel comms」(email + future chat / letters / etc.) 預留結構。Forward direction(per kiki830621/chchen-lab 2026-05-08+) |
+| **Legacy correspondence layout** | `<workspace>/correspondence/emails/` | 上面不存在但 `correspondence/emails/` 存在。pre-v2.17 既有 user convention,detection 認得不需要 migrate |
+| **Baseline default** | `<workspace>/communication/emails/` | 兩者皆無;archive-mail 自己建這個 dir 並使用 |
+
+**Precedence**(高 → 低):
+
+1. 命令列 `$ARGUMENTS[1]` (`/archive-mail <filter> <output_dir>`)
+2. `${CONFIG_FILE}` (`.claude/.mail/config.yaml`) 的 `output_dir:` 欄位
+3. **Workspace Layout Detection**(本節 v2.17.0+ 新增)
+4. Baseline default `communication/emails`
+
+**Pin convention via explicit config**:若想 lock 一個 layout(例如 `psychophysic_representations` 走 `correspondence/emails`),在 config 寫:
+
+```yaml
+# .claude/.mail/config.yaml
+output_dir: correspondence/emails
+filters:
+  - someone@example.com
+```
+
+已 explicit-pin 的 workspace 行為不變;zero-config 且 `communications/email/` 與 `correspondence/emails/` 同時存在含 `*.md` 的 mid-migration workspace 會被 ambiguity guard flag,要求 explicit pin(避免半實作狀態的 dedup-index split-brain)。
+
+**Symlink coexistence**(transitioned-project pattern):
+
+```
+chchen_lab/
+└── communications/email/
+    ├── 2026-05-09_subject.md       ← live archive (archive-mail 寫入)
+    ├── 2026-05-08_subject.md       ← live archive
+    └── application/                ← SYMLINK → ../../applications/completed/.../emails/
+        ├── 2026-04-29_old.md       ← 19 historical md files (read-only,never written)
+        └── ...
+```
+
+archive-mail v2.17.0+ 會:
+
+1. **掃 symlink subdirectories**:`find -P "${output_dir}" -maxdepth 1 -type l`
+2. **讀其下 markdown 的 `message_id:` YAML frontmatter**:`find -P "$symlink_dir/" -maxdepth 2 -name "*.md"` → `head -30` → `awk` extract
+3. **併入 in-memory dedup set**:Step 4 dedup logic 排除既有 + extended 的 Message-ID 集合
+4. **絕不寫入 symlink target**:read-only by contract
+
+**Ambiguity guard**:當 `communications/email/` 與 `correspondence/emails/` **同時存在且都有 `*.md` 檔**(mid-migration 異常情境),archive-mail abort with explicit error,要求 pin `output_dir:` in config。Empty-dir-as-marker 不算 ambiguity(常見於剛建好新 layout、還沒第一次 archive 的 workspace)。
+
+**Diagnose 與 verify 哪個 path 在用**:archive-mail 啟動會印 detection 結果:
+
+- `🔍 Detected output_dir: communications/email (from layout probe)` ← Probe 1 hit
+- `🔍 Detected output_dir: correspondence/emails (legacy layout probe)` ← Probe 2 hit
+- `🔗 Extended dedup with N entries from sibling archives:` ← Step 2.1 dedup extension fired
+- (silent) ← detection didn't fire because explicit config / `$ARGUMENTS[1]` won
+
+詳細 detection algorithm + edge cases 見 [`commands/archive-mail.md`](commands/archive-mail.md) §Step 1 Workspace Layout Detection 與 §Step 2.1 Sibling-archive dedup extension。
+
+每封 md 帶 YAML frontmatter（`message_id` / `thread_key` / `in_reply_to` / `date` / `sender` / `direction`），並同步維護 `email_index.json`（Message-ID 去重）與 `threads.json`（thread 關係索引），v2.8.0+ 收斂到 `.claude/.mail/state/archives/{slug}/`。
+
+詳細 spec 見 [`commands/archive-mail.md`](commands/archive-mail.md)。完整 changelog 見 [`CHANGELOG.md`](CHANGELOG.md)。
+
+### `/archive-mail-view` — 生成 thread 聚合視圖（v2.6.0+）
+
+```bash
+/archive-mail-view "SE manuscript 10xx-2025"
+/archive-mail-view "SE manuscript" communications
+```
+
+讀 `threads.json` + per-email md，依時序聚合成一個 thread 視圖檔（存在 `.threads/` 子目錄）。視圖是 derived 資料，原始 md 不變，可重複生成。
+
+### `/archive-mail-rebuild-threads` — 從 md 重建 thread 索引（v2.6.0+）
+
+```bash
+/archive-mail-rebuild-threads
+/archive-mail-rebuild-threads communications
+```
+
+掃所有 md 的 YAML frontmatter 重建 `threads.json`。用在索引損壞、手動改過 thread_key、或舊 archive 升級後的 sanity check。
+
+### `/archive-mail-migrate` — 收斂 indices + config 到 namespace（v2.8.0+）
+
+```bash
+/archive-mail-migrate --dry-run    # 預覽
+/archive-mail-migrate              # 執行
+```
+
+把散在各個 archive directory 的 `.email_index.json`、`.threads.json` 以及 `.claude/emails.md` 集中搬到 `.claude/.mail/` namespace（學 IDD 的 `.claude/.idd/` pattern）。`/archive-mail`、`view`、`rebuild-threads` 也會 silent auto-migrate；這個 command 是想一次 batch migrate 所有 archive targets 時用。
+
+## Skills (v2.7.0+)
+
+3 個 skills 由 `/archive-mail` 內部觸發，也可被其他工作流引用：
+
+- **`confirmation-protocol`** — NSQL-style 4-phase workflow（disambiguation → search preview → operation confirmation → execute or iterate）。v2.9.0+ Bootstrap 強制 `TaskCreate` 4 個 phase tasks，靜默 skip = 違規
+- **`email-search-disambiguation`** — 處理模糊 filter（中文人名「陳老師」、相對時間「最近」、通用 scope「全部」），列候選讓 user 選定
+- **`bulk-operation-preview`** — ≥ 5 封 emails 的 preview format，含 false-positive flagging（✓/⚠/⚠⚠/❓）
+
+## File Layout — `.claude/.mail/` Namespace (v2.8.0+)
+
+學 IDD `.claude/.idd/` 的 namespace 收斂 pattern。Config + state 集中，archive markdown 保持原位：
+
+```
+{cwd}/
+├── .claude/.mail/                              ← namespace root
+│   ├── config.yaml                             ← YAML(filters / aliases / attachment routing) — v2.16.0+;legacy .md fallback 至 v3.0
+│   └── state/archives/{slug}/                  ← per-archive-target indices
+│       ├── email_index.json                    ← Message-ID 去重
+│       └── threads.json                        ← thread 關係索引
+├── communications/emails/                      ← archive markdown 目的地（不變）
+└── correspondence/attachments/                 ← attachments（不變）
+```
+
+從 v2.7.0 ↓ 升級會 silent auto-migrate（archive-mail / view / rebuild-threads 跑時都會 detect 舊位置並搬遷）。也可主動跑 `/archive-mail-migrate` 一次完成。
+
 ## Installation
 
 ### Option 1: From Release (Recommended)
@@ -58,3 +207,33 @@ search_emails(account="your@email.com", mailbox="收件匣", query="keyword")
 ## Source Code
 
 https://github.com/kiki830621/che-apple-mail-mcp
+
+## Version History
+
+- **v2.19.6 shell + binary v2.8.5**（2026-05-12）— **hook compare 改 prefer `.binary_version`**（[#73](https://github.com/PsychQuant/psychquant-claude-plugins/issues/73)）。`hooks/session-start.sh` jq query 從 `'.version // ""'` 改 `'.binary_version // .version // ""'`,杜絕 v2.18.0 ~ v2.19.5 期間每次 session start spurious SIGTERM(runtime `version_at_spawn` 是 binary tag `2.8.5`,但 hook 比對 plugin shell `2.19.5` 永遠 mismatch trap)。Backward compat 保留 — legacy plugins(無 `binary_version`)走 `.version` fallback。Shell-only patch release,binary v2.8.5 不變。Tests 22/22 PASS;TDD RED → GREEN cycle proves fix。
+
+- **v2.19.1–v2.19.5 shell + binary v2.8.1–v2.8.5 patch series**（2026-05-11）— **markdown rendering richness + sanitize_links hardening + cleanup**。 串連發布的 5 個 patch:
+  - **v2.19.5 / binary v2.8.5** — nested markdown lists ([#16](https://github.com/PsychQuant/che-apple-mail-mcp/issues/16)) + markdown tables with alignment ([#17](https://github.com/PsychQuant/che-apple-mail-mcp/issues/17)) + malformed multipart handler fallback ([#26](https://github.com/PsychQuant/che-apple-mail-mcp/issues/26)) + `list_emails` SQLite fast-path 3× IPC reduction ([#89](https://github.com/PsychQuant/che-apple-mail-mcp/issues/89))。swift test → 342 (+29 since v2.8.0 series began)
+  - **v2.19.4 / binary v2.8.4** — `crossValidateAttachments` helper extracted + 6 filter tests ([#28](https://github.com/PsychQuant/che-apple-mail-mcp/issues/28)) + code fence language hint ([#22](https://github.com/PsychQuant/che-apple-mail-mcp/issues/22) Item D)
+  - **v2.19.3 / binary v2.8.3** — chore cluster: 4 dead AppleScript declarations removed ([#82](https://github.com/PsychQuant/che-apple-mail-mcp/issues/82)),3 deprecated `text(_:metadata:)` calls migrated ([#83](https://github.com/PsychQuant/che-apple-mail-mcp/issues/83)),31 lenient `XCTAssertTrue` retrofitted to `assertOrdered` ([#84](https://github.com/PsychQuant/che-apple-mail-mcp/issues/84))
+  - **v2.19.2 / binary v2.8.2** — `sanitize_links` hardening grab-bag ([#87](https://github.com/PsychQuant/che-apple-mail-mcp/issues/87)):allowlist tripwire、6 bypass-class regression tests、`htmlEscape` defense-in-depth on `href`、empty-scheme schema docs、payload-scaling latency test
+  - **v2.19.1 / binary v2.8.1** — `sanitize_links` schema description consistency across `create_draft`/`reply_email`/`forward_email`/`compose_email` ([#86](https://github.com/PsychQuant/che-apple-mail-mcp/issues/86)) — fixes tool-selecting LLM blindspot
+- **v2.19.0 shell + binary v2.8.0**（2026-05-11）— **`sanitize_links` security feature + formal spec coverage** ([release notes](https://github.com/PsychQuant/che-apple-mail-mcp/releases/tag/v2.8.0)). Opt-in URL scheme allowlist for markdown mode ([#19](https://github.com/PsychQuant/che-apple-mail-mcp/issues/19)) defends against `[click](javascript:alert('xss'))` and `data:`/`file:`/`vbscript:` URLs via closed allowlist `{http, https, mailto, tel}`; default `false` preserves backwards compat. Formal `openspec/specs/message-composition/spec.md` Requirement+Scenarios codifying the contract + builder-layer wiring contract tests ([#85](https://github.com/PsychQuant/che-apple-mail-mcp/issues/85)) pinning `sanitizeLinks` forwarding across the 4 script-builder functions. Cluster A hygiene: dead spec scenario delete + count-free CHANGELOG + `assertOrdered` helper ([#20](https://github.com/PsychQuant/che-apple-mail-mcp/issues/20)); reply/forward AppleScript-html-denial docs ([#21](https://github.com/PsychQuant/che-apple-mail-mcp/issues/21)); `list_attachments_batch` SQLite+.emlx cross-validation parity ([#25](https://github.com/PsychQuant/che-apple-mail-mcp/issues/25)); `attachmentNames` <200ms latency budget test ([#27](https://github.com/PsychQuant/che-apple-mail-mcp/issues/27)) + parity invariant ([#32](https://github.com/PsychQuant/che-apple-mail-mcp/issues/32)). `extractHTMLBody` base64+UTF-8-QP decoding fixes ([#73](https://github.com/PsychQuant/che-apple-mail-mcp/issues/73)). 48 tools (was 47). swift test → 313/0/8 (was 309).
+- **v2.18.1 shell + binary v2.7.2**（2026-05-10）— **wrapper sidecar tracks actual binary tag** ([#77](https://github.com/PsychQuant/che-apple-mail-mcp/issues/77))。`plugin.json` adds explicit `binary_version` field disambiguating from plugin shell `version`;wrapper writes actual downloaded binary tag (parsed from GitHub release URL) to sidecar,讓 silent skip of binary-only releases 不再發生。Binary v2.7.2 ships #71 fallback parity + cluster #61-64 hardening。
+- **v2.18.0 shell + binary v2.7.1**（2026-05-10）— **Staleness Detection** ([#76](https://github.com/PsychQuant/che-apple-mail-mcp/issues/76))。Wrapper atomic-writes `~/bin/.CheAppleMailMCP.runtime.json` 紀錄 `{pid, started_at, version_at_spawn}`;新 `hooks/session-start.sh` 偵測 plugin.json 版本 drift,SIGTERM (+5s grace + SIGKILL fallback) stale MCP PID 讓 host respawn。Sister issue [psychquant-claude-plugins#58](https://github.com/PsychQuant/psychquant-claude-plugins/issues/58) split 為 plugin-update warning。
+- **v2.10.3 shell + binary v2.6.0**（2026-05-03）— **Marathon release: 16 issues across 8 PRs** ([release notes](https://github.com/PsychQuant/che-apple-mail-mcp/releases/tag/v2.6.0))。安全強化:id 注入防護 ([#50](https://github.com/PsychQuant/che-apple-mail-mcp/issues/50))、附件路徑 deny-list + opt-in `MAIL_MCP_ATTACHMENT_ROOTS` allow-list ([#38](https://github.com/PsychQuant/che-apple-mail-mcp/issues/38))、email 地址驗證 ([#41](https://github.com/PsychQuant/che-apple-mail-mcp/issues/41))、type-strict handler params ([#35](https://github.com/PsychQuant/che-apple-mail-mcp/issues/35))、新 SECURITY.md ([#48](https://github.com/PsychQuant/che-apple-mail-mcp/issues/48))。Bug fix:`forward_email` plain mode 也嵌入 quoted original ([#44](https://github.com/PsychQuant/che-apple-mail-mcp/issues/44))。Quality:cc_additional case-insensitive dedup ([#34](https://github.com/PsychQuant/che-apple-mail-mcp/issues/34))、schema test type assertions ([#42](https://github.com/PsychQuant/che-apple-mail-mcp/issues/42))、indent cleanup ([#39](https://github.com/PsychQuant/che-apple-mail-mcp/issues/39))、README updates ([#36](https://github.com/PsychQuant/che-apple-mail-mcp/issues/36))、large-thread script size tests ([#49](https://github.com/PsychQuant/che-apple-mail-mcp/issues/49))。Tests:gated integration tests for reply runtime ([#37 + #45](https://github.com/PsychQuant/che-apple-mail-mcp/issues/37))。Smoke matrix templates ([#46 + #47](https://github.com/PsychQuant/che-apple-mail-mcp/issues/46))。**279 tests pass** (+45 from 234)。
+- **v2.10.2 shell + binary v2.5.0**（2026-05-03）— **Reply quoted-original fix** ([issue #43](https://github.com/PsychQuant/che-apple-mail-mcp/issues/43))。`reply_email` plain mode 終於把 quoted original 嵌入 draft body — 自 `b8a4a89`（initial release）以來每次 plain reply 都靜默 drop 掉 quoted original，因為 AppleScript `& content` 對 freshly-created outgoing message 讀為空。改用 Swift-side `composeReplyPlainText` helper 預先 fetch + RFC 3676 `> ` prefix 組合 quoted body。Round-1 hardening 涵蓋 CRLF/CR normalization、trailing newline trim、空行 stuffing（`>` 不含 trailing space）、pre-fetch 失敗 graceful degrade。**Wire-output 行為改變**：plain reply body 從 `<user reply>` 變成 `<user reply>\n\n> <quoted lines>`。HTML branch 不變（原本就走對的 architecture）。234 tests pass。Follow-ups #44–#50 已開。
+- **v2.10.1 shell + binary v2.4.1**（2026-05-02）— **Save-as-draft popup + path validation fix** ([issue #33 verify findings A+B](https://github.com/PsychQuant/che-apple-mail-mcp/issues/33))。`reply_email` `save_as_draft=true` 不再彈出 Mail.app 視窗（windowClause 改成條件式 with/without opening window），`replyEmail` 加 `validateFilePaths` 鏡像 composeEmail / createDraft 行為。
+- **v2.10.0 shell + binary v2.4.0**（2026-05-02）— **Reply-as-draft mode** ([issue #33](https://github.com/PsychQuant/che-apple-mail-mcp/issues/33))。`reply_email` 新增 3 個 optional params：
+  - `cc_additional: string[]` — 在 `reply_all` 算出的 CC 之外再加 recipient
+  - `attachments: string[]` — POSIX 絕對路徑檔案附件
+  - `save_as_draft: boolean` — 存草稿不寄出（預設 false 保 backward compat）
+
+  Unblocks 工作流：reply 一個既存 thread + 加 CC + 附 PDF + 存草稿等手動審。AppleScript native `reply` verb returns `outgoing message`，後續 `save` vs `send` 條件式分流。Backward compatible — 既有 callers 不變。
+- **v2.9.0**（2026-05-01）— **Task enforcement**：學 IDD 的 Step 0 Bootstrap Stage Task List 鐵律。`/archive-mail` 強制 `TaskCreate` 10 個 stage tasks，`confirmation-protocol` skill 強制 4 個 phase tasks，靜默 skip = 違規。把 v2.7.0 spec-level confirmation 升級到 enforce-level
+- **v2.8.0**（2026-05-01）— **`.claude/.mail/` namespace**：學 IDD 的 `.claude/.idd/` pattern 收斂 config + state。新增 `/archive-mail-migrate`。archive-mail / view / rebuild-threads 都加 auto-migrate。Backward compatible
+- **v2.7.0**（2026-05-01）— **NSQL confirmation protocol**：加 3 skills（confirmation-protocol / email-search-disambiguation / bulk-operation-preview）+ 2 rules + CLAUDE.md。archive-mail 預設套用 4-phase confirmation workflow。Backward compatible
+- **v2.6.0** — archive-mail YAML frontmatter + threads.json + view/rebuild commands
+- **v2.5.0** — composing tools format 參數
+- **v2.4.0** — search expansion + Coverage Audit
+- **v2.3.0** — attachment auto-download + 分流
diff --git a/plugins/che-apple-mail-mcp/bin/che-apple-mail-mcp-wrapper.sh b/plugins/che-apple-mail-mcp/bin/che-apple-mail-mcp-wrapper.sh
index 3f28294c..e39e88f2 100755
--- a/plugins/che-apple-mail-mcp/bin/che-apple-mail-mcp-wrapper.sh
+++ b/plugins/che-apple-mail-mcp/bin/che-apple-mail-mcp-wrapper.sh
@@ -1,28 +1,114 @@
 #!/bin/bash
-# Auto-download wrapper for CheAppleMailMCP
-REPO="kiki830621/che-apple-mail-mcp"
+# Version-aware auto-download wrapper for CheAppleMailMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheAppleMailMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-apple-mail-mcp"
 BINARY_NAME="CheAppleMailMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+RUNTIME_FILE="$INSTALL_DIR/.${BINARY_NAME}.runtime.json"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired BINARY version from plugin.json. Prefer the explicit
+# `binary_version` field (introduced for #77 — disambiguates from the
+# plugin shell's own `version`). Fall back to `version` for plugins that
+# haven't migrated yet — they pay the existing silent-skip risk for
+# binary-only releases (documented in #77).
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"binary_version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+    if [[ -z "$DESIRED_VERSION" ]]; then
+        DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+            | head -1 | cut -d'"' -f4 || true)
+    fi
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
     if [[ -z "$URL" ]]; then
-        echo "ERROR: No download URL found. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            # Sidecar records the ACTUAL downloaded binary tag, parsed from
+            # the GitHub release URL (path segment between /download/ and
+            # the next /). This breaks the #77 "silent skip" trap: when
+            # plugin.json lacks `binary_version`, DESIRED is the shell
+            # version which never matches a real binary tag, so writing
+            # DESIRED_VERSION makes the sidecar lie. Parsing the URL keeps
+            # the sidecar honest regardless of which path was taken.
+            ACTUAL_VERSION=$(echo "$URL" | sed -nE 's|.*/releases/download/v?([^/]+)/.*|\1|p')
+            echo "${ACTUAL_VERSION:-${DESIRED_VERSION:-unknown}}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${ACTUAL_VERSION:-${DESIRED_VERSION:-latest}}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-        || { echo "ERROR: Download failed." >&2; exit 1; }
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
+# Write runtime state (per #76 — let session-start hook detect mid-session staleness).
+# Atomic write: .tmp + mv; failures silent (|| true) so they never block spawn.
+{
+    printf '{"pid":%d,"started_at":%d,"version_at_spawn":"%s"}\n' \
+        "$$" "$(date +%s)" "${DESIRED_VERSION:-unknown}" \
+        > "${RUNTIME_FILE}.tmp" \
+        && mv "${RUNTIME_FILE}.tmp" "$RUNTIME_FILE"
+} 2>/dev/null || true
+
 exec "$BINARY" "$@"
diff --git a/plugins/che-apple-mail-mcp/commands/archive-mail-migrate.md b/plugins/che-apple-mail-mcp/commands/archive-mail-migrate.md
new file mode 100644
index 00000000..5f8a7c96
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/commands/archive-mail-migrate.md
@@ -0,0 +1,208 @@
+---
+description: 一次性把所有舊 archive 的 indices + config 搬到 .claude/.mail/ namespace
+argument-hint: [--dry-run]
+allowed-tools: Read, Write, Glob, Bash(mkdir:*, mv:*, find:*)
+---
+
+# Archive Mail — Migrate to `.claude/.mail/` Namespace（v2.8.0+）
+
+把散在各個 archive directory 的 `.email_index.json`、`.threads.json`,以及 `.claude/emails.md`,集中搬到 `.claude/.mail/` namespace。學 IDD `.claude/.idd/` 的 namespace 收斂 pattern。
+
+## 為什麼要 migrate
+
+v2.8.0 之前的 file layout:
+
+```
+{cwd}/
+├── .claude/
+│   └── emails.md                  ← config 散在 root
+└── communications/emails/
+    ├── .email_index.json          ← state 散在 archive output 裡
+    ├── .threads.json
+    ├── 2026-01-13_xxx.md          ← archive markdown(不動)
+    └── ...
+```
+
+v2.8.0+ 集中後:
+
+```
+{cwd}/
+├── .claude/.mail/
+│   ├── config.yaml                ← 從 .claude/emails.md 搬來(v2.7.0 ↓);v2.16.0+ 副檔名 .yaml
+│   └── state/
+│       └── archives/
+│           └── communications-emails/
+│               ├── email_index.json   ← 從 communications/emails/.email_index.json 搬來
+│               └── threads.json       ← 從 communications/emails/.threads.json 搬來
+└── communications/emails/
+    ├── 2026-01-13_xxx.md          ← archive markdown 不動
+    └── ...
+```
+
+`archive-mail` v2.8.0+ 會 auto-migrate(每次跑時 silent 移動),但若你有多個 archive target 不想等到下次 archive 才觸發,可以一次跑這個 command 全部搬完。
+
+## 使用方式
+
+```bash
+# Dry run(預覽會搬什麼,不實際執行)
+/archive-mail-migrate --dry-run
+
+# 實際執行
+/archive-mail-migrate
+```
+
+## 執行步驟
+
+### Step 1: 解析參數
+
+```bash
+DRY_RUN=false
+if [ "$1" = "--dry-run" ]; then
+  DRY_RUN=true
+fi
+NAMESPACE_DIR=".claude/.mail"
+```
+
+### Step 2: 掃描所有 archive targets
+
+從當前 working directory 開始,找出所有 legacy index files:
+
+```bash
+find . -maxdepth 6 -type f \( -name ".email_index.json" -o -name ".threads.json" \) \
+  -not -path "*/.claude/.mail/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/node_modules/*" \
+  2>/dev/null
+```
+
+對每一個 hit,推斷它所屬的 archive_dir(file 所在的 directory),然後計算 slug。
+
+範例 output:
+
+```
+Detected legacy archive targets:
+
+1. ./communications/emails/.email_index.json (18 entries) + .threads.json (6 threads)
+   → slug: communications-emails
+
+2. ./projects/X/comms/.email_index.json (12 entries) + .threads.json (4 threads)
+   → slug: projects-X-comms
+
+3. (etc.)
+
+Plus:
+  ./.claude/emails.md → .claude/.mail/config.yaml
+```
+
+### Step 3: 確認 plan(若非 --dry-run)
+
+用 AskUserQuestion 給 user 看完整 plan,確認後才動手:
+
+```
+即將執行 {N} 個搬移操作:
+
+  1. ./communications/emails/.email_index.json
+     → ./.claude/.mail/state/archives/communications-emails/email_index.json
+  2. ./communications/emails/.threads.json
+     → ./.claude/.mail/state/archives/communications-emails/threads.json
+  3. ./.claude/emails.md
+     → ./.claude/.mail/config.yaml
+  ...
+
+⚠ 此操作會移動(不是複製)既有檔案。Archive markdown(.md)和 attachments 不動。
+確認執行嗎? (y/n)
+```
+
+### Step 4: 執行 migration
+
+對每個 target:
+
+```bash
+SLUG=$(echo "${archive_dir}" | tr '/' '-' | sed 's/^[-.]*//;s/[-.]*$//')
+INDEX_DIR="${NAMESPACE_DIR}/state/archives/${SLUG}"
+mkdir -p "${INDEX_DIR}"
+
+# Move email_index.json
+if [ -f "${archive_dir}/.email_index.json" ]; then
+  mv "${archive_dir}/.email_index.json" "${INDEX_DIR}/email_index.json"
+fi
+
+# Move threads.json
+if [ -f "${archive_dir}/.threads.json" ]; then
+  mv "${archive_dir}/.threads.json" "${INDEX_DIR}/threads.json"
+fi
+
+# Move .threads.json.bak.* if any
+for bak in "${archive_dir}"/.threads.json.bak.*; do
+  [ -f "$bak" ] && mv "$bak" "${INDEX_DIR}/$(basename "$bak" | sed 's/^\.//')"
+done
+```
+
+對 config(v2.16.0+ #47:`.yaml` first-class,`.md` 視為 legacy):
+
+```bash
+mkdir -p "${NAMESPACE_DIR}"
+
+# Step A: legacy .claude/emails.md (v2.7.0 ↓) → namespace .yaml
+if [ -f ".claude/emails.md" ] && [ ! -f "${NAMESPACE_DIR}/config.yaml" ] && [ ! -f "${NAMESPACE_DIR}/config.md" ]; then
+  mv ".claude/emails.md" "${NAMESPACE_DIR}/config.yaml"
+  echo "✓ .claude/emails.md → ${NAMESPACE_DIR}/config.yaml"
+fi
+
+# Step B: namespace .md (v2.8.0–v2.15.0) → .yaml (v2.16.0+ #47)
+if [ -f "${NAMESPACE_DIR}/config.md" ] && [ ! -f "${NAMESPACE_DIR}/config.yaml" ]; then
+  mv "${NAMESPACE_DIR}/config.md" "${NAMESPACE_DIR}/config.yaml"
+  echo "✓ ${NAMESPACE_DIR}/config.md → ${NAMESPACE_DIR}/config.yaml"
+fi
+```
+
+### Step 5: 驗證
+
+對每個 migrated target,跑:
+
+```bash
+# Check new file exists
+[ -f "${INDEX_DIR}/email_index.json" ] && echo "✓ ${INDEX_DIR}/email_index.json"
+
+# Check JSON valid
+python3 -c "import json; json.load(open('${INDEX_DIR}/email_index.json'))" \
+  && echo "  JSON valid" \
+  || echo "  ⚠ JSON invalid"
+```
+
+### Step 6: 輸出報告
+
+```
+═══════════════════════════════════════════
+Archive Mail — Namespace Migration
+═══════════════════════════════════════════
+
+Migrated:
+  ✓ communications/emails/.email_index.json → .claude/.mail/state/archives/communications-emails/email_index.json (18 entries)
+  ✓ communications/emails/.threads.json → .claude/.mail/state/archives/communications-emails/threads.json (6 threads)
+  ✓ .claude/emails.md → .claude/.mail/config.yaml
+  ✓ .claude/.mail/config.md → .claude/.mail/config.yaml (v2.16.0+ schema rename, #47)
+
+Total: 3 files moved.
+
+Archive markdown(.md)not touched. Attachments not touched.
+
+Next: archive-mail / view / rebuild-threads 都會用新位置。
+═══════════════════════════════════════════
+```
+
+## 注意事項
+
+- **Idempotent**:重複跑沒事。已經 migrate 過的檔案會 skip(因為來源不再存在)
+- **Dry run 一定要先跑**:確認 detected targets 是預期的,避免不小心 migrate 到錯的目錄(例如別的 plugin 的 `.email_index.json`)
+- **Archive markdown 不動**:這個 migration 只動 indices + config,不動 user-visible 的 archive 結果
+- **Backup 在哪**:legacy 的 `.threads.json.bak.*` 會一起搬到新位置(保留 audit trail)
+
+## 與相關 command 的關係
+
+| Command | 做什麼 |
+|---------|--------|
+| `/archive-mail` | 歸檔新郵件,**會 auto-migrate 該 archive_dir 的 indices**(silent) |
+| `/archive-mail-view` | 讀新位置 indices 生成 thread view,**也 auto-migrate** |
+| `/archive-mail-rebuild-threads` | 從 md 重建 threads.json,**也 auto-migrate** |
+| `/archive-mail-migrate` | **本 command** — 一次性 batch migrate 所有 archive targets |
diff --git a/plugins/che-apple-mail-mcp/commands/archive-mail-rebuild-threads.md b/plugins/che-apple-mail-mcp/commands/archive-mail-rebuild-threads.md
new file mode 100644
index 00000000..715a0ad2
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/commands/archive-mail-rebuild-threads.md
@@ -0,0 +1,198 @@
+---
+description: 從 per-email md 的 frontmatter 重建 .threads.json
+argument-hint: [archive-dir]
+allowed-tools: Read, Write, Glob, Bash(mkdir:*)
+---
+
+# Archive Mail — Rebuild Threads Index
+
+掃描 archive 目錄下所有 md 檔的 YAML frontmatter，從 canonical storage 重建 `.threads.json`。
+
+## 什麼時候用
+
+1. **`.threads.json` 損壞或被刪除**
+2. **手動修改過 md frontmatter 的 thread_key**（例如拆分長 thread）
+3. **從舊版 archive 升級到 v2.6.0+**（舊 md 沒有 frontmatter，需先 backfill frontmatter 再 rebuild）
+4. **想確認 `.threads.json` 和 md 檔一致**（當作 sanity check）
+
+## 使用方式
+
+```
+/archive-mail-rebuild-threads
+/archive-mail-rebuild-threads communications/emails
+```
+
+- 第一個參數（可選）：archive 目錄，預設 `communication/emails`
+
+## 執行步驟
+
+### Step 1: 解析參數
+
+- `archive_dir`: 預設 `communication/emails`
+
+若目錄不存在，報錯退出。
+
+### Step 2: 解析 namespace 路徑 + 備份既有 `threads.json`（v2.8.0+）
+
+```bash
+NAMESPACE_DIR=".claude/.mail"
+SLUG=$(echo "${archive_dir}" | tr '/' '-' | sed 's/^[-.]*//;s/[-.]*$//')
+INDEX_DIR="${NAMESPACE_DIR}/state/archives/${SLUG}"
+THREADS_FILE="${INDEX_DIR}/threads.json"
+
+mkdir -p "${INDEX_DIR}"
+
+# Auto-migrate legacy(silent)
+if [ ! -f "${THREADS_FILE}" ] && [ -f "${archive_dir}/.threads.json" ]; then
+  mv "${archive_dir}/.threads.json" "${THREADS_FILE}"
+  echo "🔄 Migrated ${archive_dir}/.threads.json → ${THREADS_FILE}"
+fi
+
+# Backup existing threads.json before rebuild
+if [ -f "${THREADS_FILE}" ]; then
+  cp "${THREADS_FILE}" "${THREADS_FILE}.bak.$(date +%Y%m%d_%H%M%S)"
+  echo "Backed up existing threads.json"
+fi
+```
+
+備份不刪舊的,方便回滾。
+
+### Step 3: 掃描所有 md 檔
+
+用 `Glob "${archive_dir}/*.md"` 列出所有歸檔 md。
+
+對每一個 md：
+
+1. `Read` 檔案（只需要前 30 行，frontmatter 一定在這裡面）
+2. 解析 YAML frontmatter（位於檔案最前面的 `---` 之間）
+3. 提取：
+   - `message_id`（必需）
+   - `thread_key`（必需）
+   - `in_reply_to`（可選）
+   - `date`（必需）
+   - `sender`（必需）
+4. 若 frontmatter 缺失或必需欄位不全：
+   - 記錄到 `missing_frontmatter` 清單
+   - **不中斷流程**，繼續下一檔
+
+### Step 4: 聚合成 threads 結構
+
+建立新的 threads 物件：
+
+```
+new_threads = {}
+
+for each valid md:
+    key = md.thread_key
+    if key not in new_threads:
+        new_threads[key] = {
+            "messages": [],
+            "participants_set": set(),
+            "first_message": null,
+            "last_message": null
+        }
+
+    entry = new_threads[key]
+    entry.messages.append({
+        "message_id": md.message_id,
+        "file": md.filename,
+        "date": md.date,
+        "sender": md.sender,
+        "in_reply_to": md.in_reply_to or null
+    })
+    entry.participants_set.add(md.sender)
+    if md.to/cc available in frontmatter → add to set
+    entry.first_message = min(entry.first_message, md.date)
+    entry.last_message = max(entry.last_message, md.date)
+
+# 後處理
+for key, entry in new_threads:
+    entry.messages.sort(key=lambda m: m.date)  # 時序排序
+    entry.message_count = len(entry.messages)
+    entry.participants = sorted(list(entry.participants_set))
+    del entry.participants_set
+```
+
+### Step 5: 寫入新的 `.threads.json`
+
+```json
+{
+  "version": "1.0",
+  "last_updated": "2026-04-22T15:01:09Z",
+  "rebuilt_from": "frontmatter_scan",
+  "threads": { ... }
+}
+```
+
+**頂層加 `rebuilt_from` 欄位**，記錄這次是從 frontmatter 重建的（而非 archive-mail 增量維護）。方便區分。
+
+### Step 6: 輸出報告
+
+```
+═══════════════════════════════════════════
+Rebuild Threads Index
+═══════════════════════════════════════════
+
+Archive: communications/
+Scanned: 67 md files
+Parsed: 65 with valid frontmatter
+Skipped: 2 (missing thread_key)
+
+Threads rebuilt: 12
+  - "SE manuscript 10xx-2025": 17 messages (2025-12-19 → 2026-01-28)
+  - "Biometrika submission BIOMTRKA-25-780": 13 messages (2025-12-19 → 2025-12-24)
+  - "JRSS series B Overleaf template": 11 messages (2025-12-24 → 2025-12-25)
+  - ...
+
+Backup: .threads.json.bak.20260422_150109
+
+Issues:
+  ⚠️ 2024-07-14_Old-email.md: missing frontmatter (legacy md, needs backfill)
+  ⚠️ 2024-07-14_Another-old.md: missing thread_key
+
+═══════════════════════════════════════════
+```
+
+### Step 7: 比對新舊 index（可選 sanity check）
+
+若舊 `.threads.json` 存在，比對新舊差異：
+
+- 新增的 threads
+- 消失的 threads（可能表示 md 被刪除）
+- message_count 變化的 threads
+
+報告 summary：
+
+```
+Diff from previous .threads.json:
+  + 2 new threads (from recent archive)
+  - 0 removed threads
+  ~ 3 threads with message count changes
+```
+
+若有 `-` removed threads，提示使用者檢查是不是誤刪 md。
+
+## Legacy md 的 backfill 策略
+
+舊版 archive（< v2.6.0）的 md 沒有 frontmatter。本 skill 不會自動 backfill，但會列出需要 backfill 的檔案。
+
+使用者可以：
+
+1. **手動加 frontmatter**（最保險）
+2. **自動推斷並 backfill**：未來版本可提供 `--backfill` 旗標，從 md 內的 `## 元數據` 表格 + 檔名推斷 frontmatter
+3. **接受部分覆蓋**：rebuild 跳過沒 frontmatter 的 md，只用新 md 重建 index（舊 md 就不在 index 裡，但檔案仍在）
+
+## 注意事項
+
+- **不修改 md 檔**：純讀取
+- **覆蓋 `.threads.json`**：舊的會先備份
+- **等冪**：重複執行結果相同（前提是 md 沒變）
+- **跑完後建議 review**：比對 `Threads rebuilt` 數量是否合理
+
+## 與相關 skill 的關係
+
+| Skill | 做什麼 |
+|-------|--------|
+| `/archive-mail` | 存入 per-email md + 增量維護兩個索引 |
+| `/archive-mail-view` | 讀 `.threads.json` 生成聚合視圖 |
+| `/archive-mail-rebuild-threads` | **本 skill** — 從 md frontmatter 重建 `.threads.json` |
diff --git a/plugins/che-apple-mail-mcp/commands/archive-mail-view.md b/plugins/che-apple-mail-mcp/commands/archive-mail-view.md
new file mode 100644
index 00000000..1ad46491
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/commands/archive-mail-view.md
@@ -0,0 +1,188 @@
+---
+description: 從 .threads.json 生成指定 thread 的聚合視圖
+argument-hint: <thread-key-substring> [archive-dir]
+allowed-tools: Read, Write, Glob, Bash(mkdir:*)
+---
+
+# Archive Mail — Thread View
+
+讀 `.threads.json` + per-email md 檔，聚合成單一 thread 視圖檔。用來把散在多個 md 檔裡的對話串整理成敘事性的一篇。
+
+## 使用方式
+
+```
+/archive-mail-view "SE manuscript 10xx-2025"
+/archive-mail-view "SE manuscript" communications
+/archive-mail-view "SE" communications/emails
+```
+
+- 第一個參數：thread key（可以是 substring，會模糊匹配 `.threads.json` 裡的 key）
+- 第二個參數（可選）：archive 目錄，預設 `communication/emails`
+
+## 執行步驟
+
+### Step 1: 解析參數
+
+從 `$ARGUMENTS` 取得：
+- `thread_query`: 要找的 thread key（必填）
+- `archive_dir`: archive 目錄，預設 `communication/emails`
+
+若無參數，提示：
+
+```
+Usage: /archive-mail-view <thread-key> [archive-dir]
+
+Try: /archive-mail-view "SE manuscript 10xx-2025"
+```
+
+### Step 2: 載入索引（v2.8.0+ 從 `.claude/.mail/state/archives/${SLUG}/`）
+
+```bash
+NAMESPACE_DIR=".claude/.mail"
+SLUG=$(echo "${archive_dir}" | tr '/' '-' | sed 's/^[-.]*//;s/[-.]*$//')
+THREADS_FILE="${NAMESPACE_DIR}/state/archives/${SLUG}/threads.json"
+
+# Auto-migrate from legacy(silent)
+if [ ! -f "${THREADS_FILE}" ] && [ -f "${archive_dir}/.threads.json" ]; then
+  mkdir -p "$(dirname "${THREADS_FILE}")"
+  mv "${archive_dir}/.threads.json" "${THREADS_FILE}"
+  echo "🔄 Migrated ${archive_dir}/.threads.json → ${THREADS_FILE}"
+fi
+
+[ -f "${THREADS_FILE}" ] || {
+  echo "ERROR: ${THREADS_FILE} not found (also no legacy ${archive_dir}/.threads.json)."
+  echo "Run /archive-mail first to create the index, or /archive-mail-rebuild-threads to regenerate from existing md files."
+  exit 1
+}
+```
+
+### Step 3: 匹配 thread key
+
+在 `.threads.json` 的 `threads` 物件中用 **case-insensitive substring match** 找符合的 key：
+
+- **0 個匹配**：列出前 20 個可用 thread key 給使用者參考，退出
+- **1 個匹配**：使用該 key
+- **多個匹配**：列出所有匹配的 thread key（含 message_count、last_message），讓使用者用更具體的 query 重跑
+
+### Step 4: 讀取 messages 並依時序排序
+
+對選定的 thread entry：
+
+1. 從 `messages` 陣列讀取所有 `file` 路徑
+2. 依 `date` 欄位排序（asc，最早的在前）
+3. 對每個 md 檔：
+   - `Read` 該檔
+   - 解析 YAML frontmatter 取得 `message_id` / `sender` / `direction` / `date` / `in_reply_to`
+   - 提取 `## 信件內容` 到下一個 `---` 之間的 body（**不含 thread quote 尾巴**；thread quote 的辨識 pattern 同 archive-mail Step 5.5：`差出人:` / `寄件者:` / `From:` / `On .* wrote:`）
+   - 提取 `## 重點摘要`（若有）
+   - 提取 `Attachments:` 區塊（若有）
+
+### Step 5: 生成聚合視圖
+
+輸出到 `${archive_dir}/.threads/{thread_key_sanitized}.md`（預設）或根據使用者參數。
+
+檔名 sanitization：同 archive-mail Step 5 的 subject → filename 規則（標點轉 `-`，截斷至 50 字元等）。
+
+**視圖格式**：
+
+```markdown
+# Thread: SE manuscript 10xx-2025
+
+**Messages**: 17
+**Participants**: yfhsu@ntu.edu.tw, d06227105@ntu.edu.tw, d11227103@ntu.edu.tw
+**Time span**: 2025-12-19 06:19 → 2026-01-28 08:00 (40 days)
+**Source**: `.threads.json` + 17 md files
+
+---
+
+## 2025-12-19 14:19 — yfhsu@ntu.edu.tw (received)
+
+**File**: `2025-12-19_SE-manuscript-10xx-2025.md`
+**Message-ID**: `<...@ntu.edu.tw>`
+
+Dear All:
+我稍為把 10xx-2025 的版本順了一回，順便小改幾個地方。看來有模有樣，只需將 "Numerical Illustration: Asymptotic Behavior in Assessment Data" 章節未完成之處補齊即可投稿。Right?
+Best, Hsu
+
+### Attachments
+- [main.pdf](../attachments/2025-12-19_SE-manuscript-10xx-2025/main.pdf) (234 KB)
+
+---
+
+## 2025-12-21 21:50 — yfhsu@ntu.edu.tw (received)
+
+**File**: `2025-12-21_RE--SE-manuscript-10xx-2025.md`
+**Message-ID**: `<...@ntu.edu.tw>`
+
+CC:
+我們先把 10xx-2025 這篇搞定，再處理 BJMSP review.
+Best, Hsu
+
+---
+
+## 2025-12-22 15:36 — d06227105@ntu.edu.tw (sent)
+
+**File**: `2025-12-22_RE--SE-manuscript-10xx-2025.md`
+**Message-ID**: `<...@ntu.edu.tw>`
+
+To：徐老師與昊紘
+
+關於 Kolva 的文章...
+[略]
+
+---
+
+[...依序列出所有 messages...]
+
+---
+
+## Summary
+
+本 thread 共 17 封信，涵蓋 SE paper 手稿從整理到投稿前的討論，主要議題：
+- Kolva et al. (2017) 表格標記問題
+- Empirical illustration 章節完成
+- 是否拆成兩篇投稿
+- BJMSP review 的時序安排
+
+**Attachments across thread**: 8 個檔案（列出）
+
+*View generated: YYYY-MM-DD HH:MM*
+*Source archive: `{archive_dir}`*
+```
+
+**設計重點**：
+
+1. **去 quote**：每則 message 只顯示自己的新文字，不重複 thread 歷史（歷史由時序本身呈現）
+2. **附件跨引用**：每則附件連結用相對路徑指向 `../attachments/...`，從 `.threads/` 子目錄回查
+3. **可重生成**：view 是 derived 資料，`.threads.json` 或 md 改動後可重跑覆蓋
+4. **Summary 區塊**：可選。如果使用者想要，可以呼叫 AI 讀完整 thread 後生成 1-2 段 narrative 摘要
+
+### Step 6: 輸出報告
+
+```
+═══════════════════════════════════════════
+Thread View Generated
+═══════════════════════════════════════════
+
+Thread key: SE manuscript 10xx-2025
+Source: 17 messages across 40 days
+Output: communications/.threads/SE-manuscript-10xx-2025.md
+
+═══════════════════════════════════════════
+```
+
+## 注意事項
+
+- **不修改原始 md 檔**：純讀取，輸出到獨立的 `.threads/` 子目錄
+- **重跑覆蓋**：每次執行會覆蓋 output 檔案
+- **`.threads/` 不該進 git**：建議 gitignore（這是衍生檔案，canonical 在 per-email md）
+- **缺檔處理**：若 `.threads.json` 的 file 指向不存在的 md，log warning 並跳過該 message，繼續處理其他
+- **Summary 區塊**：預設不生成。若使用者想要，可加 `--summary` 旗標（未來版本）
+
+## 與相關 skill 的關係
+
+| Skill | 做什麼 |
+|-------|--------|
+| `/archive-mail` | 存入 per-email md + 維護 `.email_index.json` 和 `.threads.json` |
+| `/archive-mail-view` | **本 skill** — 生成 thread 聚合視圖（衍生資料） |
+| `/archive-mail-rebuild-threads` | 從 md frontmatter 重建 `.threads.json` |
diff --git a/plugins/che-apple-mail-mcp/commands/archive-mail.md b/plugins/che-apple-mail-mcp/commands/archive-mail.md
index fe1780d7..e6c4658d 100644
--- a/plugins/che-apple-mail-mcp/commands/archive-mail.md
+++ b/plugins/che-apple-mail-mcp/commands/archive-mail.md
@@ -1,7 +1,7 @@
 ---
 description: 歸檔指定聯絡人的 Apple Mail 郵件到 Markdown 檔案
-argument-hint: <email-filter> [output-dir]
-allowed-tools: mcp__apple-mail__*, mcp__che-apple-mail-mcp__*, mcp__plugin_che-apple-mail-mcp_mail__*, Bash(mkdir:*), Read, Write, Glob
+argument-hint: "[email-filter] [output-dir]  # 零參數時讀 .claude/.mail/config.yaml"
+allowed-tools: mcp__plugin_che-apple-mail-mcp_mail__*, Bash(mkdir:*), Read, Write, Glob
 ---
 
 # Archive Mail
@@ -11,67 +11,797 @@ allowed-tools: mcp__apple-mail__*, mcp__che-apple-mail-mcp__*, mcp__plugin_che-a
 ## 使用方式
 
 ```
-/archive-mail d06227105@ntu.edu.tw
-/archive-mail d06227105@ntu.edu.tw communication/emails
+/archive-mail                                    # 零參數(v2.12.0+;v2.16.0+ 讀 .claude/.mail/config.yaml,.md fallback)
+/archive-mail user@example.com
+/archive-mail user@example.com communication/emails
 ```
 
-- 第一個參數：Email 過濾條件（寄件人或收件人包含此字串）
-- 第二個參數（可選）：輸出目錄，預設 `communication/emails`
+- 第一個參數(**v2.12.0+ 可選**):Email 過濾條件(寄件人或收件人包含此字串)
+- 第二個參數(可選):輸出目錄,預設 `communication/emails`
+
+#### 零參數模式
+
+當 cwd 已有 `.claude/.mail/config.yaml`(v2.16.0+;舊 `.md` 仍 fallback,首次 invoke auto-migrate 為 `.yaml`)並設定 `filters` 時,可不帶任何參數呼叫;從 config 讀取:
+
+| Field | 用途 |
+|-------|------|
+| `filters` | 多個 filter,作 OR-search 合併 corpus |
+| `output_dir` | 覆寫 default `communication/emails` |
+| `last_archived` | 給 search_emails 設 `date_from`(只抓此時點之後的信)|
+| `exclude_mailboxes` | search 跳過(垃圾郵件 / 草稿等)|
+| `sender_includes` | Layer 2 post-fetch: keep thread 若任一 message sender 含 substring(v2.20.0+, #84)|
+| `sender_excludes` | Layer 2 post-fetch: drop thread 若任一 message sender 含 substring(v2.20.0+, #84)|
+| `recipient_includes` | Layer 2 post-fetch: keep thread 若任一 message recipient 含 substring(v2.20.0+, #84)|
+| `recipient_excludes` | Layer 2 post-fetch: drop thread 若任一 message recipient 含 substring(v2.20.0+, #84)|
+| `subject_includes` | Layer 2 post-fetch: keep thread 若任一 message bare subject 含 substring(v2.20.0+, #76)|
+| `subject_excludes` | Layer 2 post-fetch: drop thread 若任一 message bare subject 含 substring(v2.20.0+, #76)|
+
+兩層 corpus model:`filters` / `subject_keywords` / `exclude_mailboxes` 是 Layer 1 search-time(定義 corpus);6 個 `*_includes` / `*_excludes` 是 Layer 2 post-fetch refinement(thread-coherent narrowing,excludes-precedence on same axis,case-insensitive substring)。完整契約見 spec `openspec/specs/archive-mail-corpus-refinement/spec.md`。
+
+命令列參數仍可覆寫 config(傳一個 filter 就只用該 filter,不讀 config 的 filters 清單)。詳細 schema 見 plugin CLAUDE.md。
 
 ## 執行步驟
 
+### Step 0: Bootstrap Stage Task List(v2.9.0+ 鐵律,強制)
+
+**在動任何事之前**先用 `TaskCreate` 為這個 stage 建 stage-level todo list，確保每個 sub-step 都被追蹤。學 IDD `idd-implement` 的 enforcement pattern。
+
+```
+TaskCreate(subject="resolve_filter_and_paths",
+           description="Step 1 + 1.6: 解析 $ARGUMENTS → filter + output_dir. 計算 .claude/.mail/state/archives/{slug} 路徑。Auto-migrate legacy .email_index.json / .threads.json / .claude/emails.md。")
+
+TaskCreate(subject="phase1_disambiguation",
+           description="Step 1.5: 若 filter 模糊(中文人名「陳老師」/相對時間「最近」/通用 scope「全部」) → 列候選讓 user 選;明確 email/Message-ID/--no-confirm → skip。由 confirmation-protocol skill Phase 1 + email-search-disambiguation 處理。")
+
+TaskCreate(subject="load_indices_and_config",
+           description="Step 2: 從 ${INDEX_DIR}/ 讀 email_index.json + threads.json + ${CONFIG_FILE} 的 attachment_routing / subject_keywords / participant_aliases。")
+
+TaskCreate(subject="search_emails",
+           description="Step 3 + 3b + 3c + 3d: 對每個帳號跑 sender 搜尋 + subject_keywords 搜尋 + bare-subject thread expansion,三組結果 Message-ID 去重 → corpus。注意 account_name 必須用 display name 不可用 ews:// URL。")
+
+TaskCreate(subject="filter_and_scan_false_positives",
+           description="Step 4 + 強制 false-positive scan(rules/false-positive-detection.md): 過濾出 Message-ID 不在索引的 emails → 待歸檔清單。對每個 thread 跑 flag_thread() → 標 ✓/⚠/⚠⚠/❓。Sibling activity / CC pollution / subject collision 三種 pattern 必須 check。")
+
+TaskCreate(subject="phase2_3_preview_and_confirm",
+           description="Step 4.5: 若待歸檔 ≥ 5 封 OR 有 ⚠⚠ flag OR destructive op → Phase 2 preview (thread breakdown + flags) + Phase 3 operation confirmation (file count + attachment size)。等 user 確認(a)/排除(b)/改 filter(c)/取消(d)。User skip 條件見 confirmation-triggers.md。")
+
+TaskCreate(subject="fetch_and_write_markdown",
+           description="Step 5: 對每封新郵件 get_email(format='text', 用 display name) → YAML frontmatter (message_id/thread_key/in_reply_to/date/sender/direction) + body markdown，按檔名規則(YYYY-MM-DD_subject-hyphenated[-N].md, 截 50 graphemes) 寫到 ${output_dir}/。")
+
+TaskCreate(subject="download_and_classify_attachments",
+           description="Step 5.5: list_attachments → 用 classify() 分 data/document → save_attachment 到 data_dir / documents_dir/{email_stem}/。Markdown 插 Attachments: 區塊。回覆信無 byte 附件但引用原信附件 → cross-reference。")
+
+TaskCreate(subject="update_indices",
+           description="Step 5.7 + Step 6: 對每封新歸檔的信 append 到 ${THREADS_FILE} 的 thread_key entry (messages append, participants set, first/last_message, message_count)。把新 Message-ID + thread_key 加到 ${INDEX_FILE}。Append-only,不修改既有 entry。")
+
+TaskCreate(subject="report_and_audit",
+           description="Step 7 + 8: 輸出歸檔報告(新歸檔/跳過/thread 索引/附件分流)。執行 Coverage Audit (8a 附件完整性 + 8b thread 完整性 → search by bare_subject 比對 archived/total)。")
+```
+
+**完成每一步立即 `TaskUpdate → completed`。靜默完成 = 違規。**
+
+中途若發現要分更多 sub-tasks(例如 Phase 2 preview 需要分批,或 attachment 下載失敗需要 retry),用 `TaskCreate` 補加。
+
+**為什麼**:沒有 Stage TaskList 時,Claude 看 markdown spec 容易跳步驟(例如 false-positive scan 漏跑、Phase 2 preview 用「應該不需要」rationalize 掉)。Stage TaskList 把「跳過」變成顯眼的 incomplete task,user 在 UI 看得到。歷史上 2026-05-01 archive 陳老師信件就是因為沒跑 false-positive scan,265250 false positive 漏網,事後又花一輪 rm + index 修復。
+
 ### Step 1: 解析參數
 
-從 `$ARGUMENTS` 取得：
-- `filter`: 第一個參數（必填）
-- `output_dir`: 第二個參數，預設 `communication/emails`
+從 `$ARGUMENTS` 取得:
+- `filter`: 第一個參數(可選,**v2.12.0+ 零參數模式**)
+- `output_dir`: 第二個參數;若未給且 `${CONFIG_FILE}` 也沒設,進 **Workspace Layout Detection**(v2.17.0+,見下方)決定;最終 fallback 為 `communication/emails`
+
+#### Config parsing(always-on,v2.17.0+ #49)
+
+不論 `$ARGUMENTS` 是空還是有內容,**只要 `${CONFIG_FILE}` 存在就先 parse**。理由:`/archive-mail <filter>`(只給第一個 arg)的 user 也應該尊重 config `output_dir:` pin,不能 silently fall through 到 detection。
+
+> **Forward reference**:`${CONFIG_FILE}` 由 Step 1.6 計算(`.claude/.mail/config.yaml`,legacy `.md` fallback)。AI executor 整段 skill 讀完才開始執行,所以 forward-reference 在 markdown skill 慣例下 OK;若有人手動 copy bash 出來跑,先看 Step 1.6 的 `CONFIG_FILE` 賦值。
+
+```bash
+# Always parse config if file exists — independent of $ARGUMENTS state
+CFG_OUTPUT_DIR=""
+LAST_ARCHIVED=""
+EXCLUDE_MBX=""
+SENDER_INCLUDES=""
+SENDER_EXCLUDES=""
+RECIPIENT_INCLUDES=""
+RECIPIENT_EXCLUDES=""
+SUBJECT_INCLUDES=""
+SUBJECT_EXCLUDES=""
+if [ -f "${CONFIG_FILE}" ]; then
+    # Parse YAML config (top-level scalars + sequences only)
+    # 兼容 pure YAML(`.yaml` v2.16.0+)與 frontmatter-wrapped(`.md` legacy);awk pattern 對兩者皆 work
+    # `---` 邊界(若 .md 用 frontmatter style)由 pattern 自然 skip(不 match `^[a-z_]+:`)
+    CFG_OUTPUT_DIR=$(awk '/^output_dir:[ \t]*/{sub(/^output_dir:[ \t]*/,"");print;exit}' "${CONFIG_FILE}")
+    LAST_ARCHIVED=$(awk '/^last_archived:[ \t]*/{sub(/^last_archived:[ \t]*/,"");print;exit}' "${CONFIG_FILE}")
+    EXCLUDE_MBX=$(awk '/^exclude_mailboxes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+
+    # Layer 2 post-fetch corpus refinement (v2.20.0+, #76 + #84):
+    # Six opt-in corpus-refinement fields. Same awk shape as exclude_mailboxes — multi-line `  - item` block-style only.
+    # Full spec: openspec/specs/archive-mail-corpus-refinement/spec.md
+    SENDER_INCLUDES=$(awk '/^sender_includes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+    SENDER_EXCLUDES=$(awk '/^sender_excludes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+    RECIPIENT_INCLUDES=$(awk '/^recipient_includes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+    RECIPIENT_EXCLUDES=$(awk '/^recipient_excludes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+    SUBJECT_INCLUDES=$(awk '/^subject_includes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+    SUBJECT_EXCLUDES=$(awk '/^subject_excludes:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+
+    # Validation: malformed refinement value aborts with explicit error (spec ADDED Requirement).
+    # Sequence-form: `<field>:` on its own line, with `  - item` lines following → awk parser handles cleanly.
+    # Inline scalar or non-empty inline list on the same line → refuse here, do not silently coerce.
+    # Empty inline list `[]` and bare `<field>:` (no value) are both valid sequence forms.
+    for _f in sender_includes sender_excludes recipient_includes recipient_excludes subject_includes subject_excludes; do
+        _line=$(awk -v field="^${_f}:" '$0 ~ field {print; exit}' "${CONFIG_FILE}")
+        if [ -n "$_line" ]; then
+            _val=$(printf '%s' "$_line" | sed -E "s/^${_f}:[[:space:]]*//")
+            if [ -n "$_val" ] && [ "$_val" != "[]" ]; then
+                echo "Error: ${_f} must be a YAML multi-line block-style sequence of strings (\`${_f}:\` on its own line followed by indented \`  - item\` lines). Got inline value: ${_val}" >&2
+                exit 1
+            fi
+        fi
+    done
+
+    # Strip empty entries from refinement lists per spec (sender_excludes: [""] ≡ sender_excludes: []).
+    # The awk above prints raw item text; drop blank lines, "" and '' entries here.
+    _strip_empty_refinement_entries() {
+        printf '%s\n' "$1" | awk 'NF > 0 && $0 != "\"\"" && $0 != "'"'"''"'"'"'
+    }
+    SENDER_INCLUDES=$(_strip_empty_refinement_entries "$SENDER_INCLUDES")
+    SENDER_EXCLUDES=$(_strip_empty_refinement_entries "$SENDER_EXCLUDES")
+    RECIPIENT_INCLUDES=$(_strip_empty_refinement_entries "$RECIPIENT_INCLUDES")
+    RECIPIENT_EXCLUDES=$(_strip_empty_refinement_entries "$RECIPIENT_EXCLUDES")
+    SUBJECT_INCLUDES=$(_strip_empty_refinement_entries "$SUBJECT_INCLUDES")
+    SUBJECT_EXCLUDES=$(_strip_empty_refinement_entries "$SUBJECT_EXCLUDES")
+fi
+
+# output_dir precedence (高 → 低):
+#   1. $ARGUMENTS[2] (cmdline second arg) — 若已設,跳過下面的 fallback
+#   2. ${CONFIG_FILE} 的 output_dir: 欄位(本 step,both zero-arg and single-arg modes)
+#   3. Workspace Layout Detection(下方,v2.17.0+)
+#   4. Baseline default `communication/emails`(detection 中的 Probe 3)
+[ -z "$output_dir" ] && [ -n "$CFG_OUTPUT_DIR" ] && output_dir="$CFG_OUTPUT_DIR"
+# last_archived feeds Step 3 search_emails 的 date_from (strict `>`)
+# exclude_mailboxes feeds Step 3 mailbox-filter
+```
+
+#### Zero-arg 模式(v2.12.0+,resolves #13)
+
+若 `$ARGUMENTS` 為空,從 `${CONFIG_FILE}` 讀取 `filters`(否則無 filter 可搜):
+
+```bash
+if [ -z "$ARGUMENTS" ]; then
+    if [ ! -f "${CONFIG_FILE}" ]; then
+        echo "Error: 沒有給 filter 也找不到 ${CONFIG_FILE}。" >&2
+        echo "請建立 \${CONFIG_FILE} 並設定 filters,或直接傳 filter 參數。" >&2
+        exit 1
+    fi
+
+    # filters → list,作 OR-search 的 filter set
+    FILTERS=$(awk '/^filters:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /^  - /{sub(/^  - /,"");print}' "${CONFIG_FILE}")
+
+    if [ -z "$FILTERS" ]; then
+        echo "Error: ${CONFIG_FILE} 沒設定 filters。請補 filters 或傳命令列參數。" >&2
+        exit 1
+    fi
+fi
+```
+
+#### 命令列覆寫(現行行為,backward compat)
 
-如果沒有提供 filter，詢問用戶。
+若 `$ARGUMENTS` 非空,命令列參數覆寫 config:
+- `filter` = 第一個 arg(視為單一 filter,即使 config 有多個 filters 仍只用此一個)
+- `output_dir` = 第二個 arg(若有);**否則仍走上方 Config parsing 區段已 apply 的 `CFG_OUTPUT_DIR`**(v2.17.0+ 修掉 explicit-config-bypass-in-non-zero-arg-mode 漏洞);config 沒設則走 **Workspace Layout Detection**(v2.17.0+) / default
 
-### Step 2: 建立目錄和索引
+#### Workspace Layout Detection(v2.17.0+,#49)
+
+當 `output_dir` 既非 `$ARGUMENTS[1]` 也非 `${CONFIG_FILE}` 的 `output_dir:` 欄位給定時,probe 工作目錄看是否符合已知的 workspace layout。**Detection 只在「沒有 explicit choice」時觸發**——如果 user 在 config 或命令列已 pin,detection 完全不跑,既有行為 100% backward compat。
+
+**Probe 順序**(命中即停):
 
 ```bash
-mkdir -p "${output_dir}"
+# Only run when output_dir is still empty after $ARGUMENTS[1] + ${CONFIG_FILE} resolution
+if [ -z "$output_dir" ]; then
+    # Probe 1: communications/<channel>/ pattern (v2.17.0+ canonical)
+    if [ -d "communications/email" ]; then
+        # Ambiguity guard: if both layouts have content, refuse to guess
+        if [ -d "correspondence/emails" ] && \
+           [ -n "$(find -P correspondence/emails -maxdepth 1 -name '*.md' 2>/dev/null | head -1)" ] && \
+           [ -n "$(find -P communications/email  -maxdepth 1 -name '*.md' 2>/dev/null | head -1)" ]; then
+            echo "❌ Ambiguous workspace layout: both 'communications/email/' and 'correspondence/emails/' have archived markdowns." >&2
+            echo "   Pin 'output_dir:' in .claude/.mail/config.yaml to disambiguate." >&2
+            exit 1
+        fi
+        output_dir="communications/email"
+        echo "🔍 Detected output_dir: communications/email (from layout probe)"
+
+    # Probe 2: correspondence/emails/ legacy pattern (pre-v2.17 user convention)
+    elif [ -d "correspondence/emails" ]; then
+        output_dir="correspondence/emails"
+        echo "🔍 Detected output_dir: correspondence/emails (legacy layout probe)"
+
+    # Probe 3: nothing detected — fall back to baseline default
+    else
+        output_dir="communication/emails"
+        # No log line — silent default keeps non-detection workspace flow unchanged
+    fi
+fi
 ```
 
-讀取索引檔 `${output_dir}/.email_index.json`：
-- 若存在，載入已歸檔的 Message-ID
-- 若不存在，建立空索引 `{"version": "1.0", "emails": {}}`
+**Why probe order = `communications/email` → `correspondence/emails` → default**:
+
+1. `communications/<channel>/` 是 forward direction(per kiki830621/chchen-lab 2026-05-08 reorg)。當 user 已建好 `communications/email/`,intent 明確。
+2. `correspondence/emails/` 是 legacy convention(per 既有 `psychophysic_representations` 等 workspaces)。但這些 workspaces 通常已有 explicit `output_dir:` 在 config,此 probe 主要為「legacy workspace 沒寫 config」的少數情境兜底。
+3. 都不符合則用 baseline default,既有 zero-config flow 不變。
+
+**Ambiguity guard**:當 `communications/email/` 與 `correspondence/emails/` **同時存在且都有 `*.md`** 時,refuse 而非 silent guess。Mid-migration 的 workspace 必須 explicit pin,否則風險:detection 把新信寫到 `communications/email/` 但 dedup index 依然指 legacy 路徑,半實作狀態下的 message-id collision 不會被偵測。Empty-dir-as-marker 不算ambiguity(常見:user 才剛建好 `communications/email/`,還沒 archive 過)。
+
+**Detection 與 explicit config 的關係**(precedence,高 → 低):
+
+1. `$ARGUMENTS[1]`(命令列 `/archive-mail <filter> <output_dir>` 的第二個參數)
+2. `${CONFIG_FILE}` 的 `output_dir:` 欄位(zero-arg 模式)
+3. **Workspace Layout Detection**(本節,v2.17.0+)
+4. Baseline default `communication/emails`
+
+#### 模糊 filter
+
+不論來源(命令列 / config),若 filter 為模糊詞 → 進 Step 1.5 disambiguation。
+
+### Step 1.5: Confirmation — Phase 1: Disambiguation（v2.7.0+）
+
+**Skill ref**: `confirmation-protocol`、`email-search-disambiguation`
+
+如果 filter 是模糊詞（中文人名「陳老師」、相對時間「最近」、通用 scope「全部」），**不要直接執行 search**。先用 disambiguation:
+
+```
+「{filter}」可能對應到:
+1. {email_1} ({description_1}, 推薦)
+2. {email_2} ({description_2})
+3. 其他
+
+你要哪一個?
+```
+
+候選來源:
+- `.claude/emails.md` 的 `participant_aliases` 欄位
+- 之前歸檔的 `.threads.json` participants
+- Address book / contacts MCP
+
+**Skip Phase 1**(可直接進 Step 2):
+- Filter 是明確 email 地址(含 `@`)
+- Filter 是 Message-ID
+- 單一 user-typed `--no-confirm` flag 或明確說「直接做」
+
+詳見 `skills/confirmation-protocol/SKILL.md` 和 `skills/email-search-disambiguation/SKILL.md`。
+
+### Step 1.6: 解析 namespace 路徑（v2.8.0+,學 IDD `.claude/.idd/` pattern）
+
+統一所有 mail 工作流的 config + state 到 `.claude/.mail/`(學 idd 的 namespace 收斂):
+
+```bash
+NAMESPACE_DIR=".claude/.mail"
+
+# Slug for output_dir (用於支援多個 archive target 並存)
+SLUG=$(echo "${output_dir}" | tr '/' '-' | sed 's/^[-.]*//;s/[-.]*$//')
+
+INDEX_DIR="${NAMESPACE_DIR}/state/archives/${SLUG}"
+INDEX_FILE="${INDEX_DIR}/email_index.json"
+THREADS_FILE="${INDEX_DIR}/threads.json"
+
+# v2.16.0+ (#47): config 改 .yaml 為 first-class;.md 維持 fallback 直到 v3.0
+# Auto-migrate legacy .md → .yaml 時機在下方 "Auto-migrate" 區塊處理
+CONFIG_FILE="${NAMESPACE_DIR}/config.yaml"
+[ ! -f "$CONFIG_FILE" ] && [ -f "${NAMESPACE_DIR}/config.md" ] && CONFIG_FILE="${NAMESPACE_DIR}/config.md"
+
+mkdir -p "${INDEX_DIR}"
+```
+
+**Resolve dedup strategy** (v2.14.0+, issue #18):
+
+```bash
+# Default: index-based dedup (backward compat with v2.13.0 ↓)
+DEDUP_STRATEGY=$(awk '/^dedup_strategy:[ \t]*/{sub(/^dedup_strategy:[ \t]*/,"");print;exit}' "${CONFIG_FILE}" 2>/dev/null)
+DEDUP_STRATEGY="${DEDUP_STRATEGY:-index}"
+
+case "$DEDUP_STRATEGY" in
+    index|last_archived|both) ;;  # valid
+    *)
+        echo "Error: invalid dedup_strategy '${DEDUP_STRATEGY}'. Valid: index | last_archived | both" >&2
+        exit 1
+        ;;
+esac
+
+# If last_archived strategy: require last_archived field present
+if [ "$DEDUP_STRATEGY" = "last_archived" ]; then
+    LAST_ARCHIVED=$(awk '/^last_archived:[ \t]*/{sub(/^last_archived:[ \t]*/,"");print;exit}' "${CONFIG_FILE}" 2>/dev/null)
+    if [ -z "$LAST_ARCHIVED" ]; then
+        echo "Error: dedup_strategy=last_archived requires '${CONFIG_FILE}' to have a 'last_archived: YYYY-MM-DD' field." >&2
+        echo "Either set last_archived (manually or after first archive run) or use dedup_strategy: index | both." >&2
+        exit 1
+    fi
+fi
+```
+
+| `dedup_strategy` | Step 2 (load index) | Step 4 (dedup logic) | Step 5/6 (write index) |
+|------------------|---------------------|----------------------|-----------------------|
+| `index` (default) | load `email_index.json` | filter Message-ID not in index | append new Message-IDs |
+| `last_archived` | skip | filter received-date `>` last_archived | skip |
+| `both` | load | union: not-in-index AND date `>` last_archived | append (索引 still maintained) |
+
+**Auto-migrate from legacy paths**(silent,只在新位置不存在時觸發):
+
+```bash
+# Legacy → new: indices
+if [ ! -f "${INDEX_FILE}" ] && [ -f "${output_dir}/.email_index.json" ]; then
+  mv "${output_dir}/.email_index.json" "${INDEX_FILE}"
+  echo "🔄 Migrated ${output_dir}/.email_index.json → ${INDEX_FILE}"
+fi
+if [ ! -f "${THREADS_FILE}" ] && [ -f "${output_dir}/.threads.json" ]; then
+  mv "${output_dir}/.threads.json" "${THREADS_FILE}"
+  echo "🔄 Migrated ${output_dir}/.threads.json → ${THREADS_FILE}"
+fi
+
+# Legacy → new: config v2.7.0 ↓ (.claude/emails.md → namespace)
+if [ ! -f "${NAMESPACE_DIR}/config.yaml" ] && [ ! -f "${NAMESPACE_DIR}/config.md" ] && [ -f ".claude/emails.md" ]; then
+  mv ".claude/emails.md" "${NAMESPACE_DIR}/config.yaml"
+  CONFIG_FILE="${NAMESPACE_DIR}/config.yaml"
+  echo "🔄 Migrated .claude/emails.md → ${NAMESPACE_DIR}/config.yaml"
+fi
+
+# Legacy → new: config v2.15.0 ↓ (.md → .yaml, v2.16.0+ #47)
+# 只 rename,不改內容(awk parser 對 YAML body 兩種格式皆 work)
+if [ ! -f "${NAMESPACE_DIR}/config.yaml" ] && [ -f "${NAMESPACE_DIR}/config.md" ]; then
+  mv "${NAMESPACE_DIR}/config.md" "${NAMESPACE_DIR}/config.yaml"
+  CONFIG_FILE="${NAMESPACE_DIR}/config.yaml"
+  echo "🔄 Migrated ${NAMESPACE_DIR}/config.md → ${NAMESPACE_DIR}/config.yaml (v2.16.0+ schema rename)"
+fi
+```
+
+> **v2.16.0+ schema clarification (#47)**:config 副檔名改 `.yaml`(內容向來都是 YAML,只是 v2.15.0 ↓ 用 `.md` 副檔名造成語意 mismatch)。Auto-migrate 是 silent rename,user 不需動手。`.md` 仍 work 為 fallback,**v3.0 移除**;期間 README / CLAUDE.md schema 範例都改示範 `.yaml`。
+
+或者用 `/archive-mail-migrate` 批次 migrate 所有舊 archive targets,詳見該 command。
+
+### Step 2: 建立目錄和載入索引
+
+```bash
+mkdir -p "${output_dir}"   # archive markdown 目的地(不變)
+```
+
+**讀取兩個索引檔**(v2.8.0+ 從 `${INDEX_DIR}/` 讀;v2.14.0+ 條件 skip per `dedup_strategy`):
+
+`${INDEX_FILE}` (`.claude/.mail/state/archives/${SLUG}/email_index.json`) — Message-ID 去重索引(canonical key):
+- 若 `dedup_strategy=last_archived`(v2.14.0+) → **skip**, 完全不讀 index
+- 若 `dedup_strategy=index`(default)或 `both` → 載入已歸檔 Message-ID;不存在則建立空索引 `{"version": "1.0", "emails": {}}`
+
+`${THREADS_FILE}` (`.claude/.mail/state/archives/${SLUG}/threads.json`) — Thread 關係索引(append-only thread view):
+- 若存在,載入既有 thread 結構
+- 若不存在,建立空索引 `{"version": "1.0", "threads": {}}`
+- 格式見 Step 5.7
+
+兩個索引**獨立維護**,thread 索引純粹為了快速查詢 thread 關係,不影響單封信的儲存。若 `threads.json` 損壞,可用 `/archive-mail-rebuild-threads` 從 md frontmatter 重建。
+
+#### Step 2.1: Sibling-archive dedup extension(v2.17.0+,#49)
+
+當 `${output_dir}` 下有 symlinked subdirectory(典型情境:transitioned-project pattern,例如 chchen_lab 把 `email/application/` symlink 到 `applications/completed/.../emails/`),掃描其下 markdown 的 YAML frontmatter,把 `message_id:` 值併入 in-memory dedup set。**讀取 only,從不寫入 symlink target**。
+
+```bash
+# Only run when dedup_strategy uses index (skip if last_archived only)
+if [ "$DEDUP_STRATEGY" = "index" ] || [ "$DEDUP_STRATEGY" = "both" ]; then
+    # Find symlinked subdirectories in output_dir (1 level deep)
+    EXTENDED_COUNT=0
+    EXTENDED_SOURCES=()
+    while IFS= read -r symlink_dir; do
+        [ -z "$symlink_dir" ] && continue
+        # Bound search depth + use -P to NOT follow symlinks recursively (we follow once into the symlinked dir, then stay)
+        ENTRIES_THIS_DIR=0
+        while IFS= read -r mdfile; do
+            [ -z "$mdfile" ] && continue
+            # Read just the YAML frontmatter (first ~30 lines is generous)
+            mid=$(head -30 "$mdfile" 2>/dev/null | awk '/^message_id:[ \t]*/{sub(/^message_id:[ \t]*"?/,"");sub(/"?$/,"");print;exit}')
+            if [ -n "$mid" ]; then
+                # Add to in-memory dedup set (Message-ID is canonical key, same as INDEX_FILE)
+                # Implementation: append to a shadow set the dedup logic in Step 4 will consult
+                EXTENDED_DEDUP_IDS+=("$mid")
+                ENTRIES_THIS_DIR=$((ENTRIES_THIS_DIR + 1))
+            fi
+        done < <(find -P "$symlink_dir/" -maxdepth 2 -name "*.md" -type f 2>/dev/null)
+
+        if [ "$ENTRIES_THIS_DIR" -gt 0 ]; then
+            EXTENDED_COUNT=$((EXTENDED_COUNT + ENTRIES_THIS_DIR))
+            EXTENDED_SOURCES+=("$symlink_dir ($ENTRIES_THIS_DIR entries)")
+        fi
+    done < <(find -P "${output_dir}" -maxdepth 1 -type l 2>/dev/null)
+
+    if [ "$EXTENDED_COUNT" -gt 0 ]; then
+        echo "🔗 Extended dedup with $EXTENDED_COUNT entries from sibling archives:"
+        for src in "${EXTENDED_SOURCES[@]}"; do
+            echo "   - $src"
+        done
+    fi
+    # Silent when zero — typical zero-symlink workspace flow stays clean
+fi
+```
+
+**Step 4 dedup logic 銜接**:`EXTENDED_DEDUP_IDS` 由 Step 4 透過 set union **併入** existing predicate(不取代 strategy-specific date filter)。完整 pseudocode 見 [Step 4 過濾新郵件](#step-4-過濾新郵件)。Composition rule 摘要:
+
+- `dedup_strategy=index`:`known_ids = existing_index_ids ∪ extended_ids`,filter by Message-ID set membership only
+- `dedup_strategy=last_archived`:本 step 2.1 完全 skip(`EXTENDED_DEDUP_IDS` 不會被 populate),Step 4 仍走 date gate
+- `dedup_strategy=both`:`known_ids = existing_index_ids ∪ extended_ids` AND date > `last_archived`,**两条件 AND**(extended IDs 不打破 date filter)
+
+**Properties / invariants**:
+
+- **Read-only**:never `mv` / `rm` / `>` against symlink target;`find` + `head` + `awk` only。
+- **Bounded**:`find -P -maxdepth 2`(symlink dir 本身 + 一層 immediate children),避免 deep archive 拖慢 startup。
+- **archive-mail v2.6+ format compatibility**:設計 target 是 archive-mail 自產的 frontmatter(`message_id: "<...>"` 雙引號格式)。Manual archive 若 frontmatter 用單引號 / 內含 inline comment / CRLF / trailing whitespace,parser 不 silent skip,而是把**malformed key**(例如 `'<abc>'` 包含單引號、含 inline comment 文字、含 `\r`)加入 in-memory dedup set;Step 4 比較 archive-mail 寫的 canonical Message-ID(`<abc>` 無外引號)時對不上,造成 **dedup miss**(historic 已 archive 的信被 re-archive)。**ENTRIES_THIS_DIR 仍會 increment**(parser 認為「成功 extract」),但 key 是 garbage,有 silent miss 風險。Future hardening(yq parser / robust awk handling 單引號 / inline comment / CRLF / trailing whitespace)deferred until N≥3 user reports of manual-archive missed dedup — see follow-up #54 / #50 for tracking。
+- **Compose with `dedup_strategy`**:僅在 `index` / `both` strategy 跑;`last_archived` strategy 完全 skip(那種 strategy 的 user 顯然不依賴 Message-ID dedup)。Compose 邏輯:`EXTENDED_DEDUP_IDS` 透過 set union 併入 existing Message-ID set,不取代 strategy-specific date predicate。
+
+**讀取附件設定**(可選):檢查 `${CONFIG_FILE}` (`.claude/.mail/config.md`) 是否有 `attachment_routing` YAML front matter 區塊。
+若有，載入自訂規則（all-or-nothing 取代，不做 merge）。若無，使用以下內建預設：
+
+```yaml
+attachment_routing:
+  data_extensions: [csv, tsv, sav, dta, parquet, feather, xlsx, sas7bdat]
+  document_extensions: [pdf, docx, doc, txt, md, rtf, odt]
+  data_keywords: [data, raw, indicators, codebook, dataset]          # 大小寫不敏感子字串匹配
+  document_keywords: [Submission, Figures, Tables, Manuscript, draft, Revision, v1, v2, v3]
+  data_dir: data/raw
+  documents_dir: correspondence/attachments
+```
+
+**讀取搜尋擴展設定**（可選，v2.4.0+）：
+
+```yaml
+subject_keywords: [taxometric, SSQ, paper]    # subject 關鍵字搜尋（補抓 sender 漏掉的 internal threads）
+participant_aliases:                           # 成員別名（用於 audit 報告顯示）
+  "b08801008@ntu.edu.tw": "Pei-Chi"
+  "r13227202@ntu.edu.tw": "Pei-Chi"
+```
+
+- `subject_keywords`：可選。若有，Step 3 會做第二輪 subject 搜尋。若無，只跑 sender 搜尋（向後相容）。
+- `participant_aliases`：可選。目前用於 audit 報告的顯示名稱；不影響搜尋行為。
+
+**分類優先序**（config > keyword > extension）：
+1. YAML config 明確指定 → 最高
+2. 檔名 keyword 子字串匹配（先比 `data_keywords`，再比 `document_keywords`）→ 中
+3. 副檔名匹配（先比 `data_extensions`，再比 `document_extensions`）→ 最低
+4. 全部未命中 → 保守預設：歸類為 document
 
 ### Step 3: 搜尋郵件（使用 apple-mail MCP）
 
-使用 `mcp__apple-mail__search_emails` 搜尋：
+使用 `mcp__plugin_che-apple-mail-mcp_mail__search_emails` 搜尋：
 
 1. **搜尋收到的郵件**（sender 包含 filter）
 2. **搜尋寄出的郵件**（在 Sent 信箱搜尋）
 
-需要先用 `mcp__apple-mail__list_accounts` 取得帳號列表。
+需要先用 `mcp__plugin_che-apple-mail-mcp_mail__list_accounts` 取得帳號列表。
 
 對每個帳號執行：
 ```
-mcp__apple-mail__search_emails(
-  account: "帳號名稱",
-  sender: "${filter}",
-  include_content: true,
-  max_results: 100
+mcp__plugin_che-apple-mail-mcp_mail__search_emails(
+  account_name: "帳號名稱",
+  query: "${filter}",
+  field: "sender",
+  limit: 100
 )
 ```
 
+> **⚠️ account_name 陷阱（fixes #15）— 全域適用，`search_emails` 與 `get_email` 皆然**
+> `list_accounts` 對 Exchange 帳號回傳的 `name` 是 `ews://AAMkA...` 形式的內部 URL；`uuid` 也不接受。後續呼叫 `get_email` / `search_emails` 時必須改用 **display name**（email 地址，例如 `user@example.com`），否則會觸發：
+>
+> ```
+> AppleScript error (-1728): Mail got an error: Can't get account "ews://...".
+> ```
+>
+> 若配置 `.claude/emails.md` 的 `accounts` 欄位明列 email 地址，可直接拿來用。否則需要人工比對帳號。
+> **此陷阱對 Step 5 讀取郵件內文同樣適用**，不要假設搜尋階段記的 `account_name` 可以直接沿用——若那是 EWS URL，到 `get_email` 會重現 -1728。
+
+**3b. Subject-keyword 搜尋**（v2.4.0+，若 `subject_keywords` 有設定）：
+
+對每個 keyword，執行：
+```
+search_emails(account_name: "...", query: keyword, field: "subject", limit: 100)
+```
+
+將結果加入 corpus。
+
+**3c. Thread-subject 擴展**（v2.4.0+，自動）：
+
+對步驟 3 / 3b 找到的每封信：
+1. 提取 bare subject（去掉 `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:` 前綴，用正則 `^(Re|RE|Fwd|FW|转发|轉寄):\s*`）
+2. 用 bare subject 搜尋：`search_emails(query: bare_subject, field: "subject", limit: 100)`
+3. 將結果加入 corpus
+
+**3d. 合併去重**：
+
+三組結果（sender + subject_keywords + thread-subject）用 Message-ID 去重。最終 corpus 進入 Step 4。
+
+在 Step 7 報告中加上：`搜尋結果: {sender_count} by sender + {keyword_count} by subject + {thread_count} by thread expansion = {total_unique} unique`
+
 ### Step 4: 過濾新郵件
 
-對每封搜尋到的郵件：
-1. 檢查其 Message-ID 是否已在索引中
+Step 4 分兩個 sub-step:**先 Layer 2 pre-dedup refinement**(v2.20.0+,新,#76 + #84),**再 dedup**(原行為)。
+
+#### Step 4.0: Pre-dedup refinement (Layer 2, v2.20.0+, #76 + #84)
+
+Refinement executes after fetch and before dedup,對應 spec `openspec/specs/archive-mail-corpus-refinement/spec.md`。6 個 opt-in config 欄位(`sender_includes` / `sender_excludes` / `recipient_includes` / `recipient_excludes` / `subject_includes` / `subject_excludes`)在 thread 層級過濾 fetched corpus:case-insensitive substring matching with bare-value normalization、per-axis includes whitelist and excludes blacklist with excludes-precedence、per-thread coherence(任一 message 命中 → 整 thread keep/drop)。
+
+實作 sketch:
+
+```python
+import re
+
+_RE_FWD_PREFIX = re.compile(r'^(Re|RE|Fwd|FW|转发|轉寄):\s*')
+
+def _bare_email(addr_field):
+    """Strip display name. '"Name" <foo@bar>' → 'foo@bar'; lowercase."""
+    m = re.search(r'<([^>]+)>', addr_field or "")
+    raw = m.group(1) if m else (addr_field or "")
+    return raw.strip().strip('"').lower()
+
+def _bare_subject(subject):
+    """Strip leading Re:/Fwd:/转发:/轉寄: prefixes; lowercase."""
+    s = subject or ""
+    while True:
+        m = _RE_FWD_PREFIX.match(s)
+        if not m: break
+        s = s[m.end():]
+    return s.strip().lower()
+
+def _matches_any_substring(target_lower, substrs):
+    """Case-insensitive substring matching with bare-value normalization (target already lowered)."""
+    return any(s.strip().lower() in target_lower for s in substrs if s.strip())
+
+def _thread_passes_refinement(thread_messages, config):
+    """Per-axis includes whitelist + excludes blacklist with excludes-precedence.
+    Per-thread coherence: any message matches includes → keep thread; any matches excludes → drop thread."""
+    senders    = [_bare_email(m['sender']) for m in thread_messages]
+    recipients = [_bare_email(r) for m in thread_messages for r in (m.get('to', []) + m.get('cc', []))]
+    subjects   = [_bare_subject(m['subject']) for m in thread_messages]
+
+    # Includes whitelist (skip axis if list empty per spec empty-list-as-unset)
+    for axis_values, includes in [
+        (senders,    config.get('sender_includes',    [])),
+        (recipients, config.get('recipient_includes', [])),
+        (subjects,   config.get('subject_includes',   [])),
+    ]:
+        if includes and not any(_matches_any_substring(v, includes) for v in axis_values):
+            return False, 'includes_filter'  # whitelist active and no message matches → drop
+
+    # Excludes blacklist (excludes win when both set on same axis per spec ADDED Requirement)
+    for axis_values, excludes, reason in [
+        (senders,    config.get('sender_excludes',    []), 'sender_excludes'),
+        (recipients, config.get('recipient_excludes', []), 'recipient_excludes'),
+        (subjects,   config.get('subject_excludes',   []), 'subject_excludes'),
+    ]:
+        if excludes and any(_matches_any_substring(v, excludes) for v in axis_values):
+            return False, reason
+
+    return True, None
+
+def apply_refinement(fetched, config):
+    """Group fetched by thread key (bare subject); drop threads per per-thread coherence rule."""
+    threads = {}
+    for email in fetched:
+        threads.setdefault(_bare_subject(email['subject']), []).append(email)
+
+    stats = {'kept': 0, 'dropped_sender_excludes': 0, 'dropped_recipient_excludes': 0,
+             'dropped_subject_excludes': 0, 'dropped_includes_filter': 0}
+    refined = []
+    for thread in threads.values():
+        passed, reason = _thread_passes_refinement(thread, config)
+        if passed:
+            refined.extend(thread)
+            stats['kept'] += 1
+        else:
+            stats[f'dropped_{reason}'] += 1
+    return refined, stats
+
+# Pre-dedup refinement runs HERE, before the dedup pseudocode below.
+refined, refinement_stats = apply_refinement(fetched, config)
+```
+
+Refinement runs **before** dedup,所以被排除的 thread Message-ID **不會**進 `email_index.json` 或 `threads.json`。同一個 refinement config 在後續 run 仍會 drop 同一批 thread,不會 re-surface 為 new。下面的 dedup pseudocode 中的 `fetched` 應視為 refinement 之後的 `refined` corpus。
+
+#### Step 4.1: Dedup (既有行為,v2.17.0+ #49)
+
+對每封 refined 後的郵件,依當前 `dedup_strategy` 套用 dedup logic。**v2.17.0+ #49**:除了既有 `INDEX_FILE` 來源的 Message-ID set,**也必須消費 Step 2.1 累積的 `EXTENDED_DEDUP_IDS`**(從 sibling-archive symlink 抽出的 historical Message-ID)。
+
+```python
+# Build the canonical "known" Message-ID set per dedup_strategy
+existing_ids = set(load_json(INDEX_FILE)["emails"].keys()) if DEDUP_STRATEGY in ("index", "both") else set()
+extended_ids = set(EXTENDED_DEDUP_IDS)  # v2.17.0+ — populated by Step 2.1 if symlinked siblings exist
+known_ids = existing_ids | extended_ids
+
+# Apply strategy-specific predicate (note: extended_ids compose IN to existing predicate, not replace it)
+def is_new(email):
+    # Always: not in known Message-ID set
+    if email["message_id"] in known_ids:
+        return False
+    # Extra gate for last_archived / both: also require date > last_archived
+    if DEDUP_STRATEGY in ("last_archived", "both") and LAST_ARCHIVED:
+        if email["date"] <= LAST_ARCHIVED:
+            return False
+    return True
+
+new_emails = [e for e in fetched if is_new(e)]
+```
+
+對每封新郵件:
+1. 檢查其 Message-ID 是否已在 `known_ids`(`INDEX_FILE` ∪ `EXTENDED_DEDUP_IDS`)中
 2. 若已存在 → 跳過
-3. 若不存在 → 加入待歸檔清單
+3. 若不存在(且通過 strategy-specific date gate)→ 加入待歸檔清單
+
+> **Why `known_ids` 而非單純 `existing_ids`?** 對 transitioned-project workspace(see Step 2.1),`EXTENDED_DEDUP_IDS` 來自 read-only sibling archive(symlink target),這些 historical Message-ID 不在 `INDEX_FILE` 但代表「使用者已 archive 過的信」。若不消費 extended set,sibling archive 裡的舊信被 forward 回來會 silent re-archive。
+>
+> **`dedup_strategy=both` composition 細節**:extended IDs 透過 set union **加入** known set,而非取代。`both` strategy 的 date filter 仍照常 apply(對所有 emails,不論其 Message-ID 來源)。
+
+### Step 4.5: Confirmation — Phase 2 + 3: Search Preview + Operation Confirmation（v2.7.0+）
+
+**Skill ref**: `bulk-operation-preview`、`confirmation-protocol`
+
+如果 Step 4 過濾後的待歸檔清單 **≥ 5 封**(或 ≥ 1 封 destructive op),**不要直接進 Step 5 fetch + write**。先 preview:
+
+#### Phase 2: Search Preview
+
+按 thread 分組,跑 false-positive detection,展示給 user:
+
+```
+搜尋結果:{N} 封 emails (filter: {filter}, output: {output_dir})
+
+Filter:
+  Mail
+    -> filter(sender = '...' OR recipient = '...' OR subject contains '...')
+    -> sort(date desc)
+
+Threads 分布:
+  ✓ [{date}] {thread_key} ({M} msgs)
+       Participants: {p1, p2, p3}
+  ⚠ [{date}] {thread_key} ({M} msgs)  ← potential false positive
+       Reason: sender 不在 filter, 僅 subject 含關鍵字
+
+Corpus refinement (includes/excludes) — v2.20.0+, only shown when ≥1 refinement field non-empty:
+  Phase 2 preview surfaces refinement statistics: kept {kept} / dropped {dropped} threads.
+  Dropped by sender_excludes:    {N} threads     # category omitted if N=0
+  Dropped by recipient_excludes: {N} threads     # category omitted if N=0
+  Dropped by subject_excludes:   {N} threads     # category omitted if N=0
+  Filtered out by includes:      {N} threads     # category omitted if N=0
+  (When all six refinement fields are unset or empty, the entire refinement block is omitted from preview.)
+
+附件預估:{K} 個 ({total_size})
+```
+
+False-positive flagging 規則見 `rules/false-positive-detection.md`:
+- ✓ sender/recipient 直接匹配 filter
+- ⚠ email 在 thread 但不是 principal
+- ⚠⚠ 只 subject keyword match,sender 不符
+- ❓ metadata 不足以判斷
+
+#### Phase 3: Operation Confirmation
+
+```
+我將執行:
+  - 寫 {N} 個 markdown 檔到 {output_dir}/
+  - 下載 {K} 個 attachments ({total_size}),分流到 {data_dir}/ 和 {documents_dir}/
+  - 建立/更新 .email_index.json 和 .threads.json
+  - 不修改 Mail.app 內容(read-only operation)
+
+⚠ 此操作會建立約 {N+K+2} 個檔案
+確認執行嗎?
+
+選項:
+  (a) 確認,全部歸檔
+  (b) 排除 false positive,歸檔 {N - flagged} 封
+  (c) 修改 filter 重 search
+  (d) 取消
+```
+
+#### Phase 4: User response handling
+
+- 「對」/「a」/「OK」 → 進 Step 5 執行
+- 「b」/「排除 ⚠」 → 從待歸檔清單移除 flagged threads,重 confirm
+- 「c」/「修改 filter」 → 回 Step 1 重新 parse
+- 「d」/「取消」 → abort,不 write 任何檔案
+
+**Skip Phase 2+3**(可直接進 Step 5):
+- 待歸檔清單 < 5 封 且 沒有 false-positive flag
+- User 在 Phase 1 已說「直接做」
+- 配置 `.claude/emails.md` 含 `confirmation: skip`
+
+詳見 `skills/bulk-operation-preview/SKILL.md` 和 `rules/confirmation-triggers.md`。
 
 ### Step 5: 生成 Markdown
 
-對每封新郵件，建立 Markdown 檔案：
+對每封新郵件，建立 Markdown 檔案。
+
+> **⚠️ 再次提醒（來自 Step 3）**：在 Step 5 呼叫 `mcp__plugin_che-apple-mail-mcp_mail__get_email` 讀取內文時，同樣要用 **display name（email 地址）**作為 `account_name`，不可用 `list_accounts` 回的 `ews://` URL 或 UUID——否則 AppleScript error -1728。
+
+`search_emails` 回傳**不含**完整內容（僅 subject / sender / date / mailbox / account），因此對每封新郵件先呼叫：
+
+```
+mcp__plugin_che-apple-mail-mcp_mail__get_email(
+  id: "<id from search>",
+  mailbox: "<mailbox from search>",
+  account_name: "<display name / email 地址>",
+  format: "text"
+)
+```
+
+
+**檔名格式**（fixes #16）：`YYYY-MM-DD_{subject-hyphenated}.md`
+
+Subject → filename 轉換規則（依此順序執行）：
+1. **標點轉 `-`**：空白、冒號、斜線、反斜線、引號、問號、驚嘆號、中英標點（`,`、`。`、`、`、`:`、`；`、`(`、`)`、`[`、`]`、`?`、`!`）→ `-`
+2. **路徑字元移除**：`.` 開頭的檔名加底線前綴 `_`；`..` 保留為字面（標點轉換已把 `/` 變 `-`，不會路徑越界）
+3. **連續 dash 保留**：**不**合併連續 `-`（實務上 `Re:` + 空白 = `Re--`，符合 50 個歷史歸檔慣例）
+4. **截斷至 50 個字元**（extended grapheme clusters，即 Swift `String.count` 的語意；非 Unicode code points、非 UTF-8 byte。`é` / `🇹🇼` / 中日韓字各算 1）
+5. **首尾 `-` 去除**（截斷後若尾部是 `-`，再次去除；最終檔名不應以 `-` 結尾）
+6. **空字串 fallback**：若步驟 1–5 後為空（空白 subject 或全標點 subject），使用 `no-subject`
+7. **保留 Unicode**（中文、日文、韓文、emoji 維持原樣）
+
+同日同主旨多封郵件：
+- 第 1 封：**無後綴** → `2026-04-08_Re--Some-topic.md`
+- 第 2 封：`-1` → `2026-04-08_Re--Some-topic-1.md`
+- 第 3 封：`-2` → `2026-04-08_Re--Some-topic-2.md`
+- 第 N 封（N ≥ 2）：`-{N-1}`
+
+偵測後綴編號：用 `Glob` 列出 `YYYY-MM-DD_{subject}*.md`，取現有最大 `-N` +1（若無匹配則第 1 封無後綴；有 1 個匹配則 `-1`）。
+
+範例（來自 `tatsuma/communications/`）：
+
+| Subject | 順序 | 檔名 |
+|---------|------|------|
+| `Re: sabbatical year` | 第 1 封 | `2023-08-28_Re--sabbatical-year.md` |
+| `翻訳のお願い` | 第 1 封 | `2024-03-26_翻訳のお願い.md` |
+| `NTU PSY seminar 2024 final PPT` | 第 1 封 | `2024-04-04_NTU-PSY-seminar-2024-final-PPT.md` |
+| `Re: Poster at 九州心理学会` | 第 4 封 | `2024-11-20_Re--Poster-at-九州心理学会-3.md` |
+| `(空白 subject)` | 第 1 封 | `2026-04-08_no-subject.md` |
 
-**檔名格式**：`YYYYMMDD_brief_description.md`
+> **歷史相容 note**：`communications/` 有少量 `-a` / `-b` 字母後綴（如 `2024-07-14_...-a.md`）。新規不遷移舊檔，但新檔**一律用 `-1` `-2` `-3` 數字後綴**。若混用造成困擾，另開 follow-up issue。
+
+**內容格式**(v2.13.0+ 預設簡化,issue #17;v2.6.0+ 加入 YAML frontmatter):
+
+預設使用 **simple template**(對應 tatsuma 50 個既有檔案格式)。若 `${CONFIG_FILE}` 設 `enrichment: summary+todos`,改用下方 **enriched template** 加上 AI 摘要 + 待辦兩段。
+
+```bash
+# Step 1.6 階段已 parse;此處使用
+ENRICHMENT=$(awk '/^enrichment:[ \t]*/{sub(/^enrichment:[ \t]*/,"");print;exit}' "${CONFIG_FILE}" 2>/dev/null)
+ENRICHMENT="${ENRICHMENT:-none}"  # default: simple template (v2.13.0+)
+```
+
+#### Simple template (default, v2.13.0+):
+
+```markdown
+---
+message_id: "<9c7a43db76e94a64a51f85d04c3bf01b@ntu.edu.tw>"
+thread_key: "SE manuscript 10xx-2025"
+in_reply_to: "<eddba65d53754587aeee5d86ff631d2c@ntu.edu.tw>"
+date: 2026-01-28T08:35:34Z
+sender: yfhsu@ntu.edu.tw
+direction: received
+---
+
+Subject: <subject>
+From: <sender display name OR email>
+To: <recipient(s)>
+Date: YYYY-MM-DD HH:MM
+
+[完整 body]
+```
+
+Frontmatter 保留全部 6 欄位(thread index 重建仍依賴);header 改為 4 行純文字 `Subject/From/To/Date`,直接接 body,不再有元數據表 / 重點摘要 / 待辦事項三段。
+
+#### Enriched template (opt-in via `enrichment: summary+todos`):
+
+僅在 `${CONFIG_FILE}` 設定後觸發。Schema:
 
-**內容格式**：
 ```markdown
+---
+message_id: "<9c7a43db76e94a64a51f85d04c3bf01b@ntu.edu.tw>"
+thread_key: "SE manuscript 10xx-2025"
+in_reply_to: "<eddba65d53754587aeee5d86ff631d2c@ntu.edu.tw>"
+date: 2026-01-28T08:35:34Z
+sender: yfhsu@ntu.edu.tw
+direction: received
+---
+
 # [主題] - YYYY-MM-DD HH:MM
 
 ## 元數據
@@ -104,9 +834,213 @@ mcp__apple-mail__search_emails(
 *歸檔日期：YYYY-MM-DD*
 ```
 
-### Step 6: 更新索引
+**Frontmatter 欄位說明**：
+- `message_id`: 該封信的 RFC 5322 Message-ID（用引號包住，避免 YAML 解析角括號）
+- `thread_key`: 依下列規則計算的 bare subject：
+  1. 去掉前綴 `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:`（重複出現多次也全部去除）
+  2. 去除首尾空白
+  3. 保留原始大小寫和標點
+  4. 若結果為空，用 `no-subject`
+- `in_reply_to`: 若有，來自郵件的 `In-Reply-To` header；若 MCP 未暴露，從 body 的 quote intro 嘗試提取第一個 Message-ID，否則留空
+- `date`: ISO 8601 UTC 時間
+- `sender`: 寄件人 email 地址（display name 剝除）
+- `direction`: `received` 或 `sent`
+
+這些 frontmatter 欄位是 **canonical truth**——`.threads.json` 僅為衍生索引。
+
+### Step 5.5: 下載並分流附件
+
+對每封已歸檔的新郵件,**處理兩類**:explicit MIME attachments(由 `list_attachments` 回傳)+ inline `cid:` 圖片(由 HTML body 解析,v2.15.0+ 加,issue #45)。
+
+#### Step 5.5.0: Inline `cid:` images(v2.15.0+,resolves #45)
+
+`list_attachments` **不**回傳 inline `cid:` 圖片(`Content-Disposition: inline`)。先從 HTML body 抽出再 download:
+
+```bash
+# Parse HTML body for inline cid references + alt-attribute filenames
+# Pattern 1: <img src="cid:XXX" ... alt="filename.png">
+# Pattern 2: <span id="cid:XXX">&lt;filename.tex&gt;</span>  (Mail.app quote-time marker — 已由 Step 5.5 #6 cross-reference 處理,本 step 只處理 Pattern 1)
+
+INLINE_LIST=$(echo "$HTML_BODY" | python3 -c "
+import re, sys, html
+body = sys.stdin.read()
+# 抓 <img ... cid:XXX ... alt='...'>;tolerant 大小寫 + 屬性順序
+pattern = re.compile(
+    r'<img\b[^>]*?src=[\"\\']cid:([^\"\\']+)[\"\\'][^>]*?alt=[\"\\']([^\"\\']+)[\"\\']',
+    re.IGNORECASE | re.DOTALL
+)
+seen = set()
+for m in pattern.finditer(body):
+    cid, alt = m.group(1), html.unescape(m.group(2))
+    if cid not in seen:
+        seen.add(cid)
+        print(f'{cid}\t{alt}')
+")
+```
+
+對每個 `(cid, alt_filename)` pair:
+
+1. **目標路徑**:`{documents_dir}/{email_md_stem}/inline/{alt_filename}`
+   - 與 explicit attachments 同 stem 資料夾,但放 `inline/` 子目錄
+   - filename 保留原始 alt(空白 / emoji / 中日文都不改)
+   - 若 `documents_dir/{email_md_stem}/inline/` 不存在,先 `mkdir -p`
+
+2. **下載**:呼叫 `save_attachment(attachment_name=alt_filename, save_path=...)`
+   - **預期假設**:Apple Mail binary 接受 inline filename(尚未驗證,需要實測)
+   - 若 `save_attachment` 失敗 → log warning + 改用 cross-reference 註記(見 Step 5.5.5),不中斷歸檔
+   - 若 alt 屬性失敗解析(例如 charset 異常)→ fallback 用 `{cid}.png`(假設 PNG;典型 inline 都是)
+
+3. **去重**:同一 thread 不同信引用同一 cid(thread quote 累積) → 只在**首次**出現的信下載,後續信只在 markdown 引用既有檔(看路徑是否存在判斷)
+
+4. **計數**:記錄 `inline_count` 供 Step 7 報告 + Step 8 audit。
+
+#### Step 5.5.1: Explicit MIME attachments
+
+(原 Step 5.5 邏輯,不變)
+
+1. **列出附件**：呼叫 `mcp__plugin_che-apple-mail-mcp_mail__list_attachments`（或 `list_attachments_batch`）取得附件清單。若為空 → 跳到下一封(但 Step 5.5.0 inline 仍跑)。
+
+2. **分類每個附件**：用 Step 2 載入的分類規則判斷 `data` 或 `document`：
+
+   ```
+   classify(filename):
+     lowercase_name = filename.lowercased()
+     ext = filename 的副檔名（去掉 `.`）
+
+     # Tier 1: keyword match（先比 data_keywords）
+     for kw in data_keywords:
+       if lowercase_name contains kw → return "data"
+     for kw in document_keywords:
+       if lowercase_name contains kw → return "document"
+
+     # Tier 2: extension match
+     if ext in data_extensions → return "data"
+     if ext in document_extensions → return "document"
+
+     # Tier 3: fallback
+     return "document"
+   ```
+
+3. **決定目標路徑**：
+   - `"data"` → `{data_dir}/{original_filename}`
+   - `"document"` → `{documents_dir}/{email_md_stem}/{original_filename}`
+   
+   其中 `email_md_stem` 是該封信的 Markdown 檔名去掉 `.md`（例如 `2026-04-08_Re--Taxometric-Analysis`）。
+
+4. **下載**：呼叫 `mcp__plugin_che-apple-mail-mcp_mail__save_attachment` 將附件存到目標路徑。
+   - 檔名保留原始 bytes（空白、`&`、中日文、emoji 不改）
+   - 目標目錄若不存在，先 `mkdir -p`
+   - 若 `save_attachment` 失敗，log warning 繼續下一個（不中斷歸檔）
+
+5. **更新 Markdown**：在該封信的 Markdown 中插入 attachment 區塊。
+
+   **放置位置**：簽名（signature）之後、thread quote 之前。
+   Thread quote 的辨識 pattern：第一個匹配 `差出人:` / `寄件者:` / `From:` / `On .* wrote:` 的行。
+   若沒有 thread quote（原始信件，非回覆），attachment 區塊接在 body 最後。
+
+   **兩個獨立 section**(v2.15.0+,issue #45):若該信同時有 inline + explicit,先 `Inline images:` 後 `Attachments:`;只有一邊則只列該邊;空 thread 全省略。
+
+   **連結格式**：
+   ```markdown
+   Inline images:
+   - ![原始檔名](相對路徑URL編碼)
+
+   Attachments:
+   - [原始檔名](相對路徑URL編碼) (大小 KB)
+   ```
+
+   `Inline images:` 用 `![]()`(image syntax,markdown viewer 直接渲染),`Attachments:` 用 `[]()`(link syntax,點擊下載)。
+
+   URL 編碼規則（僅用於 Markdown link URL，display text 保留原始）：
+   - 空白 → `%20`
+   - `&` → `%26`
+   - 其餘（含中日文）→ 保留原字元
+
+   範例:
+   ```markdown
+   Inline images:
+   - ![CleanShot 2026-05-07 at 15.44.58@2x.png](attachments/2026-05-07_Re--Solution---Iverson-similarity/inline/CleanShot%202026-05-07%20at%2015.44.58%402x.png)
+
+   Attachments:
+   - [Figures & Tables20260408.docx](attachments/2026-04-08_Re--Taxometric-Analysis/Figures%20%26%20Tables20260408.docx) (93 KB)
+   - [raw_indicators.csv](../../data/raw/raw_indicators.csv) (12 KB)
+   ```
+
+6. **回覆信無附件但引用原信附件時**：若 `list_attachments` 為空，但 body 中出現 `<filename.ext>` 形式的引用標記（Mail.app 的 quote-time marker），插入 cross-reference：
+
+   ```markdown
+   Attachments:
+   (Attachments on the original email from {original_sender} — see `{original_stem}.md`)
+   ```
+
+   若無法推斷原始 stem（原信未歸檔），改為：
+   ```markdown
+   (Attachments referenced in thread quote — original not yet archived)
+   ```
+
+7. **累計計數**：記錄 `data_count`、`document_count`、`inline_count`(v2.15.0+) 供 Step 7 報告用。
+
+#### Step 5.5.5: Inline cid: download fallback (v2.15.0+, issue #45)
+
+若 Step 5.5.0 的 `save_attachment(inline_filename)` 失敗(binary 不支援 inline name 或 inline cid: 不在 binary 的 attachment list),**不**完全 skip — 改寫 cross-reference 註記:
+
+```markdown
+Inline images:
+- (cid:331ECED2 — CleanShot 2026-05-07 at 15.44.58@2x.png — binary 無法 download by name;見 Mail.app 原始信)
+```
+
+User 看到註記知道 inline 圖存在但需手動 export from Mail.app。Filed 上游 issue 在 PsychQuant/che-apple-mail-mcp 跟進 binary-side support。
 
-將新歸檔的郵件加入索引：
+### Step 5.7: 維護 `threads.json`（v2.6.0+,路徑 v2.8.0+ 改 `${THREADS_FILE}`）
+
+每封新歸檔的 md 寫出後,同步更新 `${THREADS_FILE}` (`.claude/.mail/state/archives/${SLUG}/threads.json`):
+
+**格式**：
+
+```json
+{
+  "version": "1.0",
+  "last_updated": "2026-04-22T15:01:09Z",
+  "threads": {
+    "SE manuscript 10xx-2025": {
+      "messages": [
+        {
+          "message_id": "<7F43E052-EA1B-432D-AF0C-64F0CDBD8B32@ntu.edu.tw>",
+          "file": "2026-01-28_Re--SE-manuscript-10xx-2025.md",
+          "date": "2026-01-28T08:00:24Z",
+          "sender": "d06227105@ntu.edu.tw",
+          "in_reply_to": "<eddba65d53754587aeee5d86ff631d2c@ntu.edu.tw>"
+        }
+      ],
+      "participants": ["yfhsu@ntu.edu.tw", "d06227105@ntu.edu.tw", "d11227103@ntu.edu.tw"],
+      "first_message": "2025-12-19T06:19:30Z",
+      "last_message": "2026-01-28T08:00:24Z",
+      "message_count": 1
+    }
+  }
+}
+```
+
+**更新演算法**（對每封新歸檔的信）：
+
+1. 從 md frontmatter 讀 `thread_key`
+2. 若 `.threads.json` 裡沒有此 thread_key，建立新 entry：
+   ```
+   {"messages": [], "participants": [], "first_message": null, "last_message": null, "message_count": 0}
+   ```
+3. 在 `messages` 陣列**尾端** append 新 message（保持時間序；若日期早於 last_message，可插入正確位置，但一般 append 即可）
+4. 更新 `participants` 集合（加入 sender + to + cc 的 email，去重）
+5. 更新 `first_message` = `min(first_message, new.date)`，`last_message` = `max(last_message, new.date)`
+6. `message_count += 1`
+7. 更新頂層 `last_updated` 為目前時間
+
+**Append-only 原則**：此索引只做新增，不修改、不刪除既有 entry。若 thread 需要分割或合併，用 `/archive-mail-rebuild-threads` 重建。
+
+**同 thread 不同時段的處理**：若 bare subject 相同但兩組訊息時間相差 > 90 天，**仍歸在同一 thread**（因為我們尊重使用者的 subject 選擇）。若要拆分，使用者需手動改 md frontmatter 的 `thread_key`（例如加 `-2026` 後綴），然後跑 rebuild。
+
+### Step 6: 更新 Message-ID 索引
+
+將新歸檔的郵件加入 `${INDEX_FILE}` (`.claude/.mail/state/archives/${SLUG}/email_index.json`):
 
 ```json
 {
@@ -114,14 +1048,17 @@ mcp__apple-mail__search_emails(
   "last_updated": "YYYY-MM-DD",
   "emails": {
     "message-id@example.com": {
-      "file": "20260113_topic.md",
+      "file": "2026-01-13_Meeting-notes.md",
       "date": "2026-01-13 14:30",
-      "subject": "郵件主旨"
+      "subject": "郵件主旨",
+      "thread_key": "Meeting notes"
     }
   }
 }
 ```
 
+v2.6.0+ 在每個 email entry 多記一個 `thread_key`，方便反向查詢。
+
 ### Step 7: 輸出報告
 
 ```
@@ -129,21 +1066,194 @@ mcp__apple-mail__search_emails(
 Archive Mail 完成
 ═══════════════════════════════════════════
 
-過濾條件: d06227105@ntu.edu.tw
+過濾條件: user@example.com
 輸出目錄: communication/emails
 
 新歸檔: 5 封
-  - 20260113_meeting_request.md
-  - 20260112_report_feedback.md
+  - 2026-01-13_Meeting-request.md
+  - 2026-01-12_Report-feedback.md
   - ...
 
 跳過（已歸檔）: 12 封
 
+Thread 索引: 2 new threads, 3 existing threads updated
+  - "Meeting notes": 3 new messages (total 5)
+  - "Report feedback": 2 new messages (total 2, new thread)
+
+附件: 15 個下載
+  → 4 to data/raw
+  → 11 to correspondence/attachments
+  → 2 inline images to correspondence/attachments/{stem}/inline/  (v2.15.0+, #45)
+
 ═══════════════════════════════════════════
 ```
 
+若無附件：`附件: 0 個下載`(不顯示分類明細)。
+若無 inline images,省略該行(v2.15.0+ 新加,只在有 inline 時顯示)。
+Thread 索引行（v2.6.0+）：永遠顯示，即使沒新 thread。
+
+### Step 8: 覆蓋率稽核（Coverage Audit）（v2.4.0+）
+
+歸檔主流程結束後，自動執行覆蓋率稽核：
+
+**8a. 附件完整性檢查**：
+
+對所有新歸檔的郵件,**分兩部分檢查**(v2.15.0+, #45):
+
+**8a.1 Explicit attachments**:呼叫 `list_attachments` 取得 explicit MIME attachment 數量,比對磁碟上對應目錄的實際檔案數。
+
+- 一致 → pass
+- 不一致 → 發出 warning：`⚠️ {email_stem}: {差異} explicit attachment missing (expected {報告數}, found {磁碟數})`
+
+**8a.2 Inline cid: images** (v2.15.0+):從 HTML body 解析 inline cid: 引用數量,比對 `{stem}/inline/` 目錄實際檔案數。
+
+- 一致 → pass
+- 不一致(已 cross-reference 註記取代下載)→ 發出 warning:`⚠️ {email_stem}: {N} inline images cross-referenced (binary download unsupported); see Mail.app for visual content`
+- 完全 miss(連 cross-reference 都沒)→ `⚠️ {email_stem}: {N} inline images parsed from body but not handled (skill bug, file follow-up)`
+
+**8b. Thread 完整性檢查**：
+
+對歸檔中每個唯一的 bare subject：
+1. 用 bare subject 搜尋 `search_emails(field: "subject", query: bare_subject)`，取得 total count
+2. 比對已歸檔的 count
+3. 若 `archived < total` → 發出 warning：`⚠️ Thread "{subject}": {差額} potential missing siblings (archived {已歸檔}/{total})`
+
+**8c. 稽核報告**：
+
+```
+Archive Coverage Audit
+═══════════════════════════════════════════
+附件覆蓋: explicit 15/15 + inline 2/3 (1 cross-ref'd) (94%)
+Thread 覆蓋: 3 threads, 2 complete, 1 with gaps
+
+搜尋結果: 37 by sender + 12 by subject + 9 by thread expansion = 58 unique
+
+Issues:
+  ⚠️ 2026-04-08_Re--Taxometric: 1 attachment missing
+  ⚠️ 2026-05-07_Re--Solution: 1 inline image cross-referenced (binary unsupported)
+  ⚠️ Thread "indicator selection": 2 potential missing siblings
+
+建議: 在 .claude/.mail/config.md 加入 subject_keywords 擴大搜尋範圍
+═══════════════════════════════════════════
+```
+
+若所有檢查通過：
+```
+Archive Coverage Audit
+═══════════════════════════════════════════
+附件覆蓋: explicit 15/15 + inline 3/3 (100%) ✓
+Thread 覆蓋: 3 threads, 3 complete ✓
+═══════════════════════════════════════════
+```
+
+若無 inline,簡化:`附件覆蓋: 15/15 (100%) ✓`(同 v2.14.0 ↓ 行為)。
+
 ## 注意事項
 
 - 使用 apple-mail MCP，需確保 MCP server 已連接
 - Message-ID 用於去重，確保不會重複歸檔
 - 寄出的郵件不產生「重點摘要」和「待辦事項」
+- **附件自動下載**（v2.3.0+）：每封歸檔信件的附件會自動下載到分類目錄。研究資料檔（csv / sav / xlsx 等）放到 `data/raw/`；文件附件（pdf / docx 等）放到 `correspondence/attachments/{email_stem}/`。可透過 `.claude/emails.md` 的 `attachment_routing` 區塊自訂規則。
+- **搜尋擴展 + 覆蓋率稽核**（v2.4.0+）：除了 sender 搜尋，可設定 `subject_keywords` 補抓 internal threads。每次歸檔後自動跑 Coverage Audit 檢查附件完整性和 thread 覆蓋率。
+- **Thread 索引**（v2.6.0+）：歸檔時自動維護 `.threads.json`，記錄每個 thread 包含哪些 messages、參與者、時間範圍。每封 md 的 YAML frontmatter 也帶有 `thread_key` / `in_reply_to`，為 canonical truth。搭配 `/archive-mail-view <thread_key>` 生成聚合 thread 視圖，`/archive-mail-rebuild-threads` 從 md 重建索引。
+
+## 附件分類設定範例
+
+在 `.claude/emails.md` front matter 加入 `attachment_routing` 覆寫預設規則。**注意：partial override 取代所有預設**——省略的欄位會變成空列表，不會自動使用內建預設。
+
+完整預設值（供 copy-paste）：
+
+```yaml
+---
+filters:
+  - tatsuma
+attachment_routing:
+  data_extensions: [csv, tsv, sav, dta, parquet, feather, xlsx, sas7bdat]
+  document_extensions: [pdf, docx, doc, txt, md, rtf, odt]
+  data_keywords: [data, raw, indicators, codebook, dataset]
+  document_keywords: [Submission, Figures, Tables, Manuscript, draft, Revision, v1, v2, v3]
+  data_dir: data/raw
+  documents_dir: correspondence/attachments
+---
+```
+
+只需列出想改的部分（但理解：列出即取代整組預設）：
+
+```yaml
+---
+attachment_routing:
+  data_extensions: [csv, sav]            # 只認這兩種為 data
+  data_keywords: [raw, indicators]       # 窄化 keyword
+  data_dir: research/raw-data            # 自訂 data 目標路徑
+  documents_dir: correspondence/attachments  # 保留預設
+---
+```
+
+## 搜尋擴展設定範例（v2.4.0+）
+
+```yaml
+---
+filters:
+  - tatsuma
+subject_keywords:                        # 用 subject 關鍵字補抓 internal threads
+  - taxometric
+  - SSQ
+  - "attachment security"
+participant_aliases:                     # 成員別名（audit 報告顯示用）
+  "b08801008@ntu.edu.tw": "Pei-Chi"
+  "kllay@ntu.edu.tw": "Lay"
+attachment_routing:
+  data_dir: data/raw
+  documents_dir: correspondence/attachments
+---
+```
+
+設定 `subject_keywords` 後，Step 3 會自動做三輪搜尋（sender + subject keyword + thread-subject expansion）並去重。Step 8 Coverage Audit 會報告覆蓋率。
+
+## Corpus refinement 設定範例(v2.20.0+, two-layer model)
+
+Two-layer model — `filters` (search-time) vs `*_includes` (post-fetch restriction) 的具體用法:`filters` 把寬網撒到 Mail.app(Step 3 MCP query),refinement 在 fetch 完之後縮窄到只關心的 sender / recipient / subject(Step 4.0 thread-level)。
+
+**範例 1**:對中研院 email 設 OR-search(三個 email 任一命中即拉),但要排除誤命中的補習班信件(#84)和訂閱噪音:
+
+```yaml
+filters:                              # Layer 1 search-time corpus 定義
+  - che830621@as.edu.tw
+  - che830621@gate.sinica.edu.tw
+  - che830621@stat.sinica.edu.tw
+
+recipient_excludes:                   # Layer 2 post-fetch: drop 寄到補習班的信(整 thread)
+  - EDUCATION5361@yahoo.com.tw
+
+subject_excludes:                     # Layer 2 post-fetch: drop 訂閱確認 noise
+  - 訂閱確認信
+  - 取得官方
+```
+
+**範例 2**:`filters` 撒寬,`sender_includes` 在 fetch 後再縮窄到某域名(#84 use case for narrowing collaborator scope):
+
+```yaml
+filters:
+  - yfhsu                             # 任何提到 yfhsu 的信都先拉進來
+sender_includes:                      # ...但 fetch 後只保留 sender 含 @gate.sinica 的
+  - "@gate.sinica.edu.tw"
+```
+
+**範例 3**:workspace 按 topic scoping(#76 use case),只歸檔 subject 命中關鍵字的 thread:
+
+```yaml
+filters:
+  - yfhsu
+subject_includes:                     # whitelist: 只保留 bare subject 含這些字串的 thread
+  - affine
+  - Iverson
+  - similarity
+```
+
+關鍵語意(完整契約見 spec `openspec/specs/archive-mail-corpus-refinement/spec.md`):
+
+- 6 個欄位全為 opt-in。unset 或空 list 都 = no refinement on that axis(100% backward compat)
+- **Case-insensitive substring match**:sender / recipient 比對 bare email(strip display name);subject 比對 bare subject(strip 前綴 `Re:` / `RE:` / `Fwd:` / `FW:` / `转发:` / `轉寄:`)
+- **同軸 includes + excludes 同設**:excludes win(blacklist 優先 — `sender_includes` 命中但 `sender_excludes` 也命中 → drop)
+- **Per-thread coherence**:thread 內任一 message 命中 → 整 thread keep / drop。Trap:thread 中某 message 不小心 CC 到被 exclude 的地址會拖整個 thread 下水。
+- **Refinement 在 dedup 之前**:被排除的 thread Message-ID 不會進 `email_index.json`,後續 run 仍會 drop 同一批 thread,不會 re-surface 為 new。
diff --git a/plugins/che-apple-mail-mcp/hooks/session-start.sh b/plugins/che-apple-mail-mcp/hooks/session-start.sh
new file mode 100755
index 00000000..a829ba95
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/hooks/session-start.sh
@@ -0,0 +1,75 @@
+#!/bin/bash
+# che-apple-mail-mcp SessionStart hook — detect stale MCP binary, kill PID for respawn.
+#
+# Resolves PsychQuant/che-apple-mail-mcp#76: wrapper version-check only fires at
+# spawn; in-memory binary never re-checks plugin.json. This hook compares wrapper-
+# written runtime state against current plugin.json version; if they differ and
+# the recorded PID is alive, SIGTERM (then SIGKILL after grace) so Claude Code
+# respawns MCP via wrapper, picking up the new binary.
+#
+# Failure mode: every dependency missing or unexpected → silent exit 0. Worst
+# case is no-op (current pre-fix behavior); never break session start.
+
+set -u
+
+# Dependencies — graceful skip if missing.
+command -v jq >/dev/null 2>&1 || exit 0
+command -v ps >/dev/null 2>&1 || exit 0
+
+BINARY_NAME="CheAppleMailMCP"
+INSTALL_DIR="$HOME/bin"
+RUNTIME_FILE="$INSTALL_DIR/.${BINARY_NAME}.runtime.json"
+
+# Locate plugin root via hook's own path (PLUGIN_ROOT/hooks/session-start.sh).
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Both files required.
+[ -f "$RUNTIME_FILE" ] || exit 0
+[ -f "$PLUGIN_JSON" ] || exit 0
+
+# Read versions. Runtime state records BINARY tag (per #77 fix to wrapper).
+# Plugin.json has two fields since #77: .version (plugin shell) and
+# .binary_version (binary tag). Hook must compare against .binary_version
+# when present, falling back to .version for plugins not yet migrated.
+# Without this fallback chain, the hook compares runtime binary tag against
+# plugin shell version and triggers spurious kill every session (see #73).
+RUNTIME_VERSION=$(jq -r '.version_at_spawn // ""' "$RUNTIME_FILE" 2>/dev/null)
+PLUGIN_VERSION=$(jq -r '.binary_version // .version // ""' "$PLUGIN_JSON" 2>/dev/null)
+
+[ -z "$RUNTIME_VERSION" ] && exit 0
+[ -z "$PLUGIN_VERSION" ] && exit 0
+
+# Match → no-op.
+[ "$RUNTIME_VERSION" = "$PLUGIN_VERSION" ] && exit 0
+
+# Mismatch — check if recorded PID is still alive.
+PID=$(jq -r '.pid // empty' "$RUNTIME_FILE" 2>/dev/null)
+[ -z "$PID" ] && exit 0
+
+# `ps -p $PID -o pid=` returns empty if PID is dead. Also guard against
+# matching the wrong process (e.g. PID reused by something else): require
+# the running process command to contain BINARY_NAME.
+ps -p "$PID" -o pid= >/dev/null 2>&1 || exit 0
+PID_COMM=$(ps -p "$PID" -o command= 2>/dev/null)
+case "$PID_COMM" in
+    *"$BINARY_NAME"*) ;;
+    *) exit 0 ;;
+esac
+
+echo "⚠ Killing stale ${BINARY_NAME} PID ${PID} (was v${RUNTIME_VERSION}, plugin now v${PLUGIN_VERSION}) — Claude Code will respawn with new binary." >&2
+
+# SIGTERM, give 5s for graceful shutdown (SQLite WAL flush, etc).
+kill -TERM "$PID" 2>/dev/null || true
+for _ in 1 2 3 4 5; do
+    ps -p "$PID" -o pid= >/dev/null 2>&1 || break
+    sleep 1
+done
+
+# Still alive → SIGKILL.
+if ps -p "$PID" -o pid= >/dev/null 2>&1; then
+    echo "⚠ ${BINARY_NAME} PID ${PID} did not exit on SIGTERM, sending SIGKILL." >&2
+    kill -KILL "$PID" 2>/dev/null || true
+fi
+
+exit 0
diff --git a/plugins/che-apple-mail-mcp/rules/confirmation-triggers.md b/plugins/che-apple-mail-mcp/rules/confirmation-triggers.md
new file mode 100644
index 00000000..42922d03
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/rules/confirmation-triggers.md
@@ -0,0 +1,92 @@
+# Confirmation Triggers — 何時要 confirm,何時可 skip
+
+決定何時 invoke `confirmation-protocol` skill 的判斷規則。
+
+## 必須 confirm(🔴)
+
+### Filter 模糊
+- Sender / recipient 用中文名、暱稱、角色稱呼(「陳老師」、「老闆」、「指導教授」)
+- 時間用相對詞(「最近」、「上週」、「之前」)
+- Scope 用通用詞(「全部」、「所有」、「整個」)
+
+### Destructive operation
+- `delete_email`、`delete_emails_batch`
+- 任何修改 Mail.app 狀態的 batch 操作(`mark_as_junk_batch`、`move_emails_batch`)
+- Empty Trash / Junk
+- `delete_rule`、`delete_mailbox`、`delete_signature`
+
+### Compose / Send
+- `compose_email`(寄出新信)
+- `reply_email`、`forward_email`、`redirect_email`
+- 任何 outbound side effect
+
+### Bulk(影響 ≥ 5 emails 的任何操作)
+- `archive-mail` 預期會歸檔 ≥ 5 封
+- `mark_read` 一次標 ≥ 5 封
+- `move_email` 批次移動 ≥ 5 封
+
+## 建議 confirm(🟡)
+
+### 影響 1-4 emails 的 destructive 操作
+- 單一 email 的 `delete_email` (建議 confirm,但 user 可以設定 skip)
+- 單一 email 的 `mark_as_junk` (建議 confirm)
+
+### Filter 看起來精確但範圍很大
+- Sender 是明確 email 但 search 結果 > 50 封 → confirm「真的要全部處理嗎?」
+
+## 可以 skip confirm(🟢)
+
+### Read-only 操作
+- `search_emails`、`list_emails`、`list_mailboxes`、`list_accounts`
+- `get_email`、`list_attachments`、`get_email_metadata`
+- 任何 query 不修改 state 的 op
+
+### 明確指定的 single op
+- 給定 Message-ID 的 `mark_read`(單封)
+- 給定 Message-ID 的 `unflag_email`(單封)
+- 用戶明確說「直接執行,不要問我」
+
+### Idempotent 操作
+- 重複跑不會造成額外 side effect(例如已歸檔的信再 archive 會 skip)
+
+## 判斷流程
+
+```
+operation request
+  ↓
+是否有模糊 filter?
+  ├─ Yes → confirmation-protocol Phase 1 (disambiguation)
+  └─ No → continue
+
+  ↓
+是否 destructive 或 compose?
+  ├─ Yes → confirmation-protocol Phase 3 (operation confirmation)
+  └─ No → continue
+
+  ↓
+影響 emails 數 ≥ 5?
+  ├─ Yes → bulk-operation-preview (Phase 2 + 3)
+  └─ No → 直接執行
+```
+
+## User override
+
+User 可以用以下說法 skip confirmation:
+- 「直接做」、「不要問」、「OK 直接執行」(僅該次有效)
+- `--no-confirm` 之類的 flag(if command supports)
+
+但即使 user 說 skip,仍然應該:
+- Destructive op 仍展示 op summary(但不要等 confirm)
+- Compose 仍 show 信件草稿(但 send 後再說)
+
+## 例外情況
+
+- **Reset / cleanup 工具**:例如「清空 Trash」這種 user 明確意圖 destructive 的 op,可以信任 user(但仍 show 影響範圍)
+- **Test mode**:如果 plugin 跑在 test mode,可以 skip 所有 confirmation(by env flag)
+
+## 相關
+
+- `skills/confirmation-protocol/SKILL.md` — 主 skill workflow
+- `skills/email-search-disambiguation/SKILL.md` — Phase 1
+- `skills/bulk-operation-preview/SKILL.md` — Phase 2+3
+- `rules/false-positive-detection.md` — Search 結果 false positive 標示
diff --git a/plugins/che-apple-mail-mcp/rules/false-positive-detection.md b/plugins/che-apple-mail-mcp/rules/false-positive-detection.md
new file mode 100644
index 00000000..1cf83b83
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/rules/false-positive-detection.md
@@ -0,0 +1,129 @@
+# False-Positive Detection — Search 結果 review 規則
+
+Search 結果可能含有不符合 user 真正意圖的 emails(false positives),例如 subject keyword 撞名。Bulk operation preview 階段要 flag 這些並讓 user 排除。
+
+## Enforcement(v2.9.0+ 鐵律)
+
+False-positive scan **不是 optional best practice**,是 archive-mail Step 0 Bootstrap 必建的 task `filter_and_scan_false_positives`。任何 search 結果在進 Phase 2 preview 前都要跑這份 rule 的 `flag_thread()` 算法,並在 task description 裡記下「✓ N / ⚠ M / ⚠⚠ K / ❓ J」分布。沒跑就把這個 task 標 completed = 違規。
+
+實際後果(2026-05-01 incident):filter「陳老師 + 林助理 + subject 含『陳君厚』」搜尋出 19 封,265250 是 sibling activity (subject「應徵資料科學統計合作社…」,寄給 scchen 不是 cchen),false-positive scan 沒跑,事後才發現,又走一輪 rm + index 修復。如果 scan 是 enforced task,Phase 2 preview 會 ⚠⚠ flag 這封並讓 user 排除。
+
+## 為什麼需要
+
+`mcp__plugin_che-apple-mail-mcp_mail__search_emails` 用 SQLite full-text 搜尋,query 可能 match 到:
+- Subject 含 query 但實際對象不同(例:filter「陳君厚」match 到 subject「應徵資料科學統計合作社博士後研究員(鄭澈,...)」中的「陳」)
+- Recipient 是 list 之一但 thread 主軸不是該 contact
+- 歷史 thread 標題已改但 message 還是 match
+
+實際案例(2026-05-01 archive 陳老師):filter 是 cchen + 林助理 + 「陳君厚」subject,結果 265250 (寄給 scchen)被 match 到,因為 subject「應徵資料科學統計合作社博士後研究員(鄭澈,**臺灣大學心理學博士**)」沒有「陳君厚」也沒有 cchen,但 sender 是用戶自己,而 subject 含「陳」字導致 fuzzy match。
+
+## 判斷規則
+
+### 對每個 thread 跑 false-positive check
+
+```python
+def flag_thread(thread, filter_emails, filter_keywords):
+    """
+    filter_emails: list of email addresses in the search filter
+    filter_keywords: list of keywords (subject search terms)
+    """
+    participants = set(thread.participants)
+    matches_any_email = bool(participants & set(filter_emails))
+    
+    sender_match = any(
+        any(fe in m.sender for fe in filter_emails)
+        for m in thread.messages
+    )
+    
+    subject_match_only = (
+        not matches_any_email and
+        not sender_match and
+        any(kw in thread.subject for kw in filter_keywords)
+    )
+    
+    if matches_any_email and sender_match:
+        return "✓"  # confident match
+    elif matches_any_email and not sender_match:
+        return "⚠"  # email in CC list but not principal sender
+    elif subject_match_only:
+        return "⚠⚠"  # high-probability false positive
+    else:
+        return "❓"  # unclear, ask user
+```
+
+### Flag levels
+
+| Flag | 含義 | 預設行動 |
+|------|------|---------|
+| ✓ | sender/recipient 直接匹配 filter | 包含 |
+| ⚠ | email 在 thread 但不是 principal sender | preview 時提醒,預設包含 |
+| ⚠⚠ | 只 subject keyword match,sender 不符 | preview 時 flag,預設**排除**,問 user 確認 |
+| ❓ | metadata 不足以判斷 | preview 時提醒,問 user |
+
+## False-positive 範例 patterns
+
+### Pattern 1: Sibling activity sharing keyword
+
+User 同時做幾件事(例如同時應徵多個職位),subject 含類似關鍵字但對象不同。
+
+實際案例:
+- Filter: cchen / coco891017 / 「陳君厚」
+- False positive: 寄給 scchen 的「應徵資料科學統計合作社」
+- Why: subject 含「應徵」但 recipient 完全不在 filter
+
+**Detection**: sender ∉ filter_emails AND principal recipient ∉ filter_emails
+
+### Pattern 2: CC pollution
+
+某 email 把 filter contact CC 但 thread 主題完全不同。
+
+**Detection**: filter_email 只在 CC list,不在 sender 也不在 To
+
+### Pattern 3: Subject collision
+
+不同的 conversation 用了類似 subject(例如「會議通知」)但 thread participants 完全不同。
+
+**Detection**: thread participants ∩ filter_emails == ∅
+
+## Preview 格式
+
+在 `bulk-operation-preview` skill 的 thread breakdown 加 reason:
+
+```
+⚠ [2026-03-15] 應徵資料科學統計合作社博士後研究員(鄭澈,...) (1 msg)
+    Participants: che830621, scchen
+    Reason: sender (scchen@stat.sinica.edu.tw) 不在 filter
+            recipient 也不在 filter
+            僅 subject 中的「陳」字 match filter「陳君厚」
+            高機率為 sibling 應徵活動,非陳君厚老師相關
+    建議:排除
+```
+
+## False-positive override
+
+User 看到 flag 後可以:
+- **接受預設**(排除 ⚠⚠ 標記的)
+- **保留**(說「不,這封也要,理由是...」)
+- **修改 filter** narrow 範圍重 search
+
+## 改善 search 的策略
+
+長期看,false positive 多表示 filter 太寬。建議在 `.claude/emails.md` 加:
+
+```yaml
+# 只把這些 email 視為 chchen 相關
+participants:
+  primary:
+    - cchen@stat.sinica.edu.tw
+    - cchen@webmail.stat.sinica.edu.tw
+  assistants:
+    - coco891017@webmail.stat.sinica.edu.tw
+    - coco891017@stat.sinica.edu.tw
+    - yijulee@webmail.stat.sinica.edu.tw
+    - yijulee@stat.sinica.edu.tw
+
+# Subject keywords 不可作為唯一 match 條件
+subject_keywords_strict: true  # 必須同時符合 sender/recipient 才算 match
+```
+
+這樣 search 會嚴格 require 至少一個 participant match,subject keyword 只是 supplementary。
diff --git a/plugins/che-apple-mail-mcp/skills/bulk-operation-preview/SKILL.md b/plugins/che-apple-mail-mcp/skills/bulk-operation-preview/SKILL.md
new file mode 100644
index 00000000..d0df1128
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/skills/bulk-operation-preview/SKILL.md
@@ -0,0 +1,154 @@
+---
+name: bulk-operation-preview
+description: Show structured preview of bulk email operations (5+ emails) before execute. Group by thread, flag false-positive candidates, count side-effect scope (files written, attachments downloaded, mailboxes touched). Use after email-search-disambiguation finishes Phase 1, as Phase 2 of the confirmation protocol.
+---
+
+# Bulk Operation Preview
+
+當 search 結果 ≥ 5 emails 或操作會 touch 多個 emails 時,先 show 結構化 preview 讓 user 過目。
+
+## Preview Format
+
+### 基本結構
+
+```
+搜尋結果:{N} 封 emails (by {filter_summary})
+
+Threads 分布(按時間排序):
+  ✓ [{date}] {thread_key} ({M} msgs)
+  ✓ [{date}] {thread_key} ({M} msgs)
+  ⚠ [{date}] {thread_key} ({M} msgs)  ← potential false positive,reason: {reason}
+  ...
+
+附件:{K} 個檔案 ({total_size} 預估)
+  - {file_1.pdf} ({size_1})
+  - ...
+
+⚠ {flag_count} 個 threads 標示為 potential false positive
+要排除嗎?確認操作範圍?
+```
+
+### Pipeline-style filter summary
+
+借 nsql pipeline format:
+
+```
+Mail
+  -> filter(sender = 'cchen@stat.sinica.edu.tw' 
+            OR sender = 'coco891017@webmail.stat.sinica.edu.tw'
+            OR subject contains '陳君厚')
+  -> group(thread_key)
+  -> sort(first_message asc)
+```
+
+讓 user 一眼看出 search 邏輯。
+
+## False-positive flagging(整合 false-positive-detection.md)
+
+每 thread 跑 false-positive detection:
+
+| Flag | 條件 |
+|------|------|
+| ✓ | sender/recipient 直接匹配 filter 中的 email 地址 |
+| ⚠ | sender 不在 filter 但 subject 含 filter 關鍵字(可能 false positive) |
+| ⚠⚠ | sender 完全不在 filter 且 subject 也只含通用詞(高機率 false positive) |
+| ❓ | metadata 不足以判斷(少於 1 封 email 在 thread) |
+
+詳見 `rules/false-positive-detection.md`。
+
+## Side-effect scope counting
+
+在 Phase 3 (Operation Confirmation) 之前,count operation 影響的 scope:
+
+```
+我將執行:
+  - 寫入 {N} 個 markdown 檔到 {output_dir}/
+  - 下載 {K} 個 attachments ({total_size}) 分流到:
+      → {data_dir}/ ({data_count} 個資料檔)
+      → {documents_dir}/ ({doc_count} 個文件附件)
+  - 建立/更新 {index_count} 個 index files
+  - {modify_mailapp ? "修改 Mail.app 標記/移動" : "不修改 Mail.app 內容(read-only)"}
+
+預估磁碟用量:{disk_estimate}
+預估執行時間:{time_estimate}
+
+⚠ 此操作{reversible ? "可以 undo(刪除生成的檔案)" : "無法 undo"}
+確認執行嗎?
+```
+
+## Thread breakdown 細節
+
+按 first message date 排序,format:
+
+```
+[YYYY-MM-DD] {thread_key} ({msg_count} msgs)
+   Participants: {top 3 participants}
+   First: {first_sender}, Last: {last_sender}
+```
+
+對 chchen 案例:
+
+```
+[2026-04-29] 新聘博士後研究學者繳交資料 (2 msgs)
+   Participants: yijulee, che830621, cchen, coco891017
+   First: yijulee, Last: che830621
+
+[2026-04-19] 後續面試報告時間請教 (5 msgs)
+   Participants: che830621, cchen, coco891017, yijulee, tsoping
+   First: che830621, Last: che830621
+
+⚠ [2026-03-15] 應徵資料科學統計合作社... (1 msg)
+   Participants: che830621, scchen
+   First/Last: che830621
+   ⚠ Reason: sender (scchen) 不在 filter pattern,subject 含「陳」但實際對象是另一個 unit
+```
+
+## 與 confirmation-protocol 的關係
+
+`bulk-operation-preview` 是 confirmation-protocol 的 **Phase 2 + Phase 3**。
+
+Workflow:
+- Phase 1 (disambiguation, by `email-search-disambiguation` skill) → 確認 filter
+- **Phase 2 (search preview, by THIS skill)** → 展示找到的 emails + flag false positives
+- **Phase 3 (operation confirmation, by THIS skill)** → 展示 side-effect scope
+- Phase 4 (execute) → 進入主 command 的執行階段
+
+## 範例(完整 preview)
+
+```
+搜尋結果:19 封 emails
+
+Filter:
+  Mail
+    -> filter(sender contains 'cchen@stat.sinica.edu.tw'
+              OR sender contains 'coco891017'
+              OR subject contains '陳君厚')
+    -> sort(date desc)
+
+Threads 分布:
+  ✓ [2026-04-29] 新聘博士後研究學者繳交資料_鄭澈博士 (2 msgs)
+       Participants: yijulee, che830621, cchen, coco891017
+  ✓ [2026-04-19] 後續面試報告時間請教 (5 msgs)
+       Participants: che830621, cchen, coco891017, yijulee, tsoping
+  ✓ [2026-03-31] 面試提醒 (1 msg)
+       Participants: che830621, coco891017
+  ✓ [2026-03-27] 君厚老師面試時間與地點 (時間異動) (2 msgs)
+  ✓ [2026-03-26] 君厚老師面試時間與地點 (2 msgs)
+  ✓ [2026-03-18] 應徵博士後研究員(鄭澈) (6 msgs)
+  ⚠ [2026-03-15] 應徵資料科學統計合作社... (1 msg)
+       Participants: che830621, scchen
+       ⚠ sender 不是 cchen,subject 含「陳」但實際寄給統計所其他單位
+
+附件:1 個 (handout.pdf, ~100 KB)
+
+⚠ 1 個 thread 標示為 potential false positive
+是否排除 [2026-03-15] 那封?
+
+選項:
+  (a) 排除 false positive,歸檔 18 封
+  (b) 保留 false positive,歸檔 19 封(用戶確認也要這封)
+  (c) 修改 filter(narrow / broaden)
+  (d) 取消
+
+你選哪個?
+```
diff --git a/plugins/che-apple-mail-mcp/skills/confirmation-protocol/SKILL.md b/plugins/che-apple-mail-mcp/skills/confirmation-protocol/SKILL.md
new file mode 100644
index 00000000..1de1b641
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/skills/confirmation-protocol/SKILL.md
@@ -0,0 +1,160 @@
+---
+name: confirmation-protocol
+description: NSQL-derived confirmation workflow for email operations. Use this skill BEFORE executing archive-mail with vague filters, compose_email (sending mail), delete_email/move_email in bulk, or any operation that touches 5+ emails. Show user a structured preview of "what I understood" before taking action, achieving consensus through dialogue. Skip when the input is unambiguous (specific Message-ID, single mark_read, etc.).
+---
+
+# Confirmation Protocol — Email Operations
+
+## 核心原則
+
+**AI 不直接執行,先 show 結構化的「我理解你要的是這樣」讓 user confirm/correct/reject,achieve consensus 後才執行**。
+
+借鑑自 nsql 的 Confirmation Protocol(`/Users/che/Developer/nsql`)。原始 nsql 設計給 SQL/data query;這裡 adapt 到 Apple Mail 操作。
+
+## Bootstrap(v2.9.0+ 鐵律,強制)
+
+被 trigger 時(filter 模糊 / bulk operation ≥ 5 / destructive / compose 寄出),**第一個動作就用 `TaskCreate`** 把要跑的 phases 建成 todo list:
+
+```
+TaskCreate(subject="confirm_phase1_disambiguation",
+           description="Filter 是否模糊?模糊 → 列候選 + AskUserQuestion 選定;明確 → 直接 mark completed。處理完 update。")
+
+TaskCreate(subject="confirm_phase2_search_preview",
+           description="Search 結果 ≥ 5 → bulk-operation-preview skill 跑 thread breakdown + false-positive flagging,展示 user;< 5 且無 ⚠⚠ → mark completed。")
+
+TaskCreate(subject="confirm_phase3_operation_confirmation",
+           description="展示 side-effect scope (N files written, K attachments, total bytes)。Destructive 加 ⚠ 警告。User AskUserQuestion 答覆(a)確認 (b)排除 false positive (c)改 filter (d)取消。")
+
+TaskCreate(subject="confirm_phase4_execute_or_iterate",
+           description="按 user 答覆執行 / 回 Phase 1-3 / abort。Abort 時要明確告訴 user『未做任何 side effect』。")
+```
+
+**完成每一個 phase 立即 `TaskUpdate → completed`。靜默 skip = 違規**。即使該 phase 是「可 skip」(明確 filter 跳 Phase 1),也要 `TaskUpdate completed` + 註明 skip 原因(在 description 裡 append),不可只是不做。
+
+**為什麼**:沒 task tracking 時,Claude 容易把 Phase 2 preview 用「應該還好吧」rationalize 掉,直接寫檔。Task 標 incomplete 在 UI 看得見,user 知道有東西被跳。
+
+## 何時觸發
+
+| 觸發條件 | 範例 | 嚴重度 |
+|---------|------|--------|
+| **Filter ambiguity** | 「陳老師」、「最近的信」、「VIP 寄來的」 | 🔴 必 confirm |
+| **Bulk operation** | search 結果 ≥ 5 封 | 🟡 建議 confirm |
+| **Destructive** | delete_email、empty Trash、bulk move | 🔴 必 confirm |
+| **Compose 寄出** | compose_email、reply_email | 🔴 必 confirm |
+| **Outbound side effect** | mark_as_junk、forward_email | 🟡 建議 confirm |
+
+**Skip confirm**(可以直接執行):
+- 明確 Message-ID 的 read-only 操作(get_email、list_attachments)
+- Single email mark_read/unflag
+- 純 search/list(沒有 side effect)
+
+## 4-Phase Workflow
+
+### Phase 1 — Disambiguation(若 filter 模糊)
+
+模糊 filter → 列出可能解讀,讓 user 選:
+
+```
+「陳老師」可能對應到多個 contacts:
+1. cchen@stat.sinica.edu.tw (陳君厚老師,推薦)
+2. scchen@stat.sinica.edu.tw (統計所其他「陳」)
+3. 其他同事(請補充)
+
+你要哪一個?
+```
+
+詳細 trigger 列表見 `email-search-disambiguation` skill。
+
+### Phase 2 — Search Preview(展示找到的 emails,flag false positives)
+
+Search 後 **不直接 fetch** 全部內容,先 list metadata 給 user 過目:
+
+```
+搜尋結果:19 封 emails(by sender + 林助理 + subject 含「陳君厚」)
+Threads 分布:
+
+  ✓ [04-29] 新聘博士後研究學者繳交資料 (2 msgs)
+  ✓ [04-19] 後續面試報告時間請教 (5 msgs)
+  ✓ [03-31] 面試提醒 (1 msg)
+  ✓ [03-27] 君厚老師面試時間與地點 (時間異動) (2 msgs)
+  ✓ [03-26] 君厚老師面試時間與地點 (2 msgs)
+  ✓ [03-18] 應徵博士後研究員(鄭澈) (6 msgs)
+  ⚠ [03-15] 應徵資料科學統計合作社... (1 msg, sender=scchen,可能 false positive)
+
+⚠ 1 個 thread 標示為 potential false positive(sender 不符合 cchen)
+   要排除嗎?確認歸檔範圍?
+```
+
+False-positive detection 詳見 `false-positive-detection.md` rule。
+
+### Phase 3 — Operation Confirmation(展示 side effect 規模)
+
+具體說會建立/修改/刪除什麼:
+
+```
+我將執行:
+- 歸檔 18 封 emails 到 communications/emails/
+- 下載 1 個 attachment (handout.pdf, 76 KB)
+- 寫 .email_index.json (18 entries) + .threads.json (6 threads)
+- 不修改 Mail.app 內容(read-only operation)
+
+⚠ 此操作會建立約 19 個檔案
+確認執行嗎?
+```
+
+### Phase 4 — Execute or Iterate
+
+- **User 確認** → 執行
+- **User 修正**(「不要 03-15 那封」、「也要把 scchen 那個歸入」) → 更新 plan,重新 Phase 3 confirm
+- **User 拒絕** → 重新 Phase 1 理解
+
+## Pipeline-style 表示法(default)
+
+借自 nsql 的 pipeline format。Email operation 用:
+
+```
+Mail
+  -> filter(sender=X OR recipient=X OR subject contains Y)
+  -> sort(date desc)
+  -> limit(100)
+  -> group(thread_key)
+```
+
+讓 user 一眼看出操作鏈。
+
+## Operation format(destructive)
+
+借自 nsql 的 operation format:
+
+```
+DELETE on Mail
+with sender = "spam@example.com"
+affecting 247 emails
+
+⚠ 此操作將影響 247 封 emails
+⚠ 此操作無法復原(emails 進 Trash 後 30 天清除)
+
+確認執行嗎?
+```
+
+## Response handling
+
+- 「對」/「是」/「OK」 → execute
+- 「不對,改成 X」 → update interpretation, re-confirm
+- 「排除 Y」 → narrow scope, re-confirm
+- 「補充 Z」 → expand scope, re-confirm
+- 「算了」/「不要做了」 → abort gracefully
+
+## 為什麼這個 protocol 重要
+
+實際案例(2026-05-01 archive 陳老師信件):用戶說「幫我抓陳老師有關的信」,直接 search → fetch 19 封 → 寫 markdown,**事後**發現 265250 是 false positive(寄給 scchen 不是 cchen),又走一輪 rm + index 修復。
+
+如果有這個 confirmation skill,Phase 2 會 flag 這封並讓 user 排除,完全 prevent false positive round trip。
+
+## 相關文件
+
+- `rules/confirmation-triggers.md` — 何時 confirm、何時 skip
+- `rules/false-positive-detection.md` — 偵測 search 結果中的 false positives
+- `skills/email-search-disambiguation/SKILL.md` — 模糊 filter 怎麼 disambiguate
+- `skills/bulk-operation-preview/SKILL.md` — 大量操作的 preview format
+- `/Users/che/Developer/nsql/protocol.yaml` — 原始 NSQL Confirmation Protocol spec
diff --git a/plugins/che-apple-mail-mcp/skills/email-search-disambiguation/SKILL.md b/plugins/che-apple-mail-mcp/skills/email-search-disambiguation/SKILL.md
new file mode 100644
index 00000000..b454a1d8
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/skills/email-search-disambiguation/SKILL.md
@@ -0,0 +1,146 @@
+---
+name: email-search-disambiguation
+description: Disambiguate vague email search filters before executing search. Triggers when user uses ambiguous contact references (Chinese name, nickname, role like "老闆"/"老師"), vague time references ("最近"/"上週"), or scope words ("全部"/"所有"). Present 2-3 concrete interpretations and let user choose. Adapted from nsql disambiguation triggers (D1-D5) for email domain.
+---
+
+# Email Search Disambiguation
+
+借鑑 nsql 的 disambiguation triggers,adapt 到 email search 領域。
+
+## Triggers
+
+### E1 — Vague Contact Reference
+
+**Examples**:
+- 中文人名:「陳老師」、「王教授」、「林助理」
+- 角色稱呼:「老闆」、「主管」、「指導教授」、「客戶」
+- 公司/組織:「中研院的人」、「stat.sinica 的信」
+
+**Resolution pattern**:
+
+```
+「{contact}」可能對應到:
+1. {email_1} ({description_1},推薦)
+2. {email_2} ({description_2})
+3. 其他({user 補充})
+
+你要哪一個?
+```
+
+**範例**:
+```
+「陳老師」可能對應到:
+1. cchen@stat.sinica.edu.tw (陳君厚老師,中研院統計所,推薦)
+2. scchen@stat.sinica.edu.tw (統計所其他「陳」)
+3. 其他
+
+你要哪一個?
+```
+
+**怎麼找候選**:
+- 從 `.claude/emails.md` 的 `participant_aliases` 讀別名對應
+- 從 contacts 或之前 archive 的 thread participants 找匹配
+- 如果完全找不到,問 user「我找不到匹配的 contact,你能給我 email 地址嗎?」
+
+### E2 — Vague Time Reference
+
+**Examples**: 「最近」、「上週」、「這個月」、「之前」、「半年內」
+
+**Resolution pattern**:
+
+```
+「{term}」可以有不同解釋:
+1. 過去 7 天 (今天 - 7d)
+2. 上一個完整週/月
+3. 自從某事件 (例如:上次 archive 之後)
+
+你指的是哪一個?
+```
+
+### E3 — Vague Scope
+
+**Examples**: 「全部」、「所有」、「都」、「整個 thread」
+
+**Resolution pattern**:
+
+```
+「全部」可能指:
+1. 符合 filter 的 emails (用 search criteria 限縮)
+2. 整個 mailbox 的 emails (沒有 filter)
+3. 過去 N 天/月的 emails (時間限縮)
+
+範圍多大?
+```
+
+### E4 — Ambiguous Operation Direction
+
+**Examples**:
+- 「寄給陳老師的信」← 我寄出?還是收到?
+- 「跟陳老師往來的信」← 雙向
+
+**Resolution pattern**:
+
+```
+「{phrase}」可能指:
+1. 我寄出去給 {contact} 的(Sent direction)
+2. {contact} 寄給我的(Received direction)
+3. 雙向(整個 thread)
+
+你要哪一個?
+```
+
+### E5 — Mailbox Ambiguity
+
+**Examples**: 「INBOX 的信」當有多個 accounts、「Drafts」當不確定哪個 account
+
+**Resolution pattern**:
+
+```
+你有 {N} 個 mail accounts:
+1. {account_1}
+2. {account_2}
+3. ...
+
+「{mailbox}」要在哪一個 account 找?還是全部?
+```
+
+## Disambiguation skip 條件
+
+不需要 disambiguate(直接 execute):
+
+- 明確 email 地址(`cchen@stat.sinica.edu.tw`)
+- 精確日期區間(`2026-04-01 to 2026-04-30`)
+- Message-ID 直接指定
+- 之前 session 已經 disambiguate 過同一個 term(且 user 沒改)
+
+## 與 confirmation-protocol 的關係
+
+E1-E5 是 confirmation-protocol 的 **Phase 1**(Disambiguation)。
+完成 disambiguation 後進入 Phase 2(Search Preview),由 `bulk-operation-preview` skill 接手。
+
+## 範例 dialogue
+
+```
+user: 把 jonathan 寄給我的信都歸檔
+
+AI [E1 trigger]:
+「jonathan」可能對應到:
+1. jonathan_tong@ntu.edu.tw (Jonathan Tong,合作研究者)
+2. jonathan@some-other-domain.com (其他)
+
+你要哪一個?
+
+user: 1
+
+AI [E4 trigger - direction is "寄給我的" so direction is implicitly received, but let me double check via E3]:
+「jonathan_tong@ntu.edu.tw 寄給我的信」我理解是:
+- Direction: received only (不含我寄出去的)
+- Mailbox: 預設 INBOX(若要包含其他 mailbox 例如 archived 請說)
+- Time range: 全部歷史
+
+確認嗎?
+
+user: 對,但是要包含 archived 的
+
+AI: [proceed to Phase 2 with refined filter]
+```
diff --git a/plugins/che-apple-mail-mcp/tests/test-session-start-hook.sh b/plugins/che-apple-mail-mcp/tests/test-session-start-hook.sh
new file mode 100755
index 00000000..2469b846
--- /dev/null
+++ b/plugins/che-apple-mail-mcp/tests/test-session-start-hook.sh
@@ -0,0 +1,274 @@
+#!/bin/bash
+# Integration tests for hooks/session-start.sh (#76).
+#
+# Each case: arrange (set up runtime state file + plugin.json + optional mock PID),
+# act (run hook), assert (exit code + side effects). All temp state lives under
+# $TEST_DIR which is auto-cleaned via trap.
+#
+# Mock strategy:
+# - Override $HOME via env so RUNTIME_FILE points into TEST_DIR
+# - Override BASH_SOURCE-derived plugin root by symlinking a fake plugin tree
+# - Mock MCP binary process via `sleep 1000 &` background process
+# - Process command match is on substring "CheAppleMailMCP" — sleep alone won't
+#   pass the guard, so we use exec via a renamed command via /bin/sh -c with
+#   $0 trick is too brittle; instead skip the comm check by trusting jq parse
+#   in cases where PID points to our sleep, by using a wrapper script that
+#   re-execs sleep with argv[0]=CheAppleMailMCP.
+
+set -u
+
+TEST_DIR=$(mktemp -d -t test-session-start-hook.XXXXXX)
+PASS=0
+FAIL=0
+FAIL_DETAIL=""
+
+cleanup() {
+    # Kill any tracked mock PIDs.
+    for pid in $(cat "$TEST_DIR/mock_pids" 2>/dev/null); do
+        kill -KILL "$pid" 2>/dev/null || true
+    done
+    rm -rf "$TEST_DIR"
+}
+trap cleanup EXIT
+
+# --- Setup mock plugin layout ---
+# Real hook lives at: <plugin>/hooks/session-start.sh
+# Plugin.json lives at: <plugin>/.claude-plugin/plugin.json
+# Hook resolves PLUGIN_ROOT via "$(dirname BASH_SOURCE)/..".
+# Trick: copy hook into a fake plugin root inside TEST_DIR so PLUGIN_ROOT
+# resolves to our test plugin layout.
+
+REAL_HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../hooks" && pwd)"
+REAL_HOOK="$REAL_HOOK_DIR/session-start.sh"
+
+if [ ! -x "$REAL_HOOK" ]; then
+    echo "ERROR: hook not found or not executable at $REAL_HOOK" >&2
+    exit 2
+fi
+
+FAKE_PLUGIN="$TEST_DIR/fake-plugin"
+mkdir -p "$FAKE_PLUGIN/hooks" "$FAKE_PLUGIN/.claude-plugin"
+cp "$REAL_HOOK" "$FAKE_PLUGIN/hooks/session-start.sh"
+chmod +x "$FAKE_PLUGIN/hooks/session-start.sh"
+
+# Spawn a mock binary process whose argv[0] contains "CheAppleMailMCP" so the
+# hook's comm-substring guard passes. macOS SIP / codesigning kills sleep when
+# launched from a copied path, so use `exec -a` to fake argv[0] inside a
+# subshell — sleep itself runs from /bin/sleep but appears as
+# "CheAppleMailMCP-mock" in `ps -o command=`.
+#
+# IMPORTANT: cannot use `start_mock_pid; PID=$LAST_MOCK_PID` command substitution — bash
+# waits for every child of the substitution subshell to exit, including the
+# backgrounded sleep, so $() blocks for 1000s. Use a global variable instead.
+LAST_MOCK_PID=""
+start_mock_pid() {
+    ( exec -a CheAppleMailMCP-mock sleep 1000 ) >/dev/null 2>&1 &
+    LAST_MOCK_PID=$!
+    echo "$LAST_MOCK_PID" >> "$TEST_DIR/mock_pids"
+    # Briefly wait for the exec to settle so subsequent `ps -p $pid` succeeds.
+    sleep 0.2
+}
+
+run_hook() {
+    # Override HOME so RUNTIME_FILE in hook resolves inside TEST_DIR.
+    HOME="$TEST_DIR" mkdir -p "$TEST_DIR/bin"
+    HOME="$TEST_DIR" "$FAKE_PLUGIN/hooks/session-start.sh" 2>"$TEST_DIR/hook.stderr"
+    return $?
+}
+
+write_plugin_json() {
+    local version="$1"
+    if [ "$version" = "MISSING" ]; then
+        rm -f "$FAKE_PLUGIN/.claude-plugin/plugin.json"
+    else
+        cat > "$FAKE_PLUGIN/.claude-plugin/plugin.json" <<EOF
+{"name":"test","version":"$version"}
+EOF
+    fi
+}
+
+# v2.19.5+ schema (post-#77): plugin.json has both `version` (shell) and
+# `binary_version` (binary tag). Runtime state records binary tag.
+write_plugin_json_with_binary() {
+    local shell_version="$1"
+    local binary_version="$2"
+    cat > "$FAKE_PLUGIN/.claude-plugin/plugin.json" <<EOF
+{"name":"test","version":"$shell_version","binary_version":"$binary_version"}
+EOF
+}
+
+write_runtime_file() {
+    local pid="$1"
+    local version="$2"
+    if [ "$pid" = "MISSING" ]; then
+        rm -f "$TEST_DIR/bin/.CheAppleMailMCP.runtime.json"
+        return
+    fi
+    mkdir -p "$TEST_DIR/bin"
+    cat > "$TEST_DIR/bin/.CheAppleMailMCP.runtime.json" <<EOF
+{"pid":${pid},"started_at":1000000,"version_at_spawn":"${version}"}
+EOF
+}
+
+assert() {
+    local name="$1"
+    local condition="$2"
+    if eval "$condition"; then
+        PASS=$((PASS+1))
+        printf "  PASS  %s\n" "$name"
+    else
+        FAIL=$((FAIL+1))
+        FAIL_DETAIL="${FAIL_DETAIL}\n  FAIL  ${name}\n        condition: ${condition}\n        stderr: $(cat "$TEST_DIR/hook.stderr" 2>/dev/null)"
+        printf "  FAIL  %s\n" "$name"
+    fi
+}
+
+reset_state() {
+    rm -f "$TEST_DIR/bin/.CheAppleMailMCP.runtime.json"
+    rm -f "$FAKE_PLUGIN/.claude-plugin/plugin.json"
+    : > "$TEST_DIR/hook.stderr"
+}
+
+# ============================================================
+# Case 1: no runtime state file → exit 0, no-op
+# ============================================================
+echo "Case 1: no runtime state file"
+reset_state
+write_plugin_json "2.18.0"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+
+# ============================================================
+# Case 2: version match → no kill
+# ============================================================
+echo "Case 2: version match"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+write_plugin_json "2.18.0"
+write_runtime_file "$PID" "2.18.0"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+assert "mock PID still alive" "ps -p $PID -o pid= >/dev/null 2>&1"
+kill -KILL "$PID" 2>/dev/null || true
+
+# ============================================================
+# Case 3: version mismatch + PID alive → SIGTERM, PID dies
+# ============================================================
+echo "Case 3: version mismatch + PID alive"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+write_plugin_json "2.18.0"
+write_runtime_file "$PID" "2.17.0"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "warning printed to stderr" "grep -q 'Killing stale CheAppleMailMCP' $TEST_DIR/hook.stderr"
+sleep 0.5
+assert "mock PID is dead" "! ps -p $PID -o pid= >/dev/null 2>&1"
+
+# ============================================================
+# Case 4: runtime state present but PID already dead → no-op
+# ============================================================
+echo "Case 4: stale runtime state, PID dead"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+kill -KILL "$PID" 2>/dev/null
+sleep 0.2
+write_plugin_json "2.18.0"
+write_runtime_file "$PID" "2.17.0"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+
+# ============================================================
+# Case 5: jq missing → silent exit 0
+# ============================================================
+echo "Case 5: jq missing"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+write_plugin_json "2.18.0"
+write_runtime_file "$PID" "2.17.0"
+# Mock missing jq by overriding PATH to exclude it.
+MINIMAL_PATH="/sbin:/usr/sbin"  # neither contains jq
+EXISTING_HOME="$HOME"
+HOME="$TEST_DIR" PATH="$MINIMAL_PATH" "$FAKE_PLUGIN/hooks/session-start.sh" 2>"$TEST_DIR/hook.stderr"
+EXIT=$?
+HOME="$EXISTING_HOME"
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+assert "mock PID still alive (hook should not have killed without jq)" "ps -p $PID -o pid= >/dev/null 2>&1"
+kill -KILL "$PID" 2>/dev/null || true
+
+# ============================================================
+# Case 6: plugin.json missing → silent exit 0
+# ============================================================
+echo "Case 6: plugin.json missing"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+write_plugin_json "MISSING"
+write_runtime_file "$PID" "2.17.0"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+assert "mock PID still alive" "ps -p $PID -o pid= >/dev/null 2>&1"
+kill -KILL "$PID" 2>/dev/null || true
+
+# ============================================================
+# Case 7: binary_version field present, matches runtime → no kill (#73)
+# Verifies hook prefers .binary_version over .version when comparing
+# against runtime state. Pre-#73 fix: this would FAIL because hook
+# compared runtime binary tag (2.8.5) against plugin.json shell version
+# (2.19.5), triggering unnecessary kill on every session start.
+# ============================================================
+echo "Case 7: binary_version field present, matches runtime"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+# Shell v2.19.5 + binary v2.8.5 (post-#77 two-field schema)
+write_plugin_json_with_binary "2.19.5" "2.8.5"
+# Runtime state records binary tag, not shell version
+write_runtime_file "$PID" "2.8.5"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+assert "mock PID still alive (binary_version matches, no kill)" "ps -p $PID -o pid= >/dev/null 2>&1"
+kill -KILL "$PID" 2>/dev/null || true
+
+# ============================================================
+# Case 8: binary_version absent (legacy schema) → fallback to .version (#73)
+# When plugin.json has no binary_version field (pre-#77 plugins), hook
+# falls back to comparing against .version. Verifies backward compat.
+# ============================================================
+echo "Case 8: binary_version absent, fallback to .version"
+reset_state
+start_mock_pid; PID=$LAST_MOCK_PID
+# Legacy single-field schema (no binary_version)
+write_plugin_json "2.17.0"
+# Runtime version_at_spawn matches plugin.json version
+write_runtime_file "$PID" "2.17.0"
+run_hook
+EXIT=$?
+assert "exit 0" "[ $EXIT -eq 0 ]"
+assert "no warning emitted" "[ ! -s $TEST_DIR/hook.stderr ]"
+assert "mock PID still alive (legacy fallback works)" "ps -p $PID -o pid= >/dev/null 2>&1"
+kill -KILL "$PID" 2>/dev/null || true
+
+# ============================================================
+# Summary
+# ============================================================
+echo ""
+echo "============================================="
+echo "Results: $PASS pass, $FAIL fail"
+echo "============================================="
+
+if [ "$FAIL" -gt 0 ]; then
+    printf "%b\n" "$FAIL_DETAIL"
+    exit 1
+fi
+exit 0
diff --git a/plugins/che-apple-notes-mcp/.claude-plugin/plugin.json b/plugins/che-apple-notes-mcp/.claude-plugin/plugin.json
new file mode 100644
index 00000000..615d2504
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/.claude-plugin/plugin.json
@@ -0,0 +1,18 @@
+{
+  "name": "che-apple-notes-mcp",
+  "version": "0.2.1",
+  "description": "macOS Apple Notes MCP server — SQLite fast read + AppleScript write, 18 tools, FDA fallback",
+  "author": {
+    "name": "Che Cheng"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "apple-notes",
+    "notes",
+    "macos",
+    "applescript",
+    "sqlite",
+    "productivity"
+  ]
+}
diff --git a/plugins/che-apple-notes-mcp/.mcp.json b/plugins/che-apple-notes-mcp/.mcp.json
new file mode 100644
index 00000000..92a3edac
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/.mcp.json
@@ -0,0 +1,7 @@
+{
+  "notes": {
+    "type": "stdio",
+    "command": "${CLAUDE_PLUGIN_ROOT}/bin/che-apple-notes-mcp-wrapper.sh",
+    "description": "macOS Apple Notes MCP server - SQLite fast read + AppleScript write"
+  }
+}
diff --git a/plugins/che-apple-notes-mcp/CHANGELOG.md b/plugins/che-apple-notes-mcp/CHANGELOG.md
new file mode 100644
index 00000000..8888b5cc
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [0.2.1] - (date unknown — please fill in)
+
+### Changed
+- macOS Apple Notes MCP server — SQLite fast read + AppleScript write, 18 tools, FDA fallback
diff --git a/plugins/che-apple-notes-mcp/CLAUDE.md b/plugins/che-apple-notes-mcp/CLAUDE.md
new file mode 100644
index 00000000..f4a6f82c
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/CLAUDE.md
@@ -0,0 +1,82 @@
+# che-apple-notes-mcp — CLAUDE.md
+
+## Purpose
+
+macOS Apple Notes MCP plugin. Wraps the [CheAppleNotesMCP](https://github.com/PsychQuant/che-apple-notes-mcp) binary via auto-download wrapper. Uses **SQLite fast read + AppleScript safe write** dual-track architecture (same pattern as `che-apple-mail-mcp`).
+
+## Components
+
+### MCP Tools (18)
+
+| Category | Tools | Backend |
+|----------|-------|---------|
+| Folders | `list_folders`, `create_folder`, `update_folder`, `delete_folder` | SQLite read / AS write |
+| Notes | `list_notes`, `list_notes_quick`, `get_note`, `create_note`, `update_note`, `delete_note`, `move_note` | SQLite read / AS write |
+| Search | `search_notes` | SQLite (FDA required) |
+| Batch | `create_notes_batch`, `move_notes_batch`, `delete_notes_batch` | AS write |
+| Undo/Redo | `undo`, `redo`, `undo_history` | AS write + in-memory stack |
+
+MCP namespace: `mcp__che-apple-notes-mcp__<tool>`.
+
+### Skills
+
+| Skill | 用途 |
+|-------|------|
+| `notes-management` | 工作流指南：tool 分類、body 雙軌規格、account disambiguation、常見 workflow、v0.1.0 已知限制 |
+
+### Slash Commands
+
+| Command | 用途 |
+|---------|------|
+| `/che-apple-notes-mcp:new-note` | 從自然語言建 note |
+| `/che-apple-notes-mcp:search-notes` | 關鍵字搜尋 + 結果摘要 |
+| `/che-apple-notes-mcp:list-folders` | 列出所有 folder（按帳號分組） |
+
+### Hooks
+
+| Hook | 用途 |
+|------|------|
+| `SessionStart → check-mcp.sh` | 啟動時檢查 `~/bin/CheAppleNotesMCP` 是否安裝、版本是否最新；缺的話提示下載指令 |
+
+## Binary Dependency
+
+這是 binary-based plugin：`.mcp.json` 指向 `bin/che-apple-notes-mcp-wrapper.sh`，wrapper 會 auto-download `CheAppleNotesMCP` binary 到 `~/bin/`。
+
+- Binary repo: [`PsychQuant/che-apple-notes-mcp`](https://github.com/PsychQuant/che-apple-notes-mcp)
+- Binary name: `CheAppleNotesMCP`
+- Release asset naming: asset filename must contain `CheAppleNotesMCP`
+
+### Plugin vs Binary Version Sync
+
+| 改動類型 | 處理 |
+|----------|------|
+| 改 plugin shell（commands、skill、hooks、wrapper） | `/plugin-tools:plugin-update che-apple-notes-mcp` |
+| 改 binary source（tool 新增、bug fix） | 先 `/mcp-tools:mcp-deploy` 到 binary repo → 發 GitHub Release → 再跑 `plugin-update` |
+| 同時改兩邊 | `plugin-update`（v1.11+ 會 detect 依賴不同步並 prompt 連動 mcp-deploy） |
+
+## Permissions
+
+Plugin 跑在使用者層級，需要兩個 TCC 權限：
+
+| 權限 | 觸發時機 | 缺的話 |
+|------|----------|--------|
+| Automation → Notes.app | 第一次呼叫任何 write tool 或 `--setup` | 無法 create/update/delete |
+| Full Disk Access（FDA） | SQLite 快讀 | Read 自動 fallback 到 AppleScript（慢 50–500×，但 `search_notes` 和 `list_notes_quick` 會 error，因為需 SQLite） |
+
+**FDA 無法程式觸發對話框**。使用者要手動去 System Settings → Privacy & Security → Full Disk Access 把 `~/bin/CheAppleNotesMCP` 加進去。
+
+## Development
+
+- Update after plugin-shell changes: `/plugin-tools:plugin-update che-apple-notes-mcp`
+- Full release (binary + plugin): `/plugin-tools:plugin-deploy che-apple-notes-mcp`
+- Binary source edits: go to `che-mcps/che-apple-notes-mcp/` then `/mcp-tools:mcp-deploy`
+- Health check: `/plugin-tools:plugin-health`
+
+## v0.1.0 Known Limits（寫進 README，使用者會看到）
+
+- Locked notes: body AES-encrypted，只回 metadata
+- Pin/unpin 寫入：AS 不支援
+- Attachment 寫入：不支援（讀 metadata OK）
+- Body HTML from SQLite：降級為 plaintext（protobuf attribute runs 待 v0.2.0）
+- 1 MB body 上限
+- macOS 13/14/15 測過；未來 macOS 若改 protobuf schema 需升級 decoder
diff --git a/plugins/che-apple-notes-mcp/README.md b/plugins/che-apple-notes-mcp/README.md
new file mode 100644
index 00000000..324194c6
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/README.md
@@ -0,0 +1,101 @@
+# che-apple-notes-mcp
+
+macOS Apple Notes MCP plugin. Wraps [CheAppleNotesMCP](https://github.com/PsychQuant/che-apple-notes-mcp) — a native Swift binary that reads via SQLite (fast path) and writes via AppleScript (CloudKit-safe).
+
+## Features
+
+- **24 MCP tools** covering folders, notes CRUD, search, batch ops, undo/redo, and **CloudKit sharing visibility**
+- **SQLite fast read**: `list_notes` over 1000+ notes in <10 ms vs ~5 s with AppleScript
+- **AppleScript safe write**: CloudKit sync untouched
+- **Dual-track body**: accept plaintext or HTML on input; return both on read
+- **Shared note/folder awareness**: every read emits `shared: Bool`; filter collections via `shared: true|false`
+- **Share metadata + workflow helpers** (v0.2.0): read `ZICINVITATION` without deserializing the CKShare BLOB, and trigger Notes.app's native Share sheet for manual invitation
+- **Account disambiguation**: handle iCloud + On My Mac + other accounts
+- **Graceful fallback**: read ops auto-downgrade to AppleScript if Full Disk Access is not granted
+
+## Installation
+
+Via marketplace:
+
+```
+claude plugin marketplace add kiki830621/psychquant-claude-plugins
+claude plugin install che-apple-notes-mcp@psychquant-claude-plugins
+```
+
+The wrapper downloads the `CheAppleNotesMCP` binary from GitHub Releases on first use.
+
+## First-Run Setup
+
+```bash
+~/bin/CheAppleNotesMCP --setup
+```
+
+This:
+1. Probes Full Disk Access. If denied, prints instructions.
+2. Dispatches a trivial AppleScript to trigger the Automation permission dialog for Notes.app.
+
+**Optional but strongly recommended**: grant Full Disk Access to enable the SQLite fast path. Without it, reads work via AppleScript fallback (50–500× slower but correct).
+
+## Permissions
+
+| Permission | Why | How |
+|------------|-----|-----|
+| Automation → Notes.app | All write tools + workflow helpers | Prompt appears on first write |
+| Full Disk Access (recommended) | SQLite fast reads + `shared` filter + `get_share_metadata` | System Settings → Privacy & Security → Full Disk Access, add `~/bin/CheAppleNotesMCP` |
+
+## Tools (24)
+
+### Folders (4)
+- `list_folders` (supports `shared: bool?` filter)
+- `create_folder`, `update_folder`, `delete_folder`
+
+### Notes CRUD (7)
+- `list_notes` (supports `shared: bool?` filter), `list_notes_quick`, `get_note`
+- `create_note`, `update_note`, `delete_note`, `move_note`
+
+### Search (1)
+- `search_notes` (supports `shared: bool?` filter)
+
+### Batch (3)
+- `create_notes_batch`, `move_notes_batch`, `delete_notes_batch`
+
+### Sharing (3, new in v0.2.0)
+- `get_share_metadata` — read `ZICINVITATION` (shareURL, invitation counts, receivedDate, serverShareDataPresent) without touching the CKShare BLOB
+- `prepare_share_note` — activate Notes.app, focus a note, open `File → Share Note…` (user completes invitation manually)
+- `prepare_share_folder` — same flow for folders (`Share Folder…`)
+
+### Undo/Redo (3, process-local)
+- `undo`, `redo`, `undo_history`
+
+> All read tools now emit `shared: Bool` on every folder/note (derived from AppleScript `shared` property + SQLite heuristic on `ZSERVERSHAREDATA` / `ZZONEOWNERNAME`).
+
+## Slash Commands
+
+- `/new-note` — quickly create a note
+- `/search-notes` — search and show results
+- `/list-folders` — view folder hierarchy
+
+## Skill
+
+`notes-management` auto-loads when the conversation mentions Apple Notes, 備忘錄, or note-taking on Mac.
+
+## Known Limits
+
+- Locked notes: body is AES-encrypted and cannot be read.
+- Pinning: read-only (AppleScript doesn't expose `pinned` for writes).
+- Attachments: read-only metadata (no upload/replace).
+- Body HTML from SQLite: falls back to plaintext for formatting beyond common inline styles. AppleScript path returns full HTML fidelity.
+- Large bodies: 1 MB cap per note.
+- **CloudKit share creation / invitation / revocation**: explicitly NOT implemented — Notes.app's CKContainer is private; no public API path exists. The `prepare_share_*` workflow helpers are the intended escape valve (Path D per `openspec/specs/apple-notes-sharing-workflow/`).
+
+## Version History
+
+See [CHANGELOG.md](https://github.com/PsychQuant/che-apple-notes-mcp/blob/main/CHANGELOG.md) on the upstream repo.
+
+- **v0.2.1** (2026-04-22) — Plugin wrapper now version-aware (re-downloads `~/bin/CheAppleNotesMCP` when binary lags upstream release)
+- **v0.2.0** (2026-04-22) — 6 new tools for Apple Notes sharing, `shared: Bool` on all reads, 112 unit + 11 E2E tests
+- **v0.1.0** (2026-04-21) — initial release, 18 tools, dual-track architecture
+
+## License
+
+MIT © Che Cheng
diff --git a/plugins/che-apple-notes-mcp/bin/che-apple-notes-mcp-wrapper.sh b/plugins/che-apple-notes-mcp/bin/che-apple-notes-mcp-wrapper.sh
new file mode 100755
index 00000000..36dcc02a
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/bin/che-apple-notes-mcp-wrapper.sh
@@ -0,0 +1,88 @@
+#!/bin/bash
+# Version-aware auto-download wrapper for CheAppleNotesMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheAppleNotesMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-apple-notes-mcp"
+BINARY_NAME="CheAppleNotesMCP"
+INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
+
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
+
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
+    mkdir -p "$INSTALL_DIR"
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+exec "$BINARY" "$@"
diff --git a/plugins/che-apple-notes-mcp/commands/list-folders.md b/plugins/che-apple-notes-mcp/commands/list-folders.md
new file mode 100644
index 00000000..593f1c94
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/commands/list-folders.md
@@ -0,0 +1,17 @@
+---
+name: list-folders
+description: List all Apple Notes folders grouped by account
+allowed-tools:
+  - mcp__che-apple-notes-mcp__list_folders
+---
+
+# List Folders
+
+Call `list_folders` and present the result grouped by account (iCloud / On My Mac).
+
+Show:
+- Account name as heading
+- Folder names as a list
+- Note counts if easy to obtain (or skip — keep it fast)
+
+Hide folders where `is_hidden` is true (system containers).
diff --git a/plugins/che-apple-notes-mcp/commands/new-note.md b/plugins/che-apple-notes-mcp/commands/new-note.md
new file mode 100644
index 00000000..2e714fad
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/commands/new-note.md
@@ -0,0 +1,26 @@
+---
+name: new-note
+description: Quickly create an Apple Notes note from a description
+allowed-tools:
+  - mcp__che-apple-notes-mcp__list_folders
+  - mcp__che-apple-notes-mcp__create_note
+---
+
+# New Note
+
+Create a new Apple Notes note. If the user hasn't specified a folder, either use
+the default folder or ask (prefer defaulting).
+
+Usage examples the user might write:
+- `/new-note Shopping list: milk, eggs, bread`
+- `/new-note title: Meeting notes, body: ...`
+- `/new-note in Work folder: reminder to ship the release`
+
+Steps:
+1. Parse the user's request for title, body, and optional folder.
+2. If folder is mentioned, optionally call `list_folders` to verify it exists
+   (skip for speed when the folder is common like "Notes" or "Work").
+3. Call `create_note` with `body_text` (not HTML) unless the user provided HTML.
+4. Report the returned id and folder.
+
+Use Chinese or the user's language when writing the note body.
diff --git a/plugins/che-apple-notes-mcp/commands/search-notes.md b/plugins/che-apple-notes-mcp/commands/search-notes.md
new file mode 100644
index 00000000..ccc554e1
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/commands/search-notes.md
@@ -0,0 +1,21 @@
+---
+name: search-notes
+description: Search Apple Notes by keyword and show matching titles + snippets
+allowed-tools:
+  - mcp__che-apple-notes-mcp__search_notes
+  - mcp__che-apple-notes-mcp__get_note
+---
+
+# Search Notes
+
+Search Apple Notes via `search_notes` and summarise results.
+
+Steps:
+1. Parse the keyword(s) from the user's input.
+2. For multiple keywords, default to `match_mode: "any"` (OR). If the user says
+   "all of X Y Z", use `match_mode: "all"`.
+3. Call `search_notes(keywords: [...], match_mode, limit: 10)`.
+4. Present results as a numbered list with title, folder, modified date.
+5. If the user then asks for details on a specific result, call `get_note`.
+
+Default limit: 10. Adjust if the user asks for more.
diff --git a/plugins/che-apple-notes-mcp/hooks/check-mcp.sh b/plugins/che-apple-notes-mcp/hooks/check-mcp.sh
new file mode 100755
index 00000000..97a3a272
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/hooks/check-mcp.sh
@@ -0,0 +1,68 @@
+#!/bin/bash
+# Auto-install and update check for che-apple-notes-mcp
+
+BINARY_NAME="CheAppleNotesMCP"
+INSTALL_PATH="$HOME/bin/$BINARY_NAME"
+GITHUB_REPO="PsychQuant/che-apple-notes-mcp"
+RELEASE_URL="https://github.com/$GITHUB_REPO/releases/latest/download/$BINARY_NAME"
+
+LOCATIONS=(
+    "$HOME/bin/$BINARY_NAME"
+    "/usr/local/bin/$BINARY_NAME"
+    "$HOME/.local/bin/$BINARY_NAME"
+)
+
+MCP_FOUND=false
+MCP_PATH=""
+
+for loc in "${LOCATIONS[@]}"; do
+    if [[ -x "$loc" ]]; then
+        MCP_FOUND=true
+        MCP_PATH="$loc"
+        break
+    fi
+done
+
+get_latest_version() {
+    curl -sI "https://github.com/$GITHUB_REPO/releases/latest" 2>/dev/null | \
+        grep -i "^location:" | \
+        sed -E 's|.*/v?([0-9]+\.[0-9]+\.[0-9]+).*|\1|' | \
+        tr -d '\r\n'
+}
+
+install_binary() {
+    echo "📦 Installing $BINARY_NAME..."
+    mkdir -p "$HOME/bin"
+
+    if curl -fsSL "$RELEASE_URL" -o "$INSTALL_PATH" 2>/dev/null; then
+        chmod +x "$INSTALL_PATH"
+        echo "✅ Installed $BINARY_NAME to $INSTALL_PATH"
+        echo "   Run once: $INSTALL_PATH --setup   # for Automation + FDA guidance"
+        return 0
+    else
+        echo "❌ Failed to download $BINARY_NAME"
+        echo "   Manual install: $RELEASE_URL"
+        return 1
+    fi
+}
+
+if [[ "$MCP_FOUND" == "true" ]]; then
+    INSTALLED_VERSION=$(timeout 2 "$MCP_PATH" --version 2>/dev/null | awk '{print $NF}' || true)
+    LATEST_VERSION=$(get_latest_version)
+
+    if [[ -n "$INSTALLED_VERSION" && -n "$LATEST_VERSION" ]]; then
+        if [[ "$INSTALLED_VERSION" != "$LATEST_VERSION" ]]; then
+            echo "⬆️  che-apple-notes-mcp v$INSTALLED_VERSION → v$LATEST_VERSION available"
+            echo "   Update: curl -fsSL $RELEASE_URL -o $MCP_PATH && chmod +x $MCP_PATH"
+        else
+            echo "✓ che-apple-notes-mcp v$INSTALLED_VERSION (latest)"
+        fi
+    elif [[ -n "$INSTALLED_VERSION" ]]; then
+        echo "✓ che-apple-notes-mcp v$INSTALLED_VERSION installed"
+    else
+        echo "✓ che-apple-notes-mcp installed: $MCP_PATH"
+    fi
+else
+    echo "⚠️  che-apple-notes-mcp not found — install on first MCP call, or run:"
+    echo "   curl -fsSL $RELEASE_URL -o $INSTALL_PATH && chmod +x $INSTALL_PATH"
+fi
diff --git a/plugins/che-apple-notes-mcp/hooks/hooks.json b/plugins/che-apple-notes-mcp/hooks/hooks.json
new file mode 100644
index 00000000..d33be661
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-mcp.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/che-apple-notes-mcp/skills/notes-management/SKILL.md b/plugins/che-apple-notes-mcp/skills/notes-management/SKILL.md
new file mode 100644
index 00000000..7a473cb5
--- /dev/null
+++ b/plugins/che-apple-notes-mcp/skills/notes-management/SKILL.md
@@ -0,0 +1,183 @@
+---
+name: notes-management
+description: Guide for effective use of che-apple-notes-mcp for macOS Apple Notes management. Use when user asks about Apple Notes, 備忘錄, note taking on Mac, creating/searching/organizing notes.
+allowed-tools:
+  - mcp__che-apple-notes-mcp__list_folders
+  - mcp__che-apple-notes-mcp__create_folder
+  - mcp__che-apple-notes-mcp__update_folder
+  - mcp__che-apple-notes-mcp__delete_folder
+  - mcp__che-apple-notes-mcp__list_notes
+  - mcp__che-apple-notes-mcp__list_notes_quick
+  - mcp__che-apple-notes-mcp__get_note
+  - mcp__che-apple-notes-mcp__create_note
+  - mcp__che-apple-notes-mcp__update_note
+  - mcp__che-apple-notes-mcp__delete_note
+  - mcp__che-apple-notes-mcp__move_note
+  - mcp__che-apple-notes-mcp__search_notes
+  - mcp__che-apple-notes-mcp__create_notes_batch
+  - mcp__che-apple-notes-mcp__move_notes_batch
+  - mcp__che-apple-notes-mcp__delete_notes_batch
+  - mcp__che-apple-notes-mcp__undo
+  - mcp__che-apple-notes-mcp__redo
+  - mcp__che-apple-notes-mcp__undo_history
+---
+
+# macOS Apple Notes Management
+
+Guide for operating Apple Notes.app via `che-apple-notes-mcp`.
+
+## Architecture at a Glance
+
+| Operation | Path | Speed | Needs |
+|-----------|------|-------|-------|
+| Read (list/get/search) | SQLite direct | <10 ms | Full Disk Access |
+| Write (create/update/delete/move) | AppleScript | ~50 ms | Automation permission |
+| Read (fallback) | AppleScript | ~500 ms | Automation permission only |
+
+If Full Disk Access is not granted, read ops transparently fall back to AppleScript.
+
+## Body Format (Dual-Track)
+
+**Input**: provide `body_text` OR `body_html` (not both):
+
+```
+create_note(
+  title: "Meeting notes",
+  body_text: "Plain text with\nnewlines",   # will be wrapped in <div>
+  folder: "Work"
+)
+```
+
+```
+create_note(
+  title: "Styled",
+  body_html: "<h1>Heading</h1><p>With <b>bold</b></p>",
+  folder: "Work"
+)
+```
+
+**Output**: `get_note` and `list_notes(include_body=true)` return both forms:
+
+```
+{
+  "id": "x-coredata://...",
+  "title": "Meeting notes",
+  "body_text": "Plain text with\nnewlines",
+  "body_html": "<div>Plain text with<br>newlines</div>",
+  ...
+}
+```
+
+## Tool Categories
+
+### Discovery (start here)
+
+- `list_folders` — see all folders and their account (iCloud / On My Mac)
+- `list_notes_quick` with `range: "recent" | "today" | "this_week" | "pinned"` — common views
+- `search_notes` — keyword search (title + snippet)
+
+### Folders
+
+| Task | Tool |
+|------|------|
+| List | `list_folders` (optional `account` filter) |
+| Create | `create_folder(title, account?)` |
+| Rename | `update_folder(id, title)` |
+| Delete | `delete_folder(id)` — empty folders only |
+
+### Notes CRUD
+
+| Task | Tool | Key params |
+|------|------|------------|
+| List | `list_notes` | folder, folder_id, account, pinned, locked, include_body, limit, sort |
+| Get | `get_note` | id |
+| Create | `create_note` | title, body_text XOR body_html, folder?, account? |
+| Update | `update_note` | id, title?, body_text? / body_html? |
+| Delete | `delete_note` | id |
+| Move | `move_note` | id, folder, account? |
+
+### Batch (more efficient than multiple single calls)
+
+- `create_notes_batch(notes: [{title, body_text?, body_html?, folder?, account?}, ...])`
+- `move_notes_batch(ids: [...], folder, account?)`
+- `delete_notes_batch(ids: [...])`
+
+### Undo/Redo (process-local)
+
+- `undo` — revert last write
+- `redo` — reapply an undone write
+- `undo_history` — show stack
+
+## Source Disambiguation
+
+When folder names collide across accounts (e.g., "Notes" on iCloud and On My Mac):
+
+```
+create_note(
+  title: "Shopping list",
+  body_text: "milk, eggs",
+  folder: "Notes",
+  account: "iCloud"    # disambiguate
+)
+```
+
+Available accounts can vary: `iCloud`, `On My Mac`, plus any configured accounts. Use `list_folders` to inspect.
+
+## ID Formats
+
+- `id` field returned by SQLite path = AppleScript URL form: `x-coredata://<account-uuid>/ICNote/p<PK>`. Use this directly for `update_note`, `delete_note`, `move_note`.
+- `uuid` field = raw ZIDENTIFIER (just the note's UUID). For debugging / advanced consumers.
+
+## Common Workflows
+
+### Capture a quick note
+
+```
+create_note(title: "Idea", body_text: "The thing I just thought of", folder: "Notes")
+```
+
+### Daily review
+
+```
+1. list_notes_quick(range: "today")  → see today's notes
+2. list_notes_quick(range: "pinned") → see pinned items
+```
+
+### Find and update
+
+```
+1. search_notes(keyword: "project X")
+2. get_note(id: <first result>)
+3. update_note(id: ..., body_text: "<appended content>")
+```
+
+### Bulk reorganize
+
+```
+1. list_notes(folder: "Inbox")          → collect ids
+2. move_notes_batch(ids, folder: "Archive")
+```
+
+## Performance Tips
+
+1. **Default to metadata-only listing** — only pass `include_body: true` when you need body (each body requires GZIP inflate + protobuf decode, ~1ms per note).
+2. **Prefer `list_notes_quick`** over `list_notes` for common ranges.
+3. **Batch writes** cut AppleScript dispatch overhead from ~50ms × N to a single dispatch.
+4. **Search via `search_notes`** beats listing and filtering in the caller.
+
+## Known Limits (v0.1.0)
+
+- Locked notes: body is AES-encrypted and cannot be decoded — `{locked: true, body: null}`.
+- Note pinning: read-only (AppleScript does not expose the `pinned` attribute for writes).
+- Attachment writes: not supported (read-only via `list_notes` metadata).
+- Body HTML decoded from SQLite falls back to plaintext for formatting beyond bold/italic/link/list (v0.2.0 will render full attribute runs). Read via AppleScript for full HTML fidelity.
+- Large bodies: hard-capped at 1 MB; split into multiple notes.
+
+## First-Run Setup
+
+Users must run `~/bin/CheAppleNotesMCP --setup` once to:
+
+1. Get prompted for Automation permission to Notes.app (click Allow when the dialog appears)
+2. See whether Full Disk Access is granted (if not, follow the printed instructions to enable — optional but much faster)
+
+Without Full Disk Access: read ops fall back to AppleScript, ~50–500× slower but still functional. Features `list_notes_quick`, `search_notes` require SQLite and will error if FDA is missing.
diff --git a/plugins/che-archive-lines/CHANGELOG.md b/plugins/che-archive-lines/CHANGELOG.md
new file mode 100644
index 00000000..1d6f265a
--- /dev/null
+++ b/plugins/che-archive-lines/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.0] - (date unknown — please fill in)
+
+### Changed
+- 歸檔 LINE macOS 聊天記錄到文字檔
diff --git a/plugins/che-bot-toolkit/CHANGELOG.md b/plugins/che-bot-toolkit/CHANGELOG.md
new file mode 100644
index 00000000..0dfed932
--- /dev/null
+++ b/plugins/che-bot-toolkit/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [0.1.0] - (date unknown — please fill in)
+
+### Changed
+- Telegram 群組訊息監控 → GitHub Issue 自動化 pipeline。支援多專案、多人消歧義、衝突解決、launchd 定時背景檢查。
diff --git a/plugins/che-creative-suite/CHANGELOG.md b/plugins/che-creative-suite/CHANGELOG.md
new file mode 100644
index 00000000..e2361ffb
--- /dev/null
+++ b/plugins/che-creative-suite/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [0.1.0] - (date unknown — please fill in)
+
+### Changed
+- Creative Suite — 協調 che-svg-mcp（向量）與 che-pixel-mcp（點陣）的圖形處理工作流
diff --git a/plugins/che-dropbox-ignore/CHANGELOG.md b/plugins/che-dropbox-ignore/CHANGELOG.md
new file mode 100644
index 00000000..227e0314
--- /dev/null
+++ b/plugins/che-dropbox-ignore/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [2.1.0] - (date unknown — please fill in)
+
+### Changed
+- Auto-detect and exclude build artifacts from Dropbox sync (node_modules, .build, *.xcodeproj, *.profraw, etc.) using com.dropbox.ignored xattr — Swift CLI with zero fork overhead
diff --git a/plugins/che-duckdb-mcp/.claude-plugin/plugin.json b/plugins/che-duckdb-mcp/.claude-plugin/plugin.json
index 87dd25c0..0142a54c 100644
--- a/plugins/che-duckdb-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-duckdb-mcp/.claude-plugin/plugin.json
@@ -1,8 +1,8 @@
 {
   "name": "che-duckdb-mcp",
-  "version": "1.1.0",
-  "description": "DuckDB MCP Server - 整合文檔查詢與資料庫操作，14 個工具",
+  "version": "2.3.0",
+  "description": "Swift-native DuckDB MCP — dual-source docs (llms.txt + full docs) with TF-IDF search and fuzzy function matching, plus 6 local DB tools (14 total). Pinned duckdb-swift, surfaces real DuckDB error messages. SessionStart hook for version check.",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
-  "keywords": ["mcp", "duckdb", "database", "sql", "analytics", "documentation"]
+  "keywords": ["mcp", "duckdb", "database", "sql", "analytics", "documentation", "swift"]
 }
diff --git a/plugins/che-duckdb-mcp/CHANGELOG.md b/plugins/che-duckdb-mcp/CHANGELOG.md
new file mode 100644
index 00000000..36fc3146
--- /dev/null
+++ b/plugins/che-duckdb-mcp/CHANGELOG.md
@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [2.2.1] - (date unknown — please fill in)
+
+### Changed
+- Swift-native DuckDB MCP — dual-source docs (llms.txt + full docs) with TF-IDF search and fuzzy function matching, plus 6 local DB tools (14 total).
+- Pinned duckdb-swift, surfaces real DuckDB error messages.
+- SessionStart hook for version check
diff --git a/plugins/che-duckdb-mcp/README.md b/plugins/che-duckdb-mcp/README.md
index 63f21e77..1b2f0a3b 100644
--- a/plugins/che-duckdb-mcp/README.md
+++ b/plugins/che-duckdb-mcp/README.md
@@ -1,82 +1,78 @@
 # che-duckdb-mcp
 
-**DuckDB MCP Server** - 整合 DuckDB 文檔查詢與資料庫操作功能。
+**DuckDB MCP Server (Swift)** — 整合 DuckDB 文檔查詢與本地資料庫操作。
 
 ## 功能概覽
 
-整合 14 個工具，分為兩大類：
+14 個工具 = 8 文檔 + 6 資料庫。
 
-### 文檔工具 (8 個)
+### 文檔工具 (8 個) — v2.0.0 全面升級
 
 | 工具 | 功能 |
 |------|------|
-| `search_docs` | 搜索 DuckDB 文檔 |
+| `search_docs` | **TF-IDF** 加權搜尋 + llms.txt 優先（多來源合併） |
 | `list_sections` | 列出文檔章節 |
 | `get_section` | 取得章節內容 |
-| `get_function_docs` | 查詢函數文檔 |
+| `get_function_docs` | 查詢函數文檔（**Levenshtein fuzzy matching**） |
 | `list_functions` | 列出所有函數 |
 | `get_sql_syntax` | 查詢 SQL 語法 |
 | `refresh_docs` | 強制更新文檔 |
-| `get_doc_info` | 取得文檔資訊 |
+| `get_doc_info` | 取得兩個來源的快取資訊 |
 
 ### 資料庫工具 (6 個)
 
 | 工具 | 功能 |
 |------|------|
-| `db_connect` | 連接資料庫（記憶體或檔案） |
-| `db_query` | 執行 SELECT 查詢 |
+| `db_connect` | 連接資料庫（記憶體或檔案，自動檢查 storage version） |
+| `db_query` | 執行 SELECT 查詢（錯誤訊息含 DuckDB 原始內容） |
 | `db_execute` | 執行 DDL/DML 語句 |
 | `db_list_tables` | 列出表格和視圖 |
 | `db_describe` | 描述表格或查詢結構 |
-| `db_info` | 取得資料庫資訊 |
+| `db_info` | 取得資料庫資訊（含 duckdb-swift pinned revision） |
 
 ## 安裝
 
-### 1. 編譯 Binary
+### 方式 1：Plugin 安裝（推薦，自動下載 binary）
 
-```bash
-cd /path/to/che-duckdb-mcp
-swift build -c release
-cp .build/release/CheDuckDBMCP ~/bin/
 ```
-
-### 2. 安裝 Plugin
-
-```bash
-claude /plugin che-duckdb-mcp
+/plugin install che-duckdb-mcp@psychquant-claude-plugins
 ```
 
-## 使用範例
+首次使用時 `bin/che-duckdb-mcp-wrapper.sh` 會自動從 [PsychQuant/che-duckdb-mcp releases](https://github.com/PsychQuant/che-duckdb-mcp/releases) 下載 `CheDuckDBMCP` binary 到 `~/bin/`。
 
-### 文檔查詢
+### 方式 2：從原始碼編譯
 
-```
-# 搜索文檔
-"搜索 DuckDB 的 read_csv 函數"
-
-# 查詢 SQL 語法
-"DuckDB 的 COPY 語法是什麼？"
+```bash
+git clone https://github.com/PsychQuant/che-duckdb-mcp.git
+cd che-duckdb-mcp
+swift build -c release
+cp .build/release/CheDuckDBMCP ~/bin/
 ```
 
-### 資料庫操作
+然後再 `/plugin install` 即可（wrapper 會偵測到 `~/bin/CheDuckDBMCP` 已存在）。
 
-```
-# 連接記憶體資料庫
-db_connect: {}
+## Version History
 
-# 建立表格
-db_execute: { "sql": "CREATE TABLE users (id INTEGER, name VARCHAR)" }
+| Version | Date | Changes |
+|---------|------|---------|
+| v2.2.1 | 2026-04-22 | Wrapper auto-download now version-aware (re-downloads `~/bin/CheDuckDBMCP` when binary lags upstream) |
+| v2.2.0 | 2026-04-14 | SessionStart hook for binary version check + MCP server key rename for namespace consistency |
+| v2.1.1 | 2026-04-14 | Rename MCP server to `che-duckdb-mcp` for namespace unification across plugin / wrapper / settings |
+| v2.1.0 | 2026-04-14 | Add `che-duckdb-mcp` guidance Skill — auto-loads when conversation mentions DuckDB / SQL queries / 文檔 |
+| v2.0.0 | 2026-04-14 | TF-IDF search engine + dual-source docs (llms.txt + full) + Levenshtein fuzzy matching + pinned duckdb-swift + native error messages |
 
-# 插入資料
-db_execute: { "sql": "INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')" }
+## v2.0.0 重點
 
-# 查詢資料
-db_query: { "sql": "SELECT * FROM users", "format": "markdown" }
-```
+- **TF-IDF 搜尋引擎**：倒排索引 + cosine similarity，比 substring match 精準一個數量級
+- **雙來源文檔**：llms.txt (3KB 精簡版) + duckdb-docs.md (5MB 完整版)，llms.txt 命中加 1.5× 分數
+- **Levenshtein fuzzy matching**：`read_csvs` → `read_csv`、`JSON_EXTRACT` → `json_extract`
+- **ETag/Last-Modified 條件式快取**：不再每 24h 重下 5MB
+- **Pinned duckdb-swift**：避免 storage format 相容性炸彈
+- **DuckDB 原生錯誤訊息**：`Binder Error` / `Catalog Error` / `Parser Error` 直接穿透到 MCP response，不再是 opaque `error N`（[fix #1](https://github.com/PsychQuant/che-duckdb-mcp/issues/1)）
 
 ## 輸出格式
 
-支援三種輸出格式：
+`db_query` 支援三種輸出格式：
 
 - **json**: 結構化 JSON（預設）
 - **markdown**: 表格格式（適合閱讀）
@@ -84,18 +80,21 @@ db_query: { "sql": "SELECT * FROM users", "format": "markdown" }
 
 ## 技術細節
 
-- **語言**: Swift
-- **MCP SDK**: swift-sdk 0.10.0
-- **DuckDB**: duckdb-swift
+- **語言**: Swift 5.9+
 - **平台**: macOS 13.0+
+- **MCP SDK**: swift-sdk 0.12.0
+- **DuckDB**: duckdb-swift pinned revision `d90cf8d`（DuckDB v1.5.0-dev）
+- **快取**: `~/.cache/che-duckdb-mcp/`（HTTP 條件式更新）
 
 ## 安全考量
 
 1. `db_query` 僅允許 SELECT/WITH/SHOW/DESCRIBE/EXPLAIN/PRAGMA
 2. 預設限制返回 1000 行
 3. 支援唯讀模式
+4. **Local-use only**：錯誤訊息含檔案路徑、schema、SQL 片段，不適合未經 sanitize 的遠端部署
 
-## 版本
+## 連結
 
-- **當前版本**: 1.0.0
-- **專案位置**: `/Users/che/Library/CloudStorage/Dropbox/che_workspace/projects/mcp/che-duckdb-mcp`
+- **原始碼**: https://github.com/PsychQuant/che-duckdb-mcp
+- **Releases**: https://github.com/PsychQuant/che-duckdb-mcp/releases
+- **Issues**: https://github.com/PsychQuant/che-duckdb-mcp/issues
diff --git a/plugins/che-duckdb-mcp/bin/che-duckdb-mcp-wrapper.sh b/plugins/che-duckdb-mcp/bin/che-duckdb-mcp-wrapper.sh
index 7cdea749..92a83d5f 100755
--- a/plugins/che-duckdb-mcp/bin/che-duckdb-mcp-wrapper.sh
+++ b/plugins/che-duckdb-mcp/bin/che-duckdb-mcp-wrapper.sh
@@ -1,30 +1,88 @@
 #!/bin/bash
-# Auto-download wrapper for CheDuckDBMCP
-REPO="kiki830621/che-duckdb-mcp"
+# Version-aware auto-download wrapper for CheDuckDBMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheDuckDBMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-duckdb-mcp"
 BINARY_NAME="CheDuckDBMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
     if [[ -z "$URL" ]]; then
-        echo "ERROR: No download URL found. Install manually: https://github.com/$REPO/releases" >&2
-        echo "  cd /path/to/che-duckdb-mcp && swift build -c release" >&2
-        echo "  cp .build/release/$BINARY_NAME ~/bin/" >&2
-        exit 1
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-        || { echo "ERROR: Download failed." >&2; exit 1; }
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-duckdb-mcp/hooks/check-duckdb.sh b/plugins/che-duckdb-mcp/hooks/check-duckdb.sh
new file mode 100755
index 00000000..4cfe3a44
--- /dev/null
+++ b/plugins/che-duckdb-mcp/hooks/check-duckdb.sh
@@ -0,0 +1,29 @@
+#!/bin/bash
+# Session start check for che-duckdb-mcp
+
+BINARY_NAME="CheDuckDBMCP"
+REPO="PsychQuant/che-duckdb-mcp"
+
+FOUND=""
+for loc in "$HOME/bin/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
+    if [[ -x "$loc" ]]; then
+        FOUND="$loc"
+        break
+    fi
+done
+
+if [[ -n "$FOUND" ]]; then
+    LOCAL_VERSION=$(timeout 2 "$FOUND" --version 2>/dev/null | awk '{print $NF}')
+    LATEST=$(curl -sL --max-time 3 "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null \
+        | grep '"tag_name"' | head -1 | sed 's/.*"v\{0,1\}\([^"]*\)".*/\1/')
+    if [[ -n "$LATEST" && -n "$LOCAL_VERSION" && "$LOCAL_VERSION" != "$LATEST" ]]; then
+        NEWER=$(printf '%s\n%s\n' "$LOCAL_VERSION" "$LATEST" | sort -V | tail -1)
+        if [[ "$NEWER" == "$LATEST" ]]; then
+            echo "⬆️  $BINARY_NAME $LOCAL_VERSION → v$LATEST available"
+            echo "   Update: curl -fsSL https://github.com/$REPO/releases/latest/download/$BINARY_NAME -o $HOME/bin/$BINARY_NAME && chmod +x $HOME/bin/$BINARY_NAME"
+        fi
+    fi
+else
+    echo "⚠️  $BINARY_NAME not found — wrapper.sh will auto-download on first MCP call"
+    echo "   Manual install: https://github.com/$REPO/releases"
+fi
diff --git a/plugins/che-duckdb-mcp/hooks/hooks.json b/plugins/che-duckdb-mcp/hooks/hooks.json
new file mode 100644
index 00000000..91266256
--- /dev/null
+++ b/plugins/che-duckdb-mcp/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-duckdb.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/che-duckdb-mcp/skills/che-duckdb-mcp/SKILL.md b/plugins/che-duckdb-mcp/skills/che-duckdb-mcp/SKILL.md
new file mode 100644
index 00000000..09dc6e37
--- /dev/null
+++ b/plugins/che-duckdb-mcp/skills/che-duckdb-mcp/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: che-duckdb-mcp
+description: Guide for using the che-duckdb-mcp MCP tools to search DuckDB documentation and operate local DuckDB databases. Use when user asks about DuckDB SQL syntax, DuckDB functions (read_csv, json_extract, etc.), querying local .duckdb files, or anything related to DuckDB.
+allowed-tools:
+  - mcp__plugin_che-duckdb-mcp_duckdb__*
+---
+
+# che-duckdb-mcp — DuckDB Documentation & Local Database
+
+14 tools split into documentation queries (8) and local database operations (6). The MCP runs the tools; this skill tells you *when* to use them vs alternatives.
+
+## Decision tree: which tool for which question?
+
+### "How do I use DuckDB function X?"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__get_function_docs { function_name: "X" }
+```
+
+- Supports fuzzy matching: `read_csvs` → `read_csv`, `JSON_EXTRACT` → `json_extract`
+- **Prefer this over WebFetch** — offline cached, Levenshtein-tolerant
+- **Prefer this over Grep** — already indexed by the parser
+
+### "What's the DuckDB SQL syntax for X?"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__get_sql_syntax { statement: "COPY" }   # SELECT, INSERT, CREATE TABLE, etc.
+```
+
+- Use for SQL statements (SELECT, INSERT, CREATE, COPY, ATTACH, etc.)
+- For general concepts ("window functions", "CTEs") use `search_docs` instead
+
+### "Search DuckDB docs for keyword X"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__search_docs { query: "window functions", mode: "all", limit: 10 }
+```
+
+- Uses TF-IDF ranking (not substring match) — order matters, first result is usually best
+- `mode`: `title` (fastest), `content`, `all` (default)
+- Results include `source` field: `llms.txt` (concise) or `duckdb-docs.md` (full); llms.txt hits get 1.5× score bonus
+- **Prefer this over WebFetch duckdb.org** — offline, ranked, no network round trip
+
+### "Show me section X of the docs"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__list_sections [{ level: 2 }]       # browse structure
+mcp__plugin_che-duckdb-mcp_duckdb__get_section { id: "..." }          # fetch by anchor id
+mcp__plugin_che-duckdb-mcp_duckdb__get_section { title: "COPY" }      # fuzzy title match
+```
+
+### "List all DuckDB functions"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__list_functions
+```
+
+### "My doc results look outdated"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__refresh_docs        # force re-download both llms.txt + duckdb-docs.md
+mcp__plugin_che-duckdb-mcp_duckdb__get_doc_info        # shows per-source lastUpdated, sectionCount, cachePath
+```
+
+Normally not needed — the MCP uses ETag/Last-Modified conditional HTTP caching, so it auto-refreshes when upstream changes.
+
+---
+
+## Local database operations
+
+### "Connect to a .duckdb file"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__db_connect { path: "/abs/path/to/file.duckdb", read_only: true }
+```
+
+- `path` omitted → in-memory database
+- **Storage version check** happens automatically before opening — incompatible files return a structured `storageVersionMismatch` error with upgrade suggestion
+- For **remote / MotherDuck cloud** databases, use `mcp-server-motherduck` instead (this MCP is local-only)
+
+### "Run a SELECT query"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__db_query { sql: "SELECT ...", format: "markdown", limit: 1000 }
+```
+
+- Allowed: SELECT / WITH / SHOW / DESCRIBE / EXPLAIN / PRAGMA
+- DDL / DML → `db_execute`
+- `format`: `json` (default), `markdown` (best for reading), `csv`
+- Default `limit: 1000` — override explicitly if user needs full table
+
+### "Run CREATE / INSERT / UPDATE / DELETE"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__db_execute { sql: "CREATE TABLE ... AS SELECT ..." }
+```
+
+### "What tables are there? What's this table's schema?"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__db_list_tables [{ include_views: true, schema: "main" }]
+mcp__plugin_che-duckdb-mcp_duckdb__db_describe { table: "users" }              # by name
+mcp__plugin_che-duckdb-mcp_duckdb__db_describe { query: "SELECT a+b FROM t" }  # result schema
+```
+
+### "What version / state is the DB in?"
+
+```
+mcp__plugin_che-duckdb-mcp_duckdb__db_info
+```
+
+Returns DuckDB engine version, `swiftBindingRevision` (pinned), connection path, table count, read-only state.
+
+---
+
+## When NOT to use this MCP
+
+| User wants | Use instead |
+|------------|-------------|
+| MotherDuck cloud database | `mcp-server-motherduck` |
+| Remote / S3 .duckdb files | `mcp-server-motherduck` (supports `s3://`) |
+| DuckDB installation / build guide | WebFetch `duckdb.org/docs/installation` |
+| Very recent DuckDB release notes (hours old) | WebFetch `github.com/duckdb/duckdb/releases` |
+| Writing SQL for other dialects (Postgres, SQLite) | Don't use this — DuckDB-specific |
+
+## Error messages to expect
+
+**Real DuckDB errors now surface cleanly** (as of v2.0.0):
+
+- `Binder Error: Referenced column "X" not found in FROM clause! Candidate bindings: "Y"` — typo in column name
+- `Catalog Error: Table with name X does not exist! Did you mean "Y"?` — typo in table name
+- `Parser Error: syntax error at or near "X"` — SQL syntax problem
+- `storageVersionMismatch` — file newer than current duckdb-swift
+
+Previously these were all `DuckDB.DatabaseError error N` opaque strings — if you see that, the MCP binary is outdated and needs rebuild from the fix commit `a8b5a88` or later.
+
+## Architecture notes
+
+- MCP source: https://github.com/PsychQuant/che-duckdb-mcp
+- `duckdb-swift` pinned to commit `d90cf8d` (DuckDB v1.5.0-dev)
+- Docs cache at `~/.cache/che-duckdb-mcp/` (llms.txt + duckdb-docs.md + cache-meta.json)
+- Both documentation sources are merged into a single TF-IDF inverted index at startup
diff --git a/plugins/che-ical-mcp/.claude-plugin/plugin.json b/plugins/che-ical-mcp/.claude-plugin/plugin.json
index ac82d339..5f0017e7 100644
--- a/plugins/che-ical-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-ical-mcp/.claude-plugin/plugin.json
@@ -1,8 +1,19 @@
 {
   "name": "che-ical-mcp",
-  "version": "1.3.1",
-  "description": "macOS 行事曆與提醒事項 MCP Server - EventKit 整合，25 個工具，MCP 層級 #標籤（Apple 無原生標籤 API）、冪等寫入、重複事件、地點觸發、結構化位置、彈性日期解析、模糊匹配、篩選/排序/限制",
-  "author": { "name": "Che Cheng" },
+  "version": "1.11.1",
+  "description": "macOS 行事曆與提醒事項 MCP Server - EventKit 整合，29 個工具，--cli 直接呼叫模式、--setup TCC 預授權、--self-update 自我升級+SHA-256 驗證、個別事件時區、復原/重做、週期事件 occurrence 操作、cleanup_completed_reminders 一鍵清除、清除到期日、星期驗證、MCP 層級 #標籤、冪等寫入、重複事件、地點觸發、結構化位置、彈性日期解析、模糊匹配、篩選/排序/限制",
+  "author": {
+    "name": "Che Cheng"
+  },
   "license": "MIT",
-  "keywords": ["mcp", "calendar", "reminders", "eventkit", "macos", "productivity", "i18n", "tags"]
+  "keywords": [
+    "mcp",
+    "calendar",
+    "reminders",
+    "eventkit",
+    "macos",
+    "productivity",
+    "i18n",
+    "tags"
+  ]
 }
diff --git a/plugins/che-ical-mcp/CHANGELOG.md b/plugins/che-ical-mcp/CHANGELOG.md
new file mode 100644
index 00000000..9039bd36
--- /dev/null
+++ b/plugins/che-ical-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.7.2] - (date unknown — please fill in)
+
+### Changed
+- macOS 行事曆與提醒事項 MCP Server - EventKit 整合，28 個工具，--cli 直接呼叫模式、--setup TCC 預授權、個別事件時區、復原/重做、週期事件 occurrence 操作、清除到期日、星期驗證、MCP 層級 #標籤、冪等寫入、重複事件、地點觸發、結構化位置、彈性日期解析、模糊匹配、篩選/排序/限制
diff --git a/plugins/che-ical-mcp/CLAUDE.md b/plugins/che-ical-mcp/CLAUDE.md
new file mode 100644
index 00000000..caff5746
--- /dev/null
+++ b/plugins/che-ical-mcp/CLAUDE.md
@@ -0,0 +1,69 @@
+# che-ical-mcp — Plugin Overview
+
+macOS Calendar & Reminders MCP server with native EventKit integration. Binary shipped as `.mcpb` bundle (Claude Desktop) and via wrapper auto-download (Claude Code plugin).
+
+## Components
+
+### Skills (`skills/`)
+
+- **calendar-management** — Primary guide for using the 29 MCP tools (event CRUD, reminder CRUD, batch operations, search, conflict detection, duplicate finding, --cli mode). Reference for what each tool does and when to use it.
+- **troubleshoot-tcc** — TCC permission diagnostic walkthrough. Use when user reports calendar tools failing silently / permission denied / missing dialog after upgrade. Wraps the v1.9.0 `--print-tcc-path` diagnostic flag into a 5-step fix flow.
+
+### Commands (`commands/`)
+
+- `/today` — Today's events + pending reminders, grouped by time
+- `/week` — This week's events overview
+- `/quick-event` — Fast event creation flow
+- `/remind` — Quick reminder creation
+- `/check-tcc` — Print current TCC state + ready-to-paste reset / re-prompt commands (v1.9.1+)
+
+### Rules (`rules/`)
+
+- **eventkit-error-debugging.md** — TCC-first rule: when EventKit tools return `accessDenied` / `insufficientAccess` / `unknownAuthState`, always suspect TCC state before code bugs. Routes Claude to `troubleshoot-tcc` skill rather than retry-and-hope or premature code investigation.
+
+### Hooks (`hooks/`)
+
+- `check-mcp.sh` — Validate MCP server availability on session start
+- `verify-weekday.sh` — Sanity-check weekday calculations
+
+### Binary distribution (`bin/`)
+
+`che-ical-mcp-wrapper.sh` auto-downloads the notarized binary from GitHub releases on first install. See `mcpb/README.md` in the source repo for `.mcpb` bundle installation.
+
+## Version history (recent)
+
+- **v1.9.0** (2026-05-11) — TCC access gate refactor (#108 Phase 2): removed `hasCalendarAccess` / `hasReminderAccess` cache anti-pattern; replaced with per-call `EKEventStore.authorizationStatus(for:)` check via new `AuthorizationGate` + `AuthorizationStatusSource` test seam. Bundles `--print-tcc-path` diagnostic flag (#109).
+- **v1.8.1** (2026-05-11) — Phase 1: `mcpb/README.md` post-install / upgrade TCC permission setup guide.
+- **v1.8.0** (2026-05-11) — Wire-format consistency wave (#101 cluster): `detail_level` / `fields` / `display_timezone` / `limit` response-shape parameters.
+
+See `CHANGELOG.md` in source repo for full history.
+
+## Source
+
+https://github.com/PsychQuant/che-ical-mcp
+
+## Working with this plugin
+
+### When user reports calendar / reminder issues
+
+1. **First**: read the error. If it's TCC-flavored (`accessDenied` / `insufficientAccess` / `unknownAuthState` / "permission denied"), apply `rules/eventkit-error-debugging.md` — invoke `troubleshoot-tcc` skill or suggest `/check-tcc` command.
+2. **Second**: if TCC is verified healthy and the tool still fails, then debug the tool itself per normal investigation (re-read the relevant tool's MCP schema, check arguments, look for `calendarNotFound` / `invalidTimeRange` / etc.).
+3. **Never**: blindly retry a TCC-flavored error or suggest reinstall as first action.
+
+### When user wants to work with calendar / reminders
+
+Use `calendar-management` skill as the entry point — it covers tool selection, argument shapes, common workflows. Use slash commands for shortcuts (`/today`, `/week`, `/quick-event`, `/remind`).
+
+### When making bulk operations
+
+- Prefer batch tools (`create_events_batch`, `delete_events_batch`, `move_events_batch`) over loops
+- Always use `--dry-run` first for destructive ops (see `delete_events_batch` schema)
+- Check `find_duplicate_events` before mass-creating
+
+### TCC permission model (mental model)
+
+- TCC binds grants to **binary path + Developer ID + signing requirement**, NOT cdhash
+- Same Developer ID + same path = grant survives binary upgrades (verified across v1.7.x → v1.9.0)
+- v1.9.0+ checks status per-call so user-driven changes (System Settings toggle / `tccutil reset` / future macOS policy shifts) surface immediately
+- `--mcpb` install path: `~/Library/Application Support/Claude/Claude Extensions/local.mcpb.che-cheng.che-ical-mcp/server/CheICalMCP`
+- `tccutil reset SERVICE bundleID` may silently no-op against path-keyed entries — `--setup` is the reliable re-prompt path
diff --git a/plugins/che-ical-mcp/README.md b/plugins/che-ical-mcp/README.md
index 4869728e..a7436901 100644
--- a/plugins/che-ical-mcp/README.md
+++ b/plugins/che-ical-mcp/README.md
@@ -2,14 +2,21 @@
 
 Claude Code plugin for macOS Calendar & Reminders management using native EventKit.
 
+> ## ℹ️ Why use this plugin instead of the `.mcpb` Claude Desktop install?
+>
+> Claude Desktop **1.6608.2+** (2026-05-09 release) **broke Calendar / Reminders write access for `.mcpb` extension installs** — see [`PsychQuant/che-ical-mcp#132`](https://github.com/PsychQuant/che-ical-mcp/issues/132) and [`anthropics/claude-code#58239`](https://github.com/anthropics/claude-code/issues/58239). This Claude Code plugin path is **not affected** — it spawns the binary via a different process chain that doesn't go through the broken `disclaimer` wrapper. If you tried `.mcpb` and hit "Calendar access denied", install this plugin instead.
+
 ## Features
 
-- **20 MCP Tools**: Complete calendar and reminder management
+- **29 MCP Tools**: Complete calendar and reminder management with attendees / organizer support, batch operations, undo/redo, and one-call cleanup
 - **Skills**: Guided calendar management workflow
 - **Commands**: Quick shortcuts for common operations
 - **Auto-detection**: Automatically finds installed MCP binary
-- **Setup check**: Warns if MCP is not installed on session start
+- **Setup check**: Warns if MCP is not installed on session start (version-aware auto-download since v1.7.2)
 - **i18n Week Support**: Configurable week start day (Monday/Sunday/Saturday/System)
+- **Per-event timezone**: Each event can carry its own timezone instead of relying on the system default
+- **Day-of-week verification hook** (PreToolUse): catches "Friday 2026-04-26" mismatches before they reach Calendar.app
+- **Flexible date parsing + fuzzy matching**: natural-language date strings + close-match suggestions when calendar / event names don't exactly match
 
 ## Installation
 
@@ -18,11 +25,11 @@ Claude Code plugin for macOS Calendar & Reminders management using native EventK
 ```bash
 # Download the binary
 mkdir -p ~/bin
-curl -L https://github.com/kiki830621/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
+curl -L https://github.com/PsychQuant/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP
 chmod +x ~/bin/CheICalMCP
 ```
 
-Or download `.mcpb` from [Releases](https://github.com/kiki830621/che-ical-mcp/releases) for one-click install.
+Or download `.mcpb` from [Releases](https://github.com/PsychQuant/che-ical-mcp/releases) for one-click install.
 
 On first use, macOS will prompt for **Calendar** and **Reminders** access - click "Allow".
 
@@ -93,33 +100,31 @@ Or just ask naturally:
 - "Show my pending reminders"
 - "Add a reminder to call mom"
 
-## Available Tools (20)
+## Available Tools (29)
 
-### Calendars
+### Calendars (4)
 - `list_calendars` - List all calendars
 - `create_calendar` - Create new calendar
+- `update_calendar` - Update calendar metadata
 - `delete_calendar` - Delete calendar
 
-### Events
-- `list_events` - List events in date range
-- `list_events_quick` - Quick range shortcuts
-- `create_event` - Create event
-- `update_event` - Update event
-- `delete_event` - Delete event
-- `search_events` - Search by keywords
-- `check_conflicts` - Check time conflicts
-- `copy_event` - Copy/move event
-- `create_events_batch` - Batch create
-- `move_events_batch` - Batch move
-- `delete_events_batch` - Batch delete
-- `find_duplicate_events` - Find duplicates
-
-### Reminders
-- `list_reminders` - List reminders
-- `create_reminder` - Create reminder
-- `update_reminder` - Update reminder
-- `complete_reminder` - Mark complete
-- `delete_reminder` - Delete reminder
+### Events (12)
+- `list_events` / `list_events_quick` — list by range or shortcut
+- `search_events` — keyword search
+- `create_event` / `update_event` / `delete_event` — single ops
+- `copy_event` — copy or move event across calendars
+- `check_conflicts` — time-overlap detection
+- `create_events_batch` / `move_events_batch` / `delete_events_batch` — batch ops
+- `find_duplicate_events` — surface duplicates for cleanup
+
+### Reminders (10)
+- `list_reminders` / `search_reminders` / `list_reminder_tags`
+- `create_reminder` / `update_reminder` / `complete_reminder` / `delete_reminder`
+- `create_reminders_batch` / `delete_reminders_batch` — batch ops
+- `cleanup_completed_reminders` — single-call cleanup of all completed reminders (`dry_run=true` default; new in v1.7.2)
+
+### Undo / Redo (3, process-local)
+- `undo` / `redo` / `undo_history`
 
 ## Permissions
 
@@ -129,18 +134,72 @@ This plugin requires macOS permissions:
 
 ## Version
 
-Plugin version: 0.8.2 (matches MCP server version)
+Plugin version: 1.10.0 (matches MCP server version)
 
 ### Changelog
 
-**0.8.2** (2026-01-30)
-- Fixed week boundary calculation (no longer depends on system locale)
-- Added `week_starts_on` parameter for international week definitions
-- Supports: `system`, `monday` (ISO 8601), `sunday` (US/Japan), `saturday` (Middle East)
-
-**0.8.1** (2026-01-25)
-- Fixed `update_event` time validation bug
-- Added `all_day` parameter to `update_event`
+**1.10.0** (2026-05-12)
+- **TCC drift detector + startup banner** (#122): single-shot `[banner]` line on MCP-server-mode startup with version/path/PID + drift signals (TCC.db path mismatch per-service, stale running processes). Banner is advisory, stderr-only, opt-out via `CHE_ICAL_MCP_NO_BANNER=1`. Hardened against CWE-117 stderr-injection on every interpolated value (R1 sanitization).
+- **R3.3 production POSIX hygiene fix**: parent pipe write-end fd close in `LiveTCCDatabaseSource` + `LiveProcessInventorySource`. R1's read-before-wait order fix was complementary; R3.3 completes the POSIX EOF contract that local macOS 26 masked via aggressive fd scheduling but GHA macos-15-arm64 reliably deadlocked on.
+- **#131 CI hardening**: 8 tests (5 binary-spawn banner + 3 real-server dispatch) compile-time excluded on CI via `#if !CI_BUILD` + `-Xswiftc -DCI_BUILD` workflow flag. Root cause: EventKit framework blocks on TCC prompt in macOS 15 (Sequoia) headless CI sandbox, where macOS 26 (Tahoe) returns `.denied` synchronously. CI runs 330/330; local runs 338/338. Tracked in #131.
+
+**1.9.1** (2026-05-11, plugin shell only)
+- 4 plugin-shell additions exposing v1.9.0 TCC features: `troubleshoot-tcc` skill (5-step diagnostic), `/check-tcc` slash command, `eventkit-error-debugging` rule (routes accessDenied/insufficientAccess/unknownAuthState investigations to TCC-first), CLAUDE.md plugin overview.
+
+**1.9.0** (2026-05-11)
+- **TCC access gate refactor** (#108 Phase 2, closes #109): removes process-lifetime `hasCalendarAccess`/`hasReminderAccess` cache anti-pattern; replaces with per-call `EKEventStore.authorizationStatus(for:)` cheap check via new `AuthorizationGate` + `AuthorizationStatusSource` test seam. Aligns with Apple TN3153 documented per-call pattern — TCC state changes surface immediately as actionable `accessDenied`/`insufficientAccess`/`unknownAuthState` errors instead of silent fail.
+- **`--print-tcc-path` diagnostic flag** (#109): prints binary path, bundle identifier, EventKit authorization status, `tccutil reset` snippet (with bundle ID interpolated), `sqlite3` TCC.db query snippet, and System Settings paths. Designed for `.mcpb` installed users who need to locate the extracted binary path before running `--setup` from Terminal.
+
+**1.8.1** (2026-05-11, documentation only)
+- `mcpb/README.md` post-install / upgrade TCC permission setup guide (#108 Phase 1). Diagnoses the silent-failure mode where reinstalling `.mcpb` invalidates the existing TCC grant.
+
+**1.8.0** (2026-05-11)
+- **Wire-format consistency wave** — closes #101 cluster (5 issues: #102 #103 #104 #106 #107) in 3 days, full IDD lifecycle + 6-AI ensemble verify per issue
+- **Event listing response-shape parameters** (#47/#101): `detail_level` (`summary`/`standard`), `fields` allow-list, `display_timezone` (strict IANA), `limit` (cap 10000) — LLM token-usage tuning
+- **Envelope unification — BREAKING wire-format** (#102/#107): `list_events`/`list_reminders` `metadata.returned` removed; all 5 list/search envelopes use top-level `<entity>_count` with pre-limit semantic; `search_reminders.result_count` → `reminder_count`; `search_reminders` gains `limit` parameter
+- **Validator hardening** (#101 F1–F3): `Int.max` DoS trap closed, `detail_level`/`display_timezone` validators no longer silent-coerce non-string inputs, `UTC` echo round-trips verbatim
+- **Runtime-anchored drift detection** (#103, strengthening #101 M3): `formatEventDict` ↔ `validEventFields` divergence test now via `EventFormattingSource` test seam + `FakeFormattableEvent`
+- **CHANGELOG reclass** (#106): wire-format renames moved from `Fixed` → `Changed` (Keep a Changelog 1.1.0)
+- **Release pipeline fix**: `build-mcpb.sh` pre-pack defense now derives Team ID from `DEVELOPER_ID` cert via `security find-identity` (was incorrectly comparing SHA hash against `Authority=` human-readable string)
+
+**1.7.2** (2026-05-07)
+- **Tool count 28 → 29**: `cleanup_completed_reminders` (#21) — single-call cleanup of all completed reminders, `dry_run=true` default
+- **`--self-update` flag** (#49): existing-install upgrade path with SHA-256 verification (#98). Wrapper auto-download covers fresh-install only; this fills the gap
+- **Sanitizer hardening cluster** (#73 #74 #80 #85 #86 #94): full C0+DEL escape coverage, executeUndo/executeRedo title interpolation guard, CLIRunner stderr trusted-branch carve-out, DoS amplification cap, thread-safety doc with macOS PIPE_BUF=512
+- **CI test workflow** (#51): PR-time `swift build` + `swift test` on macos-latest
+- **`make install-signed`** (#50): maintainer dev TCC flow on macOS 26
+- **Distribution polish**: README install snippets `rm -f` preamble (#90), zh-TW v1.7.1 sync (#75)
+- All 30+ commits with `Refs #N` IDD discipline + 6-AI parallel verify before merge
+
+**1.7.2-pre** (2026-04-22, pre-release plugin shell bump only)
+- Plugin wrapper now version-aware: re-downloads `~/bin/CheICalMCP` when binary lags upstream Release
+
+**1.7.1** (2026-04-20)
+- Repo URL migration: kiki830621 → PsychQuant org (no behavior change)
+
+**1.7.0** (2026-04-01)
+- Attendee + organizer info exposed on read paths
+- Tool count reaches 28 (added `find_duplicate_events`, batch operations, etc.)
+
+**1.6.0** (2026-03-30)
+- Tool surface broadened to cover full reminders CRUD + tag listing
+
+**1.5.0** (2026-03-29)
+- Per-event timezone support (no longer pinned to system locale)
+- Undo / redo on calendar mutations
+- 28 tools total
+
+**1.3.x – 1.4.x** (2026-02-22 – 2026-03-23)
+- Day-of-week verification PreToolUse hook (catches "Friday 2026-04-26" mismatches)
+- i18n SessionStart / current-time helper
+- Alarms support on `update_event`
+
+**1.0.0 – 1.2.x** (2026-02-06 – 2026-02-23)
+- Initial stable release; iCal binary auto-install + update check
+
+**0.8.x – 0.9.x** (2026-01-30)
+- Week boundary calculation fix; `week_starts_on` parameter (`system` / `monday` / `sunday` / `saturday`)
+- `update_event` time validation fix; `all_day` parameter
 
 ## Author
 
diff --git a/plugins/che-ical-mcp/bin/che-ical-mcp-wrapper.sh b/plugins/che-ical-mcp/bin/che-ical-mcp-wrapper.sh
index edcde21a..4b9a960c 100755
--- a/plugins/che-ical-mcp/bin/che-ical-mcp-wrapper.sh
+++ b/plugins/che-ical-mcp/bin/che-ical-mcp-wrapper.sh
@@ -1,28 +1,88 @@
 #!/bin/bash
-# Auto-download wrapper for CheICalMCP
-REPO="kiki830621/che-ical-mcp"
+# Version-aware auto-download wrapper for CheICalMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheICalMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-ical-mcp"
 BINARY_NAME="CheICalMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
     if [[ -z "$URL" ]]; then
-        echo "ERROR: No download URL found. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-        || { echo "ERROR: Download failed." >&2; exit 1; }
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-ical-mcp/commands/check-tcc.md b/plugins/che-ical-mcp/commands/check-tcc.md
new file mode 100644
index 00000000..806c6106
--- /dev/null
+++ b/plugins/che-ical-mcp/commands/check-tcc.md
@@ -0,0 +1,44 @@
+---
+name: check-tcc
+description: Print che-ical-mcp's current TCC permission state, binary path, and ready-to-paste reset / re-prompt commands. Use when user says "check TCC", "permission status", "tccutil"。
+allowed-tools:
+  - Bash
+---
+
+# Check TCC Permission State
+
+Run the v1.9.0+ binary's `--print-tcc-path` diagnostic, then present the output in a structured format.
+
+## Execution
+
+1. **Locate the binary**:
+
+   ```bash
+   BINARY=$(find ~/Library/Application\ Support/Claude -name CheICalMCP 2>/dev/null | head -1)
+   ```
+
+   If empty → tell user `.mcpb` is not installed in Claude Desktop and point to https://github.com/PsychQuant/che-ical-mcp/releases/latest
+
+2. **Run the diagnostic**:
+
+   ```bash
+   "$BINARY" --print-tcc-path
+   ```
+
+3. **Present the output** with a quick interpretation:
+
+   | Status | Meaning | Next step |
+   |---|---|---|
+   | `fullAccess (granted)` | ✅ OK | Tools should work |
+   | `notDetermined` | Never asked | Run `"$BINARY" --setup` from Terminal |
+   | `denied` | Explicitly denied | `tccutil reset` + re-grant via Step 3 |
+   | `writeOnly` | Partial access | Upgrade in System Settings manually |
+   | `restricted` | System policy | Check Screen Time / MDM |
+
+4. **If user wants the full troubleshooting walkthrough**, suggest `troubleshoot-tcc` skill or paste the `mcpb/README.md` link.
+
+## Why this command exists
+
+v1.9.0 introduced `--print-tcc-path` to close the documentation gap from #108 Phase 1 — `.mcpb` users couldn't easily find the extracted binary path to run `tccutil reset` or `--setup`. This slash command is the natural-language entry point: user says "check my calendar permissions" → command runs the flag → output is self-explanatory.
+
+Pair with `troubleshoot-tcc` skill when the output indicates a fix is needed.
diff --git a/plugins/che-ical-mcp/hooks/check-mcp.sh b/plugins/che-ical-mcp/hooks/check-mcp.sh
index 8b0adc4b..5fe9e759 100755
--- a/plugins/che-ical-mcp/hooks/check-mcp.sh
+++ b/plugins/che-ical-mcp/hooks/check-mcp.sh
@@ -3,7 +3,7 @@
 
 BINARY_NAME="CheICalMCP"
 INSTALL_PATH="$HOME/bin/$BINARY_NAME"
-GITHUB_REPO="kiki830621/che-ical-mcp"
+GITHUB_REPO="PsychQuant/che-ical-mcp"
 RELEASE_URL="https://github.com/$GITHUB_REPO/releases/latest/download/$BINARY_NAME"
 
 # Possible installation locations
diff --git a/plugins/che-ical-mcp/rules/eventkit-error-debugging.md b/plugins/che-ical-mcp/rules/eventkit-error-debugging.md
new file mode 100644
index 00000000..b6aa6e7c
--- /dev/null
+++ b/plugins/che-ical-mcp/rules/eventkit-error-debugging.md
@@ -0,0 +1,41 @@
+# EventKit Error Debugging — TCC-First Rule
+
+When **any** che-ical-mcp tool returns an EventKit-related error (`accessDenied`, `insufficientAccess`, `unknownAuthState`, or `permission denied`-flavored messages), **do not assume a code bug**. The first hypothesis must be **TCC state**, not the tool's logic.
+
+## Why
+
+Pre-v1.9.0 the binary cached `hasCalendarAccess` / `hasReminderAccess` for the process lifetime. After v1.9.0 the cache is removed — every tool call freshly reads `EKEventStore.authorizationStatus(for:)`. This means: when you see `accessDenied`, **the TCC state at this moment really is denied** (or notDetermined / writeOnly / restricted). The error reflects reality.
+
+Pre-v1.9.0 you could rationalize "maybe the cache is stale, retry will work"; post-v1.9.0 retry produces the same error because TCC reality hasn't changed. Fixing TCC state is the only path forward.
+
+## What to do
+
+1. **Stop**. Do not retry the failing tool.
+2. **Invoke the `troubleshoot-tcc` skill** or run the `/check-tcc` slash command (both wrap the v1.9.0 `--print-tcc-path` diagnostic flag).
+3. Read the binary's output carefully — it self-describes the current state and the appropriate fix path.
+4. Only after `--print-tcc-path` shows `fullAccess (granted)` for both Calendar and Reminders, retry the original tool call.
+5. **If the tool still fails after TCC state is verified healthy**, then suspect a real bug:
+   - Capture the full error message + `--print-tcc-path` output + tool name + arguments
+   - File an issue at https://github.com/PsychQuant/che-ical-mcp/issues
+
+## What NOT to do
+
+- ❌ Don't retry the same tool hoping the cache "refreshes" (post-v1.9.0 there is no cache)
+- ❌ Don't immediately suggest user reinstall — reinstall doesn't fix TCC state, it only adds friction
+- ❌ Don't blame transient errors — TCC errors are not transient
+- ❌ Don't tell user to "restart Claude Desktop" as the first action — that only helps if TCC was just granted (Step 4 of troubleshoot-tcc), not as a generic fix
+- ❌ Don't drift into code investigation (re-reading EventKitManager.swift, etc.) until TCC state is ruled out
+
+## When this rule does NOT apply
+
+- Errors that aren't TCC-flavored: `calendarNotFound`, `invalidTimeRange`, `weekdayMismatch`, etc. — those are real validation / lookup issues, debug per usual.
+- Build / compile errors — not a runtime TCC issue.
+- Errors from non-EventKit tools.
+
+## Reference
+
+- `troubleshoot-tcc` skill — full 4-step diagnostic walkthrough
+- `/check-tcc` — quick state read
+- `mcpb/README.md` (v1.8.1+) — user-facing setup guide
+- Issue #108 (closed) — full RCA + falsified cdhash hypothesis + corrected cache anti-pattern
+- Apple TN3153 — per-call `authorizationStatus(for:)` recommended pattern
diff --git a/plugins/che-ical-mcp/skills/troubleshoot-tcc/SKILL.md b/plugins/che-ical-mcp/skills/troubleshoot-tcc/SKILL.md
new file mode 100644
index 00000000..23f7c4bd
--- /dev/null
+++ b/plugins/che-ical-mcp/skills/troubleshoot-tcc/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: troubleshoot-tcc
+description: Diagnose and fix macOS TCC (Calendar/Reminders) permission issues for che-ical-mcp. Use when user reports calendar tools failing silently, "permission denied" errors, missing TCC dialog after reinstall/upgrade, or asks "為什麼 calendar 不能用". Walks through TCC db inspection, --print-tcc-path diagnostic, tccutil reset, and --setup re-prompt flow.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Troubleshoot TCC permissions for che-ical-mcp
+
+This skill is the **first thing to try** when calendar / reminder tools fail. Most "calendar tools don't work" reports are TCC (Transparency, Consent & Control) state issues rather than code bugs.
+
+## When to invoke
+
+User-reported symptoms that map to TCC issues:
+- "Calendar 工具沒回應 / 失敗 / permission denied"
+- "重新安裝 / 升級 mcpb 後不能用"
+- "TCC 對話框沒彈出來"
+- 收到 `accessDenied` / `insufficientAccess` / `unknownAuthState` error
+- Tool calls return blank results despite valid arguments
+
+## Diagnostic flow (4 steps)
+
+### Step 1: Locate the binary
+
+```bash
+find ~/Library/Application\ Support/Claude -name CheICalMCP 2>/dev/null | head -1
+```
+
+Expected: a path under `local.mcpb.che-cheng.che-ical-mcp/server/CheICalMCP`.
+
+If empty → `.mcpb` not installed in Claude Desktop. Send user to https://github.com/PsychQuant/che-ical-mcp/releases/latest
+
+### Step 2: Run `--print-tcc-path` (v1.9.0+ diagnostic flag)
+
+```bash
+BINARY=$(find ~/Library/Application\ Support/Claude -name CheICalMCP 2>/dev/null | head -1)
+"$BINARY" --print-tcc-path
+```
+
+The output is the single source of truth — read it carefully:
+
+| Output line | Meaning |
+|---|---|
+| `Calendar: fullAccess (granted)` | OK, this side is fine |
+| `Calendar: notDetermined` | Never asked → go to Step 4 (run `--setup`) |
+| `Calendar: denied` | Explicitly denied → go to Step 3 (reset) |
+| `Calendar: writeOnly` | Partial access (macOS 14+) → user must manually upgrade in System Settings → Privacy & Security → Calendar |
+| `Calendar: restricted` | System policy (Screen Time / MDM) — outside our control |
+
+Same logic applies to `Reminders` line.
+
+### Step 3: Reset stale TCC entries (only if `denied` or post-upgrade silent fail)
+
+```bash
+tccutil reset Calendar com.checheng.CheICalMCP
+tccutil reset Reminders com.checheng.CheICalMCP
+```
+
+> **Caveat**: TCC stores `.mcpb` clients by **binary path** rather than bundle ID. `tccutil reset SERVICE BUNDLE_ID` may report "Successfully reset" but actually no-op when the underlying entry is path-keyed. If the issue persists after reset + Step 4, fall back to manual System Settings toggle (Step 5).
+
+### Step 4: Trigger re-prompt via `--setup`
+
+```bash
+"$BINARY" --setup
+```
+
+Two macOS dialogs should appear (Calendar + Reminders) — user clicks **Allow** on both.
+
+If running over SSH or in a non-interactive shell, dialogs **cannot** appear — instruct user to run this in `Terminal.app` directly.
+
+### Step 5: Manual fallback (when --setup keeps failing)
+
+System Settings → Privacy & Security → Calendar:
+- Look for CheICalMCP, toggle on
+- If not listed, click `+`, navigate to the binary path from Step 1
+
+Repeat for Reminders.
+
+Restart Claude Desktop after granting.
+
+## Verifying the fix worked
+
+```bash
+sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
+  "SELECT service, client, auth_value, datetime(last_modified,'unixepoch','localtime') FROM access WHERE client LIKE '%CheICalMCP%'"
+```
+
+Expected: 2 rows with `auth_value=2` (granted) and `last_modified` matching today's date.
+
+Then trigger a tool call to confirm:
+
+```
+list 我今天的 events
+```
+
+## Why not just retry the failing tool?
+
+Pre-v1.9.0 binary cached the granted state in `hasCalendarAccess` / `hasReminderAccess` flags for process lifetime. After v1.9.0 the cache is removed — every tool call freshly reads `EKEventStore.authorizationStatus(for:)`, so TCC state changes surface immediately. Per-call status check means **the error you see is the current truth**, not a stale cached signal — fix the TCC state, retry the tool.
+
+## When this is NOT a TCC issue
+
+If `--print-tcc-path` shows both `fullAccess (granted)` but tools still fail with `accessDenied` or other errors:
+- TCC state is healthy → real bug, file an issue at https://github.com/PsychQuant/che-ical-mcp/issues
+- Include full error message + `--print-tcc-path` output + the failing tool name + arguments
+
+## References
+
+- mcpb/README.md (v1.8.1+): user-facing setup guide same workflow
+- Issue #108: full diagnosis of the cache anti-pattern + cdhash invalidation hypothesis (falsified) + corrected root cause
+- Issue #109: `--print-tcc-path` diagnostic flag (closed in v1.9.0)
+- Apple TN3153: per-call `authorizationStatus(for:)` recommended pattern
diff --git a/plugins/che-latex-mcp/.claude-plugin/plugin.json b/plugins/che-latex-mcp/.claude-plugin/plugin.json
new file mode 100644
index 00000000..12a917a0
--- /dev/null
+++ b/plugins/che-latex-mcp/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "che-latex-mcp",
+  "version": "0.5.0",
+  "description": "讓 AI 完全清楚 LaTeX 修正的結果 — 改一行 source 立刻知道 PDF 第幾頁變了、變成什麼樣、有沒有副作用、有沒有新 bug、PDF review 的紅圈對到哪個 source 位置。通用 LaTeX 工具,任何專案都可用。20 tools（編譯 / git ref 視覺 diff / layout overlap 偵測 / 字型缺字 / 半形標點 / chunk preview / annotation 抽取 + grep 反查）+ 4 skills。",
+  "author": { "name": "Che Cheng" },
+  "license": "MIT",
+  "keywords": ["mcp", "latex", "xelatex", "pdf", "typesetting", "visual-diff", "layout-detection", "macos"]
+}
diff --git a/plugins/che-latex-mcp/.mcp.json b/plugins/che-latex-mcp/.mcp.json
new file mode 100644
index 00000000..8125455e
--- /dev/null
+++ b/plugins/che-latex-mcp/.mcp.json
@@ -0,0 +1,7 @@
+{
+  "che-latex-mcp": {
+    "type": "stdio",
+    "command": "${CLAUDE_PLUGIN_ROOT}/bin/che-latex-mcp-wrapper.sh",
+    "description": "LaTeX 專案管理 — 編譯、視覺 diff、排版偵測、字型/標點檢查（18 tools）"
+  }
+}
diff --git a/plugins/che-latex-mcp/CHANGELOG.md b/plugins/che-latex-mcp/CHANGELOG.md
new file mode 100644
index 00000000..35de8873
--- /dev/null
+++ b/plugins/che-latex-mcp/CHANGELOG.md
@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to che-latex-mcp will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-05-18
+
+### Added — Pillar 5: Annotation-driven workflow
+
+通用的 PDF review 工作流支援。MCP 從 18 → 20 tools。
+
+- `extract_annotations(pdf_path)` — 從 reviewed PDF 抽出所有 annotations（FreeText / Text / Note / Highlight），含 page + bbox + comment + surrounding text，JSON 結構化回傳
+- `annotation_to_source(surrounding_text, source_dir)` — 給 annotation surrounding text，grep source 找對應 file:line 候選，支援 `exclude_dirs` / `file_extensions` caller-supplied 參數
+
+設計原則：MCP 只做 **generic primitive**（抽 raw annotation + grep source），**不做 classification / verification**。專案特有的分類規則由 caller skill / script 處理。
+
+### Fixed
+
+- **Server `waitUntilCompleted()` 缺失（CRITICAL）**：v0.4.0 起 `LatexMCPApp.main()` 缺 `await server.waitUntilCompleted()`，導致 stdio MCP server 在 `server.start()` 後立刻 return，process 收到第一個 request 就 exit。Plugin 連線 fragile。v0.5.0 修正
+- Plugin description 改為強調 **通用 LaTeX 工具**（不綁定特定領域）
+
+### Internal
+
+- 新增 `Sources/che-latex-mcp/Pillar5Tools.swift` — Pillar 5 tool 實作
+- 擴充 `Helpers.swift` — `PDFAnnotationData` / `AnnotationExtractor` / `SourceLine` / `SourceIndex`（全 generic，無 project-specific 假設）
+- `SourceIndex.load()` 接 caller-supplied `excludeDirs` + `fileExtensions`，default 不排除任何 dir
+
+## [0.4.0] - 2026-05-18
+
+### Added
+
+- 初版 plugin（wrap che-latex-mcp v0.4.0 binary）
+- MCP server 含 18 個 tool（8 既有 + 10 新增）
+- 4 個 LaTeX-specific skill：
+  - `latex-validate` — 編譯後 layout audit pipeline
+  - `latex-visual-diff` — git ref 對照視覺 diff
+  - `latex-precompile` — source-level static check（標點/缺字/box）
+  - `latex-preview-chunk` — 片段預覽不必編整本
+- Wrapper script 從 GitHub Release auto-download binary
+- 偏好 `~/Developer/che-mcps/che-latex-mcp` 下的 source build（手動 build 不會被 auto-replace）
+
+### MCP server 新增 tools (v0.3.0 → v0.4.0)
+
+- `compile_diff(git_ref)` — git worktree checkout + 編譯 + 跟當前 PDF 視覺 diff
+- `compare_pdfs` — 兩 PDF 像素級 diff
+- `compile_chunk` — standalone 編譯片段
+- `preview_range` — 批次截多頁
+- `get_page_metrics` — 單頁 layout 數據
+- `extract_blocks` — block bbox + text
+- `find_overlaps` — bbox 重疊偵測
+- `detect_layout_issues` — 綜合 audit
+- `fonts_check` — `.log` 缺字
+- `box_warnings` — `.log` overfull/underfull
+- `punct_check` — source 半形標點偵測
diff --git a/plugins/che-latex-mcp/README.md b/plugins/che-latex-mcp/README.md
new file mode 100644
index 00000000..cb6a184a
--- /dev/null
+++ b/plugins/che-latex-mcp/README.md
@@ -0,0 +1,142 @@
+# che-latex-mcp
+
+> **Mission：讓 AI 完全清楚 LaTeX 修正的結果。**
+>
+> 改了一行 source，AI 必須知道：PDF 第幾頁變了、變成什麼樣、有沒有副作用、有沒有新 bug。不是「我改完了你自己編譯看看」，是 AI 自己看到結果、自己 attribute 影響、自己抓 bug。
+>
+> 通用 LaTeX 工具 — 任何 LaTeX 專案（論文、CV、書、講義、簡報）都可以用，**不綁定特定領域**。
+
+## 為什麼這個 mission 重要
+
+AI 改 LaTeX 一直有個 fundamental 問題：**source 跟 output 中間隔著 xelatex 這個黑盒**。
+
+傳統 loop：
+
+```
+AI 改 source → 跟人說「請編譯看看」→ 人編譯 → 截圖貼回來 → AI 看圖
+                                  ↑ 人卡在這裡，每次 ~30 秒
+```
+
+或自動化但很重的 loop：
+
+```
+AI 改 source → bash xelatex → python render PNG → Read PNG → 視覺判斷
+              ~4 個 tool call、~15 秒、且無 attribution（改了 X 影響到哪幾頁？不知道）
+```
+
+這兩條 loop 的後果：
+
+- **不敢小步改**：每次改都要 ~15 秒驗證，AI 偏向「一次改一大段然後祈禱」，喪失 TDD 紀律
+- **不知道副作用**：改 ch01 line 100，page 187 變空城了 — AI 不會知道，要等人翻 PDF 才發現
+- **看不到細節 bug**：字疊到 box、tikz 跑到頁外、字型缺字成 □ — 這些 PDF 上一眼可見的問題，AI 從 source 完全推不出來
+- **chunk preview 沒人做**：想預覽單一片段，得編整本 PDF，30 秒起跳
+- **PDF review/校稿 對不上 source**：reviewer 在 PDF 畫紅圈寫 comment，AI 不知道怎麼把那些 comment 對到 source code
+
+## 這個 plugin 如何達成 mission
+
+把「看到結果 + attribute 變化 + 抓 bug + 預覽片段 + 對應 review」五件事壓進 single tool call，讓 AI 在改 source 的同時就完全掌握結果。
+
+### 五個 mission pillar
+
+| Pillar | 對應問題 | 解法 | 工具 |
+|---|---|---|---|
+| **1. 看到結果** | 改完不知道長怎樣 | source → PDF → PNG → AI 直接 Read，一個 call 完成 | `compile_latex` + `preview_page` / `preview_range` |
+| **2. Attribute 變化** | 改 X 影響到哪幾頁？不知道 | git ref 對照視覺 diff，紅色高亮所有變動 region | `compile_diff(git_ref)` + `compare_pdfs` |
+| **3. 抓 bug** | 字疊、缺字、跑頁外 — source 看不出 | explicit detector：bbox 重疊、log 缺字、box 警告、CJK 半形標點 | `detect_layout_issues` + `find_overlaps` + `fonts_check` + `box_warnings` + `punct_check` |
+| **4. 預覽片段** | 編整本 30 秒太重 | standalone class wrap → 單頁 PDF → 3x PNG，~3 秒 | `compile_chunk` |
+| **5. 對應 review** | PDF 紅圈 → source 位置斷層 | PDF annotation 抽出 + grep source 反查 | `extract_annotations` + `annotation_to_source` |
+
+### 結果：AI 改 LaTeX 的新 loop
+
+```
+AI 改 source → call compile_diff(HEAD~1) → 拿到 ripple page list + 視覺 diff PNG
+            → call detect_layout_issues  → 拿到所有 overlap / widow / 缺字 warning
+            → AI 直接 Read PNG，知道現在長怎樣、影響到誰、有沒有新 bug
+            → 全 in single AI turn，~5 秒
+```
+
+不必跟人說「請編譯看看」，不必猜「我改的東西會不會影響別處」，不必擔心字型缺字編出來才發現。
+
+收到 PDF review/校稿時：
+
+```
+AI call extract_annotations(pdf) → 拿到所有 reviewer comment + 位置 + surrounding text
+   → 對每條 annotation call annotation_to_source(text, src_dir) → 拿到 file:line 候選
+   → AI 直接編輯對應 source，不必人手動標 location
+```
+
+## 結構
+
+- **MCP server**（20 tools）：編譯、視覺驗證、layout 偵測、字型/標點/box overflow 檢查、PDF annotation 抽取
+- **4 個 skills**：把 tools 串成完整工作流，trigger keywords 自動 invoke
+
+## Tools 一覽（20 個）
+
+### Pillar 1：看到結果（編譯與單頁／批次預覽）
+- `compile_latex` — 編譯（xelatex / pdflatex / lualatex）
+- `preview_page` — 單頁 PDF → PNG（3x 高解析）
+- `preview_range` — 批次截多頁
+- `get_page_content` — 抽頁面文字
+- `find_pagebreaks` / `analyze_pages` — 章節對應頁碼
+- `get_document_info` — 文件 metadata
+- `check_errors` — `.log` 錯誤警告
+
+### Pillar 2：Attribute 變化（git ref 對照）
+- `compile_diff(git_ref)` — git worktree checkout → compile → 跟當前 PDF 視覺 diff，**一次 call 完成 baseline + compare**
+- `compare_pdfs` — 兩 PDF 像素級 diff，紅色高亮變動 region
+
+### Pillar 3：抓 bug（explicit detector）
+- `detect_layout_issues` — 綜合 audit：widow / empty page / overlap
+- `find_overlaps` — block 重疊（字疊／box 重疊 bug）
+- `get_page_metrics` — 單頁 layout 數據（留白比例、block 數、widow 風險）
+- `extract_blocks` — 抽頁面所有 text block（bbox + text + 字數）
+- `fonts_check` — `.log` 字型缺字（U+22EF ⋯ / U+2192 → 等 fallback 成 □）
+- `box_warnings` — `.log` overfull / underfull box
+- `punct_check` — 半形標點夾在 CJK 中間（CJK 上下文偵測）
+
+### Pillar 4：預覽片段（不必編整本）
+- `compile_chunk` — standalone class 編譯片段 → 單頁預覽
+
+### Pillar 5：對應 review（PDF annotation → source）
+- `extract_annotations` — PDF annotation 全抽出（page + bbox + type + comment + surrounding text），JSON 結構化
+- `annotation_to_source` — surrounding text → grep source 找 file:line 候選
+
+Pillar 5 是 **generic primitive**：MCP 只負責「抽出 raw annotation」+「反查 source 位置」，**不做分類 / 驗證**。專案特有的分類規則（哪些 comment 是「字型缺字」、哪些是「跨頁」）由 caller 自己處理（skill / script layer）。
+
+## Skills 一覽（4 個）
+
+| Skill | Trigger | 對應 Pillar | 串接 tools |
+|-------|---------|----------|-----------|
+| `latex-validate` | 「驗證 LaTeX」「audit」「commit 前檢查」 | Pillar 3 | fonts_check → box_warnings → detect_layout_issues → find_overlaps |
+| `latex-visual-diff` | 「視覺 diff」「跟上版比」「我改了 X 影響哪幾頁」 | Pillar 2 | compile_diff(git_ref) 或 compare_pdfs |
+| `latex-precompile` | 「precompile check」「source audit」「掃半形/缺字」 | Pillar 3（source-level） | punct_check + fonts_check + box_warnings |
+| `latex-preview-chunk` | 「預覽這個片段」「不要編整本」 | Pillar 4 | compile_chunk + Read PNG |
+
+## 安裝
+
+```bash
+claude plugin marketplace add PsychQuant/psychquant-claude-plugins
+claude plugin install che-latex-mcp@psychquant-claude-plugins
+```
+
+首次使用會自動從 GitHub Release 下載 binary 到 `~/bin/che-latex-mcp`。
+
+## 系統需求
+
+- macOS 14+
+- TeX Live 或 MacTeX（編譯功能需要）
+- git（`compile_diff(git_ref)` 需要）
+
+## 從 source build
+
+```bash
+git clone https://github.com/kiki830621/che-latex-mcp.git ~/Developer/che-mcps/che-latex-mcp
+cd ~/Developer/che-mcps/che-latex-mcp
+swift build -c release
+```
+
+Wrapper script 會優先用 `~/Developer/che-mcps/che-latex-mcp/.build/release/che-latex-mcp`（從 source build 永遠不會被 auto-replace）。
+
+## License
+
+MIT
diff --git a/plugins/che-latex-mcp/bin/che-latex-mcp-wrapper.sh b/plugins/che-latex-mcp/bin/che-latex-mcp-wrapper.sh
new file mode 100755
index 00000000..31741017
--- /dev/null
+++ b/plugins/che-latex-mcp/bin/che-latex-mcp-wrapper.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+# Wrapper for che-latex-mcp
+# Auto-download binary from GitHub Release if missing or stale.
+# Source builds in $HOME/Developer/... are NEVER auto-replaced.
+
+BINARY_NAME="che-latex-mcp"
+GITHUB_REPO="PsychQuant/che-latex-mcp"
+INSTALL_DIR="$HOME/bin"
+INSTALLED_BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+DESIRED_VERSION="0.5.0"
+DOWNLOAD_TIMEOUT=300
+
+# Find binary — prefer $HOME/bin (release) > source builds
+BINARY=""
+for loc in \
+    "$INSTALLED_BINARY" \
+    "/usr/local/bin/$BINARY_NAME" \
+    "$HOME/.local/bin/$BINARY_NAME" \
+    "$HOME/Developer/che-mcps/che-latex-mcp/.build/release/$BINARY_NAME" \
+    "$HOME/Developer/che-mcps/che-latex-mcp/.build/debug/$BINARY_NAME"
+do
+    [[ -x "$loc" ]] && BINARY="$loc" && break
+done
+
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
+
+if [[ -z "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ "$BINARY" == "$INSTALLED_BINARY" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    # Only auto-upgrade installed binaries; never touch source builds.
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $GITHUB_REPO..." >&2
+    mkdir -p "$INSTALL_DIR"
+
+    # Try pinned tag first, then latest release.
+    URL=""
+    for API_URL in \
+        "https://api.github.com/repos/$GITHUB_REPO/releases/tags/v$DESIRED_VERSION" \
+        "https://api.github.com/repos/$GITHUB_REPO/releases/latest"
+    do
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$INSTALLED_BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+            BINARY="$INSTALLED_BINARY"
+        else
+            echo "$BINARY_NAME: ERROR — no release asset found at $GITHUB_REPO." >&2
+            echo "  Install manually: https://github.com/$GITHUB_REPO/releases" >&2
+            echo "  Or build from source:" >&2
+            echo "    git clone https://github.com/$GITHUB_REPO.git ~/Developer/che-mcps/che-latex-mcp" >&2
+            echo "    cd ~/Developer/che-mcps/che-latex-mcp && swift build -c release" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time "$DOWNLOAD_TIMEOUT" "$URL" -o "${INSTALLED_BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${INSTALLED_BINARY}.tmp"
+            xattr -dr com.apple.quarantine "${INSTALLED_BINARY}.tmp" 2>/dev/null || true
+            mv "${INSTALLED_BINARY}.tmp" "$INSTALLED_BINARY"
+            echo "$DESIRED_VERSION" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v$DESIRED_VERSION" >&2
+            BINARY="$INSTALLED_BINARY"
+        else
+            rm -f "${INSTALLED_BINARY}.tmp" 2>/dev/null
+            if [[ -x "$INSTALLED_BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+                BINARY="$INSTALLED_BINARY"
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+exec "$BINARY" "$@"
diff --git a/plugins/che-latex-mcp/skills/latex-precompile/SKILL.md b/plugins/che-latex-mcp/skills/latex-precompile/SKILL.md
new file mode 100644
index 00000000..6a51d86c
--- /dev/null
+++ b/plugins/che-latex-mcp/skills/latex-precompile/SKILL.md
@@ -0,0 +1,92 @@
+---
+name: latex-precompile
+description: LaTeX source 編譯前的 static check — punct_check（半形/全形標點）+ fonts_check（字型缺字，需既有 .log）+ source-level pattern audit。當用戶說「precompile check」「編譯前檢查」「跑 make check」「source audit」「掃半形標點」「掃缺字」時使用。對應暑期班 typesetting-checklist 的 #A1 字型缺字 + #A5 標點規則。
+---
+
+# LaTeX Precompile Check
+
+編譯之前先跑 source-level static check，把「編譯出來才會發現」的 bug 提前抓出來。比 `make check` 工作流更省事的單一 skill。
+
+## Trigger
+
+用戶說：
+- 「precompile check」「編譯前檢查」「source audit」
+- 「跑 make check」「掃 LaTeX source」
+- 「掃半形標點」「掃缺字」「punct check」「fonts check」
+- 直接 `/latex-precompile`
+
+或 implicit：
+- 用戶 batch Edit 多處 .tex 後（commit 前）
+- 用戶 import 外部 source（如從 Word 轉的 .tex）
+
+## Workflow
+
+### Step 1: punct_check — 半形標點偵測
+
+```
+punct_check(source_path)
+```
+
+- `source_path` 可以是單一 .tex 或目錄（會遞迴掃所有 .tex，自動跳 `_archive`）
+- 偵測 CJK 中間夾雜的半形 `,;:?!()`
+- 智能判斷：括號只在「前後都是 CJK」時才報警，避免誤報 `\foo(x)` 這類 LaTeX 語法
+- 跳過 `$...$` math mode
+- 跳過 `%` 開頭整行 comment
+
+### Step 2: fonts_check — 字型缺字（需要 .log）
+
+```
+fonts_check(project_path, main_file?)
+```
+
+- 從 `.log` 抽 `Missing character: There is no X in font Y!` warnings
+- 自動 dedup（同一字元 + 同一字型只報一次）
+- 回傳 unicode 表 + 字型對照
+
+**前置條件**：必須已編譯過一次（`.log` 存在）。如果沒，先 call `compile_latex` 跑一次（缺字字型 fallback 不會 abort 編譯）。
+
+### Step 3: box_warnings — overfull/underfull box
+
+```
+box_warnings(project_path, main_file?, severity_min?)
+```
+
+- 從 `.log` 抽 box warnings
+- `severity_min` 過濾低分（如「10000」只看 badness ≥ 10000）
+
+### Step 4: 整理回報
+
+整理三個 check 結果成 audit 報告：
+
+```
+## LaTeX precompile check 報告
+
+### ⚠️ 標點符號（punct_check）
+共 N 處：
+- 02_暑期班/.../ch04.tex:L432:C18  ',' → '，'  「⋯⋯」
+- ...
+建議：batch 修這 N 處或跑 autofix_punct.py
+
+### ⚠️ 字型缺字（fonts_check）
+共 M 個 unique：
+| 字元 | Unicode | 字型 |
+|------|---------|------|
+| ⋯   | U+22EF  | Times New Roman |
+建議：⋯ → \dots / \cdots，→ → $\to$
+
+### ⚠️ box 警告（box_warnings, badness ≥ 10000）
+共 K 個：
+- Overfull \hbox (15.23pt too wide) at line N
+- ⋯
+建議：手動檢查指定行，調整 \hyphenpenalty 或加 \\\\ break
+```
+
+## 跟既有 make check 的關係
+
+如果 project 已有 `Makefile` 含 `check`/`check-punct`/`check-fonts` target（如 educator 暑期班的 setup），這 skill 提供更 unified 的 audit — 結果可以 cross-reference 既有 script，但不取代它們（script 跑得快，CI 用 script；互動 audit 用 skill）。
+
+## 注意事項
+
+- **fonts_check 需要 `.log`**：如果 `.log` 不存在會 error。提示用戶先 compile_latex 一次
+- **punct_check 對 _archive 目錄會自動跳過**：但 `99_archive` 之類不會。如果 user 專案用不同 archive 命名，要明說
+- **不要對 ground truth 章節改 source**：如 educator 春季班 ch01-03 是 baseline，即使 punct_check 報半形也不該動（typesetting-checklist 規則：春季班源檔不改）
diff --git a/plugins/che-latex-mcp/skills/latex-preview-chunk/SKILL.md b/plugins/che-latex-mcp/skills/latex-preview-chunk/SKILL.md
new file mode 100644
index 00000000..0ae38d16
--- /dev/null
+++ b/plugins/che-latex-mcp/skills/latex-preview-chunk/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: latex-preview-chunk
+description: 預覽單一 LaTeX 片段（vocabbox / tikz 圖 / 數學公式）不必編整本 PDF — 用 compile_chunk 把片段包進 standalone class 編譯 → 單頁 PNG。當用戶說「預覽這個 vocabbox」「看一下這個 tikz 長怎樣」「試試這個公式」「快速看片段」「不要編整本」時使用。
+---
+
+# LaTeX Preview Chunk
+
+「我改了一個 vocabbox 但不想等 30 秒編整本」這種場景的快速預覽工具。把片段 wrap 進 `standalone` document class 編出單頁 PDF + PNG。
+
+## Trigger
+
+用戶說：
+- 「預覽這個 vocabbox」「看 tikz 圖長怎樣」「試試這個公式」
+- 「不要編整本」「快速看一下」「render 這段」
+- 直接 `/latex-preview-chunk`
+
+或 implicit：
+- 用戶 draft 一段新 vocabbox / tikz / 公式還沒 insert 到主文件
+- 用戶想 iterate tikz layout，每次改完都要立即看結果
+- 用戶問「這個 LaTeX 寫對了嗎」搭配 source 片段
+
+## Workflow
+
+### Step 1: 確認片段內容
+
+如果用戶貼了 LaTeX 片段 → 直接拿來用。
+如果用戶指向 file:line range（如「ch04.tex line 100-120 的 vocabbox」）→ Read 該段 source。
+
+### Step 2: 找對應 preamble
+
+關鍵問題：**這個 chunk 用了哪些 custom command / environment**？
+
+- vocabbox / examitem / tipbox 等 → 需要 commands.tex preamble
+- tikz 用了 custom style → 需要 preamble.tex 或對應設定
+- 純數學 / 純文字 → 不需要 preamble（內建 amsmath 即可）
+
+如果片段引用 custom env，必須給 `preamble_path` 指向 project 的 `commands.tex` 或 `preamble.tex`。沒給 preamble 編 vocabbox 會炸（環境未定義）。
+
+### Step 3: call compile_chunk
+
+```
+compile_chunk(
+  tex_fragment,         # 不含 \documentclass、\begin{document}
+  preamble_path?,       # commands.tex / preamble.tex 路徑（含 custom env 時必填）
+  output_dir?,          # 預設 /tmp/latex_chunk
+  engine?               # 預設 xelatex
+)
+```
+
+工具會：
+1. 把片段 wrap 進 `\documentclass[border=10pt]{standalone}` + `\input{preamble}` + `\begin{document}`
+2. 跑 xelatex 編一次
+3. 產出 PDF + 3x 高解析 PNG
+
+### Step 4: Read 結果 PNG 給用戶看
+
+工具回傳 path，主動 Read PNG 載入視覺結果，給用戶評估。如果 user 看了不滿意要 iterate，回 Step 1。
+
+## 用法範例
+
+### 預覽 vocabbox（最常見）
+
+```
+compile_chunk(
+  tex_fragment: """
+    \\begin{vocabbox}{Cohen's $\\kappa$ 係數}
+    \\begin{vocabdesc}
+      \\item[\\uline{公式}] 校正純機率後的吻合率:
+      $$\\kappa = \\frac{p_o - p_e}{1 - p_e}$$
+    \\end{vocabdesc}
+    \\end{vocabbox}
+  """,
+  preamble_path: "/path/to/project/00_common/commands.tex"
+)
+```
+
+### 預覽 tikz
+
+```
+compile_chunk(
+  tex_fragment: """
+    \\begin{tikzpicture}
+      \\node[draw, rounded corners=8pt] (a) at (0,0) {根節點};
+      ...
+    \\end{tikzpicture}
+  """,
+  preamble_path: "/path/to/project/00_common/preamble.tex"
+)
+```
+
+### 純公式（不需 preamble）
+
+```
+compile_chunk(
+  tex_fragment: """
+    $$\\text{AVE} = \\frac{\\sum_{i=1}^{k} \\lambda_i^2}{k}$$
+  """
+)
+```
+
+## 注意事項
+
+- **standalone class 會把 page 裁切到內容大小**：所以「跨頁切斷」「page break」這類 issue 在 chunk preview 看不出來。要看那種 issue 必須編整本 PDF
+- **preamble.tex 內如果有 `\input{commands}` 之類**：直接 pass preamble.tex 即可，會 cascade load 進來
+- **commands.tex 內含 `\input` 相對路徑** → 可能 work dir 不同會找不到。改 pass 絕對路徑或先 wrap 進臨時 preamble
+- **產出的 PNG 解析度 3x**：適合載入 Read tool 看細節（vocabbox label 跟內容是否對齊、tikz box 是否重疊）
+- **編完不自動刪檔**：output_dir 內留 PDF + PNG + .aux/.log/.tex，下次 call 會覆蓋（同 output_dir）
diff --git a/plugins/che-latex-mcp/skills/latex-validate/SKILL.md b/plugins/che-latex-mcp/skills/latex-validate/SKILL.md
new file mode 100644
index 00000000..54d4bb99
--- /dev/null
+++ b/plugins/che-latex-mcp/skills/latex-validate/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: latex-validate
+description: 編譯 LaTeX 專案後跑完整 layout 驗證流程 — detect_layout_issues + find_overlaps + fonts_check + box_warnings。當用戶說「驗證 LaTeX」「檢查排版」「掃 layout 問題」「LaTeX 編完看看有沒有 bug」「latex audit」或在 LaTeX 專案目錄編譯後想自動 audit 時使用。也適用於 commit 前驗證、release 前 audit、暑校稿 batch 修完想知道剩餘 issue。
+---
+
+# LaTeX Validate
+
+編譯後完整 layout 驗證流程：把 6 個 detector tool 串成一條 audit pipeline，產生整理過的 issue 報告。
+
+## Trigger
+
+用戶說：
+- 「驗證 LaTeX」「LaTeX audit」「掃排版問題」
+- 「編完看看有沒有 bug」「commit 前檢查」
+- 「跑完整檢查」
+- 直接 `/latex-validate`
+
+或 implicit 場景：
+- 剛跑完 compile_latex / latexmk make
+- batch 修了多處 .tex 後（多輪 Edit）
+- release / publish 前
+
+## Workflow
+
+依序執行（用 `mcp__plugin_che-latex-mcp_che-latex-mcp__<tool>` 命名空間）：
+
+### Step 1: 確認 PDF 存在
+
+如果用戶沒指定 `project_path` + `main_file`，問清楚或從 cwd 推斷。確認 PDF 已編譯出來，沒有的話先 `compile_latex` 一次。
+
+### Step 2: source-level 預檢查
+
+```
+fonts_check(project_path, main_file)     # .log 字型缺字
+box_warnings(project_path, main_file)    # overfull/underfull box
+```
+
+這兩個從 `.log` 抓，速度極快（< 100ms），先跑。
+
+### Step 3: PDF-level 視覺檢查
+
+```
+detect_layout_issues(pdf_path, page_range?)
+# → widow heading / empty page / bottom gap / overlap 一次抓完
+```
+
+這是主力 detector。報告會分四類列出問題 page 跟原因。
+
+### Step 4: 重疊細查（如果 detect 報告 overlap）
+
+```
+find_overlaps(pdf_path, problematic_pages, threshold=4.0)
+# → 對問題頁面逐 block 列出重疊位置 + 文字 excerpt
+```
+
+只對 Step 3 報的 overlap pages 跑，不必整本。
+
+### Step 5: 整理 + 提出修法建議
+
+收到 4 個 tool report 後，**不要直接 dump 給用戶**。整理成：
+
+```
+## LaTeX 排版 audit 報告（main.pdf，N 頁）
+
+### ⚠️ Critical（必須修）
+- p.X: widow heading「⋯⋯」← 加 \needspace 或 \clearpage
+- p.Y: block overlap 12.4 pt² ← tikz layout 衝突或字型 ghost
+
+### ⚠️ Warning（建議修）
+- p.Z: 留白 65% ← 可能過度 \clearpage，檢查 line N
+- 字型缺字 ⋯ 3 個（U+22EF / Times New Roman）← 改 \dots
+
+### ✅ Pass
+- 標點符號（如果跑了 punct_check）
+- overfull box（如果 box_warnings 通過）
+```
+
+對每個 issue 給 **具體** 修法建議（哪個 LaTeX 指令 / 哪行加 needspace），不要泛泛說「請調整」。
+
+## 注意事項
+
+- **不要對 reading section / appendix 過度報警**：那些 section 通常排版較鬆，留白比例高是正常。可以在報告中標明「（reading section）」加註。
+- **widow heading 誤報**：tikz 流程圖、章標題前後常有短 block 但不是真的 widow heading。看 Step 4 找 block 文字確認。
+- **threshold 調整**：`find_overlaps` 預設 threshold=4 pt²，數學環境會有偽陽性。如果偽陽性多，調 threshold=50 只看明顯重疊。
diff --git a/plugins/che-latex-mcp/skills/latex-visual-diff/SKILL.md b/plugins/che-latex-mcp/skills/latex-visual-diff/SKILL.md
new file mode 100644
index 00000000..3d40d5af
--- /dev/null
+++ b/plugins/che-latex-mcp/skills/latex-visual-diff/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: latex-visual-diff
+description: 改動 LaTeX source 後做視覺 diff，知道改動影響哪幾頁 — 用 compile_diff(git_ref) 自動 checkout + compile + compare，或用 compare_pdfs 比兩個既存 PDF。當用戶說「視覺 diff」「比較改動前後」「我改了 X 影響哪幾頁」「跟上一版比」「visual regression」時使用。也適用於 batch 修完想驗證、release 前 ripple 檢查。
+---
+
+# LaTeX Visual Diff
+
+「改完不知道影響哪幾頁」是 LaTeX batch 修最大的 friction。這個 skill 把「改動 → 視覺 attribution」壓縮成單一 tool call。
+
+## Trigger
+
+用戶說：
+- 「視覺 diff」「visual diff」「跟上版比」
+- 「我改了 X 影響哪幾頁」「ripple 檢查」
+- 「比較 PDF」「compare pdfs」
+- 直接 `/latex-visual-diff`
+
+或 implicit 場景：
+- 用戶剛 batch Edit 多處 .tex
+- 用戶說「不確定改動範圍」
+- commit / push 前驗證沒 collateral damage
+
+## 兩種模式
+
+### 模式 A：git ref 對照（最常用）
+
+用戶想看「跟某個 commit 比改了什麼」。
+
+```
+compile_diff(
+  project_path,
+  main_file?,    # 預設 main
+  engine?,       # 預設 xelatex
+  git_ref,       # HEAD~1（預設）/ HEAD~3 / branch-name / commit-sha
+  page_range?,
+  output_dir?    # 預設 /tmp/latex_diff
+)
+```
+
+工具會：
+1. `git worktree add` 把 ref checkout 到暫存目錄
+2. 在那邊跑 latexmk 編出 baseline PDF
+3. 跟當前 PDF 做 pixel-level diff（紅色高亮變動區）
+4. 回傳影響 page list + 每頁 diff PNG path
+5. 自動清掉 worktree
+
+**前置條件**：當前 PDF 必須已編譯（current branch 的 main.pdf 存在）。如果還沒，先跑 `compile_latex` 再 call 這個。
+
+### 模式 B：兩個既存 PDF 直接比（手動 baseline）
+
+用戶手動保存 baseline PDF，或要比兩個 release 版本。
+
+```
+compare_pdfs(
+  before_pdf,      # baseline PDF path
+  after_pdf,       # current PDF path
+  page_range?,
+  output_dir?,
+  save_diff_images?  # 預設 true
+)
+```
+
+## Workflow
+
+### Step 1: 判斷模式
+
+問用戶或從 context 推斷：
+- 有 git ref → 模式 A
+- 有兩個 PDF path → 模式 B
+- 都沒有 → 預設模式 A，git_ref = HEAD~1
+
+### Step 2: 跑 diff
+
+call 對應的 tool。等 30 秒 - 2 分鐘（baseline 編譯需要時間）。
+
+### Step 3: 結果整理
+
+工具回傳的是「哪幾頁變了 + diff PNG path」。**不要直接 dump 整 list 給用戶**，而是：
+
+1. **分群**：把連續頁面 group（p.78-82 是同一段改動的 ripple；p.187 是另一處）
+2. **attribute**：根據改動的 .tex source（從 git diff 推），猜每群對應哪個改動
+3. **flag 意外**：如果 user 只改了 ch04 但 ch07 也有頁面變了，highlight 為「意外 ripple」要 user 注意
+
+範例輸出：
+
+```
+## 視覺 diff: HEAD~1 → 當前
+
+改動的 .tex 檔案（從 git diff）：
+- 02_暑期班/part1_心理測驗/ch04_信度/ch04.tex
+- 02_暑期班/00_common/commands.tex
+
+### 影響頁面（共 6 頁）
+
+**Group 1 — ch04 信度（4 頁，預期內）**
+- p.66, 67, 69, 71: 2-15% 像素改變
+- 對應改動：ch04 Cohen κ vocabbox + ICC vocabbox
+- diff PNG: /tmp/latex_diff/diff_p66.png ⋯⋯
+
+**Group 2 — ch10（2 頁，⚠️ 意外 ripple）**
+- p.185, 186: 0.5% 像素改變
+- 對應改動：commands.tex examitem env 改了 → 影響所有 examitem 渲染
+- diff PNG: /tmp/latex_diff/diff_p185.png
+- 建議：抽一頁 visual check 確認 examitem 改動 OK
+```
+
+## 注意事項
+
+- **`compile_diff` 需要 git repo**：如果 project 不在 git 內，會 error，改用 `compare_pdfs` + 手動 baseline
+- **git_ref 必須能編譯**：如果該 ref 的 source 本身有編譯錯誤，baseline 跑不出來。換 ref 或先修 source
+- **巨大 ripple 警訊**：如果 100+ 頁都改了，通常是改了 commands.tex / preamble.tex 這類底層檔案，視覺改變是 expected 但量大要花時間 review
+- **diff PNG 不要全載入 context**：選 2-3 個代表性頁面 Read PNG，其他列 path 不載入
diff --git a/plugins/che-pixel-mcp/.claude-plugin/plugin.json b/plugins/che-pixel-mcp/.claude-plugin/plugin.json
index 728ed54b..9e131a22 100644
--- a/plugins/che-pixel-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-pixel-mcp/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "che-pixel-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pixel MCP Server — Swift 原生 Core Image 操作，36 個工具，200+ 濾鏡，Session-based 點陣圖形編輯",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
diff --git a/plugins/che-pixel-mcp/CHANGELOG.md b/plugins/che-pixel-mcp/CHANGELOG.md
new file mode 100644
index 00000000..2fd87029
--- /dev/null
+++ b/plugins/che-pixel-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [0.1.1] - (date unknown — please fill in)
+
+### Changed
+- Pixel MCP Server — Swift 原生 Core Image 操作，36 個工具，200+ 濾鏡，Session-based 點陣圖形編輯
diff --git a/plugins/che-pixel-mcp/bin/che-pixel-mcp-wrapper.sh b/plugins/che-pixel-mcp/bin/che-pixel-mcp-wrapper.sh
index 287c0cc9..31c499ea 100755
--- a/plugins/che-pixel-mcp/bin/che-pixel-mcp-wrapper.sh
+++ b/plugins/che-pixel-mcp/bin/che-pixel-mcp-wrapper.sh
@@ -1,31 +1,88 @@
 #!/bin/bash
-# Auto-download wrapper for ChePixelMCP
+# Version-aware auto-download wrapper for ChePixelMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.ChePixelMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
 REPO="PsychQuant/che-pixel-mcp"
 BINARY_NAME="ChePixelMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    if command -v gh &>/dev/null; then
-        gh release download --repo "$REPO" --pattern "$BINARY_NAME" --dir "$INSTALL_DIR" --clobber 2>&2 \
-            && chmod +x "$INSTALL_DIR/$BINARY_NAME"
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
     else
-        echo "ERROR: gh CLI not found. Install with: brew install gh" >&2
-        echo "Then run: gh release download --repo $REPO --pattern $BINARY_NAME --dir $INSTALL_DIR" >&2
-        exit 1
-    fi
-    if [[ ! -x "$INSTALL_DIR/$BINARY_NAME" ]]; then
-        echo "ERROR: Download failed. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-svg-mcp/.claude-plugin/plugin.json b/plugins/che-svg-mcp/.claude-plugin/plugin.json
index cb082d6e..c3c985e1 100644
--- a/plugins/che-svg-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-svg-mcp/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "che-svg-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "SVG MCP Server — Swift 原生 XML 操作，33 個工具，Session-based 向量圖形編輯",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
diff --git a/plugins/che-svg-mcp/CHANGELOG.md b/plugins/che-svg-mcp/CHANGELOG.md
new file mode 100644
index 00000000..77352b9e
--- /dev/null
+++ b/plugins/che-svg-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [0.1.1] - (date unknown — please fill in)
+
+### Changed
+- SVG MCP Server — Swift 原生 XML 操作，33 個工具，Session-based 向量圖形編輯
diff --git a/plugins/che-svg-mcp/bin/che-svg-mcp-wrapper.sh b/plugins/che-svg-mcp/bin/che-svg-mcp-wrapper.sh
index 66cef0e2..1506c5d6 100755
--- a/plugins/che-svg-mcp/bin/che-svg-mcp-wrapper.sh
+++ b/plugins/che-svg-mcp/bin/che-svg-mcp-wrapper.sh
@@ -1,31 +1,88 @@
 #!/bin/bash
-# Auto-download wrapper for CheSvgMCP
+# Version-aware auto-download wrapper for CheSvgMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheSvgMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
 REPO="PsychQuant/che-svg-mcp"
 BINARY_NAME="CheSvgMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    if command -v gh &>/dev/null; then
-        gh release download --repo "$REPO" --pattern "$BINARY_NAME" --dir "$INSTALL_DIR" --clobber 2>&2 \
-            && chmod +x "$INSTALL_DIR/$BINARY_NAME"
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
     else
-        echo "ERROR: gh CLI not found. Install with: brew install gh" >&2
-        echo "Then run: gh release download --repo $REPO --pattern $BINARY_NAME --dir $INSTALL_DIR" >&2
-        exit 1
-    fi
-    if [[ ! -x "$INSTALL_DIR/$BINARY_NAME" ]]; then
-        echo "ERROR: Download failed. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-telegram-mcp/.claude-plugin/plugin.json b/plugins/che-telegram-mcp/.claude-plugin/plugin.json
index 9f181c01..9fb8c9a6 100644
--- a/plugins/che-telegram-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-telegram-mcp/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "che-telegram-mcp",
-  "version": "1.0.0",
+  "version": "1.3.1",
   "description": "Telegram MCP Server Plugin — Bot API + 個人帳號 TDLib 全功能存取，28+ 工具，Keychain 密鑰管理",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
diff --git a/plugins/che-telegram-mcp/CHANGELOG.md b/plugins/che-telegram-mcp/CHANGELOG.md
new file mode 100644
index 00000000..117277ff
--- /dev/null
+++ b/plugins/che-telegram-mcp/CHANGELOG.md
@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.3.1] - 2026-05-07
+
+### Fixed
+- `che-telegram-all-mcp-wrapper.sh`: add atomic-claim lock (flock with mkdir fallback) before PID-tracking section. Prevents the multi-window race where window B reads window A's PID, sees an alive `CheTelegramAllMCP` process, sends SIGTERM and unannouncedly kills window A's MCP server. Lock is portable: uses `flock -n` when available (Linux / macOS Sequoia+ if shipped), falls back to atomic `mkdir` directory-claim on systems without flock (verified macOS 26.4.1). Stale-lock cleanup removes orphaned locks whose owner PID is dead. Failure mode is now fail-fast with clear stderr message instead of silent SIGTERM cross-fire. `che-telegram-bot-mcp-wrapper.sh` deliberately unchanged — bot HTTPS API is stateless, multi-instance safe. New regression test (`test-wrapper-pid.sh` test 9) verifies second instance fail-fast + first instance survival. Resolves #10.
+
+## [1.3.0] - (date unknown — please fill in)
+
+### Changed
+- Telegram MCP Server Plugin — Bot API + 個人帳號 TDLib 全功能存取，28+ 工具，Keychain 密鑰管理
diff --git a/plugins/che-telegram-mcp/README.md b/plugins/che-telegram-mcp/README.md
index 3afd184d..848184ec 100644
--- a/plugins/che-telegram-mcp/README.md
+++ b/plugins/che-telegram-mcp/README.md
@@ -1,72 +1,232 @@
-# che-telegram-mcp Plugin
-
-Claude Code plugin for Telegram — combines **Bot API** and **personal account (TDLib)** in one plugin. Credentials are stored in macOS Keychain, never in config files.
-
-## Two MCP Servers
-
-| Server | Identity | Read private chats | Full history | Search |
-|--------|----------|-------------------|-------------|--------|
-| `telegram-all` | Personal account | Yes | Yes | Yes |
-| `telegram-bot` | Bot account | No | No | No |
-
-## Installation
-
-### Step 1: Build MCP Servers
-
-**telegram-all** (requires TDLib, ~300MB first build):
-```bash
-cd ~/Developer/che-mcps
-git clone https://github.com/kiki830621/che-telegram-all-mcp.git
-cd che-telegram-all-mcp && swift build -c release
-```
-
-**telegram-bot** (lightweight):
-```bash
-cd ~/Developer/che-mcps
-git clone https://github.com/kiki830621/che-telegram-bot-mcp.git
-cd che-telegram-bot-mcp && swift build -c release
-```
-
-### Step 2: Store Credentials in Keychain
-
-```bash
-# telegram-all (get from https://my.telegram.org)
-security add-generic-password -a che-telegram-all-mcp -s TELEGRAM_API_ID -w 'YOUR_API_ID' -U
-security add-generic-password -a che-telegram-all-mcp -s TELEGRAM_API_HASH -w 'YOUR_API_HASH' -U
-
-# telegram-bot (get from @BotFather)
-security add-generic-password -a che-telegram-bot-mcp -s TELEGRAM_BOT_TOKEN -w 'YOUR_BOT_TOKEN' -U
-```
-
-### Step 3: Install Plugin
-
-```bash
-claude plugin add --from /path/to/psychquant-claude-plugins/plugins/che-telegram-mcp
-```
-
-### Step 4: First-time Authentication (telegram-all only)
-
-On first use, authenticate your personal account:
-1. Use `/auth` command or ask Claude to authenticate Telegram
-2. Provide your phone number and verification code
-3. Session is saved — won't need to authenticate again
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `/chats` | Show recent Telegram conversations |
-| `/send` | Send a message (with confirmation) |
-| `/search` | Search message history |
-| `/auth` | One-time Telegram authentication |
-
-## Security
-
-- Credentials never appear in config files — always read from macOS Keychain at runtime
-- Personal account access can read **all** private chats — use responsibly
-- Messages are confirmed before sending
-- Session data: `~/Library/Application Support/che-telegram-all-mcp/tdlib/`
-
-## License
-
-MIT
+# che-telegram-mcp Plugin
+
+Claude Code plugin for Telegram — bundles **personal account (TDLib)** and **Bot API** MCP servers in one plugin. Credentials are stored in macOS Keychain, never in config files.
+
+## Two paths, one plugin
+
+This plugin ships two independent MCP servers. Pick the one(s) you need — wrappers lazy-download binaries, so an unused server costs you nothing.
+
+| Server | Identity | What it can do | Binary size | When to use |
+|--------|----------|----------------|-------------|-------------|
+| `telegram-all` | **Your personal Telegram account** (via TDLib) | Read all your private chats, send as you, search full history, manage groups, dump chats to Markdown | ~223 MB | "I want my own Telegram automated" — reading conversations, drafting replies, archiving chats |
+| `telegram-bot` | **A Telegram bot** (via Bot API) | Send/receive messages as a bot, manage chats the bot is in, get updates | ~16 MB | "I want a bot to post updates / take commands" — notifications, integrations, public chat moderation |
+
+Most personal-automation users want **`telegram-all` only**. Bot integrations are a separate use case.
+
+---
+
+## Quick start — pick your track
+
+### Track A — Personal account only (most common)
+
+You want to read/send messages as **yourself**.
+
+```bash
+# 1. Install plugin
+/plugin install che-telegram-mcp@psychquant-claude-plugins
+
+# 2. Store API credentials (from https://my.telegram.org/apps)
+security add-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_API_ID" -w 'YOUR_API_ID' -U
+security add-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_API_HASH" -w 'YOUR_API_HASH' -U
+
+# Optional: 2FA password (auto-entered if your account has 2FA)
+security add-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_2FA_PASSWORD" -w 'YOUR_2FA_PASSWORD' -U
+
+# Optional: phone number (auto-entered to skip the prompt)
+security add-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_PHONE" -w '+886912345678' -U
+
+# 3. Authenticate (one-time; SMS code is the only thing you must enter live)
+/auth
+```
+
+Don't want the bot server spawning at startup? Add this to `.claude/settings.json` in your project (or `~/.claude/settings.json` for user-wide):
+
+```json
+{
+  "disabledMcpjsonServers": ["telegram-bot"]
+}
+```
+
+### Track B — Bot only
+
+You want a **bot** to post messages or receive commands. No personal account.
+
+```bash
+# 1. Install plugin
+/plugin install che-telegram-mcp@psychquant-claude-plugins
+
+# 2. Store bot token (get one from @BotFather in Telegram)
+security add-generic-password -a "che-telegram-bot-mcp" -s "TELEGRAM_BOT_TOKEN" -w 'YOUR_BOT_TOKEN' -U
+
+# 3. Disable the personal-account server (skip TDLib download entirely)
+```
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "disabledMcpjsonServers": ["telegram-all"]
+}
+```
+
+That's it — bot tools are now available without ever fetching the 223 MB TDLib binary.
+
+### Track C — Both servers
+
+You actually use both. Run all three keychain commands from Track A **plus** the one from Track B, then `/auth`. No `disabledMcpjsonServers` needed.
+
+---
+
+## How wrappers work
+
+The plugin's wrappers (`bin/che-telegram-{all,bot}-mcp-wrapper.sh`) detect your installation in this order:
+
+1. `~/bin/$BINARY_NAME`
+2. `/usr/local/bin/$BINARY_NAME`
+3. `~/.local/bin/$BINARY_NAME`
+4. Source build at `~/Developer/che-msg/che-telegram-{all,bot}-mcp/.build/release/$BINARY_NAME`
+
+If none are found on first invocation, the wrapper **lazy-downloads** the binary from the latest [GitHub Release](https://github.com/PsychQuant/che-msg/releases/latest), strips the macOS quarantine flag, and caches it in `~/bin/`. A disabled server never triggers a download.
+
+### Auto-upgrade (v1.3.0+)
+
+The wrapper pins a **`DESIRED_VERSION`** matching the binary the plugin expects and writes a `~/bin/.${BINARY_NAME}.version` sidecar each time it installs.
+
+When the plugin is updated and the desired version changes, the wrapper detects the sidecar mismatch on the next MCP server spawn and atomically re-downloads (`.tmp` → `mv`) — falling back to the last installed binary if the network fails. Source builds under `~/Developer/...` are never auto-replaced.
+
+A **SessionStart hook** (`hooks/check-mcp.sh`) verifies on every session that:
+
+- Both binaries are installed (or buildable from source) — printing the installed version next to `✓`
+- Required Keychain entries exist
+- Compares the sidecar against `releases/latest` and prints `⬆️` when a newer release is available (silent when offline / rate-limited)
+
+It prints `⚠️` warnings with copy-pasteable fix commands when something is missing. If you've disabled a server via `disabledMcpjsonServers`, you can ignore its warnings (the hook checks both servers regardless of disable state).
+
+### Manual install (if auto-download fails)
+
+```bash
+mkdir -p ~/bin
+curl -L https://github.com/PsychQuant/che-msg/releases/latest/download/CheTelegramAllMCP -o ~/bin/CheTelegramAllMCP
+curl -L https://github.com/PsychQuant/che-msg/releases/latest/download/CheTelegramBotMCP -o ~/bin/CheTelegramBotMCP
+chmod +x ~/bin/CheTelegramAllMCP ~/bin/CheTelegramBotMCP
+xattr -dr com.apple.quarantine ~/bin/CheTelegramAllMCP ~/bin/CheTelegramBotMCP
+```
+
+> **Universal binary**: prebuilt binaries are Mach-O universal (arm64 + x86_64), so they run on both Apple Silicon and Intel Macs. Building from source: `git clone https://github.com/PsychQuant/che-msg.git && cd che-msg/che-telegram-all-mcp && swift build -c release`.
+
+## Included Components
+
+### MCP Servers
+
+| Server | Identity | Read private chats | Full history | Search |
+|--------|----------|-------------------|--------------|--------|
+| `telegram-all` | Personal account (TDLib) | Yes | Yes | Yes |
+| `telegram-bot` | Bot account (Bot API) | No (only chats the bot is in) | No (24h fetch window) | No |
+
+### Skills
+
+| Skill | Description |
+|-------|-------------|
+| `telegram-messaging` | Routes Claude to the right server (all vs bot) and walks through auth, reading, sending, search, history |
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/auth` | Walk through one-time authentication for personal account |
+| `/chats` | Show recent Telegram conversations |
+| `/search` | Search Telegram message history |
+| `/send` | Send a message to a chat |
+
+## Usage Examples
+
+```
+/auth                            → Set up personal account (one-time)
+/chats                           → See recent conversations
+/search 會議紀錄                   → Search across chats
+/send @alice "see you tomorrow"  → Send a message
+```
+
+Or just ask naturally:
+
+- "What did Bob say in the project group last week?"
+- "Send 'on my way' to Alice"
+- "Dump my chat with Carol from January to a Markdown file"
+- "Show me the last 50 messages from the dev channel"
+
+## Available Tools
+
+### `telegram-all` (Personal Account, TDLib) — 28 tools
+
+**Auth (6)**: `auth_status`, `auth_run`, `auth_set_parameters`, `auth_send_phone`, `auth_send_code`, `auth_send_password`
+
+**Read (8)**: `get_me`, `get_chats`, `get_chat`, `get_chat_history`, `search_chats`, `search_messages`, `get_chat_members`, `get_contacts`
+
+**Write (5)**: `send_message`, `edit_message`, `delete_messages`, `forward_messages`, `mark_as_read`
+
+**Manage (4)**: `pin_message`, `unpin_message`, `set_chat_title`, `set_chat_description`
+
+**Group (2)**: `create_group`, `add_chat_member`
+
+**Export (1)**: `dump_chat_to_markdown` — one-shot export with optional `since_date` / `until_date` / `max_messages`
+
+**Other (2)**: `logout`, `get_user`
+
+> v0.5.0 added `auth_run` — a single tool drives the entire auth state machine. See [v0.5.0 release notes](https://github.com/PsychQuant/che-msg/releases/tag/v0.5.0).
+
+### `telegram-bot` (Bot API)
+
+`get_me`, `get_updates`, `send_message`, `forward_message`, `get_chat`, `get_chat_administrators`, `get_chat_member_count`, `get_chat_member`, `set_chat_title`, `set_chat_description`, `pin_chat_message`, `unpin_chat_message`, `unpin_all_chat_messages`, `ban_chat_member`, `unban_chat_member`, `restrict_chat_member`, `promote_chat_member`, `leave_chat`, `delete_message`, `edit_message_text`, `copy_message`, `send_photo`, `send_document`, `send_video`, `send_audio`, `send_sticker`, `send_location`, `send_poll`, `set_my_commands`, `get_my_commands`, `delete_my_commands`
+
+## Permissions
+
+This plugin requires:
+
+- **macOS Keychain** access for credential storage
+- **Network** access for the Telegram API
+- **Disk** access for TDLib's local database (`~/Library/Application Support/che-telegram-all-mcp/`) — only used by `telegram-all`
+
+## Version
+
+Plugin version: 1.3.0 (currently pins `che-telegram-all-mcp` v0.5.0 + `che-telegram-bot-mcp` v0.5.0 binaries; wrapper auto-upgrades on version mismatch)
+
+### Changelog
+
+**1.3.0** (2026-04-28)
+
+- **Auto-upgrade wrappers**: each wrapper now pins a `DESIRED_VERSION` and writes a `~/bin/.${BINARY_NAME}.version` sidecar on install. When the plugin bumps the desired version, the wrapper detects the sidecar mismatch and atomically re-downloads (`.tmp` → `mv`) on next spawn. Source builds in `~/Developer/...` are never auto-replaced. Falls back to the existing binary on network failure (no brick).
+- **SessionStart hook upgrade notice**: `check-mcp.sh` now reads the sidecar to display installed version, queries `releases/latest`, and prints `⬆️ v0.4.3 → v0.5.0 available` when behind upstream. Silent when offline or rate-limited.
+- Pin telegram-bot binary at v0.5.0 (built from same monorepo as telegram-all v0.5.0).
+
+**1.2.1** (2026-04-27)
+
+- Fix `hooks/check-mcp.sh` source-build path: previously pointed at `~/Developer/che-mcps/che-msg/.build/release/...`, which doesn't exist (che-msg is a monorepo, the Swift packages live in sub-dirs `che-telegram-all-mcp/` and `che-telegram-bot-mcp/`). Now mirrors the wrapper's exact 5-path search (incl. `~/Developer/che-msg/<package>/.build/release/<binary>`).
+- Fix `check-mcp.sh` build instruction: was `cd che-msg && swift build -c release` (no Package.swift at monorepo root), now `cd ~/Developer/che-msg/<package> && swift build -c release --product <binary>`.
+- `check-mcp.sh` no longer warns about optional Keychain entries (`TELEGRAM_PHONE`, `TELEGRAM_2FA_PASSWORD`); they're shown only when present and silently skipped when absent.
+- `check-mcp.sh` footer now documents `disabledMcpjsonServers` so users running only one server know how to suppress the other's warnings.
+
+**1.2.0** (2026-04-27)
+
+- Documentation restructure: explicit "Two paths, one plugin" framing with three quickstart tracks (personal-account only / bot only / both)
+- README now documents how to disable an unused server via `disabledMcpjsonServers` in `settings.json`
+- Skill (`telegram-messaging`) restructured to route between `telegram-all` and `telegram-bot` with server-specific tool guidance
+- Skill `allowed-tools` removed: previous list used the wrong namespace prefix (`mcp__che-telegram-mcp__*` vs actual `mcp__plugin_che-telegram-mcp_telegram-{all,bot}__*`), so the allowlist was effectively ignored. Without it, plugin tools are accessible normally.
+
+**1.1.0** (2026-04-16)
+
+- Wrappers auto-download binaries from GitHub Release if not installed locally
+- Wrapper PID tracking refinements (Test 7 SIGKILL race fix)
+- Currently bundles `che-telegram-all-mcp` v0.4.3, which closes [PsychQuant/che-telegram-all-mcp#1](https://github.com/PsychQuant/che-telegram-all-mcp/issues/1) — TDLib auth error handling overhaul (structured `code`/`message` errors, snake_case decoder regression test, code 406 silent-ignore per protocol)
+
+**1.0.2** (earlier)
+
+- Wrapper PID tracking added
+
+## Source
+
+- Plugin source: [PsychQuant/psychquant-claude-plugins](https://github.com/PsychQuant/psychquant-claude-plugins/tree/main/plugins/che-telegram-mcp)
+- Binary source: [PsychQuant/che-msg](https://github.com/PsychQuant/che-msg) — also mirrored at [PsychQuant/che-telegram-all-mcp](https://github.com/PsychQuant/che-telegram-all-mcp) for the personal-account MCP
+
+## Author
+
+Created by **Che Cheng** ([@kiki830621](https://github.com/kiki830621))
diff --git a/plugins/che-telegram-mcp/bin/che-telegram-all-mcp-wrapper.sh b/plugins/che-telegram-mcp/bin/che-telegram-all-mcp-wrapper.sh
index f77a9419..3fa8d1bd 100755
--- a/plugins/che-telegram-mcp/bin/che-telegram-all-mcp-wrapper.sh
+++ b/plugins/che-telegram-mcp/bin/che-telegram-all-mcp-wrapper.sh
@@ -1,36 +1,210 @@
-#!/bin/bash
-# Wrapper for che-telegram-all-mcp (personal account via TDLib)
-# Credentials are read from macOS Keychain at runtime — never stored in config files.
-
-BINARY_NAME="CheTelegramAllMCP"
-GITHUB_REPO="kiki830621/che-telegram-all-mcp"
-
-# Find binary
-BINARY=""
-for loc in "$HOME/bin/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME" "$HOME/Developer/che-mcps/che-telegram-all-mcp/.build/release/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
-
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found." >&2
-    echo "Build from source:" >&2
-    echo "  git clone https://github.com/$GITHUB_REPO.git" >&2
-    echo "  cd che-telegram-all-mcp && swift build -c release" >&2
-    echo "  cp .build/release/$BINARY_NAME ~/bin/" >&2
-    exit 1
-fi
-
-# Read credentials from macOS Keychain
-export TELEGRAM_API_ID="$(security find-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_API_ID" -w 2>/dev/null)"
-export TELEGRAM_API_HASH="$(security find-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_API_HASH" -w 2>/dev/null)"
-
-if [[ -z "$TELEGRAM_API_ID" || -z "$TELEGRAM_API_HASH" ]]; then
-    echo "Telegram API credentials not found in Keychain." >&2
-    echo "Set them up:" >&2
-    echo "  security add-generic-password -a che-telegram-all-mcp -s TELEGRAM_API_ID -w 'YOUR_ID' -U" >&2
-    echo "  security add-generic-password -a che-telegram-all-mcp -s TELEGRAM_API_HASH -w 'YOUR_HASH' -U" >&2
-    echo "Get credentials at: https://my.telegram.org" >&2
-    exit 1
-fi
-
-exec "$BINARY" "$@"
+#!/bin/bash
+# Wrapper for che-telegram-all-mcp (personal account via TDLib)
+# Credentials are read from macOS Keychain at runtime — never stored in config files.
+#
+# Auto-upgrade design (v1.3.0+):
+# - DESIRED_VERSION below pins the binary version this plugin expects.
+# - ~/bin/.CheTelegramAllMCP.version sidecar tracks what's installed.
+# - On mismatch, re-downloads from GitHub Release (atomic .tmp + mv).
+# - Source builds in $HOME/Developer/... are NEVER auto-replaced.
+
+BINARY_NAME="CheTelegramAllMCP"
+GITHUB_REPO="PsychQuant/che-msg"
+INSTALL_DIR="$HOME/bin"
+INSTALLED_BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+DESIRED_VERSION="0.5.0"
+DOWNLOAD_TIMEOUT=600  # universal binary ~220MB; allow slow links
+
+# Find binary — prefer $HOME/bin (installed from release) > source builds
+BINARY=""
+for loc in "$INSTALLED_BINARY" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME" "$HOME/Developer/che-msg/che-telegram-all-mcp/.build/release/$BINARY_NAME" "$HOME/Developer/che-mcps/che-telegram-all-mcp/.build/release/$BINARY_NAME"; do
+    [[ -x "$loc" ]] && BINARY="$loc" && break
+done
+
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
+
+if [[ -z "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ "$BINARY" == "$INSTALLED_BINARY" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    # Only auto-upgrade installed binaries; never touch source builds.
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $GITHUB_REPO..." >&2
+    mkdir -p "$INSTALL_DIR"
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "https://api.github.com/repos/$GITHUB_REPO/releases/tags/v$DESIRED_VERSION" \
+        "https://api.github.com/repos/$GITHUB_REPO/releases/latest"
+    do
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$INSTALLED_BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+            BINARY="$INSTALLED_BINARY"
+        else
+            echo "$BINARY_NAME: ERROR — no release asset found at $GITHUB_REPO." >&2
+            echo "  Install manually: https://github.com/$GITHUB_REPO/releases" >&2
+            echo "  Or build from source:" >&2
+            echo "    git clone https://github.com/$GITHUB_REPO.git ~/Developer/che-msg" >&2
+            echo "    cd ~/Developer/che-msg/che-telegram-all-mcp && swift build -c release --product $BINARY_NAME" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time "$DOWNLOAD_TIMEOUT" "$URL" -o "${INSTALLED_BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${INSTALLED_BINARY}.tmp"
+            xattr -dr com.apple.quarantine "${INSTALLED_BINARY}.tmp" 2>/dev/null || true
+            mv "${INSTALLED_BINARY}.tmp" "$INSTALLED_BINARY"
+            echo "$DESIRED_VERSION" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v$DESIRED_VERSION" >&2
+            BINARY="$INSTALLED_BINARY"
+        else
+            rm -f "${INSTALLED_BINARY}.tmp" 2>/dev/null
+            if [[ -x "$INSTALLED_BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+                BINARY="$INSTALLED_BINARY"
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+# Read credentials from macOS Keychain
+export TELEGRAM_API_ID="$(security find-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_API_ID" -w 2>/dev/null)"
+export TELEGRAM_API_HASH="$(security find-generic-password -a "che-telegram-all-mcp" -s "TELEGRAM_API_HASH" -w 2>/dev/null)"
+
+if [[ -z "$TELEGRAM_API_ID" || -z "$TELEGRAM_API_HASH" ]]; then
+    echo "Telegram API credentials not found in Keychain." >&2
+    echo "Set them up:" >&2
+    echo "  security add-generic-password -a che-telegram-all-mcp -s TELEGRAM_API_ID -w 'YOUR_ID' -U" >&2
+    echo "  security add-generic-password -a che-telegram-all-mcp -s TELEGRAM_API_HASH -w 'YOUR_HASH' -U" >&2
+    echo "Get credentials at: https://my.telegram.org" >&2
+    exit 1
+fi
+
+# --- Atomic-claim lock (#10) ---
+# TDLib DB is single-instance — two MCP servers can't share it. The previous
+# PID-tracking strategy (#8) is racy on multi-window scenarios: window B reads
+# window A's PID, sees an alive CheTelegramAllMCP process, sends SIGTERM →
+# kills window A's server unannounced. Atomic claim prevents that: window B
+# finds the lock held, fails fast, lets the user decide which window keeps it.
+LOCK_DIR="$HOME/.cache/che-telegram-all-mcp.lock"
+LOCK_FILE="${LOCK_DIR}.flock"
+LOCK_MODE=""
+
+mkdir -p "$(dirname "$LOCK_DIR")"
+
+if command -v flock >/dev/null 2>&1; then
+    LOCK_MODE="flock"
+    exec 200>"$LOCK_FILE"
+    if ! flock -n 200; then
+        echo "$BINARY_NAME: Another instance is already running. Use the existing Claude Code window, or kill the previous wrapper first." >&2
+        exit 1
+    fi
+    # fd 200 stays open through wrapper lifetime; OS releases on exit
+else
+    LOCK_MODE="mkdir"
+    if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+        # Stale-lock cleanup: if owner PID is dead, remove and retry once
+        OWNER_PID=
+        [ -f "$LOCK_DIR/owner.pid" ] && read -r OWNER_PID < "$LOCK_DIR/owner.pid" 2>/dev/null
+        if [[ "$OWNER_PID" =~ ^[0-9]+$ ]] && ! kill -0 "$OWNER_PID" 2>/dev/null; then
+            rm -rf "$LOCK_DIR"
+            mkdir "$LOCK_DIR" 2>/dev/null || {
+                echo "$BINARY_NAME: Failed to claim lock (stale-cleanup race). Retry shortly." >&2
+                exit 1
+            }
+        else
+            echo "$BINARY_NAME: Another instance is already running (lock held by PID ${OWNER_PID:-?}). Use the existing Claude Code window, or kill the previous wrapper first." >&2
+            exit 1
+        fi
+    fi
+    echo $$ > "$LOCK_DIR/owner.pid"
+fi
+
+# --- PID tracking (#8, retained for cleanup() bookkeeping) ---
+# Atomic claim above prevents the multi-instance race. The PID file below is
+# now used solely by cleanup() to know which child to reap, not to gate startup.
+# The old "kill the previous PID if alive" branch is now unreachable because the
+# lock above would have refused, so the residual logic just resets a dead PID
+# file from a crashed wrapper without sending signals.
+PID_FILE="$HOME/.cache/che-telegram-all-mcp.pid"
+mkdir -p "$(dirname "$PID_FILE")"
+
+if [[ -f "$PID_FILE" ]]; then
+    OLD_PID=
+    read -r OLD_PID < "$PID_FILE" 2>/dev/null || true
+    if [[ "$OLD_PID" =~ ^[0-9]+$ ]] && kill -0 "$OLD_PID" 2>/dev/null; then
+        # If this branch fires, atomic claim above failed silently — investigate.
+        # Retain the kill-old behavior as defense-in-depth, but log it.
+        echo "$BINARY_NAME: warning — old PID $OLD_PID alive after lock claim succeeded; killing as defense-in-depth (#8)." >&2
+        OLD_COMM=$(ps -p "$OLD_PID" -o comm= 2>/dev/null)
+        OLD_BASENAME=$(basename "$OLD_COMM" 2>/dev/null)
+        if [[ "$OLD_BASENAME" == "$BINARY_NAME" ]]; then
+            kill -TERM "$OLD_PID" 2>/dev/null
+            for _ in 1 2 3 4; do
+                kill -0 "$OLD_PID" 2>/dev/null || break
+                sleep 0.5
+            done
+            kill -0 "$OLD_PID" 2>/dev/null && kill -KILL "$OLD_PID" 2>/dev/null
+        fi
+    fi
+fi
+
+# Fork + wait + trap（不能用 exec，因為 exec 會取代 shell，無法 trap cleanup）
+# CRITICAL: `<&0` explicitly inherits wrapper's stdin. Without it, POSIX/bash
+# redirects backgrounded (&) command's stdin to /dev/null, breaking MCP
+# stdio JSON-RPC protocol (#8 follow-up bug).
+"$BINARY" "$@" <&0 &
+BIN_PID=$!
+echo "$BIN_PID" > "$PID_FILE"
+
+cleanup() {
+    # Kill binary FIRST (before removing PID file, so orphans remain trackable)
+    if [[ -n "$BIN_PID" ]] && kill -0 "$BIN_PID" 2>/dev/null; then
+        kill -TERM "$BIN_PID" 2>/dev/null
+        # Wait up to 2s for graceful shutdown
+        for _ in 1 2 3 4; do
+            kill -0 "$BIN_PID" 2>/dev/null || break
+            sleep 0.5
+        done
+        kill -0 "$BIN_PID" 2>/dev/null && kill -KILL "$BIN_PID" 2>/dev/null
+        wait "$BIN_PID" 2>/dev/null
+    fi
+    # Ownership check: only remove PID file if it still belongs to us
+    # (prevents old wrapper's late-firing trap from deleting new wrapper's PID file)
+    if [[ -f "$PID_FILE" ]]; then
+        CURRENT_PID=
+        read -r CURRENT_PID < "$PID_FILE" 2>/dev/null || true
+        [[ "$CURRENT_PID" == "$BIN_PID" ]] && rm -f "$PID_FILE"
+    fi
+    # Release atomic claim (#10). flock mode auto-releases on fd close;
+    # mkdir mode needs explicit rmdir.
+    if [[ "$LOCK_MODE" == "mkdir" ]] && [[ -d "$LOCK_DIR" ]]; then
+        OWNER_PID=
+        [ -f "$LOCK_DIR/owner.pid" ] && read -r OWNER_PID < "$LOCK_DIR/owner.pid" 2>/dev/null
+        # Only release if we own it (avoid late trap deleting another wrapper's lock)
+        [[ "$OWNER_PID" == "$$" ]] && rm -rf "$LOCK_DIR"
+    fi
+}
+trap cleanup EXIT INT TERM
+
+wait "$BIN_PID"
+exit $?
diff --git a/plugins/che-telegram-mcp/bin/che-telegram-bot-mcp-wrapper.sh b/plugins/che-telegram-mcp/bin/che-telegram-bot-mcp-wrapper.sh
index fadb36e8..aeefee69 100755
--- a/plugins/che-telegram-mcp/bin/che-telegram-bot-mcp-wrapper.sh
+++ b/plugins/che-telegram-mcp/bin/che-telegram-bot-mcp-wrapper.sh
@@ -1,46 +1,103 @@
-#!/bin/bash
-# Wrapper for che-telegram-bot-mcp (Bot API)
-# Bot token is read from macOS Keychain at runtime.
-
-BINARY_NAME="CheTelegramBotMCP"
-GITHUB_REPO="kiki830621/che-telegram-bot-mcp"
-RELEASE_URL="https://github.com/$GITHUB_REPO/releases/latest/download/$BINARY_NAME"
-INSTALL_DIR="$HOME/bin"
-
-# Find binary
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME" "$HOME/Developer/che-mcps/che-telegram-bot-mcp/.build/release/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
-
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
-    mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$GITHUB_REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
-    if [[ -n "$URL" ]]; then
-        curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-            || { echo "ERROR: Download failed." >&2; exit 1; }
-        BINARY="$INSTALL_DIR/$BINARY_NAME"
-        echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
-    else
-        echo "No release found. Build from source:" >&2
-        echo "  git clone https://github.com/$GITHUB_REPO.git" >&2
-        echo "  cd che-telegram-bot-mcp && swift build -c release" >&2
-        exit 1
-    fi
-fi
-
-# Read bot token from macOS Keychain
-export TELEGRAM_BOT_TOKEN="$(security find-generic-password -a "che-telegram-bot-mcp" -s "TELEGRAM_BOT_TOKEN" -w 2>/dev/null)"
-
-if [[ -z "$TELEGRAM_BOT_TOKEN" ]]; then
-    echo "Bot token not found in Keychain." >&2
-    echo "Set it up:" >&2
-    echo "  security add-generic-password -a che-telegram-bot-mcp -s TELEGRAM_BOT_TOKEN -w 'YOUR_TOKEN' -U" >&2
-    echo "Get a token from @BotFather on Telegram." >&2
-    exit 1
-fi
-
-exec "$BINARY" "$@"
+#!/bin/bash
+# Wrapper for che-telegram-bot-mcp (Bot API)
+# Bot token is read from macOS Keychain at runtime.
+#
+# Auto-upgrade design (v1.3.0+):
+# - DESIRED_VERSION below pins the binary version this plugin expects.
+# - ~/bin/.CheTelegramBotMCP.version sidecar tracks what's installed.
+# - On mismatch, re-downloads from GitHub Release (atomic .tmp + mv).
+# - Source builds in $HOME/Developer/... are NEVER auto-replaced.
+
+BINARY_NAME="CheTelegramBotMCP"
+GITHUB_REPO="PsychQuant/che-msg"
+INSTALL_DIR="$HOME/bin"
+INSTALLED_BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+DESIRED_VERSION="0.5.0"
+DOWNLOAD_TIMEOUT=180  # bot binary is small (~30MB)
+
+# Find binary
+BINARY=""
+for loc in "$INSTALLED_BINARY" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME" "$HOME/Developer/che-msg/che-telegram-bot-mcp/.build/release/$BINARY_NAME" "$HOME/Developer/che-mcps/che-telegram-bot-mcp/.build/release/$BINARY_NAME"; do
+    [[ -x "$loc" ]] && BINARY="$loc" && break
+done
+
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
+
+if [[ -z "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ "$BINARY" == "$INSTALLED_BINARY" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $GITHUB_REPO..." >&2
+    mkdir -p "$INSTALL_DIR"
+
+    URL=""
+    for API_URL in \
+        "https://api.github.com/repos/$GITHUB_REPO/releases/tags/v$DESIRED_VERSION" \
+        "https://api.github.com/repos/$GITHUB_REPO/releases/latest"
+    do
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$INSTALLED_BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+            BINARY="$INSTALLED_BINARY"
+        else
+            echo "$BINARY_NAME: ERROR — no release asset found at $GITHUB_REPO." >&2
+            echo "  Install manually: https://github.com/$GITHUB_REPO/releases" >&2
+            echo "  Or build from source:" >&2
+            echo "    git clone https://github.com/$GITHUB_REPO.git ~/Developer/che-msg" >&2
+            echo "    cd ~/Developer/che-msg/che-telegram-bot-mcp && swift build -c release --product $BINARY_NAME" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time "$DOWNLOAD_TIMEOUT" "$URL" -o "${INSTALLED_BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${INSTALLED_BINARY}.tmp"
+            xattr -dr com.apple.quarantine "${INSTALLED_BINARY}.tmp" 2>/dev/null || true
+            mv "${INSTALLED_BINARY}.tmp" "$INSTALLED_BINARY"
+            echo "$DESIRED_VERSION" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v$DESIRED_VERSION" >&2
+            BINARY="$INSTALLED_BINARY"
+        else
+            rm -f "${INSTALLED_BINARY}.tmp" 2>/dev/null
+            if [[ -x "$INSTALLED_BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+                BINARY="$INSTALLED_BINARY"
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+# Read bot token from macOS Keychain
+export TELEGRAM_BOT_TOKEN="$(security find-generic-password -a "che-telegram-bot-mcp" -s "TELEGRAM_BOT_TOKEN" -w 2>/dev/null)"
+
+if [[ -z "$TELEGRAM_BOT_TOKEN" ]]; then
+    echo "Bot token not found in Keychain." >&2
+    echo "Set it up:" >&2
+    echo "  security add-generic-password -a che-telegram-bot-mcp -s TELEGRAM_BOT_TOKEN -w 'YOUR_TOKEN' -U" >&2
+    echo "Get a token from @BotFather on Telegram." >&2
+    exit 1
+fi
+
+# NOTE: bot-mcp 不需要 local resource PID tracking (#12)
+# Bot API 是 HTTPS client，本地端 **沒有** local DB / file lock / binlog
+# 這類 single-instance resource。所以 #8 引入的 PID file + orphan cleanup
+# 對 bot-mcp 不適用。getUpdates long-polling race 應該由 server-side
+# locking 處理，不是 wrapper PID tracking（見 #10 follow-up）。
+exec "$BINARY" "$@"
diff --git a/plugins/che-telegram-mcp/bin/test-wrapper-pid.sh b/plugins/che-telegram-mcp/bin/test-wrapper-pid.sh
new file mode 100755
index 00000000..7b5862af
--- /dev/null
+++ b/plugins/che-telegram-mcp/bin/test-wrapper-pid.sh
@@ -0,0 +1,561 @@
+#!/bin/bash
+# Smoke test for wrapper PID tracking (#8)
+#
+# Tests:
+#   1. Orphan cleanup: if PID file points to a live process matching BINARY_NAME,
+#      wrapper should kill it before starting new instance.
+#   2. PID file maintenance: new process's PID is written to PID file.
+#   3. Cleanup on exit: PID file removed when wrapper exits normally.
+#   4. PID recycling protection: if PID is alive but different command,
+#      wrapper should NOT kill it.
+#
+# Usage:
+#   ./test-wrapper-pid.sh
+#
+# Exit: 0 on all pass, 1 on any failure.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FAIL=0
+TOTAL=0
+
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; FAIL=$((FAIL + 1)); }
+test_case() { TOTAL=$((TOTAL + 1)); echo "Test: $1"; }
+
+# Extract the PID-tracking block from a wrapper into a standalone executable,
+# substituting BINARY with a fake sleep command and PID_FILE with a temp path.
+# This lets us test the logic without running the real MCP server.
+make_fake_wrapper() {
+    local out=$1
+    local pid_file=$2
+    local binary_name=$3
+    local sleep_duration=$4
+
+    cat > "$out" <<EOF
+#!/bin/bash
+BINARY_NAME="$binary_name"
+BINARY="/bin/sleep"
+PID_FILE="$pid_file"
+mkdir -p "\$(dirname "\$PID_FILE")"
+
+if [[ -f "\$PID_FILE" ]]; then
+    OLD_PID=
+    read -r OLD_PID < "\$PID_FILE" 2>/dev/null || true
+    if [[ "\$OLD_PID" =~ ^[0-9]+\$ ]] && kill -0 "\$OLD_PID" 2>/dev/null; then
+        OLD_COMM=\$(ps -p "\$OLD_PID" -o comm= 2>/dev/null)
+        OLD_BASENAME=\$(basename "\$OLD_COMM" 2>/dev/null)
+        if [[ "\$OLD_BASENAME" == "\$BINARY_NAME" ]]; then
+            kill -TERM "\$OLD_PID" 2>/dev/null
+            for _ in 1 2 3 4; do
+                kill -0 "\$OLD_PID" 2>/dev/null || break
+                sleep 0.5
+            done
+            kill -0 "\$OLD_PID" 2>/dev/null && kill -KILL "\$OLD_PID" 2>/dev/null
+        fi
+    fi
+fi
+
+"\$BINARY" $sleep_duration <&0 &
+BIN_PID=\$!
+echo "\$BIN_PID" > "\$PID_FILE"
+
+cleanup() {
+    if [[ -n "\$BIN_PID" ]] && kill -0 "\$BIN_PID" 2>/dev/null; then
+        kill -TERM "\$BIN_PID" 2>/dev/null
+        for _ in 1 2 3 4; do
+            kill -0 "\$BIN_PID" 2>/dev/null || break
+            sleep 0.5
+        done
+        kill -0 "\$BIN_PID" 2>/dev/null && kill -KILL "\$BIN_PID" 2>/dev/null
+        wait "\$BIN_PID" 2>/dev/null
+    fi
+    if [[ -f "\$PID_FILE" ]]; then
+        CURRENT_PID=
+        read -r CURRENT_PID < "\$PID_FILE" 2>/dev/null || true
+        [[ "\$CURRENT_PID" == "\$BIN_PID" ]] && rm -f "\$PID_FILE"
+    fi
+}
+trap cleanup EXIT INT TERM
+
+wait "\$BIN_PID"
+exit \$?
+EOF
+    chmod +x "$out"
+}
+
+# Helper: poll for condition with timeout (avoids timing races)
+# Uses `ps -o state=` to detect zombies (Z state) as "dead", since `kill -0`
+# returns success for zombies (process exists but is un-reaped). After detecting
+# death, attempts to reap via `wait` so subsequent checks see the PID gone.
+wait_for_dead() {
+    local pid=$1
+    local max_tenths=${2:-30}  # default 3s
+    local i=0
+    while [[ $i -lt $max_tenths ]]; do
+        local state
+        state=$(ps -p "$pid" -o state= 2>/dev/null | tr -d ' ')
+        # Treat missing process OR zombie as "dead"
+        if [[ -z "$state" ]] || [[ "$state" == Z* ]]; then
+            wait "$pid" 2>/dev/null  # reap if we're the parent
+            return 0
+        fi
+        sleep 0.1
+        i=$((i + 1))
+    done
+    return 1
+}
+
+wait_for_file() {
+    local path=$1
+    local max_tenths=${2:-30}
+    local i=0
+    while [[ $i -lt $max_tenths ]]; do
+        [[ -f "$path" ]] && return 0
+        sleep 0.1
+        i=$((i + 1))
+    done
+    return 1
+}
+
+TMPDIR=$(mktemp -d)
+trap "rm -rf '$TMPDIR'" EXIT
+
+# ----------------------------------------------------------------------
+# Test 0: stdin inheritance — critical for MCP stdio protocol
+# POSIX rule: in non-interactive shell, `cmd &` redirects stdin to /dev/null
+# unless explicitly overridden with `<&0`. Using `/bin/sleep` as fake binary
+# never exercises this path; we need a binary that actually reads stdin.
+test_case "Wrapper inherits stdin to backgrounded binary (POSIX & rule)"
+PID_FILE="$TMPDIR/test0.pid"
+OUT_FILE="$TMPDIR/test0.out"
+
+# Build a minimal wrapper that mimics the production stdin-inheritance path
+cat > "$TMPDIR/wrapper0.sh" <<EOF
+#!/bin/bash
+PID_FILE="$PID_FILE"
+/bin/cat > "$OUT_FILE" <&0 &
+BIN_PID=\$!
+echo "\$BIN_PID" > "\$PID_FILE"
+wait "\$BIN_PID"
+EOF
+chmod +x "$TMPDIR/wrapper0.sh"
+
+echo "MCP_STDIN_TEST_PAYLOAD" | "$TMPDIR/wrapper0.sh"
+if [[ "$(cat "$OUT_FILE" 2>/dev/null)" == "MCP_STDIN_TEST_PAYLOAD" ]]; then
+    pass "stdin inherited via <&0 (bug from commit 06015c9 blocked)"
+else
+    fail "stdin NOT inherited — POSIX & rule redirected to /dev/null (MCP stdio would break)"
+fi
+
+# ----------------------------------------------------------------------
+test_case "PID file created on start, removed on clean exit"
+PID_FILE="$TMPDIR/test1.pid"
+make_fake_wrapper "$TMPDIR/wrapper1.sh" "$PID_FILE" "sleep" "3"
+"$TMPDIR/wrapper1.sh" &
+WRAPPER_PID=$!
+if wait_for_file "$PID_FILE" 30; then
+    pass "PID file created"
+else
+    fail "PID file missing during run"
+fi
+wait "$WRAPPER_PID"
+if [[ ! -f "$PID_FILE" ]]; then
+    pass "PID file removed after exit"
+else
+    fail "PID file still exists after exit"
+fi
+
+# ----------------------------------------------------------------------
+test_case "Orphan process killed on startup"
+PID_FILE="$TMPDIR/test2.pid"
+# Start an orphan "sleep" process matching BINARY_NAME
+/bin/sleep 30 &
+ORPHAN_PID=$!
+echo "$ORPHAN_PID" > "$PID_FILE"
+sleep 0.1
+if kill -0 "$ORPHAN_PID" 2>/dev/null; then
+    pass "orphan started (PID $ORPHAN_PID)"
+else
+    fail "orphan setup failed"
+fi
+
+make_fake_wrapper "$TMPDIR/wrapper2.sh" "$PID_FILE" "sleep" "3"
+"$TMPDIR/wrapper2.sh" &
+WRAPPER_PID=$!
+# Poll up to 4s for orphan to be killed (wrapper uses SIGTERM + up to 2s wait + SIGKILL)
+if wait_for_dead "$ORPHAN_PID" 40; then
+    pass "orphan killed by wrapper"
+else
+    fail "orphan survived wrapper startup (PID $ORPHAN_PID still alive)"
+    kill -KILL "$ORPHAN_PID" 2>/dev/null
+fi
+wait "$WRAPPER_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "PID recycling protection (PID alive but wrong command)"
+PID_FILE="$TMPDIR/test3.pid"
+# Start a long-lived process NOT matching BINARY_NAME
+# tail -f /dev/null sits forever; comm name basename = "tail"
+/usr/bin/tail -f /dev/null &
+UNRELATED_PID=$!
+echo "$UNRELATED_PID" > "$PID_FILE"
+sleep 0.2
+if ! kill -0 "$UNRELATED_PID" 2>/dev/null; then
+    fail "unrelated process setup failed (tail died unexpectedly)"
+fi
+
+# Wrapper looks for "sleep" as BINARY_NAME, but PID points to "tail"
+make_fake_wrapper "$TMPDIR/wrapper3.sh" "$PID_FILE" "sleep" "3"
+"$TMPDIR/wrapper3.sh" &
+WRAPPER_PID=$!
+# Wait long enough to be sure wrapper's check phase has completed (>= 4s would cover SIGTERM + SIGKILL paths)
+sleep 1
+if kill -0 "$UNRELATED_PID" 2>/dev/null; then
+    pass "unrelated process NOT killed (PID recycling protection works)"
+else
+    fail "unrelated process was killed (PID recycling protection failed)"
+fi
+kill -TERM "$UNRELATED_PID" 2>/dev/null
+wait "$WRAPPER_PID" 2>/dev/null
+wait "$UNRELATED_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "Stale PID file (process already dead)"
+PID_FILE="$TMPDIR/test4.pid"
+# Write a PID that's guaranteed not to exist (very high number)
+echo "99999" > "$PID_FILE"
+
+make_fake_wrapper "$TMPDIR/wrapper4.sh" "$PID_FILE" "sleep" "3"
+"$TMPDIR/wrapper4.sh" &
+WRAPPER_PID=$!
+# Poll for file content to change
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+    NEW_PID=$(cat "$PID_FILE" 2>/dev/null | tr -d '[:space:]')
+    [[ -n "$NEW_PID" && "$NEW_PID" != "99999" ]] && break
+    sleep 0.1
+done
+if [[ -f "$PID_FILE" ]]; then
+    NEW_PID=$(cat "$PID_FILE" | tr -d '[:space:]')
+    if [[ "$NEW_PID" != "99999" ]] && [[ -n "$NEW_PID" ]] && kill -0 "$NEW_PID" 2>/dev/null; then
+        pass "stale PID replaced with live PID ($NEW_PID)"
+    else
+        fail "stale PID not handled correctly (got '$NEW_PID')"
+    fi
+else
+    fail "PID file missing during run"
+fi
+wait "$WRAPPER_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "Wrapper forwards SIGTERM to binary"
+PID_FILE="$TMPDIR/test5.pid"
+make_fake_wrapper "$TMPDIR/wrapper5.sh" "$PID_FILE" "sleep" "30"
+"$TMPDIR/wrapper5.sh" &
+WRAPPER_PID=$!
+if ! wait_for_file "$PID_FILE" 30; then
+    fail "PID file never created"
+fi
+BIN_PID=$(cat "$PID_FILE" 2>/dev/null | tr -d '[:space:]')
+if [[ -z "$BIN_PID" ]]; then
+    fail "could not read BIN_PID"
+else
+    kill -TERM "$WRAPPER_PID"
+    if wait_for_dead "$BIN_PID" 40; then
+        pass "binary terminated when wrapper received SIGTERM"
+    else
+        fail "binary survived wrapper SIGTERM (PID $BIN_PID still alive)"
+        kill -KILL "$BIN_PID" 2>/dev/null
+    fi
+fi
+wait "$WRAPPER_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "Ownership check: wrapper does not delete PID file claimed by another wrapper"
+PID_FILE="$TMPDIR/test6.pid"
+make_fake_wrapper "$TMPDIR/wrapper6.sh" "$PID_FILE" "sleep" "3"
+"$TMPDIR/wrapper6.sh" &
+WRAPPER_A_PID=$!
+wait_for_file "$PID_FILE" 30
+A_BIN_PID=$(cat "$PID_FILE" 2>/dev/null | tr -d '[:space:]')
+
+# Simulate: an old wrapper from previous session runs cleanup with stale BIN_PID
+# (replicate the ownership-check logic; should NOT delete the file)
+(
+    BIN_PID="99998"
+    if [[ -f "$PID_FILE" ]] && [[ "$(cat "$PID_FILE" 2>/dev/null | tr -d '[:space:]')" == "$BIN_PID" ]]; then
+        rm -f "$PID_FILE"
+    fi
+)
+
+if [[ -f "$PID_FILE" ]] && [[ "$(cat "$PID_FILE" | tr -d '[:space:]')" == "$A_BIN_PID" ]]; then
+    pass "PID file preserved (ownership check blocked wrong owner)"
+else
+    fail "PID file was deleted or corrupted by wrong-owner cleanup"
+fi
+wait "$WRAPPER_A_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "SIGKILL fallback: binary that ignores SIGTERM still gets killed"
+PID_FILE="$TMPDIR/test7.pid"
+# Stubborn binary structure (#11):
+#   The previous version used `trap '' TERM; sleep 30`. Bash's trap ignores
+#   SIGTERM correctly, but `sleep 30` is a CHILD process. SIGKILL of the bash
+#   subshell killed bash but left sleep as an orphan adopted by launchd. The
+#   test then "passed" by checking only the bash PID, missing the orphan.
+#
+#   Naive fix attempt: `read -t 30 < /dev/null`. DOES NOT WORK — /dev/null
+#   returns EOF immediately, `read` returns exit=1 in ~1ms regardless of -t.
+#   Verified: stubborn binary would exit before wrapper even sent SIGTERM,
+#   making Test 7 a false positive.
+#
+#   Correct fix: block the bash main process on a FIFO with no writer.
+#   Open-for-read on a FIFO without a writer blocks at the OS open()
+#   syscall. `read -t` does NOT apply during open() (bash's read timeout
+#   only applies once fd is open), so this effectively blocks forever
+#   until SIGKILL arrives. No child fork.
+#
+#   Sentinel file ($STUBBORN_READY) is touched AFTER trap is set and
+#   FIFO is created. Test harness waits for this sentinel before sending
+#   SIGTERM, avoiding the race where bash hasn't installed trap yet
+#   (verified by Codex during #11 verify round — without the sentinel,
+#   SIGTERM sometimes killed bash before trap took effect).
+STUBBORN_READY="$TMPDIR/stubborn-ready"
+cat > "$TMPDIR/stubborn-binary.sh" <<STUBBORN
+#!/bin/bash
+trap '' TERM
+FIFO="$TMPDIR/stubborn-fifo-\$\$"
+if ! mkfifo "\$FIFO" 2>/dev/null; then
+    echo "stubborn: mkfifo failed for \$FIFO" >&2
+    exit 1
+fi
+# Cleanup FIFO on normal exit (SIGKILL won't run this; leftover FIFO is harmless)
+trap 'rm -f "\$FIFO"' EXIT
+# Sentinel: signals test harness that trap + FIFO are ready
+touch "$STUBBORN_READY"
+read < "\$FIFO" || true
+STUBBORN
+chmod +x "$TMPDIR/stubborn-binary.sh"
+
+# Custom wrapper that uses stubborn binary
+cat > "$TMPDIR/wrapper7.sh" <<EOF
+#!/bin/bash
+BINARY_NAME="stubborn-binary.sh"
+BINARY="$TMPDIR/stubborn-binary.sh"
+PID_FILE="$PID_FILE"
+
+"\$BINARY" <&0 &
+BIN_PID=\$!
+echo "\$BIN_PID" > "\$PID_FILE"
+
+cleanup() {
+    if [[ -n "\$BIN_PID" ]] && kill -0 "\$BIN_PID" 2>/dev/null; then
+        kill -TERM "\$BIN_PID" 2>/dev/null
+        for _ in 1 2 3 4; do
+            kill -0 "\$BIN_PID" 2>/dev/null || break
+            sleep 0.5
+        done
+        kill -0 "\$BIN_PID" 2>/dev/null && kill -KILL "\$BIN_PID" 2>/dev/null
+        wait "\$BIN_PID" 2>/dev/null
+    fi
+    if [[ -f "\$PID_FILE" ]]; then
+        CURRENT_PID=
+        read -r CURRENT_PID < "\$PID_FILE" 2>/dev/null || true
+        [[ "\$CURRENT_PID" == "\$BIN_PID" ]] && rm -f "\$PID_FILE"
+    fi
+}
+trap cleanup EXIT INT TERM
+
+wait "\$BIN_PID"
+EOF
+chmod +x "$TMPDIR/wrapper7.sh"
+
+"$TMPDIR/wrapper7.sh" &
+WRAPPER_PID=$!
+wait_for_file "$PID_FILE" 30
+STUBBORN_PID=$(cat "$PID_FILE" 2>/dev/null | tr -d '[:space:]')
+
+# CRITICAL: wait for stubborn binary to install its SIGTERM-ignore trap
+# AND be blocked inside read < FIFO before sending SIGTERM. Otherwise
+# bash dies on default SIGTERM handler and test becomes false positive.
+if ! wait_for_file "$STUBBORN_READY" 30; then
+    fail "stubborn binary failed to become ready"
+fi
+
+# Snapshot any children of stubborn binary BEFORE termination (for orphan check)
+CHILDREN_BEFORE=$(pgrep -P "$STUBBORN_PID" 2>/dev/null | tr '\n' ' ')
+
+# Tell wrapper to terminate; binary will ignore SIGTERM, wrapper should SIGKILL it
+START_NS=$(date +%s%N 2>/dev/null || python3 -c 'import time; print(int(time.time()*1e9))')
+kill -TERM "$WRAPPER_PID"
+if wait_for_dead "$STUBBORN_PID" 50; then
+    # Verify wrapper actually took the SIGKILL path (≥1.5s elapsed).
+    # If it died quickly (<500ms), bash died before trap took effect,
+    # meaning SIGKILL fallback was never exercised.
+    wait "$WRAPPER_PID" 2>/dev/null
+    END_NS=$(date +%s%N 2>/dev/null || python3 -c 'import time; print(int(time.time()*1e9))')
+    ELAPSED_MS=$(( (END_NS - START_NS) / 1000000 ))
+    if (( ELAPSED_MS < 1500 )); then
+        fail "wrapper exited in ${ELAPSED_MS}ms — SIGKILL path not exercised (trap race?)"
+    else
+        pass "stubborn binary killed via SIGKILL fallback (${ELAPSED_MS}ms elapsed, SIGTERM-ignore verified)"
+    fi
+else
+    fail "stubborn binary survived SIGKILL fallback"
+    kill -KILL "$STUBBORN_PID" 2>/dev/null
+fi
+
+# Verify NO orphan children remain (#11)
+ORPHAN_FOUND=
+for child_pid in $CHILDREN_BEFORE; do
+    if kill -0 "$child_pid" 2>/dev/null; then
+        ORPHAN_FOUND="$child_pid"
+        kill -KILL "$child_pid" 2>/dev/null
+        break
+    fi
+done
+if [[ -z "$ORPHAN_FOUND" ]]; then
+    pass "no orphan children left after SIGKILL (process tree fully reaped)"
+else
+    fail "orphan child PID $ORPHAN_FOUND survived parent SIGKILL"
+fi
+wait "$WRAPPER_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "Corrupted PID file with internal whitespace is rejected, not coalesced"
+PID_FILE="$TMPDIR/test8.pid"
+# Write corrupted content: "12 34" should NOT be parsed as PID 1234
+echo "12 34" > "$PID_FILE"
+
+make_fake_wrapper "$TMPDIR/wrapper8.sh" "$PID_FILE" "sleep" "2"
+"$TMPDIR/wrapper8.sh" &
+WRAPPER_PID=$!
+
+# Poll until wrapper overwrites PID file with its own BIN_PID
+NEW_CONTENT=""
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do
+    NEW_CONTENT=$(cat "$PID_FILE" 2>/dev/null)
+    [[ "$NEW_CONTENT" != "12 34" ]] && break
+    sleep 0.1
+done
+
+if [[ "$NEW_CONTENT" == "1234" ]]; then
+    fail "wrapper parsed '12 34' as '1234' (tr -d bug regressed)"
+elif [[ "$NEW_CONTENT" =~ ^[0-9]+$ ]]; then
+    pass "corrupted PID rejected, valid new PID written ($NEW_CONTENT)"
+else
+    fail "unexpected PID file content: '$NEW_CONTENT'"
+fi
+wait "$WRAPPER_PID" 2>/dev/null
+
+# ----------------------------------------------------------------------
+test_case "Atomic-claim lock: second instance fails fast, first instance survives (#10)"
+LOCK_DIR="$TMPDIR/test9-lock"
+LOCK_FILE="${LOCK_DIR}.flock"
+PID_FILE="$TMPDIR/test9.pid"
+
+# Build a wrapper that uses the same atomic-claim primitive as production
+# (mkdir-based fallback path; works even on macOS without flock)
+make_lock_wrapper() {
+    local out=$1
+    local sleep_duration=$2
+
+    cat > "$out" <<EOF
+#!/bin/bash
+LOCK_DIR="$LOCK_DIR"
+LOCK_FILE="${LOCK_FILE}"
+LOCK_MODE=""
+mkdir -p "\$(dirname "\$LOCK_DIR")"
+
+if command -v flock >/dev/null 2>&1; then
+    LOCK_MODE="flock"
+    exec 200>"\$LOCK_FILE"
+    if ! flock -n 200; then
+        echo "Another instance is already running." >&2
+        exit 1
+    fi
+else
+    LOCK_MODE="mkdir"
+    if ! mkdir "\$LOCK_DIR" 2>/dev/null; then
+        OWNER_PID=
+        [ -f "\$LOCK_DIR/owner.pid" ] && read -r OWNER_PID < "\$LOCK_DIR/owner.pid" 2>/dev/null
+        if [[ "\$OWNER_PID" =~ ^[0-9]+\$ ]] && ! kill -0 "\$OWNER_PID" 2>/dev/null; then
+            rm -rf "\$LOCK_DIR"
+            mkdir "\$LOCK_DIR" 2>/dev/null || { echo "Failed to claim lock." >&2; exit 1; }
+        else
+            echo "Another instance is already running." >&2
+            exit 1
+        fi
+    fi
+    echo \$\$ > "\$LOCK_DIR/owner.pid"
+fi
+
+/bin/sleep $sleep_duration <&0 &
+BIN_PID=\$!
+
+cleanup() {
+    if [[ -n "\$BIN_PID" ]] && kill -0 "\$BIN_PID" 2>/dev/null; then
+        kill -TERM "\$BIN_PID" 2>/dev/null
+        wait "\$BIN_PID" 2>/dev/null
+    fi
+    if [[ "\$LOCK_MODE" == "mkdir" ]] && [[ -d "\$LOCK_DIR" ]]; then
+        OWNER_PID=
+        [ -f "\$LOCK_DIR/owner.pid" ] && read -r OWNER_PID < "\$LOCK_DIR/owner.pid" 2>/dev/null
+        [[ "\$OWNER_PID" == "\$\$" ]] && rm -rf "\$LOCK_DIR"
+    fi
+}
+trap cleanup EXIT INT TERM
+wait "\$BIN_PID"
+EOF
+    chmod +x "$out"
+}
+
+make_lock_wrapper "$TMPDIR/wrapper9a.sh" "3"
+make_lock_wrapper "$TMPDIR/wrapper9b.sh" "3"
+
+# Start first instance — should claim lock and run
+"$TMPDIR/wrapper9a.sh" &
+W9A_PID=$!
+# Wait for lock to be claimed
+LOCK_CLAIMED=0
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+    if [[ -d "$LOCK_DIR" ]] || [[ -f "$LOCK_FILE" ]]; then
+        LOCK_CLAIMED=1
+        break
+    fi
+    sleep 0.05
+done
+
+if [[ "$LOCK_CLAIMED" != 1 ]]; then
+    fail "first wrapper failed to claim lock"
+    kill -TERM "$W9A_PID" 2>/dev/null
+    wait "$W9A_PID" 2>/dev/null
+else
+    # Start second instance — should fail-fast with "already running"
+    SECOND_OUT="$TMPDIR/test9-second.stderr"
+    "$TMPDIR/wrapper9b.sh" 2>"$SECOND_OUT"
+    SECOND_EXIT=$?
+
+    if [[ "$SECOND_EXIT" -eq 1 ]] && grep -q "already running" "$SECOND_OUT"; then
+        pass "second instance fail-fast (exit=1, stderr contains 'already running')"
+    else
+        fail "second instance behavior unexpected (exit=$SECOND_EXIT, stderr=$(cat "$SECOND_OUT"))"
+    fi
+
+    # First instance should still be alive
+    if kill -0 "$W9A_PID" 2>/dev/null; then
+        pass "first instance survived second-instance attempt (no SIGTERM cross-fire)"
+    else
+        fail "first instance died unexpectedly"
+    fi
+
+    # Cleanup
+    kill -TERM "$W9A_PID" 2>/dev/null
+    wait "$W9A_PID" 2>/dev/null
+fi
+
+# ----------------------------------------------------------------------
+echo ""
+echo "Results: $((TOTAL - FAIL))/$TOTAL passed"
+exit $FAIL
diff --git a/plugins/che-telegram-mcp/hooks/check-mcp.sh b/plugins/che-telegram-mcp/hooks/check-mcp.sh
index 411466e3..b8706df5 100755
--- a/plugins/che-telegram-mcp/hooks/check-mcp.sh
+++ b/plugins/che-telegram-mcp/hooks/check-mcp.sh
@@ -1,34 +1,106 @@
-#!/bin/bash
-# Session start check for che-telegram-mcp plugin
-
-check_binary() {
-    local name="$1" repo="$2" label="$3"
-    local found=false
-    for loc in "$HOME/bin/$name" "/usr/local/bin/$name" "$HOME/.local/bin/$name" "$HOME/Developer/che-mcps/$(echo "$repo" | cut -d/ -f2)/.build/release/$name"; do
-        [[ -x "$loc" ]] && found=true && break
-    done
-    if [[ "$found" == "true" ]]; then
-        echo "✓ $label installed: $loc"
-    else
-        echo "⚠️  $label not found"
-        echo "   Build: git clone https://github.com/$repo.git && cd $(echo "$repo" | cut -d/ -f2) && swift build -c release"
-    fi
-}
-
-check_keychain() {
-    local account="$1" service="$2" label="$3"
-    if security find-generic-password -a "$account" -s "$service" -w &>/dev/null; then
-        echo "✓ $label in Keychain"
-    else
-        echo "⚠️  $label not in Keychain"
-        echo "   Run: security add-generic-password -a $account -s $service -w 'VALUE' -U"
-    fi
-}
-
-echo "── Telegram MCP Status ──"
-check_binary "CheTelegramAllMCP" "kiki830621/che-telegram-all-mcp" "telegram-all (TDLib)"
-check_keychain "che-telegram-all-mcp" "TELEGRAM_API_ID" "API ID"
-check_keychain "che-telegram-all-mcp" "TELEGRAM_API_HASH" "API Hash"
-
-check_binary "CheTelegramBotMCP" "kiki830621/che-telegram-bot-mcp" "telegram-bot"
-check_keychain "che-telegram-bot-mcp" "TELEGRAM_BOT_TOKEN" "Bot Token"
+#!/bin/bash
+# SessionStart check for che-telegram-mcp plugin
+#
+# Verifies binaries + Keychain entries needed by the two bundled MCP servers
+# (telegram-all and telegram-bot). Output mirrors what the wrappers will look
+# for at runtime, so a green checkmark here means the wrapper will succeed.
+#
+# Note: this hook does NOT read disabledMcpjsonServers from settings.json. If
+# you've intentionally disabled one server, ignore its warnings (the footer
+# note explains how).
+
+GITHUB_REPO="PsychQuant/che-msg"
+
+# Search locations — MUST match the wrapper's `for loc in ...` list.
+# See bin/che-telegram-{all,bot}-mcp-wrapper.sh.
+check_binary() {
+    local name="$1" pkg_dir="$2" label="$3"
+    local found=""
+    # Order matters: prefer installed binary > source build (matches wrapper).
+    for loc in \
+        "$HOME/bin/$name" \
+        "/usr/local/bin/$name" \
+        "$HOME/.local/bin/$name" \
+        "$HOME/Developer/che-msg/$pkg_dir/.build/release/$name" \
+        "$HOME/Developer/che-mcps/$pkg_dir/.build/release/$name"; do
+        if [[ -x "$loc" ]]; then
+            found="$loc"
+            break
+        fi
+    done
+    if [[ -n "$found" ]]; then
+        # Read sidecar version (only present for $HOME/bin installs).
+        local version_file="$HOME/bin/.${name}.version"
+        local installed_version=""
+        [[ -f "$version_file" ]] && installed_version=$(tr -d '[:space:]' < "$version_file" 2>/dev/null || true)
+        if [[ -n "$installed_version" ]]; then
+            echo "✓ $label v$installed_version installed: $found"
+        else
+            echo "✓ $label installed: $found"
+        fi
+    else
+        echo "⚠️  $label not found"
+        echo "   Wrappers will auto-download on first invocation, or build manually:"
+        echo "     git clone https://github.com/$GITHUB_REPO.git ~/Developer/che-msg"
+        echo "     cd ~/Developer/che-msg/$pkg_dir && swift build -c release --product $name"
+    fi
+}
+
+# Single GitHub API hit for both binaries (same release / same tag).
+fetch_latest_tag() {
+    curl -sL --max-time 5 "https://api.github.com/repos/$GITHUB_REPO/releases/latest" 2>/dev/null \
+        | grep '"tag_name"' | head -1 | sed 's/.*"v\([^"]*\)".*/\1/'
+}
+
+notify_if_outdated() {
+    local name="$1" label="$2" latest="$3"
+    [[ -z "$latest" ]] && return  # API failed / offline / rate-limited; stay quiet
+    local version_file="$HOME/bin/.${name}.version"
+    local installed=""
+    [[ -f "$version_file" ]] && installed=$(tr -d '[:space:]' < "$version_file" 2>/dev/null || true)
+    [[ -z "$installed" ]] && return  # not a managed install (source build / manual)
+    if [[ "$installed" != "$latest" ]]; then
+        echo "⬆️  $label v$installed → v$latest available (wrapper auto-upgrades on next plugin update)"
+    fi
+}
+
+check_keychain_required() {
+    local account="$1" service="$2" label="$3"
+    if security find-generic-password -a "$account" -s "$service" -w &>/dev/null; then
+        echo "✓ $label in Keychain"
+    else
+        echo "⚠️  $label not in Keychain"
+        echo "   security add-generic-password -a $account -s $service -w 'VALUE' -U"
+    fi
+}
+
+check_keychain_optional() {
+    local account="$1" service="$2" label="$3"
+    if security find-generic-password -a "$account" -s "$service" -w &>/dev/null; then
+        echo "✓ $label in Keychain (optional)"
+    fi
+    # Silent when missing — optional creds shouldn't generate warnings.
+}
+
+echo "── Telegram MCP Status ──"
+
+# telegram-all: personal account via TDLib
+check_binary "CheTelegramAllMCP" "che-telegram-all-mcp" "telegram-all (TDLib)"
+check_keychain_required "che-telegram-all-mcp" "TELEGRAM_API_ID" "API ID"
+check_keychain_required "che-telegram-all-mcp" "TELEGRAM_API_HASH" "API Hash"
+check_keychain_optional "che-telegram-all-mcp" "TELEGRAM_PHONE" "Phone (auto-fire)"
+check_keychain_optional "che-telegram-all-mcp" "TELEGRAM_2FA_PASSWORD" "2FA password (auto-fire)"
+
+# telegram-bot: bot account via Bot API
+check_binary "CheTelegramBotMCP" "che-telegram-bot-mcp" "telegram-bot"
+check_keychain_required "che-telegram-bot-mcp" "TELEGRAM_BOT_TOKEN" "Bot Token"
+
+# Upstream-version notice (single API call, both binaries share one release).
+LATEST=$(fetch_latest_tag)
+notify_if_outdated "CheTelegramAllMCP" "telegram-all" "$LATEST"
+notify_if_outdated "CheTelegramBotMCP" "telegram-bot" "$LATEST"
+
+# Footer: how to silence warnings for a server you don't use.
+echo "ℹ  Using only one server? Add the other to disabledMcpjsonServers in"
+echo "    ~/.claude/settings.json or .claude/settings.json (project), e.g."
+echo "    {\"disabledMcpjsonServers\": [\"telegram-bot\"]}  ← suppresses bot."
diff --git a/plugins/che-telegram-mcp/skills/telegram-messaging/SKILL.md b/plugins/che-telegram-mcp/skills/telegram-messaging/SKILL.md
index 5af69710..2d228bf3 100644
--- a/plugins/che-telegram-mcp/skills/telegram-messaging/SKILL.md
+++ b/plugins/che-telegram-mcp/skills/telegram-messaging/SKILL.md
@@ -1,110 +1,173 @@
----
-name: telegram-messaging
-description: Guide for using Telegram MCP tools to read chats, send messages, search history, and manage groups. Use when user asks about Telegram messages, chats, or contacts.
-allowed-tools:
-  - mcp__che-telegram-mcp__auth_status
-  - mcp__che-telegram-mcp__auth_set_parameters
-  - mcp__che-telegram-mcp__auth_send_phone
-  - mcp__che-telegram-mcp__auth_send_code
-  - mcp__che-telegram-mcp__auth_send_password
-  - mcp__che-telegram-mcp__logout
-  - mcp__che-telegram-mcp__get_me
-  - mcp__che-telegram-mcp__get_user
-  - mcp__che-telegram-mcp__get_contacts
-  - mcp__che-telegram-mcp__get_chats
-  - mcp__che-telegram-mcp__get_chat
-  - mcp__che-telegram-mcp__search_chats
-  - mcp__che-telegram-mcp__get_chat_history
-  - mcp__che-telegram-mcp__send_message
-  - mcp__che-telegram-mcp__edit_message
-  - mcp__che-telegram-mcp__delete_messages
-  - mcp__che-telegram-mcp__forward_messages
-  - mcp__che-telegram-mcp__search_messages
-  - mcp__che-telegram-mcp__get_chat_members
-  - mcp__che-telegram-mcp__pin_message
-  - mcp__che-telegram-mcp__unpin_message
-  - mcp__che-telegram-mcp__set_chat_title
-  - mcp__che-telegram-mcp__set_chat_description
-  - mcp__che-telegram-mcp__create_group
-  - mcp__che-telegram-mcp__add_chat_member
-  - mcp__che-telegram-mcp__mark_as_read
----
-
-# Telegram Messaging
-
-This skill covers the **telegram-all** MCP (personal account via TDLib). It can read all chats, send messages, and search full history.
-
-## Authentication
-
-Authentication is **one-time**. Session persists in `~/Library/Application Support/che-telegram-all-mcp/tdlib/`.
-
-**Always check `auth_status` first.** If "ready", skip auth. If not:
-```
-auth_set_parameters → auto-loaded from Keychain
-auth_send_phone     → user provides phone (+886...)
-auth_send_code      → user provides verification code
-auth_send_password  → only if 2FA enabled
-```
-
-## Tool Categories
-
-### 1. Discovery (Start Here)
-| Tool | Purpose |
-|------|---------|
-| `get_chats` | List recent conversations (limit param) |
-| `search_chats` | Find chat by name |
-| `get_chat` | Get details of a specific chat |
-| `get_contacts` | List saved contacts |
-
-### 2. Reading Messages
-| Tool | Purpose |
-|------|---------|
-| `get_chat_history` | Read message history (chat_id, limit, from_message_id) |
-| `search_messages` | Search within a chat by keyword |
-
-### 3. Sending Messages
-| Tool | Purpose |
-|------|---------|
-| `send_message` | Send text to a chat |
-| `edit_message` | Edit your own sent message |
-| `forward_messages` | Forward messages between chats |
-| `delete_messages` | Delete messages |
-
-**CRITICAL**: Always confirm with user before `send_message`, `delete_messages`, or `forward_messages`. These actions affect real conversations.
-
-### 4. Group Management
-| Tool | Purpose |
-|------|---------|
-| `get_chat_members` | List group members |
-| `create_group` | Create a new group |
-| `add_chat_member` | Add member to group |
-| `pin_message` / `unpin_message` | Pin/unpin messages |
-| `set_chat_title` / `set_chat_description` | Edit group info |
-
-## Common Workflows
-
-### Read Recent Messages
-```
-1. get_chats(limit: 10)           → find the chat
-2. get_chat_history(chat_id, limit: 20) → read messages
-```
-
-### Search for Something
-```
-1. search_chats(query: "name")    → find the chat
-2. search_messages(chat_id, query: "keyword") → find messages
-```
-
-### Send a Message
-```
-1. search_chats(query: "recipient") → find chat_id
-2. CONFIRM with user               → show recipient + message
-3. send_message(chat_id, text)     → send
-```
-
-## Security Notes
-
-- This MCP operates as the user's **personal Telegram account**
-- It can read **all** private chats — handle content with care
-- Never log or store message content beyond the current conversation
-- Always get explicit user confirmation before sending messages
+---
+name: telegram-messaging
+description: Guide for using Telegram MCP tools across both servers — telegram-all (personal account, full access) and telegram-bot (Bot API). Covers reading chats, sending messages, search, history, group management, and how to pick the right server. Use when the user asks about Telegram messages, chats, contacts, or bot operations.
+---
+
+# Telegram Messaging
+
+This plugin ships **two MCP servers** — pick the right one before invoking any tool.
+
+## Server selection — always do this first
+
+| User's intent | Server | Why |
+|---------------|--------|-----|
+| "Read my chat with Alice" / "what did Bob say" / "search my messages" / "send a message as me" | **`telegram-all`** | Operates as the user's personal Telegram account. Sees all private chats, full history, can act as the user. |
+| "Send a notification from the bot" / "respond to bot updates" / "moderate the group with the bot" | **`telegram-bot`** | Operates as a Telegram bot. Only sees chats the bot is in; no access to user's private chats. |
+| User says "Telegram" without context | Default to **`telegram-all`** | Personal-account use is the more common path; bot use is usually explicit. |
+
+**If both servers are configured and the request is ambiguous, ask the user which one.** Don't silently pick.
+
+If a tool call fails with "server not connected" or similar, the corresponding server is likely disabled via the user's `disabledMcpjsonServers` setting — explain this and offer to fall back to the other server if it makes sense.
+
+---
+
+## Path A: `telegram-all` (Personal Account, TDLib)
+
+Tool names: `mcp__plugin_che-telegram-mcp_telegram-all__<tool>`
+
+### Auth — one-time setup
+
+Auth state persists in `~/Library/Application Support/che-telegram-all-mcp/tdlib/`.
+
+**Always check `auth_status` before doing real work.** It returns `{state, next_step, last_error}`.
+
+- If `state == "ready"`, skip auth.
+- Otherwise, prefer `auth_run` (v0.5.0+) which drives the state machine in one tool:
+  ```
+  auth_run                         → fires auto-set params (if env present)
+  auth_run                         → fires auto-send phone (if env present)
+  auth_run(code: "12345")          → caller MUST supply SMS code (never auto-fired)
+  auth_run                         → fires auto-send 2FA password (if env present)
+  auth_run                         → state == "ready"
+  ```
+- Legacy per-step tools (`auth_set_parameters`, `auth_send_phone`, `auth_send_code`, `auth_send_password`) are still available as escape hatches.
+
+`auth_status.next_step` tells you exactly which arg the next call needs (e.g., `{tool: "auth_run", required_args: ["code"], hint: "..."}`); follow it.
+
+### Tool categories
+
+#### Discovery (start here)
+| Tool | Purpose |
+|------|---------|
+| `get_chats` | List recent conversations (`limit` param) |
+| `search_chats` | Find chat by name |
+| `get_chat` | Get details of a specific chat |
+| `get_contacts` | List saved contacts |
+| `get_me` | Your own profile |
+| `get_user` | Look up another user by ID |
+
+#### Reading messages
+| Tool | Purpose |
+|------|---------|
+| `get_chat_history` | Read history (`chat_id`, `limit`, `from_message_id`, optional `since_date` / `until_date` / `max_messages`) |
+| `search_messages` | Search within a chat by keyword |
+| `dump_chat_to_markdown` | One-shot export with date range / cap |
+
+#### Sending / modifying messages
+| Tool | Purpose |
+|------|---------|
+| `send_message` | Send text to a chat |
+| `edit_message` | Edit your own sent message |
+| `forward_messages` | Forward between chats |
+| `delete_messages` | Delete messages |
+| `mark_as_read` | Mark messages read |
+
+> ⚠️ **CRITICAL**: Always confirm with the user before `send_message`, `edit_message`, `delete_messages`, or `forward_messages`. These actions show up in real conversations and cannot always be undone.
+
+#### Group management
+| Tool | Purpose |
+|------|---------|
+| `get_chat_members` | List group members |
+| `create_group` | Create a new group |
+| `add_chat_member` | Add member to group |
+| `pin_message` / `unpin_message` | Pin/unpin |
+| `set_chat_title` / `set_chat_description` | Edit group info |
+
+### Common workflows (`telegram-all`)
+
+```
+Read recent messages:
+1. get_chats(limit: 10)           → find the chat
+2. get_chat_history(chat_id, limit: 20) → read messages
+
+Search:
+1. search_chats(query: "name")    → find the chat
+2. search_messages(chat_id, query: "keyword") → find messages
+
+Send a message:
+1. search_chats(query: "recipient") → find chat_id
+2. CONFIRM with user               → show recipient + message preview
+3. send_message(chat_id, text)     → send
+```
+
+---
+
+## Path B: `telegram-bot` (Bot API)
+
+Tool names: `mcp__plugin_che-telegram-mcp_telegram-bot__<tool>`
+
+### What the bot can / cannot do
+
+- ✅ Send/receive messages in chats the bot has been added to
+- ✅ Manage chats it's an admin of (pin, ban, restrict, set title)
+- ✅ Send media (photo, video, document, audio, sticker, location, poll)
+- ❌ Read the user's private chats (Bot API has no access)
+- ❌ Search across history (Bot API only fetches via 24h `get_updates` window or webhooks)
+
+### Tool categories
+
+#### Identity & updates
+| Tool | Purpose |
+|------|---------|
+| `get_me` | Bot's profile |
+| `get_updates` | Poll for new messages / events (24h window) |
+
+#### Send messages & media
+| Tool | Purpose |
+|------|---------|
+| `send_message` | Send text |
+| `send_photo` / `send_video` / `send_audio` / `send_document` / `send_sticker` / `send_location` / `send_poll` | Send specific media types |
+| `forward_message` / `copy_message` | Forward / copy between chats |
+| `edit_message_text` | Edit a sent message |
+| `delete_message` | Delete a message |
+
+#### Chat info
+| Tool | Purpose |
+|------|---------|
+| `get_chat` | Chat details |
+| `get_chat_administrators` | List admins |
+| `get_chat_member_count` | Member count |
+| `get_chat_member` | One member's role |
+
+#### Admin actions (bot must be admin)
+| Tool | Purpose |
+|------|---------|
+| `pin_chat_message` / `unpin_chat_message` / `unpin_all_chat_messages` | Pin/unpin |
+| `ban_chat_member` / `unban_chat_member` | Ban control |
+| `restrict_chat_member` / `promote_chat_member` | Permissions |
+| `set_chat_title` / `set_chat_description` | Edit chat info |
+| `leave_chat` | Bot leaves the chat |
+
+#### Bot commands
+| Tool | Purpose |
+|------|---------|
+| `set_my_commands` / `get_my_commands` / `delete_my_commands` | Manage `/command` list shown in Telegram clients |
+
+> ⚠️ Same confirmation rule as Path A — always confirm with the user before any send / delete / ban / restrict / promote action.
+
+---
+
+## Security notes
+
+- `telegram-all` operates as the user's **personal account**. It can read all private chats — handle content with care; never log or store message content beyond the current conversation.
+- `telegram-bot` operates as a public bot — its actions are visible to everyone in the chat. Treat bot tokens as secrets (they're stored in macOS Keychain).
+- Always get explicit user confirmation before any send / delete / forward / ban action. Don't infer consent from earlier turns of the conversation.
+
+## When tools fail
+
+| Error pattern | Likely cause | Fix |
+|---------------|--------------|-----|
+| `Not authenticated` (telegram-all) | Auth not completed | Walk through `auth_run` flow above |
+| `FLOOD_WAIT_X` | Rate limited by Telegram | Surface the wait time to the user; retry after X seconds |
+| `Server not connected` | Server disabled in settings, or binary missing | Check `disabledMcpjsonServers` and the SessionStart hook output |
+| Bot 401 / `Unauthorized` | Bot token wrong or revoked | Re-issue token via @BotFather and update Keychain |
diff --git a/plugins/che-things-mcp/.claude-plugin/plugin.json b/plugins/che-things-mcp/.claude-plugin/plugin.json
index b8131064..250573ae 100644
--- a/plugins/che-things-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-things-mcp/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "che-things-mcp",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Things 3 任務管理 MCP Server - 47 個工具支援完整 GTD 工作流程",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
diff --git a/plugins/che-things-mcp/CHANGELOG.md b/plugins/che-things-mcp/CHANGELOG.md
new file mode 100644
index 00000000..8b99fa93
--- /dev/null
+++ b/plugins/che-things-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.6.2] - (date unknown — please fill in)
+
+### Changed
+- Things 3 任務管理 MCP Server - 47 個工具支援完整 GTD 工作流程
diff --git a/plugins/che-things-mcp/README.md b/plugins/che-things-mcp/README.md
index c2e76b34..04c43ba0 100644
--- a/plugins/che-things-mcp/README.md
+++ b/plugins/che-things-mcp/README.md
@@ -165,7 +165,12 @@ This plugin requires macOS permissions:
 
 ## Version
 
-Plugin version: 1.6.1 (matches MCP server version)
+Plugin version: 1.6.2 (matches MCP server version)
+
+### Changelog
+
+- **1.6.2** (2026-04-22) — Wrapper auto-download now version-aware (re-downloads when `~/bin/CheThingsMCP` lags upstream)
+- **1.6.1** — Earlier patch releases tracked in [upstream CHANGELOG](https://github.com/PsychQuant/che-things-mcp/blob/main/CHANGELOG.md)
 
 ## Author
 
diff --git a/plugins/che-things-mcp/bin/che-things-mcp-wrapper.sh b/plugins/che-things-mcp/bin/che-things-mcp-wrapper.sh
index 89df42b1..5ec25a4d 100755
--- a/plugins/che-things-mcp/bin/che-things-mcp-wrapper.sh
+++ b/plugins/che-things-mcp/bin/che-things-mcp-wrapper.sh
@@ -1,28 +1,88 @@
 #!/bin/bash
-# Auto-download wrapper for CheThingsMCP
-REPO="kiki830621/che-things-mcp"
+# Version-aware auto-download wrapper for CheThingsMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheThingsMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-things-mcp"
 BINARY_NAME="CheThingsMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
     if [[ -z "$URL" ]]; then
-        echo "ERROR: No download URL found. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-        || { echo "ERROR: Download failed." >&2; exit 1; }
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-transport-mcp/.claude-plugin/plugin.json b/plugins/che-transport-mcp/.claude-plugin/plugin.json
new file mode 100644
index 00000000..9a2f7bef
--- /dev/null
+++ b/plugins/che-transport-mcp/.claude-plugin/plugin.json
@@ -0,0 +1,22 @@
+{
+  "name": "che-transport-mcp",
+  "version": "0.6.1",
+  "binaryVersion": "0.6.1",
+  "description": "Taiwan TDX transport MCP — 21 tools across Rail / Bus / Bike / Air / Traffic / Parking. Wraps PsychQuant/che-transport-mcp binary with version-aware auto-download (release-pinned + sha256 sidecar), 3-tier cache TTL (24h static / 1h timetable / 0s live), parallel cross-system station search, NSQL confirmation discipline for ambiguous queries. v0.2.3: soft dependency on PsychQuant/che-keychain — when installed, setup-tdx skill invokes it directly for a native NSAlert (id + secret in one dialog), no Terminal window needed. Binary v0.2.3 also auto-delegates --setup to che-keychain if present. Falls back to in-binary getpass otherwise.",
+  "author": {
+    "name": "Che Cheng"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "taiwan",
+    "transport",
+    "tdx",
+    "rail",
+    "bus",
+    "youbike",
+    "flight",
+    "parking",
+    "traffic"
+  ]
+}
diff --git a/plugins/che-transport-mcp/.mcp.json b/plugins/che-transport-mcp/.mcp.json
new file mode 100644
index 00000000..5ea3c1f1
--- /dev/null
+++ b/plugins/che-transport-mcp/.mcp.json
@@ -0,0 +1,7 @@
+{
+  "transport": {
+    "type": "stdio",
+    "command": "${CLAUDE_PLUGIN_ROOT}/bin/che-transport-mcp-wrapper.sh",
+    "description": "Taiwan TDX transport MCP — rail / bus / bike / air / traffic / parking"
+  }
+}
diff --git a/plugins/che-transport-mcp/CLAUDE.md b/plugins/che-transport-mcp/CLAUDE.md
new file mode 100644
index 00000000..000e73fd
--- /dev/null
+++ b/plugins/che-transport-mcp/CLAUDE.md
@@ -0,0 +1,134 @@
+# che-transport-mcp — CLAUDE.md
+
+Plugin wrapper for the `che-transport-mcp` MCP server (Swift, source at [PsychQuant/che-transport-mcp](https://github.com/PsychQuant/che-transport-mcp)).
+
+## What this plugin does
+
+Provides **21 MCP tools** querying Taiwan transport data via [TDX 運輸資料流通服務](https://tdx.transportdata.tw/) across 6 transport modes. Read-only — no execution risk. (Maritime/ferry is not offered — TDX has no callable maritime endpoint; see PsychQuant/che-transport-mcp#4.)
+
+## Tools surface
+
+| Mode | Count | Tools |
+|------|-------|-------|
+| Rail | 5 | `rail_list_systems`, `rail_search_stations`, `rail_find_trains`, `rail_status_train`, `rail_status_station` |
+| Bus | 5 | `bus_search_routes`, `bus_search_stops`, `bus_find_routes`, `bus_status_arrivals`, `bus_status_positions` |
+| Bike | 3 | `bike_search_stations`, `bike_stations_nearby`, `bike_status_station` |
+| Air | 3 | `air_list_airports`, `air_find_flights`, `air_status_flights` |
+| Traffic | 3 | `traffic_freeway_live`, `traffic_incidents`, `traffic_cctv` |
+| Parking | 2 | `parking_list_lots`, `parking_status` |
+
+MCP tool names appear as `mcp__che-transport-mcp__<tool>` or `mcp__plugin_che-transport-mcp_transport__<tool>` depending on Claude Code's registration namespace.
+
+## Skills
+
+| Skill | When to invoke |
+|-------|----------------|
+| `/che-transport-mcp:setup-tdx` | First-time TDX credential setup, or when SessionStart banner shows "⚠ TDX credentials missing" |
+| `/che-transport-mcp:today-rail` | Quick O/D rail timetable lookups (台北→左營, 下一班高鐵, 末班自強號) |
+| `/che-transport-mcp:nearby-bike` | YouBike geographic search (附近 YouBike, 哪裡借／還車) |
+
+## NSQL interaction discipline
+
+This MCP is read-only (no execution risk), but **input ambiguity is frequent**:
+
+- 「中山」站 → 紅線？淡水線？桃捷？台中？
+- 「下一班」→ 時間錨點為何？
+- 「往台北」→ 起站為何？
+
+Before calling any tool, **follow NSQL confirmation protocol**:
+
+1. Parse the user query into `function + arguments`
+2. Render the parsed form back to the user
+3. Wait for confirmation
+4. Then call the tool
+
+### Common ambiguity hotspots
+
+| Query phrase | Ambiguity | Resolution |
+|--------------|-----------|------------|
+| 「中山」「忠孝」 | Multi-system same-name stations | Call `rail_search_stations(query)` first, show user the matches |
+| 「下一班」「最近」 | Time anchor | Default = now (Asia/Taipei) unless user says otherwise |
+| 「往北」「往南」 | Direction phrases | Convert to two station_ids; TDX takes O/D, not directions |
+| 「自強號」「對號」 | Train type filter | Client-side filter after `rail_find_trains` returns |
+| 「中山路 / 中山國中」 in bus context | City scoping | Bus tools require `city` — disambiguate Taipei vs Kaohsiung vs ... |
+| 「我附近」 in bike context | Coordinates | Convert landmark to lat/lon via WebSearch; confirm before calling |
+
+## Architecture invariants (binary-side, inherited)
+
+These come from the underlying Swift binary at `PsychQuant/che-transport-mcp`. Worth knowing because they shape tool behavior:
+
+- **Time zone**: All time strings emitted by tools are in Asia/Taipei (`+08:00`)
+- **Empty ≠ error**: Tools return `{"matches": []}` / `{"trains": []}` etc. when no data matches — that's a legitimate result, not a tool failure. Errors (`isError: true`) are reserved for system-level issues (auth, network, rate limit, schema drift)
+- **Cache TTL tiers**: 24h static (stations / routes / lots / CCTV) · 1h timetables · 5-10 min news · 0s live data
+- **Rate limit**: TDX free tier = 50 req/min. 429 triggers single 1s retry; second 429 returns error
+- **臺/台 bidirectional normalization**: Both query and candidate name are normalized before fuzzy matching
+- **LRU cache cap**: default 1000 entries; long sessions won't grow unbounded
+- **City required** for Bus / Parking tools (no fan-out — TDX rate limit + disambiguation)
+- **Parallel fan-out** for `rail_search_stations` when system is unspecified — results stably re-sorted by `RailSystem.allCases` order
+
+## Auth setup (first time)
+
+The binary reads credentials from macOS keychain service `che-transport-tdx`. SessionStart hook surfaces credential presence + binary version. If credentials missing → invoke `/che-transport-mcp:setup-tdx`.
+
+## Update flow
+
+| Scenario | Action |
+|----------|--------|
+| Upgrade plugin shell only (skills / hooks / wrapper) | See **Plugin-shell-only changes** below |
+| Upgrade binary version (full chain) | See **Full upgrade chain** below |
+| Plugin not picking up changes | `Cmd+Q` Claude Code + reopen; closing the window is not enough for MCP servers |
+
+### Two version fields — `version` vs `binaryVersion`
+
+`plugin.json` carries **two** version numbers, deliberately decoupled:
+
+| Field | Tracks | Read by |
+|-------|--------|---------|
+| `version` | The plugin **shell** (skills, hooks, wrapper, docs) | Claude Code marketplace / `claude plugin update` |
+| `binaryVersion` | The **CheTransportMCP binary** release tag | `bin/che-transport-mcp-wrapper.sh` for auto-download |
+
+This split exists because the wrapper downloads the binary release tagged `v$binaryVersion`. If the wrapper read `version`, a shell-only bump (e.g. new skill) would make it chase a binary release tag that doesn't exist → 404 → fallback-to-latest with a lying sidecar. Keeping `binaryVersion` separate means shell and binary cadences are independent. The wrapper falls back to `version` if `binaryVersion` is absent (older plugin.json files).
+
+### Full upgrade chain (binary + plugin)
+
+Triggered when there's a new binary release (new tools, bug fixes, or schema changes in the underlying Swift MCP). Three repos are touched in order:
+
+1. **Source repo** `PsychQuant/che-transport-mcp`
+   - Bump `Sources/CheTransportMCP/Version.swift` (`AppVersion.version = "X.Y.Z"`)
+   - Bump `mcpb/manifest.json` version to match (build-mcpb.sh enforces parity)
+   - Move CHANGELOG `[Unreleased]` content under `[X.Y.Z] — YYYY-MM-DD`
+   - Commit + push
+   - `export DEVELOPER_ID=F2523DCF6D02BE99B67C7D27F633119292DA4934 NOTARY_PROFILE=che-mcps-notary`
+   - `make release-signed` (universal build → Developer ID sign → Apple notarize → pack .mcpb; ~2-10 min)
+   - `git tag vX.Y.Z && git push --tags`
+   - `gh release create vX.Y.Z mcpb/server/CheTransportMCP mcpb/server/CheTransportMCP.sha256 mcpb/che-transport-mcp-X.Y.Z.mcpb mcpb/che-transport-mcp-X.Y.Z.mcpb.sha256 --repo PsychQuant/che-transport-mcp --title "vX.Y.Z — …" --notes-file <notes>`
+   - **Critical**: include the **raw `CheTransportMCP` binary** as a release asset, not just the `.mcpb`. The wrapper greps `browser_download_url` looking for `/CheTransportMCP"` — without the raw binary asset, auto-download fails (the .mcpb is a Claude Desktop bundle, not what the wrapper consumes)
+
+2. **Marketplace repo** `PsychQuant/psychquant-claude-plugins`
+   - Bump **both** `version` and `binaryVersion` in `plugins/che-transport-mcp/.claude-plugin/plugin.json` to `X.Y.Z` (a binary release moves both in lockstep)
+   - Bump matching `version` in `.claude-plugin/marketplace.json`
+   - Optionally refresh the description / keywords if the surface area changed
+   - The fastest path: `/plugin-tools:plugin-update che-transport-mcp` — it bumps + commits + pushes + runs `claude plugin marketplace update` + `claude plugin update` automatically
+
+3. **End-user side** (automatic, no action needed)
+   - Wrapper sees `plugin.json.binaryVersion` ≠ `~/bin/.CheTransportMCP.version` sidecar
+   - Re-downloads pinned tag `vX.Y.Z` from GitHub Release on next MCP spawn (atomic `.tmp + mv` swap)
+   - Falls back to `releases/latest` if pinned tag missing
+   - If anon GitHub API rate limit (60/hr) hit, wrapper preserves the existing binary instead of failing — graceful degradation
+
+### Plugin-shell-only changes
+
+If you only touched skills / hooks / wrapper / CLAUDE.md / README (no binary code change), skip Step 1 entirely:
+
+- Bump only `version` in `plugin.json` (leave `binaryVersion` pinned to the current binary release)
+- Bump the matching entry in `marketplace.json`
+- `/plugin-tools:plugin-update che-transport-mcp`
+
+Because the wrapper reads `binaryVersion` (not `version`), a shell-only `version` bump will NOT trigger a spurious binary re-download. Convention: shell-only bumps keep the binary's major.minor and add a patch — e.g. binary `binaryVersion: 0.2.0`, shell `version: 0.2.1`.
+
+## References
+
+- Source repo: <https://github.com/PsychQuant/che-transport-mcp>
+- TDX register: <https://tdx.transportdata.tw/register>
+- Design spec (in source repo): `docs/superpowers/specs/2026-05-20-che-transport-mcp-design.md`
+- NSQL discipline reference: <https://github.com/kiki830621/NSQL>
diff --git a/plugins/che-transport-mcp/README.md b/plugins/che-transport-mcp/README.md
new file mode 100644
index 00000000..237d6bb0
--- /dev/null
+++ b/plugins/che-transport-mcp/README.md
@@ -0,0 +1,68 @@
+# che-transport-mcp
+
+[![Marketplace](https://img.shields.io/badge/marketplace-psychquant--claude--plugins-blue)](https://github.com/PsychQuant/psychquant-claude-plugins) [![Source](https://img.shields.io/badge/source-PsychQuant%2Fche--transport--mcp-blue)](https://github.com/PsychQuant/che-transport-mcp)
+
+Claude Code plugin wrapping the `che-transport-mcp` Swift MCP server.
+21 tools querying Taiwan's [TDX 運輸資料流通服務](https://tdx.transportdata.tw/) across **Rail / Bus / Bike / Air / Traffic / Parking**.
+
+## Install
+
+```
+/plugin marketplace add PsychQuant/psychquant-claude-plugins
+/plugin install che-transport-mcp@psychquant-claude-plugins
+```
+
+The wrapper auto-downloads the signed + notarized `CheTransportMCP` binary from the corresponding GitHub Release on first MCP spawn (atomic swap, sha256-verifiable).
+
+## Setup (one-time, ~3 min)
+
+1. Register a free TDX account: <https://tdx.transportdata.tw/register>
+2. From the TDX 會員中心 → API 金鑰, create an API key (you get `client_id` + `client_secret`)
+3. Seed the macOS keychain:
+
+```
+/che-transport-mcp:setup-tdx
+```
+
+The skill opens a **real Terminal window** running `CheTransportMCP --setup` — a subcommand of the signed binary that prompts for `client_id` / `client_secret` (the secret hidden via `getpass`), writes them to keychain service `che-transport-tdx`, and verifies with a live OAuth round-trip. The secret is typed into that separate window, so it never appears in Claude Code's transcript.
+
+4. **Quit Claude Code fully** (Cmd+Q) and reopen so the MCP server picks up the new credentials.
+
+## What you can ask
+
+| Example user query | Tools that fire |
+|--------------------|-----------------|
+| 下一班高鐵台北到左營 | `rail_search_stations` → `rail_find_trains` |
+| 台北車站附近 YouBike | `bike_stations_nearby` |
+| 307 公車到站時間 | `bus_search_stops` → `bus_status_arrivals` |
+| 桃園機場 BR189 班機狀態 | `air_status_flights` |
+| 國道 1 號現在塞嗎 | `traffic_freeway_live` |
+| 信義區停車場 | `parking_list_lots` → `parking_status` |
+
+## Components
+
+- **MCP server**: `transport` (auto-spawned via `.mcp.json` + wrapper)
+- **Skills**: `/che-transport-mcp:setup-tdx`, `/che-transport-mcp:today-rail`, `/che-transport-mcp:nearby-bike`
+- **Hooks**: `SessionStart` — single-line banner with binary version + TDX credential status
+
+## Architecture
+
+See [CLAUDE.md](./CLAUDE.md) for invariants the LLM should respect:
+
+- Time zone Asia/Taipei
+- Empty ≠ error
+- City required for Bus / Parking
+- NSQL parse-confirm-call discipline for ambiguous queries
+
+## Update
+
+Plugin shell changes (skills, wrapper, hooks):
+```
+/plugin-tools:plugin-update che-transport-mcp
+```
+
+Binary upgrade — bump `version` in `.claude-plugin/plugin.json`; wrapper detects drift via the `~/bin/.CheTransportMCP.version` sidecar and re-downloads on next spawn.
+
+## License
+
+MIT. See [LICENSE](https://github.com/PsychQuant/che-transport-mcp/blob/main/LICENSE) in the binary source repo.
diff --git a/plugins/che-transport-mcp/bin/che-transport-mcp-wrapper.sh b/plugins/che-transport-mcp/bin/che-transport-mcp-wrapper.sh
new file mode 100755
index 00000000..b94bbe77
--- /dev/null
+++ b/plugins/che-transport-mcp/bin/che-transport-mcp-wrapper.sh
@@ -0,0 +1,103 @@
+#!/bin/bash
+# Version-aware auto-download wrapper for CheTransportMCP.
+#
+# Pattern shared with sibling che-*-mcp plugins (e.g. che-ical-mcp):
+# - Reads desired version from plugin.json (single source of truth)
+# - Compares against ~/bin/.CheTransportMCP.version sidecar
+# - Re-downloads when plugin updated but binary stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+#
+# Unlike che-ical-mcp this binary has no TCC requirement (TDX is plain HTTPS);
+# user only needs to seed credentials via `make setup-tdx` in the source repo or
+# `/che-transport-mcp:setup-tdx` skill.
+
+set -u
+
+REPO="PsychQuant/che-transport-mcp"
+BINARY_NAME="CheTransportMCP"
+INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read the desired *binary* version from plugin.json.
+#
+# IMPORTANT: this is "binaryVersion", NOT "version". The plugin shell version
+# ("version") and the binary release version ("binaryVersion") are decoupled —
+# a shell-only update (new skill, doc fix) bumps "version" but must NOT make the
+# wrapper chase a binary release tag that doesn't exist. Falls back to "version"
+# for backward compatibility with plugin.json files predating the split, then to
+# "latest" if neither field is parseable.
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"binaryVersion":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+    if [[ -z "$DESIRED_VERSION" ]]; then
+        DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+            | head -1 | cut -d'"' -f4 || true)
+    fi
+fi
+
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
+
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
+    mkdir -p "$INSTALL_DIR"
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
+    fi
+fi
+
+exec "$BINARY" "$@"
diff --git a/plugins/che-transport-mcp/bin/setup-tdx.sh b/plugins/che-transport-mcp/bin/setup-tdx.sh
new file mode 100755
index 00000000..a95e6a7b
--- /dev/null
+++ b/plugins/che-transport-mcp/bin/setup-tdx.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# setup-tdx.sh — launcher shim. All real logic lives in the Swift binary's
+# `--setup` subcommand (interactive prompt + keychain write + OAuth verify).
+#
+# This file exists only so the setup-tdx skill can `open -a Terminal` a single
+# file: `open` cannot pass arguments to a script, so we need a fixed entry
+# point that forwards to `wrapper --setup`. The wrapper auto-downloads the
+# binary first if it isn't installed yet.
+#
+# Run interactively in a real Terminal window — the binary's getpass() prompt
+# needs a TTY.
+exec "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/che-transport-mcp-wrapper.sh" --setup
diff --git a/plugins/che-transport-mcp/hooks/hooks.json b/plugins/che-transport-mcp/hooks/hooks.json
new file mode 100644
index 00000000..d087c3ab
--- /dev/null
+++ b/plugins/che-transport-mcp/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/che-transport-mcp/hooks/session-start.sh b/plugins/che-transport-mcp/hooks/session-start.sh
new file mode 100755
index 00000000..b437eb73
--- /dev/null
+++ b/plugins/che-transport-mcp/hooks/session-start.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# SessionStart hook — emit single-line status banner for che-transport-mcp.
+# Shows binary version (from sidecar) + whether TDX credentials are seeded.
+
+set -u
+
+BINARY_NAME="CheTransportMCP"
+VERSION_FILE="$HOME/bin/.${BINARY_NAME}.version"
+BINARY="$HOME/bin/$BINARY_NAME"
+
+if [[ -x "$BINARY" ]]; then
+    VERSION="$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || echo 'unknown')"
+    echo "✓ $BINARY_NAME v${VERSION} installed: $BINARY"
+else
+    echo "ℹ $BINARY_NAME not installed — will auto-download on first MCP call"
+fi
+
+# Surface TDX credential status. Keychain account names match the Auth.swift
+# convention (service=che-transport-tdx). We don't print the secret — just
+# whether the keychain entry exists. Soft-fail: missing creds is not a fatal
+# state, it just means /setup-tdx hasn't been run yet.
+if security find-generic-password -s che-transport-tdx -a client_id >/dev/null 2>&1 \
+   && security find-generic-password -s che-transport-tdx -a client_secret >/dev/null 2>&1; then
+    echo "✓ TDX credentials present in keychain (service: che-transport-tdx)"
+else
+    echo "⚠ TDX credentials missing — run /che-transport-mcp:setup-tdx or \`make setup-tdx\` in source repo"
+    echo "   register free TDX account: https://tdx.transportdata.tw/register"
+fi
diff --git a/plugins/che-transport-mcp/skills/nearby-bike/SKILL.md b/plugins/che-transport-mcp/skills/nearby-bike/SKILL.md
new file mode 100644
index 00000000..44677c94
--- /dev/null
+++ b/plugins/che-transport-mcp/skills/nearby-bike/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: nearby-bike
+description: Find YouBike (1.0 + 2.0) stations near a location with live available-rent / available-return counts. Use when user says "我附近有 YouBike 嗎 / 哪裡有 ubike / 借車 / 還車 / 信義區誠品 youbike / 北車 youbike" or similar geographic bike queries. Walks user from landmark → coordinates → `bike_stations_nearby`, sorts by distance, surfaces available counts so user can pick a station with capacity.
+allowed-tools:
+  - AskUserQuestion
+  - WebSearch
+---
+
+# nearby-bike — find YouBike near a location
+
+Wraps `bike_stations_nearby` for the most common bike-share use case: "where's the closest YouBike with a bike to rent (or empty slot to return)?"
+
+## NSQL discipline
+
+Parse → confirm → call. The slippery part for bike queries is converting **landmark names to lat/lon coordinates**, since `bike_stations_nearby` takes geographic input not station names.
+
+## Step-by-step flow
+
+### Step 1: Parse the user query
+
+Extract:
+- **Location anchor** (landmark / address / explicit lat-lon)
+- **City** (BikeCity code — Taipei / NewTaipei / Taoyuan / Taichung / Tainan / Kaohsiung / Hsinchu / HsinchuCounty / ChanghuaCounty / PingtungCounty / Chiayi / ChiayiCounty / MiaoliCounty / YilanCounty / Keelung)
+- **Search radius** (default 500 m; clamp to [50, 3000])
+- **Intent** — borrow (need `available_rent > 0`) or return (need `available_return > 0`)? Default = borrow.
+
+### Step 2: Geocode landmark → lat/lon
+
+If user gave coordinates directly, skip this step. Otherwise:
+
+- For well-known landmarks (台北車站 / 101 / 西門町 / 高雄美麗島站 / 中正紀念堂 / 高鐵某站), you may already know coordinates.
+- For ambiguous or less-famous addresses, use WebSearch with query like `"<landmark> latitude longitude"` to get coordinates from Wikipedia / Google Maps page snippets.
+- Always **confirm the geocoded coordinates with the user before proceeding** — "誠品" matches dozens of locations across Taiwan.
+
+### Step 3: Pick a city
+
+Most landmarks map unambiguously to a city, but show your inferred BikeCity to the user and let them correct.
+
+### Step 4: Confirm before calling
+
+Render the parsed form, e.g.:
+
+> 即將呼叫 `bike_stations_nearby(lat=25.0478, lon=121.5170, city='Taipei', radius_m=500)`（台北車站方圓 500 公尺）。確認嗎？
+
+### Step 5: Call `bike_stations_nearby`
+
+```
+mcp__che-transport-mcp__bike_stations_nearby(lat=<float>, lon=<float>, city=<BikeCity>, radius_m=<int>)
+```
+
+### Step 6: Filter by intent
+
+- **Borrow** (default): only show stations with `available_rent > 0` AND `service_status == 1` (營運中)
+- **Return**: only show stations with `available_return > 0` AND `service_status == 1`
+- Sort by `distance_m` ascending
+- Show top 5 with: name_zh, distance_m, service_type (1.0 vs 2.0), available_rent / available_return
+
+### Step 7 (optional): Empty radius expansion
+
+If filtered result is empty:
+1. **Confirm with user** before expanding — "500m 內沒有可借的 YouBike，要擴大到 1000m 嗎？"
+2. Re-call with larger radius (capped at 3000m)
+3. Do NOT silently expand — wastes their attention if they actually want to know "nothing close"
+
+## Empty result handling
+
+- Empty within max radius = legitimate result, present as "您附近沒有 YouBike 站點" not as an error
+- City coverage uneven — TDX YouBike data spans ~15 cities but rural counties may return empty regardless
+- Service type filter: most users don't care 1.0 vs 2.0 — surface it as info but don't require user to specify
diff --git a/plugins/che-transport-mcp/skills/setup-tdx/SKILL.md b/plugins/che-transport-mcp/skills/setup-tdx/SKILL.md
new file mode 100644
index 00000000..5f8bc0fd
--- /dev/null
+++ b/plugins/che-transport-mcp/skills/setup-tdx/SKILL.md
@@ -0,0 +1,177 @@
+---
+name: setup-tdx
+description: Guide user through obtaining TDX (運輸資料流通服務) credentials and seeding them into the macOS keychain so che-transport-mcp tools can authenticate. Handles both first-time users with no TDX account (walks through registration + API-key retrieval) and users who already have credentials. Use when che-transport-mcp tools fail with "TDX auth failed" / "Missing TDX credentials" / "401", when the SessionStart banner shows "⚠ TDX credentials missing", or when the user asks to set up TDX / 註冊 TDX / 拿 TDX API key / 設定憑證. Credentials live under keychain service "che-transport-tdx" with accounts "client_id" and "client_secret".
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+---
+
+# Setup TDX credentials for che-transport-mcp
+
+TDX 運輸資料流通服務 is the Taiwan government open-data API that all 21 tools in this plugin query. Free tier = 50 requests/min, no card needed.
+
+Setup has **two halves**, and it matters which one the user is stuck on:
+
+1. **Get a TDX account + API key** — a web task on the TDX portal. A brand-new user has to register and dig the key out of the member area. This skill hand-holds that (Step 3) — it is the part people actually get stuck on.
+2. **Seed the keychain** — `CheTransportMCP --setup`, an interactive flow in the signed binary that reads `client_secret` via `getpass()` (hidden), writes to keychain, and verifies with a live OAuth round-trip. This skill launches it in a **real Terminal window** so the secret never enters Claude Code's transcript.
+
+Do NOT seed the keychain via the Bash tool with the secret inline — that leaks it into the conversation log. Always go through the Terminal-window path (Step 5) or have the user run `--setup` in their own terminal.
+
+## Step 1: Check if already seeded
+
+```bash
+security find-generic-password -s che-transport-tdx -a client_id  >/dev/null 2>&1 \
+  && security find-generic-password -s che-transport-tdx -a client_secret >/dev/null 2>&1 \
+  && echo "SEEDED" || echo "MISSING"
+```
+
+If `SEEDED`: credentials already exist. Ask if the user wants to re-run setup anyway (rotated / wrong key). If not, stop — just remind them to `Cmd+Q` + reopen Claude Code if tools still fail.
+
+If `MISSING`: proceed.
+
+## Step 2: Does the user already have a TDX API key?
+
+This is the branch point. Ask with `AskUserQuestion`:
+
+> 你已經有 TDX 的 `client_id` 和 `client_secret` 了嗎？
+
+- **Options**: "有，憑證在手邊" / "沒有，需要先申請" / "不確定 / 不知道那是什麼"
+- "有" → skip to **Step 4**
+- "沒有" or "不確定" → do **Step 3** first
+
+Never assume the user has credentials. A first-time plugin user almost certainly does not — the SessionStart banner saying "⚠ TDX credentials missing" only means the keychain is empty, not that they have a key ready to paste.
+
+## Step 3: Register a TDX account + retrieve the API key
+
+This is a **web task** — it cannot be automated. Walk the user through it conversationally and stay with them; answer questions as they go.
+
+### 3a. Register
+
+Offer to open the registration page:
+
+```bash
+open "https://tdx.transportdata.tw/register"
+```
+
+Registration is free, no credit card, ~2 minutes. A standard account is usable right after signup; the 學研單位 (academic) tier additionally goes through a review step before the key activates — most users want the standard account.
+
+### 3b. Retrieve client_id + client_secret
+
+Once registered and logged in, the API key is **not** shown on the landing page. Guide them through the exact path:
+
+1. Top-right corner → **會員中心**
+2. → **資料服務**
+3. → **API 金鑰**
+4. A key pair already exists by default. Click the green **編輯** button on that row to reveal **Client Id** and **Client Secret**.
+5. Copy **both** values somewhere safe (Notes, password manager) — the secret is not always re-displayed later.
+
+Notes to relay:
+- Each account may hold up to **3** API keys (新增 API 金鑰 to add more) — one is plenty here.
+- If the user can't find 會員中心 / the menu wording differs, the portal UI may have changed — have them look for any "API 金鑰" / "API Key" entry under the member/account area, or check the TDX 介接指南.
+- Do NOT ask the user to paste the values into the chat. They only need them in hand for Step 5, typed into a separate Terminal window.
+
+Wait until the user confirms they have both values before continuing.
+
+## Step 4: Pick the credential-entry path
+
+Two paths exist; **prefer (A)**. The preference is purely UX — both paths have the same security property (typed values never enter this Claude Code session).
+
+### (A) `che-keychain` is installed → direct native dialog
+
+Detect:
+
+```bash
+which che-keychain >/dev/null 2>&1 || [ -x ~/bin/che-keychain ] && echo "PRESENT" || echo "ABSENT"
+```
+
+If `PRESENT`, invoke directly via the Bash tool. che-keychain pops a native NSAlert (`client_id` visible + `client_secret` masked, in **one** dialog). User types into that dialog; this Claude Code session never sees the values.
+
+```bash
+che-keychain set-pair \
+  --service che-transport-tdx \
+  --visible-account client_id \
+  --secure-account client_secret \
+  --visible-label "TDX client_id" \
+  --secure-label "TDX client_secret" \
+  --title "che-transport-mcp — TDX setup" \
+  --explain "Free TDX account: https://tdx.transportdata.tw/register  •  會員中心 → 資料服務 → API 金鑰 → 編輯"
+```
+
+Exit codes from the Bash tool: `0` stored, `2` user cancelled, other → error (see stderr).
+
+After exit `0`, run the OAuth verification step yourself via the CheTransportMCP binary (skip to **Step 6**):
+
+```bash
+~/bin/CheTransportMCP --check-auth
+```
+
+Tell the user clearly:
+
+> 已彈出 che-keychain 對話框 — 請在**那個視窗**輸入 client_id / client_secret。client_secret 全程不會經過這裡的對話。完成後我會自動驗證。
+
+If `che-keychain` is `ABSENT`, point the user at <https://github.com/PsychQuant/che-keychain> as a one-time install, OR proceed with path (B).
+
+### (B) Fallback — Terminal window running the binary's built-in `--setup`
+
+If `che-keychain` isn't installed (or the user doesn't want to install it), launch the plugin's launcher shim in a real Terminal window. The shim forwards to `wrapper --setup` → `CheTransportMCP --setup` (getpass-based; CheTransportMCP v0.2.2+ also auto-detects che-keychain itself, so if che-keychain shows up later this same shim picks it up).
+
+Locate the shim:
+
+```bash
+SETUP=$(ls ~/.claude/plugins/cache/*/che-transport-mcp/*/bin/setup-tdx.sh 2>/dev/null | sort -V | tail -1)
+[ -z "$SETUP" ] && SETUP=$(find ~/.claude/plugins -path '*che-transport-mcp*/bin/setup-tdx.sh' -type f 2>/dev/null | sort -V | tail -1)
+```
+
+If still empty, the plugin install is broken — tell the user to `/plugin install che-transport-mcp@psychquant-claude-plugins`.
+
+Launch:
+
+```bash
+open -a Terminal "$SETUP"
+```
+
+Tell the user:
+
+> 已開了一個 Terminal 視窗。請在**那個視窗**裡完成 — client_secret 用 getpass 隱藏輸入，全程不會經過這裡的對話。完成後回來告訴我。
+
+Then wait for the user to report back.
+
+## Step 6: Confirm result
+
+After the user says they're done, re-check:
+
+```bash
+security find-generic-password -s che-transport-tdx -a client_id  >/dev/null 2>&1 \
+  && security find-generic-password -s che-transport-tdx -a client_secret >/dev/null 2>&1 \
+  && echo "SEEDED ✓" || echo "STILL MISSING"
+```
+
+If still missing, the user likely aborted or hit an error in the dialog / Terminal window. Ask what was reported:
+- `che-keychain` returned exit code `2` → user cancelled. Just re-run from Step 4.
+- `verification failed: ... HTTP 401` → key pair was wrong or mis-copied (trailing space, swapped id/secret). Re-run from Step 4; double-check against the TDX 編輯 page.
+- The user closed the dialog / Terminal early → just re-run Step 4.
+
+## Step 7: Restart Claude Code
+
+Even after credentials verify, the MCP server already spawned by the current Claude Code session won't see them. The user must **fully quit Claude Code (Cmd+Q)** and reopen. Closing the window is not enough — MCP server processes outlive a closed window.
+
+## Fallback: no Terminal.app available
+
+If `open -a Terminal` is unavailable (SSH session, headless), tell the user to run the binary's `--setup` directly in whatever interactive shell they have. Emphasize: run it in a **terminal, not in Claude Code chat** — the secret prompt needs a TTY.
+
+```bash
+~/bin/CheTransportMCP --setup
+```
+
+Same interactive flow, no shell-script middleman. If the binary isn't at `~/bin/CheTransportMCP` yet, run the wrapper instead (it downloads then forwards):
+
+```bash
+~/.claude/plugins/cache/*/che-transport-mcp/*/bin/che-transport-mcp-wrapper.sh --setup
+```
+
+## When NOT to invoke this skill
+
+- User reports tools returning empty arrays `{"matches": [], "trains": []}` — that's "empty ≠ error" by design, not a credential issue
+- User reports `429 rate limit` — credentials are fine, slow down request rate
+- User reports `Invalid station '...'` — credentials are fine, query format wrong (use `rail_search_stations` first to get IDs)
diff --git a/plugins/che-transport-mcp/skills/today-rail/SKILL.md b/plugins/che-transport-mcp/skills/today-rail/SKILL.md
new file mode 100644
index 00000000..905fadb9
--- /dev/null
+++ b/plugins/che-transport-mcp/skills/today-rail/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: today-rail
+description: Quick rail query helper — find the next train(s) between two stations today on TRA / THSR / metros. Use when user says "下一班高鐵 / 台北到左營 / 下午回新竹的高鐵 / 今天最後一班自強號 / 還來得及搭末班車嗎" or similar O/D timetable queries. Walks NSQL discipline (parse → confirm → call) using rail_search_stations to disambiguate Chinese station names like 中山 / 忠孝 across multiple systems, then rail_find_trains for the actual schedule, optionally rail_status_train for live delay.
+allowed-tools:
+  - AskUserQuestion
+---
+
+# today-rail — quick rail query
+
+Wraps `rail_search_stations` → `rail_find_trains` → optional `rail_status_train` for the most common Taiwan rail use case: "what trains run from A to B today / at this time?"
+
+## NSQL discipline (mandatory)
+
+Per the plugin's CLAUDE.md, **never call rail tools without first parsing user intent into `function + arguments` and confirming with the user**. Common ambiguity:
+
+| User phrase | Question to resolve |
+|-------------|---------------------|
+| 「中山」「忠孝」 | Multiple systems have same-named stations — TRTC vs TYMC vs Taichung MRT? |
+| 「下一班」「最近」 | Time anchor — now (Asia/Taipei) unless user specifies |
+| 「往台北」「往南」 | Direction phrases must be converted to actual origin/destination IDs |
+| 「自強號」「對號」 | Train type filter applied client-side after rail_find_trains returns |
+
+## Step-by-step flow
+
+### Step 1: Parse the user query
+
+Extract:
+- **Origin station name** (zh or en)
+- **Destination station name**
+- **System** (TRA / THSR — required for `rail_find_trains`; metros use station-board tools instead)
+- **Date** (default = today in Asia/Taipei)
+- **Time anchor** (default = now; filter results to trains departing >= now)
+- **Train type filter** (optional — 自強 / 莒光 / 區間 / etc.)
+
+### Step 2: Resolve station IDs via `rail_search_stations`
+
+If either station name is ambiguous (matches multiple stations) or you can't be sure of the system, call:
+
+```
+mcp__che-transport-mcp__rail_search_stations(query="<name>", system=<TRA|THSR|...>)
+```
+
+Show the user the matches and ask them to pick if >1 result.
+
+### Step 3: Confirm before calling
+
+Render the parsed form back to the user, e.g.:
+
+> 即將呼叫 `rail_find_trains(from='1000', to='1070', system='THSR', date='2026-05-21')`，篩選 17:00 之後的班次。確認嗎？
+
+Wait for "對 / 好 / yes / 確認". Don't preemptively call.
+
+### Step 4: Call `rail_find_trains`
+
+```
+mcp__che-transport-mcp__rail_find_trains(from=<ID>, to=<ID>, system=<TRA|THSR>, date=YYYY-MM-DD)
+```
+
+### Step 5: Filter + format
+
+- Filter trains where departure time >= time anchor
+- Apply train-type filter if user requested
+- Sort by departure time ascending
+- Show top 3-5 to keep response readable
+
+For each train show: train_no, 車種, 起站 dep, 迄站 arr, 行車時間, 票價（若有）.
+
+### Step 6 (optional): Live delay check
+
+If user explicitly asks "誤點" / "delayed" / "real-time" or the train they're picking departs within the next hour, additionally call:
+
+```
+mcp__che-transport-mcp__rail_status_train(train_no=<N>, system=<TRA|THSR>)
+```
+
+…and overlay delay info on the picked train.
+
+## Empty result handling
+
+If `rail_find_trains` returns `{"trains": []}`:
+
+- Verify station IDs and date are valid (most likely cause: wrong system — e.g. asking THSR between two TRA-only stations)
+- "Empty ≠ error" — say "今天該方向沒有班次" rather than treating as a tool failure
+- Do NOT retry with different parameters without user input — that's scope creep
+
+## When NOT to invoke
+
+- Metro queries (`中山站下一班捷運往淡水`) — TRA/THSR `rail_find_trains` doesn't cover metro, use `rail_status_station` for metro arrivals
+- Cross-system journeys (台北→台中→嘉義 mixed TRA+THSR) — out of scope for v0.2; tell user to query each leg
diff --git a/plugins/che-word-mcp/.claude-plugin/plugin.json b/plugins/che-word-mcp/.claude-plugin/plugin.json
index e9cb74db..5f44475f 100644
--- a/plugins/che-word-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-word-mcp/.claude-plugin/plugin.json
@@ -1,8 +1,17 @@
 {
   "name": "che-word-mcp",
-  "version": "1.17.0",
-  "description": "Word MCP Server - Swift 原生 OOXML 操作，148 個工具，支援 Dual-Mode + Session 狀態管理",
-  "author": { "name": "Che Cheng" },
+  "version": "3.20.0",
+  "description": "v3.20.0 cross-document OMath splice MCP tools (#160) — splice_omath_from_source + splice_paragraph_omath_from_source wrap ooxml-swift v0.24.0's spliceOMath API for verbatim copy of <m:oMath> XML blocks between WordDocument paragraphs. Source via source_path (Direct mode read-only) or source_doc_id (Session mode); target requires session-mode doc_id. Position via atStart/atEnd/afterText/beforeText with optional anchor + instance. Carrier preservation (Run.rawXML stays inline, unrecognizedChildren stays direct-child); joint document-order index for omath_index across both source carriers. rpr_mode controls source Run rPr propagation (full default verbatim / omathOnly whitelist / discard empty); namespace_policy controls prefix vs URI handling (lenient default accepts mml: vs m: prefix mismatch with same URI per ECMA-376 / strict throws on any mismatch). Error taxonomy returned as structured strings: sourceHasNoOMath / omathIndexOutOfRange / targetParagraphOutOfRange / anchorNotFound / namespaceMismatch / contextAnchorNotFound (batch only). Unblocks kiki830621/collaboration_guo_analysis Phase 7 inline-math restoration pipeline. Tests: 8 new Issue160SpliceOMathFromSourceTests (Direct/Session source modes, atEnd/afterText positions, error taxonomy, batch mode, rPr discard). Full suite: 297 passing, 0 failures, 9 pre-existing skips. Bumps ooxml-swift dep 0.21.0 → 0.24.0. v3.19.0 caption detection (#136) + estimate_paragraph_for_page structural weights v2 (#142). #136: two-layer detection — Paragraph.style primary + expanded prefix set (English Tab./Fig./Listing + CJK 表3/圖1 no-separator + U+3000 ideographic space) with digit-after-prefix guard rejecting body sentences like \"Table reservations are required...\". 17 new tests. #142: walker upgrade getParagraphs → collectStructuralBlocks enum (.paragraph/.table/.imageOnlyParagraph/.displayEquationParagraph). Per-block weights (12pt thesis calibration): table = tableRows × avgCellChars (200/row fallback), image = +200/drawing, display eq = 120 chars. New structural_breakdown metadata (9 sub-fields). API method bumped char_count_heuristic → char_count_heuristic_v2. ~95× thesis figure-counting accuracy improvement. paragraph_index semantics + getParagraphs() preserved (30+ other callers unaffected). Tests: 6 new + #89 backward-compat passes (text-only fixtures unchanged, just method literal updated). 1 P3 follow-up filed (#159 display-eq fixture limitation). v3.18.1 transitive dependency bump — ooxml-swift v0.21.11 → v0.22.1. Closes PsychQuant/che-word-mcp#155 (parent / mirror) auto-resolves via Package.resolved bump alone (no MCP source change). Pre-fix: che-word-mcp__search_text MCP tool's Server.swift:10310 calls para.getText(), which was a legacy 7-line implementation that only joined runs.map { $0.text } + hyperlink.text — missed every walker enhancement landed in flattenedDisplayText() over the #85 / #92 / #99 / #100 / #101 / #102 / #103 cluster. Callers couldn't grep for inline math symbols (α / β / γ / θ / λ / t) — silent zero gaps in match positions. Post-fix: ooxml-swift#43 collapsed Paragraph.getText() to single-line return flattenedDisplayText(); two text-extraction paths now return identical strings. Server.swift:10310 still calls para.getText() but that method now traverses inline OMML correctly. Position arithmetic now matches before_text / after_text anchor-matching paths. Downstream impact: kiki830621/collaboration_guo_analysis#6 (thesis 30 inline math symbols) unblocked from automation — re-running search_text 進行t檢定 against 碩士論文.docx para 324 now returns a match. Released via /idd-all #43 --cwd cross-repo IDD orchestration (issue-driven-dev v2.40.0). Closing summary at https://github.com/PsychQuant/ooxml-swift/issues/43#issuecomment-4365430488. v3.18.0 insert_equation argument-contract hardening (closes #105 #106 #107). v3.17.8 closes PsychQuant/che-word-mcp#98 — insert_equation MCP handler refactored across 3 commits (91506f8/357cbe7/339ab77). Pre-fix three structural defects: (1) silent-clamp on out-of-range paragraph_index via non-throwing insertParagraph(_:at: Int) — tool reported success but inserted at wrong location; (2) lib's #84/#91 InsertLocation overload + InsertLocationError.inlineModeRequiresParagraphIndex / .invalidParagraphIndex(Int) structured errors never reached MCP callers (handler self-built OMML and bypassed lib); (3) inline mode (display_mode=false) always created a NEW Paragraph(runs: [eqRun]) instead of appending OMML run to the EXISTING paragraph at paragraph_index. v1 (91506f8) tried delegating to lib but Codex 6-AI verify caught P1 regression: lib's Document.insertEquation overload internally uses @available(*, deprecated, ...) MathEquation flat output (Field.swift:301) — emits truncated '(a)/(b' AND nested <w:p><w:p> invalid OOXML. v2 (357cbe7) unified handler — both latex AND components paths use MathComponent.toOMML() for structurally correct OMML; display mode routes through lib's throwing insertParagraph(_:at: InsertLocation); inline mode handler-side appends OMML run to existing paragraph. v3 (339ab77) restored eqPara.properties.alignment = .center for display mode. BREAKING for inline mode callers: pre-fix inserted NEW paragraph; post-fix appends OMML run to EXISTING paragraph at paragraph_index. Migration: use display_mode=true for 'new paragraph with equation' or call insert_paragraph + insert_equation separately. 7 NEW Issue98InsertEquationLibBypassTests pin contracts (5 RED→GREEN scenarios + 2 quality regression tests including unzip -p document.xml verifying <m:f> structure + centering survives + deprecated '(a)/(b)' pattern absent). 6-AI verify ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) caught both P1 regressions in v1; Codex sanity check on v2 caught the centering P2. 6 P2/P3 follow-up issues filed (#105-#110). Suite: 236 → 243 tests, 0 failures, 9 pre-existing skips. Backward compatible except inline-mode BREAKING (documented). v3.17.7 ooxml-swift dep bump 0.21.10 → 0.21.11 — closes 5-issue cluster PsychQuant/che-word-mcp #99 + #100 + #101 + #102 + #103. Bilateral mirror coverage for direct-child OMML at 4 wrapper positions (<w:p> direct child for Pandoc display math / <w:hyperlink> direct child / <mc:Fallback> direct child / nested wrapper combos), plus 2 NEW library-wide spec capabilities. Pre-fix Paragraph.flattenedDisplayText AND Document.replaceInParagraphSurfaces shared a symmetric blind spot: direct-child <m:oMath>/<m:oMathPara> (not wrapped in <w:r>) was silently dropped → anchor lookups against paragraphs containing display math silently 0-matched. Spectra change flatten-replace-omml-bilateral-coverage. 2 NEW spec capabilities promoted to openspec/specs/: ooxml-paragraph-text-mirror (mirror invariant + ReplaceResult informative refusal contract) + ooxml-library-design-principles (Correctness primacy + Human-like operations as foundational normative invariants for all ooxml-swift mutators). Read side: flattenedDisplayText walks direct-child OMML at all 4 wrapper positions with source-XML position ordering. Write side: NEW public API WordDocument.replaceTextWithBoundaryDetection returns ReplaceResult enum (.replaced(count:) / .refusedDueToOMMLBoundary(occurrences:) / .mixed(replacedCount:, refusedOccurrences:)) with Occurrence(matchSpan:, ommlSpans:) carrying flattened-text coordinates. Mirror invariant — asymmetric by design: reads include OMML visibleText (anchor lookup universe extends to math); writes treat OMML as opaque structural units (refuse cross-OMML mutation rather than silently delete equations). Decision 4 raw passthrough preserved: direct-child OMML stays in Paragraph.unrecognizedChildren / HyperlinkChild.rawXML(_) / AlternateContent.rawXML — no parser change, no writer change, round-trip fidelity unaffected. MCP impact: replace_text and other anchor-lookup tools now find paragraphs containing direct-child OMML at all 4 wrapper positions; existing replace_text MCP tool unchanged (backward-compatible). Tests: 236 passing che-word-mcp / 813→829 ooxml-swift (+16 in Issue99FlattenReplaceOMMLBilateralTests). Backward compatible — strict superset of pre-fix behavior. v3.17.6 ooxml-swift dep bump 0.21.9 → 0.21.10 — closes PsychQuant/che-word-mcp#104. Form-level FieldParser canonical 5-run fldChar fix (orthogonal to v3.17.5's #94 container-level fix). Pre-fix update_all_fields returned silent no-op ('no SEQ fields found') on docs containing valid SEQ paragraphs at body top level when fldChar block was emitted in canonical 5-run form (each <w:fldChar>/<w:instrText>/<w:t> in its own <w:r> sibling — what DocxReader produces post-roundtrip and what native Word always emits). Pre-fix worked only on in-memory wrap_caption_seq output before save. Two ooxml-swift commits land via this dep bump: 537de62 FieldParser two-phase parse (Phase-1 baked form + Phase-2 parseFiveRunSpan state machine probing both Run.rawXML and Run.rawElements per recognizedRunChildren = ['rPr','t','drawing','oMath','oMathPara'] allowlist) + 58fe4f9 P1 sub-fix surfaced by 6-AI verify (Logic + Devil's Advocate runtime test): canonical-branch Run.text rewrite was silently overridden by Run.toXML() rawXML short-circuit; new rewriteCanonicalCachedText helper splices new value into embedded <w:t> while preserving <w:rPr> + xml:space=preserve, AND keeps Run.text in sync. MCP impact: update_all_fields now finds and updates SEQ fields in canonical 5-run form (post-roundtrip / native Word emission); list_captions benefits transitively via shared FieldParser. Verified by 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) — 4 PASS / 2 WARN / 0 BLOCK; production reproducer rescue-swift-v317.docx via DocxReader path confirmed working. 5 P3 follow-ups filed in ooxml-swift (#29 SEQ Table coverage / #30 multi-paragraph counter / #31 multi-SEQ same paragraph / #32 DoS hardening / #33 discriminator invariant). Tests: 236 passing che-word-mcp / 809→813 ooxml-swift (+4 sub-tests in Issue104FieldParserCanonicalFormTests). Backward compatible — strict superset of pre-fix behavior. v3.17.5 ooxml-swift dep bump 0.21.8 → 0.21.9 — triple #87 + #93 + #94 release. #87 (Comment.paragraphIndex flat-counter, observable behavior change): list_comments paragraph_index now consistently 0-indexed against get_paragraphs() flat list; pre-fix off-by-N for any docx with non-paragraph BodyChild siblings before commented paragraph; callers manually compensating with paragraph_index - 1 must remove compensation. #93 (wrap_caption_seq SEQ inherits source position, caption visual fix): pre-fix 「圖 4-1：xxx」 became 「圖 4-：xxx1」 because new SEQ run had position=nil while source-loaded preText/postText had position>0; one-line fix seqRun.position = preRun.position; insert_bookmark=true × source-loaded paragraph still has same gap (filed PsychQuant/ooxml-swift#24, default insert_bookmark=false unaffected). #94 (update_all_fields traverses .table and .contentControl containers): pre-fix body loop only processed top-level .paragraph BodyChild, silently skipped .table and .contentControl(_, children:) — SEQ fields inside table cells/block-level SDTs never updated, returning 'no SEQ fields found' for thesis docs (caption paragraphs commonly live inside the table they describe); same gap #68 closed for findBodyChildContainingText; new walkAndProcessBodyChildForFields recursive walker mirrors #68 pattern; heading-count semantics: only top-level direct .paragraph body children count toward chapter-reset. Known incompleteness (3 follow-ups filed): ooxml-swift#25 header/footer/footnote/endnote SEQ scans still flat .paragraphs view; ooxml-swift#26 FieldParser.parse(paragraph:) misses inline SDT/hyperlink/fieldSimple/alternateContent surfaces; ooxml-swift#27 verify-with-user-fixture for real thesis docx roundtrip; plus ooxml-swift#28 refactor candidate (extract BodyChildVisitor protocol). Verified by 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh). Tests: 236 passing che-word-mcp / 805→809 ooxml-swift. Backward compatible except #87 documented behavior change. v3.17.4 paired #91 + #92 release. v3.17.3 bump ooxml-swift dep 0.21.6 → 0.21.7 (pure transitive bump, no MCP source changes; exposes public anchor lookup API). Three WordDocument APIs upgraded private → public (PsychQuant/che-word-mcp#86): findBodyChildContainingText(_:nthInstance:) instance method + bodyChildContainsText(_:needle:) static + tableContainsText(_:needle:) static. External Swift SPM consumers (rescue scripts, dxedit CLI, third-party tooling) can now call canonical anchor-lookup logic directly instead of reimplementing with diverging semantics (some skipped .contentControl recursion, some skipped table cell traversal pre-#68, some used different nthInstance counting rules). Result is exactly what insert_paragraph / insert_image_from_path / insert_caption etc. tools see when resolving after_text / before_text anchors. 10 new public-API surface tests in Issue86PublicAnchorLookupTests pin the canonical behavior across releases. Backward compatible: pure additive private → public visibility change; no API removals, no behavioral changes for existing callers. v3.17.2 bump ooxml-swift dep 0.21.2 → 0.21.6 (pure transitive bump, no MCP source changes; 4 ooxml-swift releases worth of hardening + new APIs land transparently). v0.21.3 (XML hardening, PsychQuant/ooxml-swift#7): DTD reject + 64KB attr-value cap + SAX-based root-element attribute parsing + name whitelist on emit. New XMLHardeningError throws on malicious .docx input. v0.21.4 (roundtrip loud-fail, PsychQuant/ooxml-swift#6): AlternateContent.fallbackRunsModified dirty flag throws RoundtripError.unserializedFallbackEdit on stale fallbackRuns mutation. Run.commentIds @available deprecated; migrate to commentRangeMarkers. v0.21.5 (insertEquation flexibility, PsychQuant/che-word-mcp#84 #85): InsertLocation overload for Document.insertEquation + flattenedDisplayText OMML coverage extends anchor lookup beyond plain runs. v0.21.6 (mutation surface, PsychQuant/ooxml-swift#5): Hyperlink.text setter @available deprecated (lossy); migrate to .runs property. Position field cascade Int = 0 → Int? = nil across 13 typed-child models. xml:space=preserve autosense in Run.toXMLThrowing emit. Plus 3 unreleased docs commits on ooxml-swift main (PsychQuant/ooxml-swift#14 #15 #17 + corrective cd841e7) covering needsPPr emit-gate ↔ Issue4 lock-in test bidirectional reference, parseRun vs parseParagraph walker pattern divergence rationale, foreign-namespace pPr asymmetry documentation. Tests: 236 passing (no regressions). Backward compatible: deprecation warnings only; no API removals. v3.17.1 bump ooxml-swift dep to v0.21.2 — pulls in pPr regression-guard + test infrastructure hardening from upstream (ooxml-swift#4 walker whitelist + #if DEBUG assert / ooxml-swift#13 empty <w:pPr/> self-closing test gap / ooxml-swift#16 countPPrOpenTags regex hardening excluding <w:pPrChange>). No public MCP tool change. v3.17.0 wrap_caption_seq MCP tool (Refs #62): Phase 2 of cross-repo work — exposes ooxml-swift v0.21.0 lib API as MCP tool. Bulk-wraps plain-text caption number portions in SEQ field runs across body paragraphs whose flattened text matches a regex (EXACTLY ONE numeric capture group). Captured digit becomes SEQ field cachedResult so Word's first-open render preserves user-typed numbering before F9. Rescues docs pasted from external sources (LaTeX-converted Word, Google Docs, Pandoc) so insert_table_of_figures / insert_table_of_tables produce populated TOFs. Idempotent: paragraphs already wrapping a SEQ field for sequence_name reported in skipped, never double-wrapped (detection covers both FieldSimple AND rawXML fldChar emissions). Phase 1 ships scope:body only (recurses into table cells + nestedTables + block-level SDT children); scope:all returns Error: scope_not_implemented for now (cross-container path lands in v3.17.x). Bookmark wrap opt-in (insert_bookmark + bookmark_template with literal ${number}) so default 23-caption rescue does NOT pollute list_bookmarks. Returns JSON: {matched_paragraphs, fields_inserted, paragraphs_modified:[idx,...], skipped:[{paragraph_index, reason},...]}. All preconditions checked BEFORE document mutation (regex compile + capture-group count + format/scope enums + bookmark_template invariant + doc_id opened). Tests: 5 new sub-tests in Issue62WrapCaptionSeqTests covering Scenarios 1-5. Suite 231 → 236 (+5, 0 fail / 9 skip). No ooxml-swift dep bump (still v0.21.0 from v3.16.2). v3.16.2 ooxml-swift dep bump 0.20.5 → 0.21.0 (Refs #62 #68): pure dep bump, no MCP source changes. Picks up two ooxml-swift fixes that surface transparently via existing tool dispatch. #68 (ooxml-swift v0.20.6): InsertLocation.findBodyChildContainingText now traverses .table (rows × cells × paragraphs + nestedTables) and .contentControl(_, children:) (recursive). MCP impact — insert_paragraph / insert_image_from_path / insert_equation / insert_caption calls using before_text / after_text now succeed when anchor text lives inside a table cell or block-level SDT (common in thesis docs with figure/table captions inside table cells). Returned position is top-level body.children index of the containing structure. Use into_table_cell for inside-cell inserts. Empty-needle guard: passing before_text:'' / after_text:'' now returns textNotFound instead of silently inserting at index 1. #62 (ooxml-swift v0.21.0): WordDocument.wrapCaptionSequenceFields(...) is now linked into the binary. Not yet exposed as an MCP tool — the wrap_caption_seq MCP wrapper ships in v3.17.0 (Phase 2 of the cross-repo work). Existing MCP tools unaffected. Suite: 231 → 231 (0 fail / 9 skip). v3.16.1 anchorPresence whitelist drift prevention (Refs #80): pure refactor, no runtime behavior change. New static toolAnchorWhitelists dict (single source of truth, keyed by MCP tool name → accepted anchor list) + new detectPresentAnchors(_:tool:) overload. 4 conflict-detection call sites switched from literal anchor arrays to (tool:) lookup. 4 new invariant/parity tests. Suite 227 → 231 (+4). Old (args, anchors:) overload preserved. Out-of-scope follow-ups: schema descriptions + dispatcher if-else chains still hardcode anchor names (pre-existing surfaces, not introduced by this PR). v3.16.0 Bundle B anchor DX consistency (Refs #70 #71 #72): BREAKING (input validation only) — three coordinated MCP-layer changes across the 4 #61-target tools. #71 (behavior) silent priority on conflicting anchors → structured error: insert_paragraph(after_text + index) was previously silent-priority; now returns 'Error: insert_paragraph: received conflicting anchors: after_text + index. Specify exactly one.' New static helper detectPresentAnchors with per-anchor type-aware predicates (null and wrong-type values do NOT count). #72 (validation) explicit text_instance ≤ 0 rejected — 'Error: <tool>: text_instance must be ≥ 1, got <N>.' Omitted text_instance still defaults to 1. #70 (DX) all 32 'return Error:' lines in 4 #61-target tools rewritten as 'Error: <tool>: <body>' for AI-caller error attribution. throw WordError.* paths unchanged. Scope deliberately limited to 4 tools; remaining 41 return Error lines elsewhere deferred to error-prefix-sweep follow-up. SemVer rationale (minor not major): no schema break, no tool removal, restricting previously-undefined behavior. Tests: 201 → 227 (+26 sub-tests, 0 fail / 9 skip). No ooxml-swift dep bump (still v0.20.5). v3.15.3 Bundle A2 polish from v3.15.2 verify R3-R6 follow-ups (Refs #76 #77 #78 #79): #76 (docs) insert_caption description corrected from '三種 anchor' to enumerate all 5 (paragraph_index / after_image_id / after_table_index / after_text / before_text); insert_equation paragraph_index description clarified that the int is body.children-indexed (cross-references PsychQuant/ooxml-swift#10 for the lib-layer convention split). #77 (docs) insert_caption anchor set wording precision in CHANGELOG / manifest / marketplace.json / plugin.json — was 'its own anchor set including after_table_index' (implies disjoint), now 'shares after_image_id / after_text / before_text / paragraph_index, adds after_table_index + position, lacks into_table_cell' (explicit shared/adds/lacks). #78 (test) extends #69 append-index regression pin to bookmarkMarker / rawBlockElement / block-level contentControl body-children — the table case alone wouldn't catch a regression to getParagraphs().count - 1 that breaks for SDT / TOC bookmark / vendor extensions. #79 (test) adds round-trip depth: testInsertParagraphAppendIndexRoundTripsForInsertCalls demonstrates insert-family round-trip works (append + insert(N+1) + verify ordering); testInsertParagraphAppendIndexCannotRoundTripToUpdate pins the cross-family trade-off (update_paragraph(index=N) throws WordError.invalidIndex). Tests: 196 → 201 (+5 sub-tests, 0 fail / 9 skip). No production code change. No ooxml-swift dep bump (still v0.20.5). v3.15.2 closes Bundle A polish from #61 R2 verify (Refs #69 #73 #74 #75): #69 (bug) insert_paragraph append message reports body.children index instead of getParagraphs().count - 1 (mis-reported in docs with tables/SDTs by skipping table children); #74 (bug) insert_image_from_path debug log labels after_image_id correctly (was silently labeled 'index' since v3.15.1); #73 (test) regression pin for equation F5 partial-dict guard (existed since v3.15.1 but was untested); #75 (docs) clarifies '3 insert tools' wording — scope is the 3 #61-target tools (insert_paragraph / insert_equation / insert_image_from_path); insert_caption is a 4th insert tool with a partially-overlapping anchor set (shares after_image_id / after_text / before_text / paragraph_index, adds after_table_index + position, lacks into_table_cell), intentionally outside this unification scope. Tests: 194 → 196 (0 fail / 9 skip). No behavior change in normal call paths. No ooxml-swift dep bump (still v0.20.5). Word MCP Server - Swift 原生 OOXML 操作，233 個工具。v3.15.1 closes verify findings F1+F2+F3+F5 from v3.15.0 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh)：F1 (P1) `after_image_id` anchor 加到 insert_paragraph + insert_equation (display only) + insert_image_from_path — lib InsertLocation.afterImageId 從 #44 起就 ready 但只有 insert_caption 暴露 MCP-layer；v3.15.0 inherited 這個 gap，本 release 補齊。F2 (P1) `into_table_cell` 加到 insert_equation (display only) — display equation 是新建 paragraph，cell 放置 well-defined；inline mode 拒絕。F3 (P2) equation 成功訊息加 anchor info（'Inserted equation (display mode: true, after text X (instance N))' 等）— 關閉同 v3.14.4 LOOKUP 的 over-claim 模式（caller 之前無法區分 anchor 命中 vs append fallthrough）。F5 (P2) malformed `into_table_cell` partial dict（傳 `{table_index: 0}` 缺 row + col）silent fallthrough → 走 next anchor / append → 結果在錯位置且 caller 不知。改回 structured 'Error: into_table_cell requires all three fields'，3 #61-target tools 同步修（cross-cutting consistency）。Anchor priority unified across all 3 #61-target insert tools (`insert_paragraph` / `insert_equation` / `insert_image_from_path`; `insert_caption` has its own anchor set)：into_table_cell > after_image_id > after_text > before_text > index > append。Inline equation 拒絕擴大 — 現在拒絕所有 4 個 anchor params（before/after_text + after_image_id + into_table_cell），不只 v3.15.0 的 2 個。Tests: Issue61V315PointReleaseTests (9 sub-tests cross 3 tools)。Suite 185 → 194 (0 fail / 9 pre-existing skips)。**No ooxml-swift dep bump** — 仍 v0.20.5（lib 從 #44 起就 ready）。Follow-up issues 另開：F4 inline equation 更通用設計 (e.g. into_paragraph_with_text) / F6 text anchor 擴及 table-cell paragraphs 與 block-level SDT / F7 getParagraphs().count - 1 message 在 doc 含 tables/SDTs 時 mis-report (pre-existing) / F8 error message 加 tool-prefix / F9 multiple anchor params 同時傳入 silent priority winner / F10 text_instance≤0 normalize。Backward compatible — schema additions optional，既有 v3.15.0 callers 不變；只有 malformed into_table_cell 從 silent fallthrough 改成 structured error（會被 buggy caller 注意到）+ equation message 加 suffix（substring 'Inserted equation' 仍存在）。v3.15.0 closes #61 — insert_paragraph 與 insert_equation 現在接受跟 insert_image_from_path 一致的 anchor 參數（after_text / before_text / text_instance / into_table_cell — into_table_cell 僅 insert_paragraph）。Pre-fix MCP 層 silently drop 這些參數 — JSON schema 接受但 handler dispatch 忽略，呼叫 fall through 到 legacy paragraph_index path 或 append at end。Lib API Document.insertParagraph(_: at: InsertLocation) 從 #44 起就支援所有六種 anchor cases（paragraphIndex / afterImageId / afterTableIndex / intoTableCell / afterText / beforeText），本 release 補齊 MCP 側 wire-up gap，無需 ooxml-swift dep bump（v0.20.5 已足夠）。Anchor priority mirror insert_image_from_path：into_table_cell > after_text > before_text > index > append。Errors（textNotFound / tableIndexOutOfRange / tableCellOutOfRange）回 structured 訊息而非 silent fallthrough — AI caller 能 surface failure 而非拿到位置錯誤的 misleading 'success'。**Inline equation explicit rejection**：insert_equation 在 display_mode=false（inline）時 explicitly 拒絕 after_text / before_text，回 structured error — 語意模糊（'append OMML run into existing para containing this text' vs 'insert new para before/after target para'），inline placement 仍用 paragraph_index。Display-mode equation 建新 paragraph，anchor 語意明確。Tests: Issue61InsertParagraphAnchorsSmokeTests（5 sub-tests：after_text resolution / before_text resolution / text_instance disambiguation / into_table_cell append / textNotFound error）+ Issue61InsertEquationAnchorsSmokeTests（4 sub-tests：after_text + before_text in display mode / inline mode rejection / textNotFound error）。Suite 176 → 185 (0 fail / 9 pre-existing skips)。**No ooxml-swift dep bump** — v0.20.5 已有所有需要的 lib API。Backward compatible — anchor params 全 optional；既有 index / paragraph_index callers 不變；無 schema removal、無既有行為改動。**Real-world impact**：thesis-rescue / template-population workflow 不再需要 fall back 到「append at end + 手動 cut/paste in Word UI」或 binary-search 猜 paragraph_index，AI caller 對 3 #61-target insert tools（insert_image_from_path / insert_paragraph / insert_equation）對稱地用 surrounding context 定位 anchor。v3.14.5 closes Refs #63 verify F1 P1：擴充 findBodyChildContainingText 涵蓋所有 editable surfaces，補上 v3.14.4 CHANGELOG over-claim 的 insert anchor lookup gap。Pre-fix v3.14.4 只修了 REPLACE path（replace_text → Document.replaceInParagraphSurfaces 走 contentControls / hyperlinks / fieldSimples / alternateContents）但 LOOKUP path（findBodyChildContainingText 用於 InsertLocation.afterText / .beforeText 解析）只看 para.runs，所以 insert_image_from_path / insert_paragraph / insert_caption before_text/after_text 對 SDT-wrapped anchor 仍丟 textNotFound。Verify ensemble（5 Claude reviewers + Codex）的 requirements F1 P1 finding 抓到 CHANGELOG over-claim — 用戶選擇 Option B 擴充修而非縮 scope。ooxml-swift v0.20.5 新增 TextReplacementEngine.flatTextOfContentXML（read-only XML walker mirror replaceInContentXML flattening rules，跳過 <w:delText> / <w:instrText> / nested <w:sdt> subtrees）+ Paragraph.flattenedDisplayText 擴充 method 涵蓋 runs + hyperlinks + fieldSimples + alternateContents + contentControls（recursive into nested SDT children）。findBodyChildContainingText 改用 flattenedDisplayText 取代原本的 para.runs.map { $0.text }.joined()。新增 Issue63InsertAnchorInlineSDTTests（lib，3 wrappers × afterText/beforeText/insertImage = 3 sub-tests / 5 assertions）+ Issue63InsertAnchorInlineSDTSmokeTests（MCP，2 sub-tests pin lib-layer fix）。Suite 693 → 696 ooxml-swift / 174 → 176 che-word-mcp（0 fail）。基於 ooxml-swift v0.20.5。Backward compatible — strict superset of pre-fix lookup behavior（找到更多 anchors，既有 plain runs anchor 仍照常運作）。**Insert anchor lookup gap 此 release 完整補齊**，所有 inline wrappers 在 REPLACE + LOOKUP 兩個 path 都對稱覆蓋。v3.14.4 修 replace_text 對 inline `<w:sdt>` content control 的 wrapper coverage gap（Refs #63）：Document.replaceInParagraphSurfaces 之前覆蓋 paragraph.runs / hyperlinks / fieldSimples / alternateContents 但 **沒有** paragraph.contentControls — 包在 inline `<w:sdt>` 裡的文字 silently 0-match。外部 converter（pandoc / Quarto / LaTeX→docx）習慣把 cross-ref placeholder（[tab:foo] / [fig:bar] / [Smith 2020]）包成 inline SDT，所以症狀跟 bracketed text 高度相關，但其實 **brackets 是 coincidence** — bracket-free needle 在 inline SDT 裡也 fail。Issue title「literal `[ ]` brackets」是誤導，差別測試（fldChar / fldSimple / hyperlink / inlineSDT 四個 inline wrapper × 四種 needle）證實只有 inline SDT case 失敗，其他三個 wrapper 從 v0.19.0+ #56 Phase 5 起就 typed-runs 覆蓋好了。Surgical fix architecture：ooxml-swift v0.20.4 新增 TextReplacementEngine.replaceInContentXML（XML DOM walker，wrap ContentControl.content 在 synthetic root xmlns:w，遍歷所有 `<w:t>` descendants 在 document order，build flat string + offset map mirror flattenRuns invariant，run same literal/regex find logic，splice replacements 回 `<w:t>` element string content；re-serialize wrapper children 去掉 wrapper tag）+ Document.replaceInContentControl（recursive helper 涵蓋 cc.content + cc.children 處理 nested SDT）。Wired 進 Document.replaceInParagraphSurfaces 接在 alternateContents loop 之後。設計上跳過：`<w:delText>`（TC deletion text，不顯示）、`<w:instrText>`（field instruction code，不顯示）、nested `<w:sdt>` subtrees（typed cc.children 由外層 recursion 處理避免 double-replacement）。Round-trip discipline：只 mutate `<w:t>` element 的 string content；xml:space=\"preserve\" 與其他 attribute 完整保留（attribute set 從不被 touch）。新增 Issue63InlineSDTReplaceTests（4 個 wrapper × 4 個 needle 的 differential test + nested SDT recursion + round-trip wrapper preservation = 3 sub-tests / 18 assertions）+ MCP-layer Issue63ReplaceTextInlineSDTSmokeTests（2 sub-tests pin lib-layer fix）。Suite 690 → 693 ooxml-swift / 172 → 174 che-word-mcp（0 fail）。基於 ooxml-swift v0.20.4。Backward compatible — surgical fix 只新增 code path，沒改任何既有行為（runs/hyperlinks/fieldSimples/alternateContents replacement path 不動，ContentControl model 維持 raw XML storage 不重構）。Out-of-scope（separate follow-up）：ContentControl 從 content:String 升級為 typed Run 列表（SDD-warranted refactor）；smartTags / bidiOverrides / customXmlBlocks / unrecognizedChildren 維持 raw-carrier passthrough。v3.14.3 sub-stack E of paragraph-level content-equality (closes #66)：Paragraph 新增 w14ParaId / w14TextId 欄位，提取並 round-trip <w:p> opening tag 上的 w14:* 屬性（Word 用於 collaborative editing 和 comment threading 的 revision-tracking GUIDs）。Plain attribute passthrough，String? typing — Word 的 GUIDs 是 8-char hex tokens（NOT RFC 4122 UUIDs），所以 opaque-string round-trip 是正確選擇。Pre-fix v3.14.2 silently dropped 兩個 attributes — 佔了 NTPU 論文 fixture w14:* token loss 的 ~95%（2214 / 2359 lost tokens 是這兩個 attrs）。Post-E 量測：w14: 保留率 10.55% → 93.98%；document.xml 流失 10.95% → 8.02%。Combined with sub-stack D (#65), total impact since v3.14.1：<w:lang> 50% → 98.89% (D)、w14:* 5% → 93.98% (E)、document.xml 流失 16.66% → 8.02% (D+E, -8.64 pp)。Matrix-pin testDocumentContentEqualityInvariant 同步抬升 floor（w14: 0.04→0.90、sizeLossRatio 上限 0.12→0.10）— matrix-pin 現在 LOAD-BEARING across **5 preservation classes**（rFonts/noProof/lang/kern/w14:）spanning run-level + paragraph-level + paragraph-mark scope。Defensive design (R2 review fixes)：openingPTag() routes attributes through escapeXMLAttribute；parseParagraph rejects schema-invalid empty-string GUIDs。基於 ooxml-swift v0.20.3。Backward compatible（兩個 fields 都 optional、default nil；openingPTag empty-attrs gate 防止 synthetic emit）。剩餘 8% 流失主要是其他 w14:* attribute classes（如 w14:* on <w:r>）— tracked as separate follow-up SDD。v3.14.2 sub-stack D of paragraph-level content-equality (closes #65)：ParagraphProperties 新增 markRunProperties 欄位，提取並 round-trip <w:rPr> direct child of <w:pPr> — paragraph-mark formatting per ECMA-376 §17.3.1.27 CT_PPrBase（控制 pilcrow ¶ 字符外觀的字型/顏色/語言/字距）。Reuses parseRunProperties verbatim — schema 跟 run-level CT_RPr 一致，所以 sub-stack C 的 typed extraction（rFonts 4-axis / noProof / kern / lang 3-axis）和 rawChildren passthrough（w14:* 效果）全部免費繼承。NTPU 論文 fixture 量測影響：<w:lang> 保留率 50% → 98.89%；<w:rFonts> 88% → 98.77%；<w:noProof> 92% → 100%；<w:kern> 84% → 99.93%；document.xml 大小流失 16.66% → 10.95%。Matrix-pin testDocumentContentEqualityInvariant 同步抬升 floor（lang 0.45→0.95、rFonts/noProof/kern 0.95、sizeLossRatio 上限 0.175→0.12）。Sub-stack E (#66 w14:paraId/textId) 接著 ship 到 v3.14.3，把流失壓到 < 5%，達成「edit 一個字 → document.xml shrinks <1%」strong demo。基於 ooxml-swift v0.20.2。Backward compatible（markRunProperties optional、default nil、writer empty-gate 防止 synthetic empty <w:rPr/>）。v3.14.1 sub-stack C-CONT closes triple-confirmed P0 (R2 + R5 + Codex 6-AI verify)：recognizedRprChildren Set 列了 ~16+ rPr child kinds 為 'recognized' 但 parseRunProperties 沒有 typed extraction → silent drop。受影響的常見元素：<w:spacing>（character spacing）、<w:caps>/<w:smallCaps>、<w:position>、<w:shd>（run shading）、<w:bdr>、<w:em>（CJK emphasis marks）、<w:effect>、<w:vanish>/<w:specVanish>/<w:webHidden>、<w:outline>/<w:shadow>/<w:emboss>/<w:imprint>、<w:bCs>/<w:iCs>/<w:dstrike>。Fix：trim Set 到 ONLY actually-typed-extracted-or-emitted kinds。Round-trip size loss: pre-fix v3.13.x 32% → v3.14.0 17.75% → v3.14.1 16.66%。Methodology lesson (6th)：P2 from one reviewer can become P0 when another applies real-world impact lens. v3.14.0 closes #60（sub-stack C of #58/#59/#60）— RunProperties field-loss audit。Bump ooxml-swift v0.19.13→v0.20.0。新增 typed fields：4-axis rFonts (ascii/hAnsi/eastAsia/cs/hint — 之前被收斂成單一值)、noProof、kern、3-axis lang (val/eastAsia/bidi)，加上 rawChildren passthrough 處理 unrecognized rPr children（如 w14:textOutline / w14:textFill / w14:glow）。**Pre-fix MCP 用戶看到 eastAsia/cs 字型（如 DFKai-SB 用於繁體中文）在 round-trip 時 silently 被替換成 ascii 值；v3.14.0 完整保留 4 個 axis**。Matrix-pin testDocumentContentEqualityInvariant 加上 preservation-class-3 ratio-floor assertions，現在 LOAD-BEARING — 任何未來 RunProperties regression 都會被 matrix-pin 抓到。Thesis fixture document.xml round-trip 大小：pre-fix 32% 損失 → post-sub-stack-C 17.75% 損失（改善 14.25 percentage points）。剩餘 17.75% 是 paragraph-mark rPr + w14:paraId/textId drops（separate out-of-scope follow-up SDD）。**'if not typed, preserve as raw' 原則架構性完成** — 從 sub-stack A (#58 BodyChild)、B (#59 WhitespaceOverlay) 一路發展到 C (#60 RunProperties)。Backward compatible — 保留 fontName field，mirror rFonts.ascii。v3.13.13 CRITICAL HOTFIX (sub-stack B-CONT-2-CONT) reverted v3.13.12 的 TIER-0 over-fix。v3.13.12 (DO NOT USE — 刪除 <w:del> 內容)。v3.13.11 sub-stack B-CONT。基於 ooxml-swift v0.20.0。",
+  "author": {
+    "name": "Che Cheng"
+  },
   "license": "MIT",
-  "keywords": ["mcp", "word", "docx", "ooxml", "document", "swift"]
-}
+  "keywords": [
+    "mcp",
+    "word",
+    "docx",
+    "ooxml",
+    "document",
+    "swift"
+  ]
+}
\ No newline at end of file
diff --git a/plugins/che-word-mcp/.mcp.json b/plugins/che-word-mcp/.mcp.json
index cd9921bf..ad4f7de5 100644
--- a/plugins/che-word-mcp/.mcp.json
+++ b/plugins/che-word-mcp/.mcp.json
@@ -2,6 +2,6 @@
   "word": {
     "type": "stdio",
     "command": "${CLAUDE_PLUGIN_ROOT}/bin/che-word-mcp-wrapper.sh",
-    "description": "Word MCP server - Complete Word document manipulation with 105 tools"
+    "description": "Word (.docx) MCP server — Swift-native OOXML manipulation, 218+ tools. Read/write paragraphs, runs, tables, hyperlinks, headers/footers, sections, styles, numbering, content controls (SDT), comments, footnotes/endnotes, equations, fields. v3.12.0: programmatic Track Changes (insert_text_as_revision / delete_text_as_revision / move_text_as_revision + as_revision flag on format_text / set_paragraph_format). Built on ooxml-swift v0.18.0. Office.js OOXML Roadmap P0 100% complete (PsychQuant/che-word-mcp#43)."
   }
 }
diff --git a/plugins/che-word-mcp/CHANGELOG.md b/plugins/che-word-mcp/CHANGELOG.md
new file mode 100644
index 00000000..3339897c
--- /dev/null
+++ b/plugins/che-word-mcp/CHANGELOG.md
@@ -0,0 +1,236 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [3.20.0] - 2026-05-04
+
+### Added
+
+- **Cross-document OMath splice MCP tools** ([#160](https://github.com/PsychQuant/che-word-mcp/issues/160)) — two new MCP tools wrapping [PsychQuant/ooxml-swift v0.24.0's `spliceOMath` API](https://github.com/PsychQuant/ooxml-swift/issues/57):
+  - `splice_omath_from_source` — single-OMath low-level splice between two documents. Source via `source_path` (Direct mode read-only) or `source_doc_id` (Session); target requires session-mode `doc_id`. Position via `atStart` / `atEnd` / `afterText` / `beforeText` with optional `anchor` + `instance`. `omath_index` 0-based, joint document-order across both source carriers. `rpr_mode`: `full` (default verbatim) / `omathOnly` (whitelist rFonts/sz/lang/bold/italic) / `discard` (empty). `namespace_policy`: `lenient` (default — accepts `mml:` vs `m:` prefix mismatch with same URI per ECMA-376) / `strict` (any mismatch throws).
+  - `splice_paragraph_omath_from_source` — paragraph-level batch convenience. Splices all OMath blocks from source paragraph in source-document order via auto-derived ~10-char context anchors. Returns count or `contextAnchorNotFound(omath_index, snippet)` with partial-success state.
+
+### Changed
+
+- Bumps `ooxml-swift` dep `0.21.0` → `0.24.0` (required for `spliceOMath` API).
+
+### Tests
+
+- `Issue160SpliceOMathFromSourceTests` — 8 cases covering Direct/Session source modes, atEnd / afterText positions, error taxonomy, batch mode, rPr discard.
+- Full suite: 297 tests, 0 failures, 9 pre-existing skips.
+
+### Use case
+
+Unblocks [kiki830621/collaboration_guo_analysis#17](https://github.com/kiki830621/collaboration_guo_analysis/issues/17) Phase 7 inline-math restoration — 522 inline OMath blocks restored from `_raw.docx` into `碩士論文-rescue-swift-v317.docx` (95.5% paragraph coverage in first pass; 100% after suffix-anchor fallback in [collaboration_guo_analysis@43465a6](https://github.com/kiki830621/collaboration_guo_analysis/commit/43465a6)).
+
+## [3.19.0] - 2026-05-04
+
+### Fixed — `find_inline_math_gaps` caption detection ([#136](https://github.com/PsychQuant/che-word-mcp/issues/136))
+
+Two-layer detection. **Layer 1**: `Paragraph.style?.lowercased().contains("caption")` — Word's canonical OOXML signal. **Layer 2**: 7 English prefixes (Table / Figure / Tab. / Fig. / Listing) + 9 CJK prefixes (incl. U+3000 ideographic space) + CJK no-separator regex `^[表圖图]\d` + label-only `表格`/`图表`. Digit-after-prefix guard rejects body sentences like "Table reservations are required...". `isLikelyTableCaption(_:)` signature changed `String → Paragraph`; private → internal for `@testable`. PR [#157](https://github.com/PsychQuant/che-word-mcp/pull/157), 17 new tests.
+
+### Fixed — `estimate_paragraph_for_page` structural weights v2 ([#142](https://github.com/PsychQuant/che-word-mcp/issues/142))
+
+Walker upgrade: `getParagraphs()` → `collectStructuralBlocks()` returning `[StructuralBlock]` enum (`.paragraph` / `.table` / `.imageOnlyParagraph(drawingCount:)` / `.displayEquationParagraph`). Per-block weights (12pt thesis calibration): table = `tableRows × avgCellChars` (200/row fallback), image = +200 chars/drawing, display eq = 120 chars. New `structural_breakdown` field with 9 sub-fields. `method` field bumped `char_count_heuristic` → `char_count_heuristic_v2`. ~95× thesis figure-counting accuracy improvement. PR [#158](https://github.com/PsychQuant/che-word-mcp/pull/158), 6 new tests + #89 backward-compat (text-only fixtures unchanged).
+
+### Backward compat preserved
+
+- `getParagraphs()` UNCHANGED — 30+ other callers unaffected
+- `paragraph_count` semantics: body-paragraph blocks only (paragraph_index math invariant preserved)
+- `chars_per_page` override path UNCHANGED
+- Existing #89 / #94 tests pass; only `Issue89...Tests:29` `method` literal updated to `_v2`
+
+### Verified
+
+- `swift build`: clean (only pre-existing deprecation warnings)
+- `swift test`: 289 pass, 9 pre-existing skips, 0 failures
+- 1 P3 follow-up filed: [#159](https://github.com/PsychQuant/che-word-mcp/issues/159) (display-eq fixture limitation, non-blocking)
+
+## [3.17.8] - 2026-05-01
+
+### Changed
+- closes PsychQuant/che-word-mcp#98 — insert_equation MCP handler refactored across 3 commits (91506f8/357cbe7/339ab77).
+- **BREAKING:** BREAKING for inline mode callers: pre-fix inserted NEW paragraph; post-fix appends OMML run to EXISTING paragraph at paragraph_index.
+- Suite: 236 → 243 tests, 0 failures, 9 pre-existing skips.
+- **BREAKING:** Backward compatible except inline-mode BREAKING (documented)
+
+### Deprecated
+- Pre-fix three structural defects: (1) silent-clamp on out-of-range paragraph_index via non-throwing insertParagraph(_:at: Int) — tool reported success but inserted at wrong location; (2) lib's #84/#91 InsertLocation overload + InsertLocationError.inlineModeRequiresParagraphIndex / .invalidParagraphIndex(Int) structured errors never reached MCP callers (handler self-built OMML and bypassed lib); (3) inline mode (display_mode=false) always created a NEW Paragraph(runs: [eqRun]) instead of appending OMML run to the EXISTING paragraph at paragraph_index. v1 (91506f8) tried delegating to lib but Codex 6-AI verify caught P1 regression: lib's Document.insertEquation overload internally uses @available(*, deprecated, ...) MathEquation flat output (Field.swift:301) — emits truncated '(a)/(b' AND nested <w:p><w:p> invalid OOXML. v2 (357cbe7) unified handler — both latex AND components paths use MathComponent.toOMML() for structurally correct OMML; display mode routes through lib's throwing insertParagraph(_:at: InsertLocation); inline mode handler-side appends OMML run to existing paragraph. v3 (339ab77) restored eqPara.properties.alignment = .center for display mode.
+- Migration: use display_mode=true for 'new paragraph with equation' or call insert_paragraph + insert_equation separately. 7 NEW Issue98InsertEquationLibBypassTests pin contracts (5 RED→GREEN scenarios + 2 quality regression tests including unzip -p document.xml verifying <m:f> structure + centering survives + deprecated '(a)/(b)' pattern absent). 6-AI verify ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) caught both P1 regressions in v1; Codex sanity check on v2 caught the centering P2. 6 P2/P3 follow-up issues filed (#105-#110).
+
+## [3.17.7] - 2026-05-01
+
+### Added
+- Bilateral mirror coverage for direct-child OMML at 4 wrapper positions (<w:p> direct child for Pandoc display math / <w:hyperlink> direct child / <mc:Fallback> direct child / nested wrapper combos), plus 2 NEW library-wide spec capabilities.
+- Spectra change flatten-replace-omml-bilateral-coverage. 2 NEW spec capabilities promoted to openspec/specs/: ooxml-paragraph-text-mirror (mirror invariant + ReplaceResult informative refusal contract) + ooxml-library-design-principles (Correctness primacy + Human-like operations as foundational normative invariants for all ooxml-swift mutators).
+- Write side: NEW public API WordDocument.replaceTextWithBoundaryDetection returns ReplaceResult enum (.replaced(count:) / .refusedDueToOMMLBoundary(occurrences:) / .mixed(replacedCount:, refusedOccurrences:)) with Occurrence(matchSpan:, ommlSpans:) carrying flattened-text coordinates.
+
+### Changed
+- ooxml-swift dep bump 0.21.10 → 0.21.11 — closes 5-issue cluster PsychQuant/che-word-mcp #99 + #100 + #101 + #102 + #103.
+- Read side: flattenedDisplayText walks direct-child OMML at all 4 wrapper positions with source-XML position ordering.
+- Mirror invariant — asymmetric by design: reads include OMML visibleText (anchor lookup universe extends to math); writes treat OMML as opaque structural units (refuse cross-OMML mutation rather than silently delete equations).
+- Decision 4 raw passthrough preserved: direct-child OMML stays in Paragraph.unrecognizedChildren / HyperlinkChild.rawXML(_) / AlternateContent.rawXML — no parser change, no writer change, round-trip fidelity unaffected.
+- MCP impact: replace_text and other anchor-lookup tools now find paragraphs containing direct-child OMML at all 4 wrapper positions; existing replace_text MCP tool unchanged (backward-compatible).
+- Tests: 236 passing che-word-mcp / 813→829 ooxml-swift (+16 in Issue99FlattenReplaceOMMLBilateralTests).
+
+### Fixed
+- Pre-fix Paragraph.flattenedDisplayText AND Document.replaceInParagraphSurfaces shared a symmetric blind spot: direct-child <m:oMath>/<m:oMathPara> (not wrapped in <w:r>) was silently dropped → anchor lookups against paragraphs containing display math silently 0-matched.
+- Backward compatible — strict superset of pre-fix behavior
+
+## [3.17.6] - 2026-04-30
+
+### Changed
+- ooxml-swift dep bump 0.21.9 → 0.21.10 — closes PsychQuant/che-word-mcp#104.
+- MCP impact: update_all_fields now finds and updates SEQ fields in canonical 5-run form (post-roundtrip / native Word emission); list_captions benefits transitively via shared FieldParser.
+- Verified by 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) — 4 PASS / 2 WARN / 0 BLOCK; production reproducer rescue-swift-v317.docx via DocxReader path confirmed working. 5 P3 follow-ups filed in ooxml-swift (#29 SEQ Table coverage / #30 multi-paragraph counter / #31 multi-SEQ same paragraph / #32 DoS hardening / #33 discriminator invariant).
+- Tests: 236 passing che-word-mcp / 809→813 ooxml-swift (+4 sub-tests in Issue104FieldParserCanonicalFormTests).
+
+### Fixed
+- Form-level FieldParser canonical 5-run fldChar fix (orthogonal to v3.17.5's #94 container-level fix).
+- Pre-fix update_all_fields returned silent no-op ('no SEQ fields found') on docs containing valid SEQ paragraphs at body top level when fldChar block was emitted in canonical 5-run form (each <w:fldChar>/<w:instrText>/<w:t> in its own <w:r> sibling — what DocxReader produces post-roundtrip and what native Word always emits).
+- Pre-fix worked only on in-memory wrap_caption_seq output before save.
+- Two ooxml-swift commits land via this dep bump: 537de62 FieldParser two-phase parse (Phase-1 baked form + Phase-2 parseFiveRunSpan state machine probing both Run.rawXML and Run.rawElements per recognizedRunChildren = ['rPr','t','drawing','oMath','oMathPara'] allowlist) + 58fe4f9 P1 sub-fix surfaced by 6-AI verify (Logic + Devil's Advocate runtime test): canonical-branch Run.text rewrite was silently overridden by Run.toXML() rawXML short-circuit; new rewriteCanonicalCachedText helper splices new value into embedded <w:t> while preserving <w:rPr> + xml:space=preserve, AND keeps Run.text in sync.
+- Backward compatible — strict superset of pre-fix behavior
+
+## [3.17.5] - 2026-04-30
+
+### Changed
+- Known incompleteness (3 follow-ups filed): ooxml-swift#25 header/footer/footnote/endnote SEQ scans still flat .paragraphs view; ooxml-swift#26 FieldParser.parse(paragraph:) misses inline SDT/hyperlink/fieldSimple/alternateContent surfaces; ooxml-swift#27 verify-with-user-fixture for real thesis docx roundtrip; plus ooxml-swift#28 refactor candidate (extract BodyChildVisitor protocol).
+- Verified by 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh).
+- Tests: 236 passing che-word-mcp / 805→809 ooxml-swift.
+- Backward compatible except #87 documented behavior change
+
+### Removed
+- ooxml-swift dep bump 0.21.8 → 0.21.9 — triple #87 + #93 + #94 release. #87 (Comment.paragraphIndex flat-counter, observable behavior change): list_comments paragraph_index now consistently 0-indexed against get_paragraphs() flat list; pre-fix off-by-N for any docx with non-paragraph BodyChild siblings before commented paragraph; callers manually compensating with paragraph_index - 1 must remove compensation. #93 (wrap_caption_seq SEQ inherits source position, caption visual fix): pre-fix 「圖 4-1：xxx」 became 「圖 4-：xxx1」 because new SEQ run had position=nil while source-loaded preText/postText had position>0; one-line fix seqRun.position = preRun.position; insert_bookmark=true × source-loaded paragraph still has same gap (filed PsychQuant/ooxml-swift#24, default insert_bookmark=false unaffected). #94 (update_all_fields traverses .table and .contentControl containers): pre-fix body loop only processed top-level .paragraph BodyChild, silently skipped .table and .contentControl(_, children:) — SEQ fields inside table cells/block-level SDTs never updated, returning 'no SEQ fields found' for thesis docs (caption paragraphs commonly live inside the table they describe); same gap #68 closed for findBodyChildContainingText; new walkAndProcessBodyChildForFields recursive walker mirrors #68 pattern; heading-count semantics: only top-level direct .paragraph body children count toward chapter-reset.
+
+## [3.17.4] - 2026-04-30
+
+### Changed
+- paired #91 + #92 release
+
+## [3.17.3] - 2026-04-29
+
+### Added
+- Result is exactly what insert_paragraph / insert_image_from_path / insert_caption etc. tools see when resolving after_text / before_text anchors. 10 new public-API surface tests in Issue86PublicAnchorLookupTests pin the canonical behavior across releases.
+
+### Changed
+- bump ooxml-swift dep 0.21.6 → 0.21.7 (pure transitive bump, no MCP source changes; exposes public anchor lookup API).
+- Three WordDocument APIs upgraded private → public (PsychQuant/che-word-mcp#86): findBodyChildContainingText(_:nthInstance:) instance method + bodyChildContainsText(_:needle:) static + tableContainsText(_:needle:) static.
+- External Swift SPM consumers (rescue scripts, dxedit CLI, third-party tooling) can now call canonical anchor-lookup logic directly instead of reimplementing with diverging semantics (some skipped .contentControl recursion, some skipped table cell traversal pre-#68, some used different nthInstance counting rules).
+- Backward compatible: pure additive private → public visibility change; no API removals, no behavioral changes for existing callers
+
+## [3.17.2] - 2026-04-29
+
+### Added
+- bump ooxml-swift dep 0.21.2 → 0.21.6 (pure transitive bump, no MCP source changes; 4 ooxml-swift releases worth of hardening + new APIs land transparently). v0.21.3 (XML hardening, PsychQuant/ooxml-swift#7): DTD reject + 64KB attr-value cap + SAX-based root-element attribute parsing + name whitelist on emit.
+- New XMLHardeningError throws on malicious .docx input. v0.21.4 (roundtrip loud-fail, PsychQuant/ooxml-swift#6): AlternateContent.fallbackRunsModified dirty flag throws RoundtripError.unserializedFallbackEdit on stale fallbackRuns mutation.
+
+### Changed
+- Position field cascade Int = 0 → Int? = nil across 13 typed-child models. xml:space=preserve autosense in Run.toXMLThrowing emit.
+- Plus 3 unreleased docs commits on ooxml-swift main (PsychQuant/ooxml-swift#14 #15 #17 + corrective cd841e7) covering needsPPr emit-gate ↔ Issue4 lock-in test bidirectional reference, parseRun vs parseParagraph walker pattern divergence rationale, foreign-namespace pPr asymmetry documentation.
+- Tests: 236 passing (no regressions).
+
+### Deprecated
+- Run.commentIds @available deprecated; migrate to commentRangeMarkers. v0.21.5 (insertEquation flexibility, PsychQuant/che-word-mcp#84 #85): InsertLocation overload for Document.insertEquation + flattenedDisplayText OMML coverage extends anchor lookup beyond plain runs. v0.21.6 (mutation surface, PsychQuant/ooxml-swift#5): Hyperlink.text setter @available deprecated (lossy); migrate to .runs property.
+- Backward compatible: deprecation warnings only; no API removals
+
+## [3.17.1] - 2026-04-29
+
+### Changed
+- bump ooxml-swift dep to v0.21.2 — pulls in pPr regression-guard + test infrastructure hardening from upstream (ooxml-swift#4 walker whitelist + #if DEBUG assert / ooxml-swift#13 empty <w:pPr/> self-closing test gap / ooxml-swift#16 countPPrOpenTags regex hardening excluding <w:pPrChange>).
+- No public MCP tool change
+
+## [3.17.0] - 2026-04-28
+
+### Added
+- Tests: 5 new sub-tests in Issue62WrapCaptionSeqTests covering Scenarios 1-5.
+
+### Changed
+- wrap_caption_seq MCP tool (Refs #62): Phase 2 of cross-repo work — exposes ooxml-swift v0.21.0 lib API as MCP tool.
+- Bulk-wraps plain-text caption number portions in SEQ field runs across body paragraphs whose flattened text matches a regex (EXACTLY ONE numeric capture group).
+- Captured digit becomes SEQ field cachedResult so Word's first-open render preserves user-typed numbering before F9.
+- Rescues docs pasted from external sources (LaTeX-converted Word, Google Docs, Pandoc) so insert_table_of_figures / insert_table_of_tables produce populated TOFs.
+- Idempotent: paragraphs already wrapping a SEQ field for sequence_name reported in skipped, never double-wrapped (detection covers both FieldSimple AND rawXML fldChar emissions).
+- Phase 1 ships scope:body only (recurses into table cells + nestedTables + block-level SDT children); scope:all returns Error: scope_not_implemented for now (cross-container path lands in v3.17.x).
+- Bookmark wrap opt-in (insert_bookmark + bookmark_template with literal ${number}) so default 23-caption rescue does NOT pollute list_bookmarks.
+- Returns JSON: {matched_paragraphs, fields_inserted, paragraphs_modified:[idx,...], skipped:[{paragraph_index, reason},...]}.
+- All preconditions checked BEFORE document mutation (regex compile + capture-group count + format/scope enums + bookmark_template invariant + doc_id opened).
+- Suite 231 → 236 (+5, 0 fail / 9 skip).
+- No ooxml-swift dep bump (still v0.21.0 from v3.16.2)
+
+## [3.16.2] - 2026-04-28
+
+### Changed
+- ooxml-swift dep bump 0.20.5 → 0.21.0 (Refs #62 #68): pure dep bump, no MCP source changes.
+- MCP impact — insert_paragraph / insert_image_from_path / insert_equation / insert_caption calls using before_text / after_text now succeed when anchor text lives inside a table cell or block-level SDT (common in thesis docs with figure/table captions inside table cells).
+- Returned position is top-level body.children index of the containing structure.
+- Use into_table_cell for inside-cell inserts.
+- Empty-needle guard: passing before_text:'' / after_text:'' now returns textNotFound instead of silently inserting at index 1. #62 (ooxml-swift v0.21.0): WordDocument.wrapCaptionSequenceFields(...) is now linked into the binary.
+- Not yet exposed as an MCP tool — the wrap_caption_seq MCP wrapper ships in v3.17.0 (Phase 2 of the cross-repo work).
+- Existing MCP tools unaffected.
+- Suite: 231 → 231 (0 fail / 9 skip)
+
+### Fixed
+- Picks up two ooxml-swift fixes that surface transparently via existing tool dispatch. #68 (ooxml-swift v0.20.6): InsertLocation.findBodyChildContainingText now traverses .table (rows × cells × paragraphs + nestedTables) and .contentControl(_, children:) (recursive).
+
+## [3.16.1] - 2026-04-28
+
+### Added
+- New static toolAnchorWhitelists dict (single source of truth, keyed by MCP tool name → accepted anchor list) + new detectPresentAnchors(_:tool:) overload. 4 conflict-detection call sites switched from literal anchor arrays to (tool:) lookup. 4 new invariant/parity tests.
+
+### Changed
+- anchorPresence whitelist drift prevention (Refs #80): pure refactor, no runtime behavior change.
+- Suite 227 → 231 (+4).
+- Old (args, anchors:) overload preserved.
+- Out-of-scope follow-ups: schema descriptions + dispatcher if-else chains still hardcode anchor names (pre-existing surfaces, not introduced by this PR)
+
+## [3.16.0] - 2026-04-28
+
+### Added
+- Specify exactly one.' New static helper detectPresentAnchors with per-anchor type-aware predicates (null and wrong-type values do NOT count). #72 (validation) explicit text_instance ≤ 0 rejected — 'Error: <tool>: text_instance must be ≥ 1, got <N>.' Omitted text_instance still defaults to 1. #70 (DX) all 32 'return Error:' lines in 4 #61-target tools rewritten as 'Error: <tool>: <body>' for AI-caller error attribution. throw WordError.* paths unchanged.
+
+### Changed
+- **BREAKING:** Bundle B anchor DX consistency (Refs #70 #71 #72): BREAKING (input validation only) — three coordinated MCP-layer changes across the 4 #61-target tools. #71 (behavior) silent priority on conflicting anchors → structured error: insert_paragraph(after_text + index) was previously silent-priority; now returns 'Error: insert_paragraph: received conflicting anchors: after_text + index.
+- Scope deliberately limited to 4 tools; remaining 41 return Error lines elsewhere deferred to error-prefix-sweep follow-up.
+- Tests: 201 → 227 (+26 sub-tests, 0 fail / 9 skip).
+- No ooxml-swift dep bump (still v0.20.5)
+
+### Removed
+- SemVer rationale (minor not major): no schema break, no tool removal, restricting previously-undefined behavior.
+
+## [3.15.3] - 2026-04-28
+
+### Added
+- Bundle A2 polish from v3.15.2 verify R3-R6 follow-ups (Refs #76 #77 #78 #79): #76 (docs) insert_caption description corrected from '三種 anchor' to enumerate all 5 (paragraph_index / after_image_id / after_table_index / after_text / before_text); insert_equation paragraph_index description clarified that the int is body.children-indexed (cross-references PsychQuant/ooxml-swift#10 for the lib-layer convention split). #77 (docs) insert_caption anchor set wording precision in CHANGELOG / manifest / marketplace.json / plugin.json — was 'its own anchor set including after_table_index' (implies disjoint), now 'shares after_image_id / after_text / before_text / paragraph_index, adds after_table_index + position, lacks into_table_cell' (explicit shared/adds/lacks). #78 (test) extends #69 append-index regression pin to bookmarkMarker / rawBlockElement / block-level contentControl body-children — the table case alone wouldn't catch a regression to getParagraphs().count - 1 that breaks for SDT / TOC bookmark / vendor extensions. #79 (test) adds round-trip depth: testInsertParagraphAppendIndexRoundTripsForInsertCalls demonstrates insert-family round-trip works (append + insert(N+1) + verify ordering); testInsertParagraphAppendIndexCannotRoundTripToUpdate pins the cross-family trade-off (update_paragraph(index=N) throws WordError.invalidIndex).
+
+### Changed
+- Tests: 196 → 201 (+5 sub-tests, 0 fail / 9 skip).
+- No production code change.
+- No ooxml-swift dep bump (still v0.20.5)
+
+## [3.15.2] - 2026-04-28
+
+### Changed
+- Tests: 194 → 196 (0 fail / 9 skip).
+- No behavior change in normal call paths.
+- No ooxml-swift dep bump (still v0.20.5).
+
+### Removed
+- Word MCP Server - Swift 原生 OOXML 操作，233 個工具。v3.15.1 closes verify findings F1+F2+F3+F5 from v3.15.0 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh)：F1 (P1) `after_image_id` anchor 加到 insert_paragraph + insert_equation (display only) + insert_image_from_path — lib InsertLocation.afterImageId 從 #44 起就 ready 但只有 insert_caption 暴露 MCP-layer；v3.15.0 inherited 這個 gap，本 release 補齊。F2 (P1) `into_table_cell` 加到 insert_equation (display only) — display equation 是新建 paragraph，cell 放置 well-defined；inline mode 拒絕。F3 (P2) equation 成功訊息加 anchor info（'Inserted equation (display mode: true, after text X (instance N))' 等）— 關閉同 v3.14.4 LOOKUP 的 over-claim 模式（caller 之前無法區分 anchor 命中 vs append fallthrough）。F5 (P2) malformed `into_table_cell` partial dict（傳 `{table_index: 0}` 缺 row + col）silent fallthrough → 走 next anchor / append → 結果在錯位置且 caller 不知。改回 structured 'Error: into_table_cell requires all three fields'，3 #61-target tools 同步修（cross-cutting consistency）。Anchor priority unified across all 3 #61-target insert tools (`insert_paragraph` / `insert_equation` / `insert_image_from_path`; `insert_caption` has its own anchor set)：into_table_cell > after_image_id > after_text > before_text > index > append。Inline equation 拒絕擴大 — 現在拒絕所有 4 個 anchor params（before/after_text + after_image_id + into_table_cell），不只 v3.15.0 的 2 個。Tests: Issue61V315PointReleaseTests (9 sub-tests cross 3 tools)。Suite 185 → 194 (0 fail / 9 pre-existing skips)。**No ooxml-swift dep bump** — 仍 v0.20.5（lib 從 #44 起就 ready）。Follow-up issues 另開：F4 inline equation 更通用設計 (e.g. into_paragraph_with_text) / F6 text anchor 擴及 table-cell paragraphs 與 block-level SDT / F7 getParagraphs().count - 1 message 在 doc 含 tables/SDTs 時 mis-report (pre-existing) / F8 error message 加 tool-prefix / F9 multiple anchor params 同時傳入 silent priority winner / F10 text_instance≤0 normalize。Backward compatible — schema additions optional，既有 v3.15.0 callers 不變；只有 malformed into_table_cell 從 silent fallthrough 改成 structured error（會被 buggy caller 注意到）+ equation message 加 suffix（substring 'Inserted equation' 仍存在）。v3.15.0 closes #61 — insert_paragraph 與 insert_equation 現在接受跟 insert_image_from_path 一致的 anchor 參數（after_text / before_text / text_instance / into_table_cell — into_table_cell 僅 insert_paragraph）。Pre-fix MCP 層 silently drop 這些參數 — JSON schema 接受但 handler dispatch 忽略，呼叫 fall through 到 legacy paragraph_index path 或 append at end。Lib API Document.insertParagraph(_: at: InsertLocation) 從 #44 起就支援所有六種 anchor cases（paragraphIndex / afterImageId / afterTableIndex / intoTableCell / afterText / beforeText），本 release 補齊 MCP 側 wire-up gap，無需 ooxml-swift dep bump（v0.20.5 已足夠）。Anchor priority mirror insert_image_from_path：into_table_cell > after_text > before_text > index > append。Errors（textNotFound / tableIndexOutOfRange / tableCellOutOfRange）回 structured 訊息而非 silent fallthrough — AI caller 能 surface failure 而非拿到位置錯誤的 misleading 'success'。**Inline equation explicit rejection**：insert_equation 在 display_mode=false（inline）時 explicitly 拒絕 after_text / before_text，回 structured error — 語意模糊（'append OMML run into existing para containing this text' vs 'insert new para before/after target para'），inline placement 仍用 paragraph_index。Display-mode equation 建新 paragraph，anchor 語意明確。Tests: Issue61InsertParagraphAnchorsSmokeTests（5 sub-tests：after_text resolution / before_text resolution / text_instance disambiguation / into_table_cell append / textNotFound error）+ Issue61InsertEquationAnchorsSmokeTests（4 sub-tests：after_text + before_text in display mode / inline mode rejection / textNotFound error）。Suite 176 → 185 (0 fail / 9 pre-existing skips)。**No ooxml-swift dep bump** — v0.20.5 已有所有需要的 lib API。Backward compatible — anchor params 全 optional；既有 index / paragraph_index callers 不變；無 schema removal、無既有行為改動。**Real-world impact**：thesis-rescue / template-population workflow 不再需要 fall back 到「append at end + 手動 cut/paste in Word UI」或 binary-search 猜 paragraph_index，AI caller 對 3 #61-target insert tools（insert_image_from_path / insert_paragraph / insert_equation）對稱地用 surrounding context 定位 anchor。v3.14.5 closes Refs #63 verify F1 P1：擴充 findBodyChildContainingText 涵蓋所有 editable surfaces，補上 v3.14.4 CHANGELOG over-claim 的 insert anchor lookup gap。Pre-fix v3.14.4 只修了 REPLACE path（replace_text → Document.replaceInParagraphSurfaces 走 contentControls / hyperlinks / fieldSimples / alternateContents）但 LOOKUP path（findBodyChildContainingText 用於 InsertLocation.afterText / .beforeText 解析）只看 para.runs，所以 insert_image_from_path / insert_paragraph / insert_caption before_text/after_text 對 SDT-wrapped anchor 仍丟 textNotFound。Verify ensemble（5 Claude reviewers + Codex）的 requirements F1 P1 finding 抓到 CHANGELOG over-claim — 用戶選擇 Option B 擴充修而非縮 scope。ooxml-swift v0.20.5 新增 TextReplacementEngine.flatTextOfContentXML（read-only XML walker mirror replaceInContentXML flattening rules，跳過 <w:delText> / <w:instrText> / nested <w:sdt> subtrees）+ Paragraph.flattenedDisplayText 擴充 method 涵蓋 runs + hyperlinks + fieldSimples + alternateContents + contentControls（recursive into nested SDT children）。findBodyChildContainingText 改用 flattenedDisplayText 取代原本的 para.runs.map { $0.text }.joined()。新增 Issue63InsertAnchorInlineSDTTests（lib，3 wrappers × afterText/beforeText/insertImage = 3 sub-tests / 5 assertions）+ Issue63InsertAnchorInlineSDTSmokeTests（MCP，2 sub-tests pin lib-layer fix）。Suite 693 → 696 ooxml-swift / 174 → 176 che-word-mcp（0 fail）。基於 ooxml-swift v0.20.5。Backward compatible — strict superset of pre-fix lookup behavior（找到更多 anchors，既有 plain runs anchor 仍照常運作）。**Insert anchor lookup gap 此 release 完整補齊**，所有 inline wrappers 在 REPLACE + LOOKUP 兩個 path 都對稱覆蓋。v3.14.4 修 replace_text 對 inline `<w:sdt>` content control 的 wrapper coverage gap（Refs #63）：Document.replaceInParagraphSurfaces 之前覆蓋 paragraph.runs / hyperlinks / fieldSimples / alternateContents 但 **沒有** paragraph.contentControls — 包在 inline `<w:sdt>` 裡的文字 silently 0-match。外部 converter（pandoc / Quarto / LaTeX→docx）習慣把 cross-ref placeholder（[tab:foo] / [fig:bar] / [Smith 2020]）包成 inline SDT，所以症狀跟 bracketed text 高度相關，但其實 **brackets 是 coincidence** — bracket-free needle 在 inline SDT 裡也 fail。Issue title「literal `[ ]` brackets」是誤導，差別測試（fldChar / fldSimple / hyperlink / inlineSDT 四個 inline wrapper × 四種 needle）證實只有 inline SDT case 失敗，其他三個 wrapper 從 v0.19.0+ #56 Phase 5 起就 typed-runs 覆蓋好了。Surgical fix architecture：ooxml-swift v0.20.4 新增 TextReplacementEngine.replaceInContentXML（XML DOM walker，wrap ContentControl.content 在 synthetic root xmlns:w，遍歷所有 `<w:t>` descendants 在 document order，build flat string + offset map mirror flattenRuns invariant，run same literal/regex find logic，splice replacements 回 `<w:t>` element string content；re-serialize wrapper children 去掉 wrapper tag）+ Document.replaceInContentControl（recursive helper 涵蓋 cc.content + cc.children 處理 nested SDT）。Wired 進 Document.replaceInParagraphSurfaces 接在 alternateContents loop 之後。設計上跳過：`<w:delText>`（TC deletion text，不顯示）、`<w:instrText>`（field instruction code，不顯示）、nested `<w:sdt>` subtrees（typed cc.children 由外層 recursion 處理避免 double-replacement）。Round-trip discipline：只 mutate `<w:t>` element 的 string content；xml:space="preserve" 與其他 attribute 完整保留（attribute set 從不被 touch）。新增 Issue63InlineSDTReplaceTests（4 個 wrapper × 4 個 needle 的 differential test + nested SDT recursion + round-trip wrapper preservation = 3 sub-tests / 18 assertions）+ MCP-layer Issue63ReplaceTextInlineSDTSmokeTests（2 sub-tests pin lib-layer fix）。Suite 690 → 693 ooxml-swift / 172 → 174 che-word-mcp（0 fail）。基於 ooxml-swift v0.20.4。Backward compatible — surgical fix 只新增 code path，沒改任何既有行為（runs/hyperlinks/fieldSimples/alternateContents replacement path 不動，ContentControl model 維持 raw XML storage 不重構）。Out-of-scope（separate follow-up）：ContentControl 從 content:String 升級為 typed Run 列表（SDD-warranted refactor）；smartTags / bidiOverrides / customXmlBlocks / unrecognizedChildren 維持 raw-carrier passthrough。v3.14.3 sub-stack E of paragraph-level content-equality (closes #66)：Paragraph 新增 w14ParaId / w14TextId 欄位，提取並 round-trip <w:p> opening tag 上的 w14:* 屬性（Word 用於 collaborative editing 和 comment threading 的 revision-tracking GUIDs）。Plain attribute passthrough，String? typing — Word 的 GUIDs 是 8-char hex tokens（NOT RFC 4122 UUIDs），所以 opaque-string round-trip 是正確選擇。Pre-fix v3.14.2 silently dropped 兩個 attributes — 佔了 NTPU 論文 fixture w14:* token loss 的 ~95%（2214 / 2359 lost tokens 是這兩個 attrs）。Post-E 量測：w14: 保留率 10.55% → 93.98%；document.xml 流失 10.95% → 8.02%。Combined with sub-stack D (#65), total impact since v3.14.1：<w:lang> 50% → 98.89% (D)、w14:* 5% → 93.98% (E)、document.xml 流失 16.66% → 8.02% (D+E, -8.64 pp)。Matrix-pin testDocumentContentEqualityInvariant 同步抬升 floor（w14: 0.04→0.90、sizeLossRatio 上限 0.12→0.10）— matrix-pin 現在 LOAD-BEARING across **5 preservation classes**（rFonts/noProof/lang/kern/w14:）spanning run-level + paragraph-level + paragraph-mark scope。Defensive design (R2 review fixes)：openingPTag() routes attributes through escapeXMLAttribute；parseParagraph rejects schema-invalid empty-string GUIDs。基於 ooxml-swift v0.20.3。Backward compatible（兩個 fields 都 optional、default nil；openingPTag empty-attrs gate 防止 synthetic emit）。剩餘 8% 流失主要是其他 w14:* attribute classes（如 w14:* on <w:r>）— tracked as separate follow-up SDD。v3.14.2 sub-stack D of paragraph-level content-equality (closes #65)：ParagraphProperties 新增 markRunProperties 欄位，提取並 round-trip <w:rPr> direct child of <w:pPr> — paragraph-mark formatting per ECMA-376 §17.3.1.27 CT_PPrBase（控制 pilcrow ¶ 字符外觀的字型/顏色/語言/字距）。Reuses parseRunProperties verbatim — schema 跟 run-level CT_RPr 一致，所以 sub-stack C 的 typed extraction（rFonts 4-axis / noProof / kern / lang 3-axis）和 rawChildren passthrough（w14:* 效果）全部免費繼承。NTPU 論文 fixture 量測影響：<w:lang> 保留率 50% → 98.89%；<w:rFonts> 88% → 98.77%；<w:noProof> 92% → 100%；<w:kern> 84% → 99.93%；document.xml 大小流失 16.66% → 10.95%。Matrix-pin testDocumentContentEqualityInvariant 同步抬升 floor（lang 0.45→0.95、rFonts/noProof/kern 0.95、sizeLossRatio 上限 0.175→0.12）。Sub-stack E (#66 w14:paraId/textId) 接著 ship 到 v3.14.3，把流失壓到 < 5%，達成「edit 一個字 → document.xml shrinks <1%」strong demo。基於 ooxml-swift v0.20.2。Backward compatible（markRunProperties optional、default nil、writer empty-gate 防止 synthetic empty <w:rPr/>）。v3.14.1 sub-stack C-CONT closes triple-confirmed P0 (R2 + R5 + Codex 6-AI verify)：recognizedRprChildren Set 列了 ~16+ rPr child kinds 為 'recognized' 但 parseRunProperties 沒有 typed extraction → silent drop。受影響的常見元素：<w:spacing>（character spacing）、<w:caps>/<w:smallCaps>、<w:position>、<w:shd>（run shading）、<w:bdr>、<w:em>（CJK emphasis marks）、<w:effect>、<w:vanish>/<w:specVanish>/<w:webHidden>、<w:outline>/<w:shadow>/<w:emboss>/<w:imprint>、<w:bCs>/<w:iCs>/<w:dstrike>。Fix：trim Set 到 ONLY actually-typed-extracted-or-emitted kinds。Round-trip size loss: pre-fix v3.13.x 32% → v3.14.0 17.75% → v3.14.1 16.66%。Methodology lesson (6th)：P2 from one reviewer can become P0 when another applies real-world impact lens
+
+### Fixed
+- closes Bundle A polish from #61 R2 verify (Refs #69 #73 #74 #75): #69 (bug) insert_paragraph append message reports body.children index instead of getParagraphs().count - 1 (mis-reported in docs with tables/SDTs by skipping table children); #74 (bug) insert_image_from_path debug log labels after_image_id correctly (was silently labeled 'index' since v3.15.1); #73 (test) regression pin for equation F5 partial-dict guard (existed since v3.15.1 but was untested); #75 (docs) clarifies '3 insert tools' wording — scope is the 3 #61-target tools (insert_paragraph / insert_equation / insert_image_from_path); insert_caption is a 4th insert tool with a partially-overlapping anchor set (shares after_image_id / after_text / before_text / paragraph_index, adds after_table_index + position, lacks into_table_cell), intentionally outside this unification scope.
+
+## [3.14.0] - 2026-04-27
+
+### Fixed
+- closes #60（sub-stack C of #58/#59/#60）— RunProperties field-loss audit。Bump ooxml-swift v0.19.13→v0.20.0。新增 typed fields：4-axis rFonts (ascii/hAnsi/eastAsia/cs/hint — 之前被收斂成單一值)、noProof、kern、3-axis lang (val/eastAsia/bidi)，加上 rawChildren passthrough 處理 unrecognized rPr children（如 w14:textOutline / w14:textFill / w14:glow）。**Pre-fix MCP 用戶看到 eastAsia/cs 字型（如 DFKai-SB 用於繁體中文）在 round-trip 時 silently 被替換成 ascii 值；v3.14.0 完整保留 4 個 axis**。Matrix-pin testDocumentContentEqualityInvariant 加上 preservation-class-3 ratio-floor assertions，現在 LOAD-BEARING — 任何未來 RunProperties regression 都會被 matrix-pin 抓到。Thesis fixture document.xml round-trip 大小：pre-fix 32% 損失 → post-sub-stack-C 17.75% 損失（改善 14.25 percentage points）。剩餘 17.75% 是 paragraph-mark rPr + w14:paraId/textId drops（separate out-of-scope follow-up SDD）。**'if not typed, preserve as raw' 原則架構性完成** — 從 sub-stack A (#58 BodyChild)、B (#59 WhitespaceOverlay) 一路發展到 C (#60 RunProperties)。Backward compatible — 保留 fontName field，mirror rFonts.ascii。v3.13.13 CRITICAL HOTFIX (sub-stack B-CONT-2-CONT) reverted v3.13.12 的 TIER-0 over-fix。v3.13.12 (DO NOT USE — 刪除 <w:del> 內容)。v3.13.11 sub-stack B-CONT。基於 ooxml-swift v0.20.0。
diff --git a/plugins/che-word-mcp/CLAUDE.md b/plugins/che-word-mcp/CLAUDE.md
new file mode 100644
index 00000000..84022209
--- /dev/null
+++ b/plugins/che-word-mcp/CLAUDE.md
@@ -0,0 +1,107 @@
+# che-word-mcp — CLAUDE.md
+
+## Purpose
+
+Microsoft Word (.docx) MCP plugin. Wraps the [CheWordMCP](https://github.com/PsychQuant/che-word-mcp) Swift binary via auto-download wrapper. **Swift-native OOXML manipulation** — reads and writes .docx without requiring Microsoft Word installation. 218+ tools cover the full Office.js OOXML Roadmap P0 set ([#43](https://github.com/PsychQuant/che-word-mcp/issues/43) closed 100%).
+
+Built on [`ooxml-swift`](https://github.com/PsychQuant/ooxml-swift) v0.18.0.
+
+## Components
+
+### MCP Tools (218+)
+
+| Category | Representative tools |
+|----------|---------------------|
+| Document lifecycle | `create_document`, `open_document`, `save_document`, `close_document`, `finalize_document`, `recover_from_autosave`, `checkpoint`, `revert_to_disk` |
+| Properties / theme | `get_document_properties`, `set_theme`, `update_theme_color`, `update_theme_fonts`, `set_language` |
+| Content (text + paragraphs) | `get_text`, `get_paragraphs`, `insert_paragraph`, `update_paragraph`, `replace_text`, `replace_text_batch`, `search_text_with_formatting`, `list_all_formatted_text` |
+| Formatting | `format_text` (with `as_revision`), `set_paragraph_format` (with `as_revision`), `set_character_spacing`, `set_text_effect`, `set_paragraph_border`, `set_paragraph_shading` |
+| Styles (v3.10) | `list_styles`, `apply_style`, `create_style`, `update_style`, `delete_style` |
+| Numbering / lists (v3.10) | `insert_bullet_list`, `insert_numbered_list`, `set_list_level`, `set_outline_level` |
+| Sections / page setup (v3.10) | `get_section_properties`, `insert_section_break`, `set_page_size`, `set_page_margins`, `set_page_orientation`, `set_columns`, `set_line_numbers` |
+| Tables (v3.11) | `insert_table`, `update_cell`, `add_row_to_table`, `merge_cells`, `set_cell_vertical_alignment`, `set_table_style`, `set_header_row`, `set_table_alignment` |
+| Hyperlinks (v3.11) | `insert_hyperlink`, `update_hyperlink`, `list_hyperlinks`, `insert_internal_link`, `insert_cross_reference` |
+| Headers / footers (v3.11) | `add_header`, `update_header`, `list_headers`, `add_footer`, `insert_page_number` (even/odd + section header map) |
+| Comments | `insert_comment`, `update_comment`, `reply_to_comment`, `resolve_comment`, `list_comment_threads`, `sync_extended_comments`, `add_person`, `list_people` |
+| Track Changes — accept/reject | `enable_track_changes`, `disable_track_changes`, `get_revisions`, `accept_revision`, `reject_revision`, `accept_all_revisions`, `reject_all_revisions` |
+| Track Changes — write side (v3.12) | `insert_text_as_revision`, `delete_text_as_revision`, `move_text_as_revision`, `format_text` / `set_paragraph_format` with `as_revision: true` |
+| Content controls / SDT (v3.9) | `insert_content_control`, `list_content_controls`, `update_content_control_text`, `replace_content_control_content`, `insert_repeating_section`, `insert_checkbox`, `insert_dropdown` |
+| Images | `insert_image`, `insert_floating_image`, `update_image`, `set_image_style`, `export_image`, `export_all_images`, `insert_drop_cap` |
+| Footnotes / endnotes / equations / captions | `insert_footnote`, `insert_endnote`, `insert_equation`, `insert_caption`, `list_captions` |
+| Bookmarks / TOC / watermarks | `insert_bookmark`, `insert_toc`, `insert_table_of_figures`, `insert_index`, `insert_watermark`, `insert_image_watermark` |
+| Fields | `insert_date_field`, `insert_page_field`, `insert_sequence_field`, `insert_calculation_field`, `insert_if_field`, `insert_merge_field`, `update_all_fields` |
+| Document protection | `protect_document`, `set_document_password`, `restrict_editing_region` |
+| Compare / export | `compare_documents`, `compare_documents_markdown`, `export_text`, `export_markdown`, `export_revision_summary_markdown`, `export_comment_threads_markdown` |
+
+MCP namespace: `mcp__che-word-mcp__<tool>`.
+
+### Skills
+
+| Skill | 用途 |
+|-------|------|
+| `che-word-mcp` | 工作流指南：Direct vs Session 模式、tool 分類、Track Changes 寫側合約（`as_revision` + `track_changes_not_enabled` 例外）、SDT 控件、author resolution chain、常見 workflow（contract redline、multi-author review、fillable form） |
+
+## Two Operating Modes
+
+| Mode | Param | Tools | Use when |
+|------|-------|-------|----------|
+| Direct | `source_path` | 18 | 快速 read-only 檢查（list/search/info），不需 open/close lifecycle |
+| Session | `doc_id` | All 218+ | 任何寫入或多步驟編輯都要走這個 |
+
+## Track Changes Contract（v3.12.0+ 重要）
+
+`as_revision: true` 是 **per-call opt-in**，不會自動開啟 track changes：
+
+| 狀態 | `as_revision: true` 行為 |
+|------|--------------------------|
+| Track changes enabled | 包成 `<w:ins>` / `<w:del>` / `<w:rPrChange>` / `<w:pPrChange>` 標記 |
+| Track changes disabled | **拋出 `track_changes_not_enabled`**，不靜默 enable |
+
+設計理由：避免副作用 — 呼叫 `format_text(as_revision: true)` 不會偷偷修改文件全域的 track changes 狀態。要先 `enable_track_changes(author: "...")` 再呼叫。
+
+**Author resolution chain**：explicit `author` arg → `revisions.settings.author`（在 `enable_track_changes` 時設定）→ `"Unknown"`。
+
+## Binary Dependency
+
+這是 binary-based plugin：`.mcp.json` 指向 `bin/che-word-mcp-wrapper.sh`，wrapper 會 auto-download `CheWordMCP` binary 到 `~/bin/`。
+
+- Binary repo: [`PsychQuant/che-word-mcp`](https://github.com/PsychQuant/che-word-mcp)
+- Binary name: `CheWordMCP`
+- Underlying lib: [`PsychQuant/ooxml-swift`](https://github.com/PsychQuant/ooxml-swift) v0.18.0
+- Release asset naming: asset filename must contain `CheWordMCP`
+
+### Plugin vs Binary Version Sync
+
+| 改動類型 | 處理 |
+|----------|------|
+| 改 plugin shell（skill、CLAUDE.md、wrapper、`.mcp.json`） | `/plugin-tools:plugin-update che-word-mcp` |
+| 改 binary source（新 tool、bug fix、ooxml-swift 升級） | 先 `/mcp-tools:mcp-deploy`（在 `mcp/che-word-mcp/`）→ 發 GitHub Release → 再跑 `plugin-update` |
+| 同時改兩邊 | `plugin-update`（v1.11+ 會 detect 依賴不同步並 prompt 連動 mcp-deploy） |
+
+Plugin shell 與 binary 版本獨立。Plugin shell 升 minor 反映文件/skill/CLAUDE.md 變動；binary 版升反映 MCP server 內部新增 tool 或修 bug。
+
+## Permissions
+
+無 macOS TCC 權限需求。plugin 跑在使用者層級，讀寫 `.docx` 檔案使用標準檔案系統權限（會繼承呼叫者的 sandbox / FDA 設定）。
+
+## Development
+
+- Update after plugin-shell changes: `/plugin-tools:plugin-update che-word-mcp`
+- Full release (binary + plugin): `/plugin-tools:plugin-deploy che-word-mcp`
+- Binary source edits: go to `mcp/che-word-mcp/` (or sibling clone of `PsychQuant/che-word-mcp`) then `/mcp-tools:mcp-deploy`
+- Health check: `/plugin-tools:plugin-health`
+
+## Office.js OOXML Roadmap P0 Closure Map
+
+| § | Sub-issue | che-word-mcp version |
+|---|-----------|----------------------|
+| §1 Content Controls (SDT) | [#44](https://github.com/PsychQuant/che-word-mcp/issues/44) | v3.9.0 |
+| §2 Track Changes 寫側 | [#45](https://github.com/PsychQuant/che-word-mcp/issues/45) | v3.12.0 |
+| §3 Numbering | [#46](https://github.com/PsychQuant/che-word-mcp/issues/46) | v3.10.0 |
+| §4 Sections | [#47](https://github.com/PsychQuant/che-word-mcp/issues/47) | v3.10.0 |
+| §8 Styles | [#48](https://github.com/PsychQuant/che-word-mcp/issues/48) | v3.10.0 |
+| §9 Tables | [#49](https://github.com/PsychQuant/che-word-mcp/issues/49) | v3.11.0 |
+| §14 Hyperlinks | [#50](https://github.com/PsychQuant/che-word-mcp/issues/50) | v3.11.0 |
+| §16 Headers / Footers | [#51](https://github.com/PsychQuant/che-word-mcp/issues/51) | v3.11.0 |
+
+Umbrella: [#43](https://github.com/PsychQuant/che-word-mcp/issues/43) — closed 2026-04-25.
diff --git a/plugins/che-word-mcp/README.md b/plugins/che-word-mcp/README.md
index d2cb8307..e3feba05 100644
--- a/plugins/che-word-mcp/README.md
+++ b/plugins/che-word-mcp/README.md
@@ -1,6 +1,159 @@
 # che-word-mcp
 
-**Word MCP Server** - Swift 原生 OOXML 操作，146 個工具，支援 Dual-Mode 存取。
+**Word MCP Server** — Swift 原生 OOXML 操作，**235 個工具**，支援 Dual-Mode 存取 + preserve-by-default round-trip fidelity + programmatic Track Changes 生成 + `document.xml` lossless round-trip。
+
+當前版本：**v3.20.0**（Plugin shell + Binary 同步）— closes [PsychQuant/che-word-mcp#160](https://github.com/PsychQuant/che-word-mcp/issues/160) — 兩個新 MCP tools 暴露 [PsychQuant/ooxml-swift v0.24.0](https://github.com/PsychQuant/ooxml-swift/releases/tag/v0.24.0) 的 `spliceOMath` API 給 MCP callers，跨 document 拷貝 verbatim `<m:oMath>` XML 區塊。
+
+- **`splice_omath_from_source`** — 單一 OMath splice，low-level。Source 用 `source_path`（Direct mode 唯讀）或 `source_doc_id`（Session mode）；target 必須是 session-mode `doc_id`。Position 支援 `atStart` / `atEnd` / `afterText` / `beforeText`（後兩者配合 `anchor` + 可選 `instance`）。`omath_index` 0-based、按 source-document order 跨 carrier 統一排序。`rpr_mode` 控制 source Run rPr 怎麼帶到 target Run（`full` 預設 verbatim / `omathOnly` 白名單 / `discard` 空 rPr）；`namespace_policy` 控制 prefix vs URI 處理（`lenient` 預設接受 `mml:` vs `m:` prefix mismatch / `strict` 任何 prefix 不同就 throw）。回傳 `Spliced 1 OMath block (...)` 或 structured error。
+- **`splice_paragraph_omath_from_source`** — paragraph-level batch convenience。把 source paragraph 內所有 OMath 按 source-document order splice 到 target paragraph 對應位置（內部用 ~10 chars source-text-context 自動推 anchor）。回傳 splice 數量或 `contextAnchorNotFound(omath_index, snippet)`（partial-success state 已留在 target）。
+
+**Use case**：unblocks [kiki830621/collaboration_guo_analysis](https://github.com/kiki830621/collaboration_guo_analysis/issues/17) Phase 7 inline-math restoration — 522 inline OMath blocks 從 `_raw.docx` 救回 `碩士論文-rescue-swift-v317.docx`。
+
+**Tests**：8 個新 `Issue160SpliceOMathFromSourceTests` cases（Direct/Session source modes、atEnd/afterText positions、error taxonomy、batch mode、rPr discard）。Full suite: 297 passing, 0 failures, 9 pre-existing skips。Bumps `ooxml-swift` dep `0.21.0` → `0.24.0`。
+
+---
+
+當前版本：**v3.19.0**（Plugin shell + Binary 同步）— closes [PsychQuant/che-word-mcp#105](https://github.com/PsychQuant/che-word-mcp/issues/105) + [#106](https://github.com/PsychQuant/che-word-mcp/issues/106) + [#107](https://github.com/PsychQuant/che-word-mcp/issues/107)（`insert_equation` argument-contract hardening from #98 verify follow-up）。**#106 (P2)** — reject `components`+`latex` 同時呼叫，handler 在解析前回 structured error（之前 silent 用 components、丟 latex 而不警示）。**#107 (P2)** — reject 非 boolean `display_mode`（agent caller 傳 `"false"` string 等），之前 `args["display_mode"]?.boolValue` 回 nil → `?? true` fall-back，inline-intent 呼叫被路由成 display-mode。**#105 (P3)** — `paragraph_index` schema 拆 display-mode（`body.children` 索引）vs inline-mode（top-level paragraph ordinal）；新增 MCP-vs-lib `display_mode` 預設值差異說明（MCP 預設 `true` 對 agent 友好，lib 預設 `false`）；移除 unreachable `inlineModeRequiresParagraphIndex` defensive arm。6 NEW `Issue98InsertEquationLibBypassTests` 釘住 contract（2 runtime errors + 4 source-grep contract tests）。6-AI verify ensemble（5 Claude reviewers + Codex gpt-5.5 xhigh）：PASS with 0 blocking, 5 P2 follow-up, 6 P3 nits。6 follow-up issues opened：[#124](https://github.com/PsychQuant/che-word-mcp/issues/124) sibling fail-open（`paragraph_index` / `text_instance` / `into_table_cell.*` 同類 string-fail-open）/ [#125](https://github.com/PsychQuant/che-word-mcp/issues/125) JSON null vs absent semantics / [#126](https://github.com/PsychQuant/che-word-mcp/issues/126) runtime regression test for #105 with `[paragraph, table/SDT, paragraph]` fixture / [#127](https://github.com/PsychQuant/che-word-mcp/issues/127) `paragraphIndex!` force-unwrap → defensive guard / [#128](https://github.com/PsychQuant/che-word-mcp/issues/128) schema "anchor" phrasing 與 #71 anchor whitelist 對齊 / [#129](https://github.com/PsychQuant/che-word-mcp/issues/129) echo received value in arg-validation errors。Suite: 243 → 249 tests, 0 failures, 9 pre-existing skips。**Backward compatible** — only newly fail 在 caller 傳 `components`+`latex` 同時（之前 silent component-wins）或 string `display_mode`（之前 silent fail-open to true）—— 如果舊 caller 依賴這兩個 silent 行為，那個 call 本來就 buggy。
+
+---
+
+當前版本：**v3.17.8**（Plugin shell + Binary 同步）— closes [PsychQuant/che-word-mcp#98](https://github.com/PsychQuant/che-word-mcp/issues/98)，`insert_equation` MCP handler 跨 3 commits 重構（`91506f8` v1 / `357cbe7` v2 / `339ab77` v3）。Pre-fix 三個 structural defects：(1) **silent-clamp** on out-of-range `paragraph_index`（handler 用 non-throwing `insertParagraph(_:at: Int)` overload，tool 回 success 但插錯位置）；(2) lib `#84`/`#91` 的 `InsertLocation` overload + `InsertLocationError.inlineModeRequiresParagraphIndex` / `.invalidParagraphIndex(Int)` structured errors **從未到達 MCP callers**（handler 自建 OMML 完全 bypass lib）；(3) inline mode（`display_mode: false`）總是建立 NEW `Paragraph(runs: [eqRun])` 而**不是** append OMML run 到既有段落。v1 嘗試委派 lib 但 Codex 6-AI verify 抓到 P1 regression：lib 的 overload 內部用 `@available(*, deprecated, ...)` `MathEquation` flat output（`Field.swift:301`）— `\frac{a}{b}` 被截斷成 `(a)/(b` AND 嵌套 `<w:p><w:p>` invalid OOXML。v2 unified handler — 兩條 path（`latex` + `components`）都用 `MathComponent.toOMML()` 建結構化 OMML；display mode 走 lib 的 throwing `insertParagraph(_:at: InsertLocation)`；inline mode handler-side append OMML run 到既有段落。v3 補回 `eqPara.properties.alignment = .center`（lib display-mode convention，Codex sanity check P2）。**BREAKING for inline mode callers**：pre-fix 插新段落 → post-fix append 到既有段落（matches lib `#84`/`#91` design）；migration 見下方 v3.17.8 區塊。7 NEW `Issue98InsertEquationLibBypassTests` 釘住 contract（5 RED→GREEN scenarios + 2 quality regression tests 含 `unzip -p document.xml` 驗 `<m:f>` 結構 + centering 存活 + deprecated `(a)/(b)` 不出現）。6-AI verify ensemble（5 Claude reviewers + Codex gpt-5.5 xhigh）抓到 v1 兩個 P1 regression；Codex sanity check 抓到 v2 centering P2。6 P2/P3 follow-ups filed [#105](https://github.com/PsychQuant/che-word-mcp/issues/105) [#106](https://github.com/PsychQuant/che-word-mcp/issues/106) [#107](https://github.com/PsychQuant/che-word-mcp/issues/107) [#108](https://github.com/PsychQuant/che-word-mcp/issues/108) [#109](https://github.com/PsychQuant/che-word-mcp/issues/109) [#110](https://github.com/PsychQuant/che-word-mcp/issues/110)。Tests: 236 → 243 passing, 0 failures, 9 pre-existing skips。Backward compatible **except inline-mode BREAKING (documented)**。
+
+**v3.17.8 BREAKING migration guide**
+
+```
+// Pre-fix（會插入 NEW paragraph at index 5）
+insert_equation(doc_id, latex: "x", display_mode: false, paragraph_index: 5)
+
+// Post-fix（append OMML run 到既有段落 5；matches lib #84/#91 design）
+insert_equation(doc_id, latex: "x", display_mode: false, paragraph_index: 5)
+
+// 若舊行為（要 NEW paragraph）：改用 display mode 或拆兩步
+insert_equation(doc_id, latex: "x", display_mode: true, paragraph_index: 5)   // 新段落 + 公式
+// 或
+insert_paragraph(doc_id, paragraph_index: 5)
+insert_equation(doc_id, latex: "x", display_mode: false, paragraph_index: 6)
+```
+
+Pre-fix 的 silent-clamp + 新段落行為是 **bug**，不是 backward-compat surface — v3.17.8 的 BREAKING 是修復結構錯誤。
+
+---
+
+當前版本：**v3.17.7**（Plugin shell + Binary 同步）— bump `ooxml-swift` dep 0.21.10 → 0.21.11，closes 5-issue cluster [#99](https://github.com/PsychQuant/che-word-mcp/issues/99) + [#100](https://github.com/PsychQuant/che-word-mcp/issues/100) + [#101](https://github.com/PsychQuant/che-word-mcp/issues/101) + [#102](https://github.com/PsychQuant/che-word-mcp/issues/102) + [#103](https://github.com/PsychQuant/che-word-mcp/issues/103). **Bilateral mirror coverage** for direct-child OMML at 4 wrapper positions（`<w:p>` direct child for Pandoc display math / `<w:hyperlink>` direct child / `<mc:Fallback>` direct child / nested wrapper combos）+ 2 NEW library-wide spec capabilities（`ooxml-paragraph-text-mirror` + `ooxml-library-design-principles`）。Pre-fix `Paragraph.flattenedDisplayText` AND `Document.replaceInParagraphSurfaces` 共享 symmetric blind spot：direct-child `<m:oMath>`/`<m:oMathPara>`（沒有 `<w:r>` wrapper）silently dropped → 對含 display math 的 paragraph anchor lookup silently 0-matched。讀側：`flattenedDisplayText` 走訪 4 wrapper positions 的 direct-child OMML，source XML position 排序。寫側：NEW 公開 API `WordDocument.replaceTextWithBoundaryDetection` 回 `ReplaceResult` enum（`.replaced(count:)` / `.refusedDueToOMMLBoundary(occurrences:)` / `.mixed(...)`），cross-OMML mutation 拒絕並回傳 informative `Occurrence(matchSpan:, ommlSpans:)`。Mirror invariant — **asymmetric by design**：reads include OMML visibleText（anchor lookup universe extends to math），writes treat OMML as opaque structural units（refuse cross-OMML mutation rather than silently delete equations）。Principle-driven（`ooxml-library-design-principles` spec）：**Correctness primacy** + **Human-like operations** as foundational normative invariants for all `ooxml-swift` mutators。Decision 4 raw passthrough preserved — round-trip fidelity unaffected。Tests: 236 passing che-word-mcp / 813→829 ooxml-swift (+16 in `Issue99FlattenReplaceOMMLBilateralTests`)。Backward compatible — strict superset of pre-fix behavior。
+
+**v3.17.7 bump `ooxml-swift` dep v0.21.10 → v0.21.11** — Bilateral mirror coverage for direct-child OMML（5-issue cluster #99-#103, Spectra change `flatten-replace-omml-bilateral-coverage`）。Pure transitive, no MCP source changes:
+
+- **Read side**: `flattenedDisplayText` walks direct-child OMML at all 4 wrapper positions
+- **Write side**: NEW public API `WordDocument.replaceTextWithBoundaryDetection` returns informative `ReplaceResult` enum
+- **Mirror invariant**: same surface coverage, asymmetric on OMML detected (reads include / writes refuse cross)
+- **Library principles** (NEW spec capability): Correctness primacy + Human-like operations
+
+---
+
+當前版本：**v3.17.6**（Plugin shell + Binary 同步）— bump `ooxml-swift` dep 0.21.9 → 0.21.10，closes [PsychQuant/che-word-mcp#104](https://github.com/PsychQuant/che-word-mcp/issues/104). **Form-level** FieldParser canonical 5-run fldChar fix（orthogonal to v3.17.5 的 #94 **container-level** fix — 兩者解 independent walker dimensions）。Pre-fix `update_all_fields` 在 docs containing valid SEQ paragraphs at body top level when fldChar block emitted in canonical 5-run form（每個 `<w:fldChar>` / `<w:instrText>` / `<w:t>` 各在獨立 `<w:r>` sibling — DocxReader 後 / native Word emission）回 silent no-op (`"no SEQ fields found"`)。兩個 ooxml-swift commits land via dep bump：`537de62` FieldParser two-phase parse（Phase-1 baked + Phase-2 `parseFiveRunSpan` state machine probing both `Run.rawXML` and `Run.rawElements`）+ `58fe4f9` P1 sub-fix surfaced by 6-AI verify (Logic + Devil's Advocate runtime test): canonical-branch `Run.text` rewrite was silently overridden by `Run.toXML()` rawXML short-circuit; new `rewriteCanonicalCachedText` helper splices new value into embedded `<w:t>` while preserving `<w:rPr>` + `xml:space="preserve"`. **MCP impact**: `update_all_fields` now finds SEQ in canonical 5-run form (post-roundtrip / native Word emission); `list_captions` benefits transitively. Verified 6-AI ensemble (4 PASS / 2 WARN / 0 BLOCK)。5 P3 follow-ups filed in ooxml-swift（#29 SEQ Table coverage / #30 multi-paragraph counter / #31 multi-SEQ same paragraph / #32 DoS hardening / #33 discriminator invariant）。Tests: 236 passing che-word-mcp / 809→813 ooxml-swift (+4 sub-tests in `Issue104FieldParserCanonicalFormTests`)。Backward compatible — strict superset of pre-fix behavior。
+
+**v3.17.6 bump `ooxml-swift` dep v0.21.9 → v0.21.10** — Form-level FieldParser fix closing [PsychQuant/che-word-mcp#104](https://github.com/PsychQuant/che-word-mcp/issues/104). Pure transitive, no MCP source changes:
+
+- **Form-level vs container-level distinction**: 此 fix 是 form-level（baked vs canonical fldChar emission），orthogonal to v3.17.5 的 #94 container-level fix（`.table` / `.contentControl` recursion）。兩者解 independent walker dimensions：v3.17.5 補 container 走訪、v3.17.6 補 fldChar form 偵測。Production reproducer `rescue-swift-v317.docx` 內 19 個 SEQ paragraphs（12 SEQ Figure + 7 SEQ Table）DocxReader 後是 canonical 5-run 形式，pre-v3.17.6 的 FieldParser 只看 baked form（v2.0.0 全 5 個 fldChar 元素塞同一 `Run.rawXML`）→ silent skip 整批。
+- **P1 sub-fix surfaced by 6-AI verify**: 第一輪 fix 只 mutate `Run.text`，但 `Run.toXML()` short-circuits on non-nil `rawXML`（`Run.swift:246-248`）— hand-built fixtures / native-Word-emit / 任何 upstream tool preserving raw form 都會 silent-broken。新 `rewriteCanonicalCachedText` helper 解決：splice 新值進 embedded `<w:t>` 同時保留 `<w:rPr>` 跟 `xml:space="preserve"`；`Run.text` 並行同步。
+- **5 P3 follow-ups filed (out of scope)**: ooxml-swift [#29](https://github.com/PsychQuant/ooxml-swift/issues/29) (SEQ Table identifier coverage) / [#30](https://github.com/PsychQuant/ooxml-swift/issues/30) (multi-paragraph counter accumulation) / [#31](https://github.com/PsychQuant/ooxml-swift/issues/31) (multiple SEQ in same paragraph) / [#32](https://github.com/PsychQuant/ooxml-swift/issues/32) (DoS hardening) / [#33](https://github.com/PsychQuant/ooxml-swift/issues/33) (discriminator invariant pin)。
+
+**Tests**: 236 passing che-word-mcp / 809 → 813 ooxml-swift（+4 sub-tests）。Backward compatible — strict superset of pre-fix behavior。
+
+**Verification**: 6-AI ensemble (5 Claude reviewers + Codex gpt-5.5 xhigh) — 4 PASS / 2 WARN / 0 BLOCK; production reproducer (rescue-swift-v317.docx via DocxReader path) confirmed working.
+
+---
+
+**v3.17.5 bump `ooxml-swift` dep v0.21.8 → v0.21.9** — triple lib-only patch release covering [PsychQuant/che-word-mcp#87](https://github.com/PsychQuant/che-word-mcp/issues/87) + [#93](https://github.com/PsychQuant/che-word-mcp/issues/93) + [#94](https://github.com/PsychQuant/che-word-mcp/issues/94). Pure transitive, no MCP source changes:
+
+- **#87 `Comment.paragraphIndex` flat-paragraph counter (observable behavior change)** — pre-fix used `body.children.enumerated()` index counting tables/SDTs/markers; post-fix walks flat-paragraph counter mirroring `getParagraphs()` semantics. MCP impact: `list_comments` `paragraph_index` field now consistently 0-indexed against `get_paragraphs()` flat list. **Caller migration**: callers manually compensating with `paragraph_index - 1` (or `- N`) to work around the bug must remove their compensation, will over-correct otherwise.
+- **#93 `wrap_caption_seq` SEQ inherits source `position`** — pre-fix caption like 「圖 4-1：xxx」 rendered as 「圖 4-：xxx1」 on real Word docs because SEQ run had `position=nil` while source-loaded preText/postText had `position>0`. Paragraph emit bifurcates by position field — positioned section vs legacy post-content section — so SEQ landed at end. One-line fix `seqRun.position = preRun.position`. **Known incompleteness**: `insert_bookmark=true` × source-loaded paragraph still has same gap on bookmarkStart/End markers (filed [PsychQuant/ooxml-swift#24](https://github.com/PsychQuant/ooxml-swift/issues/24)); default `insert_bookmark=false` unaffected.
+- **#94 `update_all_fields` traverses `.table` and `.contentControl` containers** — pre-fix body loop only processed top-level `.paragraph` BodyChild — silently skipped `.table` and `.contentControl(_, children:)`. SEQ fields anchored inside table cells or block-level SDTs were never updated. New `walkAndProcessBodyChildForFields` recursive walker mirrors #68 pattern. Heading-count semantics: only top-level direct `.paragraph` body children count toward chapter-reset (container-nested headings do NOT trigger SEQ resets — conservative thesis-aligned choice). **Known incompleteness** (filed): [ooxml-swift#25](https://github.com/PsychQuant/ooxml-swift/issues/25) header/footer/footnote/endnote SEQ scans still flat `.paragraphs` view; [ooxml-swift#26](https://github.com/PsychQuant/ooxml-swift/issues/26) `FieldParser.parse(paragraph:)` misses inline SDT/hyperlink/fieldSimple/AlternateContent surfaces; [ooxml-swift#27](https://github.com/PsychQuant/ooxml-swift/issues/27) verify-with-user-fixture for real thesis docx roundtrip; plus [ooxml-swift#28](https://github.com/PsychQuant/ooxml-swift/issues/28) refactor candidate (extract `BodyChildVisitor` protocol to dedupe 5+ body-children walkers).
+
+**Tests**: 236 passing che-word-mcp / 805 → 809 ooxml-swift (no new MCP tests, no regressions). Backward compatible **except #87 documented behavior change**.
+
+**Verification**: 6-AI ensemble (5 Claude reviewers: requirements / logic / security / regression / devils-advocate + Codex gpt-5.5 xhigh).
+
+---
+
+**v3.17.4 bump `ooxml-swift` dep v0.21.7 → v0.21.8** — paired patch release covering [PsychQuant/che-word-mcp#91](https://github.com/PsychQuant/che-word-mcp/issues/91) + [#92](https://github.com/PsychQuant/che-word-mcp/issues/92), both lib-only post-#85 verify follow-ups. Pure transitive, no MCP source changes:
+
+- **#91 `insertEquation` inline-mode error semantics** — `InsertLocationError.inlineModeRequiresParagraphIndex` (anchor type other than `.paragraphIndex` with inline math) + `.invalidParagraphIndex(Int)` (negative or `≥ topLevelParagraphCount`). MCP impact: `insert_equation` `paragraph_index` out-of-bounds now returns structured error instead of silent fallthrough.
+- **#92 `flattenedDisplayText` OMML wrapper coverage** — extracted `flattenRunsWithOMML(_:)` private static helper; applied uniformly to top-level runs + `hyperlinks[].runs` + `fieldSimples[].runs` + `alternateContents[].fallbackRuns`. `contentControls` path remains separate via `flattenContentControlText` (different recursion strategy, established in #63). MCP impact: anchor lookups (`replace_text` / `insert_paragraph` / `insert_image_from_path` / `insert_caption` `before_text` / `after_text`) against paragraphs containing inline math inside hyperlink / fldSimple / AC fallback wrappers now succeed where they previously silently 0-matched.
+
+**Tests**: 236 passing (no new MCP tests, no regressions). Backward compatible (strict superset of pre-fix lookup behavior).
+
+**Follow-ups filed (out of scope)**: 5 sibling bugs surfaced by devils-advocate verify of #92 — DA-1..DA-4 cover direct-child OMML in `<w:p>` / `<w:hyperlink>` / `<mc:Fallback>` + nested wrapper; DA-5 docstring qualifier. Filed as [#99](https://github.com/PsychQuant/che-word-mcp/issues/99)–[#103](https://github.com/PsychQuant/che-word-mcp/issues/103). NOT regressions introduced by v3.17.4.
+
+---
+
+**v3.17.3 bump `ooxml-swift` dep v0.21.6 → v0.21.7** — patch release exposing public anchor lookup API ([che-word-mcp#86](https://github.com/PsychQuant/che-word-mcp/issues/86)). Pure transitive, no MCP source changes:
+
+- **`WordDocument.findBodyChildContainingText(_:nthInstance:)`** — instance method, was `private`. Walks `body.children` returning the top-level index of the BodyChild whose flattened text contains the needle. `nthInstance` disambiguates among repeats. Traverses `.contentControl(_, children:)` recursively + `.table` cells / `nestedTables` (since #68); skips `bookmarkMarker` / `rawBlockElement`.
+- **`WordDocument.bodyChildContainsText(_:needle:)`** — static primitive, was `private static`. Single-child predicate; useful for custom traversal.
+- **`WordDocument.tableContainsText(_:needle:)`** — static primitive, was `private static`. Walks all cells + nested tables.
+
+External consumers previously had to reimplement this with diverging semantics — some skipped `.contentControl` recursion, some skipped table cell traversal (pre-#68 default), some used different `nthInstance` counting rules (top-level body child vs flattened paragraph). Now they get *exactly* the canonical behavior `insert_paragraph` etc. tools see.
+
+**Tests**: 236 passing (no regressions). 10 new public-API surface tests in `Issue86PublicAnchorLookupTests` pin the canonical behavior across releases (top-level paragraph match / `nthInstance` disambiguation / invalid input contracts / SDT recursion / table cell traversal / bookmark + raw skip / `bodyChildContainsText` predicate / `tableContainsText` nested-table walk / round-trip parity with `insertParagraph(at: .afterText)`).
+
+**Backward compatibility**: Pure additive (private → public visibility change). No API removals, no behavioral changes for existing callers.
+
+---
+
+**v3.17.2 bump `ooxml-swift` dep v0.21.2 → v0.21.6** — patch release pulling in 4 ooxml-swift releases worth of hardening + new APIs (no MCP source changes, no MCP tool surface change). New typed errors fire only on edge cases (malicious input, dirty fallback edits); deprecation warnings only when callers actively use lossy/legacy APIs. Pure transitive bump:
+
+- **[ooxml-swift#7](https://github.com/PsychQuant/ooxml-swift/issues/7) v0.21.3 XML hardening** — DTD reject + 64KB attribute-value cap + SAX-based root-element attribute parsing + name whitelist on emit. New `XMLHardeningError.{dtdNotAllowed, attributeValueTooLarge, invalidAttributeName}` throws on malicious .docx input.
+- **[ooxml-swift#6](https://github.com/PsychQuant/ooxml-swift/issues/6) v0.21.4 roundtrip loud-fail** — `AlternateContent.fallbackRunsModified` dirty flag throws `RoundtripError.unserializedFallbackEdit` when in-memory mutation isn't propagated back to rawXML. `Run.commentIds` `@available(*, deprecated)`; migrate to `commentRangeMarkers`.
+- **[che-word-mcp#84 #85](https://github.com/PsychQuant/che-word-mcp/issues/84) v0.21.5 insertEquation flexibility** — new `Document.insertEquation(at: InsertLocation, ...)` overload + `flattenedDisplayText` extension covers OMML so anchor-text resolution traverses display-mode equations.
+- **[ooxml-swift#5](https://github.com/PsychQuant/ooxml-swift/issues/5) v0.21.6 mutation surface fix** — `Hyperlink.text` setter `@available(*, deprecated)` (lossy: discards `RunProperties` + `rawElements`); migrate to `.runs` property. Position field cascade `Int = 0` → `Int? = nil` across 13 typed-child models with tri-state semantics. `xml:space="preserve"` autosense in `Run.toXMLThrowing` emit.
+- **Plus 3 unreleased docs commits on ooxml-swift main** — [#17](https://github.com/PsychQuant/ooxml-swift/issues/17) bidirectional `needsPPr` ↔ `Issue4PPrRegressionGuardTests` reference; [#15](https://github.com/PsychQuant/ooxml-swift/issues/15) `parseRun` vs `parseParagraph` walker pattern divergence rationale; [#14](https://github.com/PsychQuant/ooxml-swift/issues/14) foreign-namespace pPr asymmetry documentation.
+
+**Tests**: 236 passing (no regressions). Suite breakdown: 0 failures, 9 pre-existing skips. **Backward compatibility**: Deprecation warnings only when callers use `Hyperlink.text` setter / `commentIds`; new typed errors only on edge cases (malicious input, dirty fallback edits) — code that previously silently lost data now throws fail-fast. No API removals (all v0.21.x deprecations queued for v0.22).
+
+**Verification**: 6-AI ensemble verified each ooxml-swift release upstream (5 Claude reviewers + Codex CLI gpt-5.5 xhigh). Three SDD bundles archived: `mutation-surface-fix`, `roundtrip-loud-fail`, `harden-xml-security`.
+
+---
+
+**v3.17.1 bump `ooxml-swift` dep v0.21.0 → v0.21.2** — patch release pulling in upstream test/regression-guard hardening from the post-#56 follow-up bundle. **No public MCP tool change**, no behaviour change for valid input。Pure transitive hardening at the parser invariant layer：
+
+- **[ooxml-swift#4](https://github.com/PsychQuant/ooxml-swift/issues/4)** — `pPr` regression guard. 3-layer defense-in-depth on the v0.19.1 hot-fix invariant：`walkerPreConsumed: Set<String> = ["pPr"]` 在 `parseParagraph` walker loop entry filter；既有 `case "pPr": break` 保留為 belt-and-suspenders；`#if DEBUG assert(name != "pPr", ...)` 在 catch-all default `unrecognizedChildren.append` site 作 dev-time canary。5 regression tests in `Issue4PPrRegressionGuardTests`。
+- **[ooxml-swift#13](https://github.com/PsychQuant/ooxml-swift/issues/13)** — empty `<w:pPr/>` self-closing test gap closed。TDD discovered emitter drops empty pPr blocks（`needsPPr` gate at `Paragraph.swift:335,466`）；test name + assertion direction 反映 empirical OOXML-spec behaviour。
+- **[ooxml-swift#16](https://github.com/PsychQuant/ooxml-swift/issues/16)** — `countPPrOpenTags` helper regex hardening。Substring `<w:pPr` 替換為 `NSRegularExpression #"<w:pPr[\s/>]"#"` — 排除 `<w:pPrChange>`（Track Changes paragraph-property revision element），先前會虛增計數造成 brittle 假失敗。
+
+ooxml-swift suite 720 → 722（0 fail）。che-word-mcp suite 不變（pure transitive dep bump）。
+
+**Verification**：6-reviewer cross-verification on #4（5 Claude teammates + Codex CLI gpt-5.5 xhigh, all PASS unanimous）；5-reviewer on #13/#16 batch（Codex hung, skipped）。
+
+---
+
+**Pre-v3.17.x architectural milestones**（detail in [CHANGELOG](https://github.com/PsychQuant/che-word-mcp/blob/main/CHANGELOG.md)）：sub-stacks A–E 完整覆蓋 paragraph + run scope（`if not typed, preserve as raw` principle）。Combined preservation gains since v3.14.0：`<w:lang>` 50% → 98.89%；`w14:` 5% → 93.98%；`document.xml` size loss 16.66% → 8.02%。Matrix-pin `testDocumentContentEqualityInvariant` 現在 LOAD-BEARING across 5 preservation classes（rFonts / noProof / lang / kern / w14:）spanning run + paragraph + paragraph-mark scope — 任何一類 regression 都會 trip。
+
+---
+
+Office.js OOXML Roadmap **P0 100% 完成**（Umbrella issue [#43](https://github.com/PsychQuant/che-word-mcp/issues/43)）。Latest milestones：v3.17.4 — bump ooxml-swift dep to v0.21.8（paired #91 insertEquation inline-mode error semantics + #92 flattenedDisplayText OMML wrapper coverage, both lib-only post-#85 verify follow-ups）；v3.17.3 — bump ooxml-swift dep to v0.21.7（exposes public anchor lookup API for external Swift SPM consumers, [che-word-mcp#86](https://github.com/PsychQuant/che-word-mcp/issues/86)）；v3.17.2 — bump ooxml-swift dep to v0.21.6（4-version transitive bump pulling in XML hardening + roundtrip loud-fail + insertEquation InsertLocation overload + mutation surface fix from ooxml-swift#5/#6/#7）；v3.17.1 — bump ooxml-swift dep to v0.21.2（pPr regression-guard hardening from ooxml-swift#4/#13/#16）；v3.17.0 — `wrap_caption_seq` MCP tool（[#62](https://github.com/PsychQuant/che-word-mcp/issues/62)，rescues docs pasted from external sources so `insert_table_of_figures` / `insert_table_of_tables` produce populated TOFs）；v3.16.0 — Bundle B anchor DX consistency（[#70](https://github.com/PsychQuant/che-word-mcp/issues/70) [#71](https://github.com/PsychQuant/che-word-mcp/issues/71) [#72](https://github.com/PsychQuant/che-word-mcp/issues/72)，BREAKING input-validation：conflicting anchors + `text_instance ≤ 0` 改 structured error）。**Architectural extension of 'if not typed, preserve as raw' principle** — 從 sub-stack A (#58 BodyChild) → B (#59 WhitespaceOverlay) → C (#60 RunProperties) → D (#65 ParagraphProperties.markRunProperties) → **E (#66 paragraph w14:* attrs)** 完整覆蓋 paragraph + run scope。
+
+**前次 milestones**：
+
+- **v3.17.4** — bump `ooxml-swift` dep v0.21.7 → v0.21.8（paired #91 + #92 release）。#91 adds `InsertLocationError.inlineModeRequiresParagraphIndex` + `.invalidParagraphIndex(Int)` for `insert_equation` inline-mode anchor type / out-of-bounds `paragraph_index` (was silent fallthrough). #92 extends `flattenedDisplayText` OMML walk via shared `flattenRunsWithOMML(_:)` helper across hyperlink / fldSimple / AC.fallbackRuns wrappers (top-level runs + 3 wrapper paths now uniformly covered; contentControls path remains separate via `flattenContentControlText` per #63). MCP impact: `insert_equation` returns structured errors instead of silent no-op; anchor lookups against wrapper-nested OMML paragraphs now succeed where they previously silently 0-matched. Strict superset of pre-fix lookup behavior. Tests 236 passing. 5 follow-up issues #99-#103 filed for sibling bugs (DA-1..DA-5: direct-child OMML in `<w:p>` / `<w:hyperlink>` / `<mc:Fallback>` + nested wrapper + docstring qualifier).
+- **v3.17.3** — bump `ooxml-swift` dep v0.21.6 → v0.21.7（exposes public anchor lookup API: `WordDocument.findBodyChildContainingText` instance method + `bodyChildContainsText` / `tableContainsText` static primitives, all `private → public`）。Pure transitive, no MCP source changes. External Swift SPM consumers can now call canonical anchor-lookup logic directly instead of reimplementing with diverging semantics. 10 new public-API surface tests. Backward compatible (additive visibility change).
+- **v3.17.2** — bump `ooxml-swift` dep v0.21.2 → v0.21.6 (4-version transitive bump: v0.21.3 XML hardening + v0.21.4 roundtrip loud-fail + v0.21.5 insertEquation InsertLocation overload + v0.21.6 mutation surface fix + 3 unreleased docs commits on ooxml-swift main)。No MCP tool surface change. Deprecation warnings for `Hyperlink.text` setter / `commentIds` (queued for v0.22 removal). Tests 236 passing.
+- **v3.17.1** — bump `ooxml-swift` dep v0.21.0 → v0.21.2 (pPr regression-guard + test infra hardening from upstream #4/#13/#16)。No public MCP tool change。
+- **v3.17.0** — `wrap_caption_seq` MCP tool（Refs [#62](https://github.com/PsychQuant/che-word-mcp/issues/62)，Phase 2）：bulk-wraps plain-text caption number portions in SEQ field runs across body paragraphs whose flattened text matches a regex (EXACTLY ONE numeric capture group)。Captured digit becomes SEQ field cachedResult so Word's first-open render preserves user-typed numbering。Idempotent + scope:body-only + bookmark wrap opt-in。Suite 231 → 236 (+5)。Tools 234 → 235。
+- **v3.16.2** — pure dep bump `ooxml-swift` v0.20.5 → v0.21.0 (Refs [#62](https://github.com/PsychQuant/che-word-mcp/issues/62) [#68](https://github.com/PsychQuant/che-word-mcp/issues/68))：picks up `InsertLocation.findBodyChildContainingText` recursing into table cells + block-level SDT (#68) + `WordDocument.wrapCaptionSequenceFields` lib API ready for v3.17.0 MCP wrapper (#62)。
+- **v3.16.1** — anchor-presence whitelist drift prevention（Refs [#80](https://github.com/PsychQuant/che-word-mcp/issues/80)）：pure refactor，static `toolAnchorWhitelists` dict 替換 4 個分散的 literal anchor arrays。4 invariant tests（4 → 8）防將來新增 anchor 漏接 conflict-detection。No runtime behavior change。
+- **v3.16.0** — Bundle B anchor DX consistency（Refs [#70](https://github.com/PsychQuant/che-word-mcp/issues/70) [#71](https://github.com/PsychQuant/che-word-mcp/issues/71) [#72](https://github.com/PsychQuant/che-word-mcp/issues/72)，**BREAKING input validation only**）：(a) conflicting anchors（如 `after_text` + `index`）silent-priority 改成 structured error；(b) explicit `text_instance ≤ 0` 拒絕；(c) 4 個 #61-target tools 統一錯誤格式 `Error: <tool>: <body>` 給 AI-caller 錯誤歸因。Suite 201 → 227 (+26)。
+- **v3.15.3** — Bundle A2 polish（Refs [#76](https://github.com/PsychQuant/che-word-mcp/issues/76) [#77](https://github.com/PsychQuant/che-word-mcp/issues/77) [#78](https://github.com/PsychQuant/che-word-mcp/issues/78) [#79](https://github.com/PsychQuant/che-word-mcp/issues/79))：schema description doc rot 修正 + bookmarkMarker / SDT / TOC bookmark / contentControl 的 append-index regression pin。Suite 196 → 201。
+- **v3.15.2** — Bundle A polish（Refs [#69](https://github.com/PsychQuant/che-word-mcp/issues/69) [#73](https://github.com/PsychQuant/che-word-mcp/issues/73) [#74](https://github.com/PsychQuant/che-word-mcp/issues/74) [#75](https://github.com/PsychQuant/che-word-mcp/issues/75))：`insert_paragraph` append message 改回 body.children index（pre-fix `getParagraphs().count - 1` 在含 tables/SDTs 文件 mis-report）+ debug log label fixes + equation F5 partial-dict regression pin。Suite 194 → 196。
+- **v3.15.1** — Verify findings F1+F2+F3+F5 closed（Refs [#61](https://github.com/PsychQuant/che-word-mcp/issues/61))：`after_image_id` 加到 insert_paragraph + insert_equation (display only) + insert_image_from_path；`into_table_cell` 加到 insert_equation (display only)；equation 成功訊息加 anchor info；malformed `into_table_cell` partial dict 改 structured error。Suite 185 → 194。
+- **v3.15.0** — `insert_paragraph` / `insert_equation` accept anchor parameters（Refs [#61](https://github.com/PsychQuant/che-word-mcp/issues/61)）：closes MCP-side wire-up gap，handler dispatch 之前 silently 丟棄 `after_text` / `before_text` / `text_instance` / `into_table_cell`。Anchor priority `into_table_cell > after_text > before_text > index > append`。Inline equation explicitly 拒絕 anchor。Suite 176 → 185。
+- **v3.14.5** — `findBodyChildContainingText` 涵蓋所有 editable surfaces（Refs [#63](https://github.com/PsychQuant/che-word-mcp/issues/63) verify F1)：bumps `ooxml-swift` v0.20.4 → v0.20.5。Closes v3.14.4 CHANGELOG over-claim — REPLACE path 已修但 LOOKUP path（`InsertLocation.afterText`）仍只看 `para.runs`。`Paragraph.flattenedDisplayText` 擴充為涵蓋 runs + hyperlinks + fieldSimples + alternateContents + contentControls (recursive into nested SDT)。Suite 174 → 176。
+- **v3.14.4** — `replace_text` on inline `<w:sdt>` content controls fix（Refs [#63](https://github.com/PsychQuant/che-word-mcp/issues/63))：`Document.replaceInParagraphSurfaces` 之前覆蓋 runs / hyperlinks / fieldSimples / alternateContents 但 **沒有** contentControls — 包在 inline `<w:sdt>` 裡的文字 silently 0-match。常見於 pandoc / Quarto / LaTeX→docx cross-ref placeholder。bumps `ooxml-swift` v0.20.3 → v0.20.4。Suite 172 → 174。
+- **v3.14.3** sub-stack E (#66) — paragraph `w14:paraId` / `w14:textId` round-trip；`w14:` retention 5% → 93.98%；document.xml size loss 16.66% → 8.02%。
+- **v3.14.2** sub-stack D (#65) — `ParagraphProperties.markRunProperties` round-trips `<w:rPr>` direct child of `<w:pPr>`（pilcrow ¶ 字符外觀 per ECMA-376 §17.3.1.27）。`<w:lang>` retention 50% → 98.89%。
+- **v3.14.1** sub-stack C-CONT — closes triple-confirmed P0 (R2 + R5 + Codex 6-AI verify)：trim `recognizedRprChildren` Set 到 actually-extracted kinds（修了 `<w:spacing>` / `<w:caps>` / `<w:position>` / `<w:shd>` / `<w:em>` 等的 silent drop）。Round-trip size loss 17.75% → 16.66%。
+- **v3.14.0** sub-stack C of [#60](https://github.com/PsychQuant/che-word-mcp/issues/60) — `RunProperties` 新增 4-axis rFonts / noProof / kern / 3-axis lang typed fields + rawChildren passthrough（w14:textOutline / textFill / glow 等）。Pre-fix `eastAsia="DFKai-SB"`（繁體中文）會 silently 被 `ascii` 值替換掉；v3.14.0 完整保留 4 個 axis。
+- **v3.13.13** CRITICAL HOTFIX (sub-stack B-CONT-2-CONT)；v3.13.12 (DO NOT USE — 刪除 `<w:del>` 內容)；v3.13.11 sub-stack B-CONT；v3.13.10 sub-stack B 初版 (#59 WhitespaceOverlay)；v3.13.9 A-CONT-3 silent correctness regression；v3.13.6-v3.13.8 sub-stack A cycles (#58 BodyChild)；v3.13.5 R5 stack-completion — 詳見 [CHANGELOG](https://github.com/PsychQuant/che-word-mcp/blob/main/CHANGELOG.md)。
 
 ## 兩種操作模式
 
@@ -9,8 +162,8 @@
 傳入檔案路徑直接使用，不需要先 `open_document`。適合快速檢視。
 
 ```
-list_images: { "source_path": "/path/to/file.docx" }
-search_text: { "source_path": "/path/to/file.docx", "query": "keyword" }
+list_images:    { "source_path": "/path/to/file.docx" }
+search_text:    { "source_path": "/path/to/file.docx", "query": "keyword" }
 get_paragraphs: { "source_path": "/path/to/file.docx" }
 ```
 
@@ -19,96 +172,271 @@ get_paragraphs: { "source_path": "/path/to/file.docx" }
 先 `open_document` 取得 `doc_id`，再進行編輯操作。
 
 ```
-open_document: { "path": "/path/to/file.docx", "doc_id": "mydoc" }
+open_document:    { "path": "/path/to/file.docx", "doc_id": "mydoc" }
 insert_paragraph: { "doc_id": "mydoc", "text": "Hello World" }
-save_document: { "doc_id": "mydoc", "path": "/path/to/output.docx" }
-close_document: { "doc_id": "mydoc" }
+save_document:    { "doc_id": "mydoc", "path": "/path/to/output.docx" }
+close_document:   { "doc_id": "mydoc" }
 ```
 
-## Direct Mode 支援的工具（18 個）
+v3.0.0+ session state 追蹤：dirty tracking、autosave、`finalize_document`、disk drift 偵測。
+
+## Round-trip Fidelity（v3.5.0 true byte-preservation）
+
+底層 `ooxml-swift v0.19.2` 採用 **preserve-by-default + dirty tracking** 架構：`open_document` 保留原始 archive tempDir；`save_document` overlay 模式透過 `WordDocument.modifiedParts: Set<String>` 精確判斷哪些 part 真正被改動，**未改動的 typed-managed part 完全不重寫**——byte-for-byte 保留 `word/theme/`、`webSettings.xml`、`people.xml`、`commentsExtended/Extensible/Ids`、`glossary/`、`customXml/`、**以及 `word/document.xml`、`styles.xml`、`fontTable.xml`、`header*.xml`、`footer*.xml`、`comments.xml`、`footnotes.xml`、`endnotes.xml`** 等所有 typed parts。v0.19.x 額外解決 #56 P0：`<w:document>` root 34 個 `xmlns:*` declarations 完整保留，`<w:bookmarkStart>` / `<w:hyperlink>` / `<w:fldSimple>` / `<mc:AlternateContent>` 結構化 wrapper 全程 round-trip（pre-v0.19.0 會 silently 丟掉 wrapper 內 354 個 `<w:t>` text nodes）。
+
+NTPU 學位論文模板的中文字體（DFKai-SB / 華康中楷體）no-op `save_document` 後完整保留 13 fontTable + 6 distinct headers + 4 footers + three-segment PAGE field + `<w15:presenceInfo>` identity。
+
+## Track Changes 寫側合約（v3.12.0+）
+
+兩條路徑：**accept/reject 既有修訂** OR **程式化生成新修訂**。
+
+### 程式化生成（v3.12.0 新增）
+
+```
+1. enable_track_changes(doc_id, author: "Reviewer A")
+2. insert_text_as_revision(doc_id, paragraph_index, position, text)
+   delete_text_as_revision(doc_id, paragraph_index, start, end)
+   move_text_as_revision(doc_id, source/dest)
+   format_text(doc_id, paragraph_index, bold: true, as_revision: true)
+   set_paragraph_format(doc_id, paragraph_index, alignment: "center", as_revision: true)
+3. save_document(...)
+```
+
+**Author resolution 三層 fallback**：explicit `author` arg → `revisions.settings.author`（在 `enable_track_changes` 時設定）→ `"Unknown"`。
+
+**Side-effect 合約**（重要）：`as_revision: true` 要求 track changes 已開啟。Disabled 時呼叫**會拋 `track_changes_not_enabled`**，不會偷偷 auto-enable。設計理由：避免 hidden state mutation。
+
+### Accept / Reject 既有修訂
+
+```
+get_revisions / accept_revision / reject_revision / accept_all_revisions / reject_all_revisions
+```
+
+## Direct Mode 支援的工具
 
 | 類別 | 工具 |
 |------|------|
 | 讀取內容 | `get_text`, `get_document_text`, `get_paragraphs`, `get_document_info`, `search_text` |
-| 列出元素 | `list_images`, `list_styles`, `get_tables`, `list_comments`, `list_hyperlinks`, `list_bookmarks`, `list_footnotes`, `list_endnotes`, `get_revisions` |
+| 列出元素 | `list_images`, `list_styles`, `get_tables`, `list_comments`, `list_hyperlinks`, `list_bookmarks`, `list_footnotes`, `list_endnotes`, `get_revisions`, `list_content_controls` |
 | 屬性 | `get_document_properties`, `get_section_properties`, `get_word_count_by_section` |
 | 匯出 | `export_markdown` |
 
-## 功能概覽（146 個工具）
+## 工具總覽
+
+### 文件管理 + Session 生命週期（v3.0.0+）
+
+- `create_document`, `open_document`, `save_document`, `close_document`, `finalize_document`
+- `list_open_documents`, `get_document_info` ⚡, `get_document_session_state`, `get_session_state`
+- `check_disk_drift`, `revert_to_disk`, `reload_from_disk`, `recover_from_autosave`, `checkpoint`
 
-### 文件管理 (6 個)
-- `create_document`, `open_document`, `save_document`, `close_document`
-- `list_open_documents`, `get_document_info` ⚡
+### 內容操作
 
-### 內容操作 (9 個)
-- `get_text` ⚡, `get_document_text` ⚡, `get_paragraphs` ⚡, `search_text` ⚡
-- `insert_paragraph`, `update_paragraph`, `delete_paragraph`, `replace_text`, `insert_text`
+- `get_text` ⚡, `get_document_text` ⚡, `get_paragraphs` ⚡, `search_text` ⚡, `search_text_batch`
+- `insert_paragraph`, `update_paragraph`, `delete_paragraph`
+- `replace_text`, `replace_text_batch`, `insert_text`
 
-### 格式設定 (9 個)
-- `format_text`, `set_paragraph_format`, `apply_style`
+### 格式設定
+
+- `format_text`（**v3.12.0+ `as_revision: bool`**）, `set_paragraph_format`（**v3.12.0+ `as_revision: bool`**）, `apply_style`
 - `set_paragraph_border`, `set_paragraph_shading`, `set_character_spacing`, `set_text_effect`
-- `get_paragraph_runs`, `get_text_with_formatting`, `search_by_formatting`
+- `get_paragraph_runs`, `get_text_with_formatting`, `search_by_formatting`, `search_text_with_formatting`, `list_all_formatted_text`
+
+### 樣式管理（v3.10.0+ 強化，#48）
+
+- `list_styles` ⚡, `apply_style`, `create_style`, `update_style`, `delete_style`
+- v3.10.0 新增：`get_style_inheritance_chain`（含 cycle detection）, `link_styles`（`<w:link>` 段落+字元 pair）, `set_latent_styles`, `add_style_name_alias`（BCP 47 多語）
+- `create_style` / `update_style` 新增 6 個 args：`based_on`, `linked_style_id`, `next_style_id`, `q_format`, `hidden`, `semi_hidden`
+
+### Numbering / 編號清單（v3.10.0+ 完整補完，#46）
+
+- 入門：`insert_bullet_list`, `insert_numbered_list`, `set_list_level`, `set_outline_level`
+- 定義管理（v3.10.0 新增 8 個）：`list_numbering_definitions`, `get_numbering_definition`, `create_numbering_definition`（max 9 levels）, `override_numbering_level`, `assign_numbering_to_paragraph`, `continue_list`, `start_new_list`, `gc_orphan_numbering`
+
+### 區段 / 頁面設定（v3.10.0+ 強化，#47）
+
+- 基礎：`set_page_size`, `set_page_margins`, `set_page_orientation`, `set_page_borders`, `set_columns`, `set_line_numbers`, `set_text_direction`
+- 區段斷點：`insert_page_break`, `insert_section_break`, `insert_continuous_section_break`, `insert_column_break`
+- v3.10.0 新增 7 個：`set_line_numbers_for_section`（legal docs `<w:lnNumType>`）, `set_section_vertical_alignment`（封面置中）, `set_page_number_format`（羅馬數字等）, `set_section_break_type`, `set_title_page_distinct`, `set_section_header_footer_references`, `get_all_sections`
+
+### 表格（v3.11.0+ 強化，#49）
+
+- 基礎：`insert_table`, `get_tables` ⚡, `update_cell`, `delete_table`
+- 結構：`merge_cells`, `set_table_style`, `set_table_alignment`
+- 行列：`add_row_to_table`, `add_column_to_table`, `delete_row_from_table`, `delete_column_from_table`
+- 尺寸：`set_cell_width`, `set_row_height`, `set_cell_vertical_alignment`, `set_header_row`
+- v3.11.0 新增 5 個：`set_table_conditional_style`（10 種 region：firstRow / lastRow / bandedRows…），`insert_nested_table`（最深 5 層，超過拋 `nested_too_deep`），`set_table_layout`（fixed/autofit），`set_table_indent`（`<w:tblInd>`）
+
+### 超連結（v3.11.0+ 三種 typed，#50）
 
-### 表格 (11 個)
-- `insert_table`, `get_tables` ⚡, `update_cell`, `delete_table`
-- `merge_cells`, `set_table_style`, `set_table_alignment`
-- `add_row_to_table`, `add_column_to_table`, `delete_row_from_table`, `delete_column_from_table`
-- `set_cell_width`, `set_row_height`, `set_cell_vertical_alignment`, `set_header_row`
+- 基礎：`insert_hyperlink`, `update_hyperlink`, `delete_hyperlink`, `list_hyperlinks` ⚡
+- 內部連結：`insert_internal_link`, `insert_cross_reference`
+- v3.11.0 新增 3 個 typed：`insert_url_hyperlink`（外部 URL + tooltip + history flag），`insert_bookmark_hyperlink`（`w:anchor`，無 rId），`insert_email_hyperlink`（`mailto:` + URL-encoded subject）— 三者自動建 Hyperlink character style
 
-### 樣式管理 (4 個)
-- `list_styles` ⚡, `create_style`, `update_style`, `delete_style`
+### 頁首頁尾 + 浮水印（v3.3.0+ → v3.11.0+ 強化，#51）
 
-### 清單 (3 個)
-- `insert_bullet_list`, `insert_numbered_list`, `set_list_level`
+- 寫入：`add_header`, `update_header`, `add_footer`, `update_footer`, `insert_page_number`
+- 列舉與讀取：`list_headers`, `get_header`, `list_footers`, `get_footer`
+- 刪除：`delete_header`, `delete_footer`
+- v3.11.0 新增 4 個：`enable_even_odd_headers`（`<w:evenAndOddHeaders/>`），`link_section_header_to_previous` / `unlink_section_header_from_previous`（Word-compat clone），`get_section_header_map`
+- 浮水印：`insert_watermark`, `insert_image_watermark`, `remove_watermark`, `list_watermarks`, `get_watermark`
 
-### 頁面設定 (5 個)
-- `set_page_size`, `set_page_margins`, `set_page_orientation`
-- `insert_page_break`, `insert_section_break`
+### Content Controls / SDT（v3.9.0+ 完整 read/write，#44）
 
-### 頁首頁尾 (5 個)
-- `add_header`, `update_header`, `add_footer`, `update_footer`, `insert_page_number`
+- 寫入：`insert_content_control`（12 type discrimination：richText / plainText / picture / date / dropDownList / comboBox / checkBox / bibliography / citation / group / repeatingSection / repeatingSectionItem）
+- 讀取：`list_content_controls` ⚡（flat 或 nested tree mode），`get_content_control`（by id / tag / alias，回 metadata + `<w:sdtContent>` XML）
+- 修改：`update_content_control_text`（preserves `<w:sdtPr>` byte-identical），`replace_content_control_content`（whitelist validation，拒絕含 `<w:sdt>` / `<w:body>` / `<w:sectPr>` 的 input）
+- 刪除：`delete_content_control`（`keep_content: true` 預設 unwrap children）
+- Repeating sections：`insert_repeating_section`, `list_repeating_section_items`, `update_repeating_section_item`
+- 表單便利：`insert_checkbox`, `insert_dropdown`, `insert_text_field`
+- v0.15.0 SDT id allocator 改 max+1 deterministic（取代 random）
+
+### 主題編輯（v3.3.0+，#28）
+
+- `get_theme` — 讀 major/minor 字體 + 色盤
+- `update_theme_fonts` — 部分更新字體 slot（latin/ea/cs）。**用於 NTPU 論文中文字體修復**：`update_theme_fonts({ minor: { ea: "DFKai-SB" }})`
+- `update_theme_color` — slot-named hex color 更新（accent1-6 / hyperlink / followedHyperlink）
+- `set_theme` — 完整 theme XML 覆寫 escape hatch
+
+### 圖片
 
-### 圖片 (9 個)
 - `insert_image`, `insert_image_from_path`, `insert_floating_image`
 - `update_image`, `delete_image`, `list_images` ⚡, `set_image_style`
-- `export_image`, `export_all_images`
+- `export_image`, `export_all_images`, `insert_drop_cap`
+
+### 數學公式（v3.2.0+ 完整 LaTeX 子集）
+
+- `insert_equation` — 透過 [`latex-math-swift`](https://github.com/PsychQuant/latex-math-swift)：`\frac`, `\sqrt`, `\hat`/`\bar`/`\tilde`, `\left/\right`, `\sum`/`\int`/`\prod`（with bounds），`\ln`/`\sin`/`\cos`/`\tan`/`\log`/`\exp`/`\max`/`\min`/`\det`，`\sup`/`\inf`/`\lim`，`\text{}`，全部希臘字母（含 `\varepsilon` 變體）+ 常用運算子
+- `list_equations`, `get_equation`, `update_equation`, `delete_equation`
+- `splice_omath_from_source`, `splice_paragraph_omath_from_source` — 跨 doc verbatim copy `<m:oMath>` XML（v3.20.0+，#160；wraps ooxml-swift v0.24.0 `spliceOMath` API）
+
+### 匯出
+
+- `export_text`, `export_markdown` ⚡, `export_revision_summary_markdown`, `export_comment_threads_markdown`
+
+### 註解（v3.4.0+ thread 管理）
+
+- 寫入：`insert_comment`, `update_comment`, `delete_comment`, `reply_to_comment`, `resolve_comment`
+- 讀取：`list_comments` ⚡
+- Thread 管理：`list_comment_threads`, `get_comment_thread`, `sync_extended_comments`
+
+### People / Comment Authors（v3.4.0+，v3.5.0 dual identity #34）
+
+- `list_people` — 解析完整 `<w15:presenceInfo>`，回 dual identity：
+  - `person_id` (GUID, 來自 `userId="S::email::guid"` 第三段)，rename 跨版本穩定
+  - `display_name_id` (= author，v3.4.0 legacy id)
+  - `display_name`, `email`, `color`, `provider_id`
+- `add_person`, `update_person`, `delete_person` — 接受 GUID **或** legacy author 任一形式
+
+### Track Changes / Revisions（v3.12.0 寫側 #45）
+
+- 既有修訂處理：`enable_track_changes`, `disable_track_changes`, `get_revisions` ⚡, `accept_revision`, `reject_revision`, `accept_all_revisions`, `reject_all_revisions`
+- **v3.12.0 程式化生成（NEW）**：
+  - `insert_text_as_revision(doc_id, paragraph_index, position, text, author?, date?)` — `<w:ins>` 包覆，跨 run split 處理
+  - `delete_text_as_revision(doc_id, paragraph_index, start, end, author?, date?)` — `<w:del>` 標記 + `<w:t>` → `<w:delText>` substitution（單段內，跨段 OOS）
+  - `move_text_as_revision(doc_id, from_paragraph_index, from_start, from_end, to_paragraph_index, to_position, author?, date?)` — paired `<w:moveFrom>` / `<w:moveTo>` with adjacent revision ids
+  - `format_text` 加 `as_revision: bool` → `<w:rPrChange>`
+  - `set_paragraph_format` 加 `as_revision: bool` → `<w:pPrChange>`
+- 比對：`compare_documents`, `compare_documents_markdown`
+
+### 註腳與尾注（v3.4.0+ 補完 update）
 
-### 匯出 (2 個)
-- `export_text`, `export_markdown` ⚡
+- 寫入：`insert_footnote`, `delete_footnote`, `insert_endnote`, `delete_endnote`
+- 讀取：`list_footnotes` ⚡, `list_endnotes` ⚡
+- v3.4.0+：`get_footnote`, `update_footnote`, `get_endnote`, `update_endnote`（in-place 替換、保留 ID）
 
-### 超連結與書籤 (8 個)
-- `insert_hyperlink`, `insert_internal_link`, `update_hyperlink`, `delete_hyperlink`
-- `insert_bookmark`, `delete_bookmark`, `list_hyperlinks` ⚡, `list_bookmarks` ⚡
+### 標號與目錄
 
-### 註解與修訂 (13 個)
-- `insert_comment`, `update_comment`, `delete_comment`, `list_comments` ⚡
-- `reply_to_comment`, `resolve_comment`
-- `enable_track_changes`, `disable_track_changes`
-- `accept_revision`, `reject_revision`, `get_revisions` ⚡
-- `accept_all_revisions`, `reject_all_revisions`
+- `insert_caption`, `list_captions`, `get_caption`, `update_caption`, `delete_caption`（v3.1.0+）
+- `insert_table_of_figures`, `insert_index`, `insert_index_entry`, `insert_toc`
+- `update_all_fields`（v3.1.0+，#19）— F9 等價，全文 SEQ 重算
+- `insert_cross_reference`
 
-### 註腳與尾注 (6 個)
-- `insert_footnote`, `delete_footnote`, `list_footnotes` ⚡
-- `insert_endnote`, `delete_endnote`, `list_endnotes` ⚡
+### Custom XML / Web Settings
+
+- `list_custom_xml_parts`（v3.9.0+ stub，real impl 待 Change B）
+- `get_web_settings`, `update_web_settings`（v3.4.0+，#31）— `relyOnVML` / `optimizeForBrowser` / `allowPNG` / `doNotSaveAsSingleFile`
+
+### 屬性與保護
 
-### 屬性與區段 (3 個)
 - `get_document_properties` ⚡, `set_document_properties`
 - `get_section_properties` ⚡, `get_word_count_by_section` ⚡
+- `protect_document`, `unprotect_document`, `set_document_password`, `remove_document_password`
+- `restrict_editing_region`
+
+### 欄位代碼
+
+- `insert_date_field`, `insert_page_field`, `insert_sequence_field`, `insert_merge_field`
+- `insert_calculation_field`, `insert_if_field`, `insert_text_field`
 
-### 進階功能
-- 欄位代碼、表單控件、目錄、浮水印、文件保護、索引、方程式等
+### 進階格式 / 排版
+
+- 分欄、tab stops、drop cap、horizontal line、symbol
+- `insert_horizontal_line`, `insert_drop_cap`, `insert_symbol`, `insert_column_break`
+- `insert_tab_stop`, `clear_tab_stops`
+- `set_keep_lines`, `set_keep_with_next`, `set_widow_orphan`, `set_outline_level`, `set_page_break_before`
+- 字體和語言：`set_language`
 
 ⚡ = 支援 Direct Mode
 
 ## 技術細節
 
-- **語言**: Swift
-- **MCP SDK**: swift-sdk 0.11.0
-- **OOXML**: ooxml-swift 0.5.2 (Pure Swift)
-- **平台**: macOS 13.0+
+- **語言**: Swift（macOS 13.0+）
+- **MCP SDK**: swift-sdk 0.12+
+- **OOXML 引擎**: [`ooxml-swift v0.19.2`](https://github.com/PsychQuant/ooxml-swift)（preserve-by-default + dirty tracking + revision generation + `document.xml` lossless round-trip）
+- **LaTeX parser**: [`latex-math-swift v0.1.0+`](https://github.com/PsychQuant/latex-math-swift)（v3.2.0+）
+- **Markdown export**: [`word-to-md-swift`](https://github.com/PsychQuant/word-to-md-swift) + [`markdown-swift`](https://github.com/PsychQuant/markdown-swift)
 
 ## 版本
 
-- **當前版本**: 1.16.0
-- **專案位置**: `/Users/che/Developer/macdoc/mcp/che-word-mcp`
-- **GitHub**: https://github.com/kiki830621/che-word-mcp
+- **Plugin shell**: v3.13.2
+- **Binary**: v3.13.2（`CheWordMCP`）
+- **GitHub**: https://github.com/PsychQuant/che-word-mcp
+- **完整 CHANGELOG**: https://github.com/PsychQuant/che-word-mcp/blob/main/CHANGELOG.md
+
+### Plugin Shell vs Binary 版本
+
+兩者獨立但本次 v3.13.2 同步。Plugin shell（marketplace 端，含 SKILL.md / CLAUDE.md / `.mcp.json` / wrapper）有自己的 minor，反映文件 / skill 變動；Binary（GitHub release 端）有自己的 minor，反映 MCP server 內部新增 tool 或修 bug。Wrapper auto-download 從 release fetch binary 到 `~/bin/CheWordMCP`。
+
+### 重要 milestones
+
+- **v3.13.2** — bump ooxml-swift v0.19.1→v0.19.2，修正 v3.13.1 的 6-AI verification 找到的 4 個 blocking findings（無 source 變更）：F1 `Hyperlink.toXML()` 真正 emit Reader 解出的 runs/rawAttributes/rawChildren（pre-fix 把所有 inner runs 攤平成單一 hardcoded 藍底線 styled run）、F2 `addBookmark`/`deleteBookmark` 同步 `bookmarkMarkers`（pre-fix source-loaded paragraph 的新 bookmark 在 save 時被靜默丟掉、刪除留下 zombie `name=""` markers）、F3 `<w:ins>`/`<w:del>`/`<w:moveFrom>`/`<w:moveTo>` Reader 為 inner runs 設 `position`+`revisionId` + Writer sort path 重新 group runs by revisionId 包回 wrapper（pre-fix wrapper 在 source-load round-trip 後完全消失）、F4 namespace 保留從 `document.xml` 擴展到 header/footer/footnote/endnote 各自的 root（pre-fix NTPU thesis VML watermark headers declaring mc/wp/w14/w15 silently 退化到 hardcoded 5-namespace template）
+- **v3.13.1** — `pPr` double-emission silent regression hot-fix（bump ooxml-swift v0.19.0→v0.19.1，無 source 變更）。NTPU thesis 驗證時抓到：v3.13.0 round-trip 後 `<w:pPr>` 被雙重 emit，unrecognized children 從 799→1333（+67%）。1-line `case "pPr": break` 修正
+- **v3.13.0** — `document.xml` lossless round-trip + tool-mediated wrapper edits（closes [#56](https://github.com/PsychQuant/che-word-mcp/issues/56) P0）— 完整保留 `<w:document>` root 34 個 `xmlns:*` declarations、`<w:bookmarkStart>` / `<w:hyperlink>` / `<w:fldSimple>` / `<mc:AlternateContent>` 全程 round-trip（pre-v3.13.0 silently 丟掉 32 namespaces / 100% bookmarks / 354 個 `<w:t>` text nodes 在 wrapper 內），`replace_text` 走 wrapper-internal runs（無 silent failure）。Built on ooxml-swift v0.19.x
+- **v3.12.0** — Programmatic Track Changes 生成 — 3 新 MCP 工具（insert_text_as_revision / delete_text_as_revision / move_text_as_revision）+ 2 擴充 args（format_text / set_paragraph_format 加 `as_revision: bool`）— closes [#45](https://github.com/PsychQuant/che-word-mcp/issues/45)，**Office.js OOXML Roadmap P0 100% 完成**
+- **v3.11.0** — Tables / Hyperlinks / Headers extensions（16 新工具：5 table conditional/nested/layout + 3 typed hyperlinks + 4 header even/odd/link/section-map）— closes [#49](https://github.com/PsychQuant/che-word-mcp/issues/49) [#50](https://github.com/PsychQuant/che-word-mcp/issues/50) [#51](https://github.com/PsychQuant/che-word-mcp/issues/51)
+- **v3.10.0** — Styles + Numbering + Sections foundation（19 新工具 + 6 擴充 args：4 style inheritance/link/latent/alias + 8 numbering definition lifecycle + 7 section vertical/break/title-page）— closes [#46](https://github.com/PsychQuant/che-word-mcp/issues/46) [#47](https://github.com/PsychQuant/che-word-mcp/issues/47) [#48](https://github.com/PsychQuant/che-word-mcp/issues/48)
+- **v3.9.0** — Content Controls (SDT) 完整 read/write（7 新工具 + 12-type discrimination + nested SDT tree）— closes [#44](https://github.com/PsychQuant/che-word-mcp/issues/44)
+- **v3.8.0** — Header/footer raw-element preservation + counter-isolation flag — closes [#52](https://github.com/PsychQuant/che-word-mcp/issues/52)
+- **v3.7.0–v3.7.2** — Save durability cycle: path-traversal 修正 / hdr-ftr auto-suffix / `updateAllFields`（#53–#55, #54）
+- **v3.6.0** — Save durability + autosave Design B + serial-only OOXML IO — closes #40 #41
+- **v3.5.0** — true byte-preservation via dirty tracking — closes #23 round-2 + #32 #33 #34
+- **v3.4.0** — Phase 2B+2C: 13 個 comment-thread/people/notes-update/web-settings 工具 — closes #24 #25 #29 #30 #31
+- **v3.3.0** — Phase 2A: 12 個 theme/header/footer/watermark 工具 — closes #26 #27 #28
+- **v3.2.0** — `insert_equation` LaTeX parser delegated to `latex-math-swift` — closes #22
+- **v3.1.0** — 9 個 readback tools（Caption CRUD, update_all_fields, Equation CRUD）— closes #17 #19 #21
+- **v3.0.0** — Session state API（dirty tracking, autosave, finalize_document, disk drift detection）— closes #12 #13 #15
+
+### 底層架構里程碑
+
+- **`ooxml-swift v0.19.0–0.19.2`** — `document.xml` lossless round-trip：root namespace preservation（34 `xmlns:*` + `mc:Ignorable`）+ Bookmark Reader parsing + Wrapper hybrid model（`Hyperlink` / `FieldSimple` / `AlternateContent` typed editable surface + raw passthrough）+ sort-by-position Writer emit + 6 raw-carrier types for `<w:p>` schema completeness。v0.19.1 修正 v0.19.0 的 pPr double-emission silent regression。v0.19.2 修正 6-AI verification 找到的 4 個 blocking findings：Hyperlink writer 真正 iterate runs+rawAttributes+rawChildren、bookmark mutation API 同步 markers、ins/del/moveFrom/moveTo wrapper round-trip（Reader 設 position+revisionId、Writer sort path 重新 group by revisionId）、namespace 保留擴展到 header/footer/footnote/endnote（新 `ContainerRootTag` helper）
+- **`ooxml-swift v0.18.0`** — Revision generation primitives（6 new WordDocument methods + writer-side `Paragraph.toXML()` revision wrapping + `<w:t>` → `<w:delText>` substitution）
+- **`ooxml-swift v0.16.0–0.17.0`** — Styles inheritance / Numbering lifecycle / Section vertical alignment / Table conditional+nested+indent / Typed hyperlinks / Even-odd headers
+- **`ooxml-swift v0.15.0–0.15.1`** — `SDTParser` first-class `<w:sdt>` model + `BodyChild.contentControl` + max+1 SDT id allocator
+- **`ooxml-swift v0.13.0–0.14.0`** — true byte-preservation via dirty tracking + raw-element preservation
+- **`ooxml-swift v0.12.0`** — preserve-by-default 架構（PreservedArchive + RelationshipIdAllocator + ContentTypesOverlay）
+- **`ooxml-swift v0.10.0–0.11.0`** — `FieldParser` + `OMMLParser` readback primitives + `MathAccent`
+
+## Office.js OOXML Roadmap P0 Closure Map
+
+| § | Sub-issue | che-word-mcp 版本 |
+|---|-----------|-------------------|
+| §1 Content Controls (SDT) | [#44](https://github.com/PsychQuant/che-word-mcp/issues/44) | v3.9.0 |
+| §2 Track Changes 寫側 | [#45](https://github.com/PsychQuant/che-word-mcp/issues/45) | v3.12.0 |
+| §3 Numbering | [#46](https://github.com/PsychQuant/che-word-mcp/issues/46) | v3.10.0 |
+| §4 Sections | [#47](https://github.com/PsychQuant/che-word-mcp/issues/47) | v3.10.0 |
+| §8 Styles | [#48](https://github.com/PsychQuant/che-word-mcp/issues/48) | v3.10.0 |
+| §9 Tables | [#49](https://github.com/PsychQuant/che-word-mcp/issues/49) | v3.11.0 |
+| §14 Hyperlinks | [#50](https://github.com/PsychQuant/che-word-mcp/issues/50) | v3.11.0 |
+| §16 Headers / Footers | [#51](https://github.com/PsychQuant/che-word-mcp/issues/51) | v3.11.0 |
+
+Umbrella [#43](https://github.com/PsychQuant/che-word-mcp/issues/43) — closed 2026-04-25。
diff --git a/plugins/che-word-mcp/bin/che-word-mcp-wrapper.sh b/plugins/che-word-mcp/bin/che-word-mcp-wrapper.sh
index fbbddaef..2d08728a 100755
--- a/plugins/che-word-mcp/bin/che-word-mcp-wrapper.sh
+++ b/plugins/che-word-mcp/bin/che-word-mcp-wrapper.sh
@@ -1,28 +1,92 @@
 #!/bin/bash
-# Auto-download wrapper for CheWordMCP
-REPO="kiki830621/che-word-mcp"
+# Version-aware auto-download wrapper for CheWordMCP.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheWordMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+#
+# Fixed in 2.0.1:
+# - No version check → now checks plugin.json version against installed sidecar
+# - REPO was obsolete fork kiki830621 → now PsychQuant
+
+set -u
+
+REPO="PsychQuant/che-word-mcp"
 BINARY_NAME="CheWordMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
 
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
     if [[ -z "$URL" ]]; then
-        echo "ERROR: No download URL found. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-        || { echo "ERROR: Download failed." >&2; exit 1; }
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-word-mcp/skills/che-word-mcp/SKILL.md b/plugins/che-word-mcp/skills/che-word-mcp/SKILL.md
new file mode 100644
index 00000000..847af239
--- /dev/null
+++ b/plugins/che-word-mcp/skills/che-word-mcp/SKILL.md
@@ -0,0 +1,261 @@
+---
+name: che-word-mcp
+description: Use when working with Microsoft Word (.docx) documents — reading content, creating new documents, modifying text/formatting/structure, working with tables/images/comments/track-changes/SDT/sections/styles/headers/hyperlinks. Swift-native OOXML server, 218+ tools, no Word install required.
+---
+
+# che-word-mcp
+
+A Swift-native MCP server for Microsoft Word (.docx) document manipulation. **218+ tools** for reading, writing, and modifying Word documents without requiring Microsoft Word installation. Built on `ooxml-swift` v0.18.0.
+
+Office.js OOXML Roadmap P0 = **100% complete** ([PsychQuant/che-word-mcp#43](https://github.com/PsychQuant/che-word-mcp/issues/43)). Latest: v3.12.0 ships programmatic Track Changes generation.
+
+## Two Modes of Operation
+
+| Mode | Parameter | Use when | Tool count |
+|------|-----------|----------|------------|
+| **Direct Mode** | `source_path` | Quick read-only access, no state needed | 18 tools |
+| **Session Mode** | `doc_id` | Full read/write with open→edit→save lifecycle | All 218+ tools |
+
+### Direct Mode (`source_path`)
+
+Pass `source_path` with the .docx path. No `open_document` needed. Best for quick inspection.
+
+```
+list_images:  { "source_path": "/path/to/file.docx" }
+search_text:  { "source_path": "/path/to/file.docx", "query": "keyword" }
+```
+
+### Session Mode (`doc_id`)
+
+Call `open_document` first, then pass `doc_id`. Required for any edit.
+
+```
+open_document:    { "path": "/path/to/file.docx", "doc_id": "mydoc" }
+insert_paragraph: { "doc_id": "mydoc", "text": "Hello" }
+save_document:    { "doc_id": "mydoc", "path": "/path/to/output.docx" }
+close_document:   { "doc_id": "mydoc" }
+```
+
+## Core Workflows
+
+### Reading Documents
+
+```text
+1. open_document(path: "...")          → returns doc_id
+2. get_document_text(doc_id: "...")    → plain text
+   OR get_paragraphs(doc_id: "...")    → with formatting + indices
+3. close_document(doc_id: "...")
+```
+
+### Creating Documents
+
+```text
+1. create_document(doc_id: "report")
+2. insert_paragraph(doc_id, text: "Title", style: "Heading1")
+   insert_table(doc_id, rows: 3, cols: 4, data: [...])
+   insert_image(doc_id, path: "/image.png")
+3. save_document(doc_id, path: "/out.docx")
+```
+
+### Modifying Documents
+
+```text
+1. open_document(path: "...")
+2. update_paragraph(doc_id, paragraph_index: 0, text: "...")
+   format_text(doc_id, paragraph_index: 0, bold: true)
+   replace_text(doc_id, find: "...", replace: "...")
+3. save_document(doc_id, path: "...")
+```
+
+### Track Changes Workflow (v3.12.0+)
+
+Two paths: **accept/reject existing revisions** OR **generate new revisions programmatically**.
+
+```text
+# Accept/reject existing revisions
+1. open_document(path: "...")
+2. get_revisions(doc_id)                  → list with revision ids
+3. accept_revision(doc_id, revision_id) / reject_revision(...)
+   accept_all_revisions(doc_id) / reject_all_revisions(doc_id)
+
+# Generate new revisions (NEW in v3.12.0)
+1. enable_track_changes(doc_id, author: "Reviewer A")
+2. insert_text_as_revision(doc_id, paragraph_index, position, text)
+   delete_text_as_revision(doc_id, paragraph_index, start, end)
+   move_text_as_revision(doc_id, source/dest)
+   format_text(doc_id, paragraph_index, bold: true, as_revision: true)
+   set_paragraph_format(doc_id, paragraph_index, alignment: "center", as_revision: true)
+3. save_document(...)
+```
+
+**Author resolution chain**: explicit `author` arg → `revisions.settings.author` (set at `enable_track_changes`) → `"Unknown"`.
+
+**Side-effect contract** (important): `as_revision: true` requires track changes to be enabled. If disabled, the call **throws `track_changes_not_enabled`** instead of silently auto-enabling. Call `enable_track_changes` first.
+
+### Content Controls / SDT (v3.9.0+)
+
+```text
+insert_content_control(doc_id, paragraph_index, control_type: "richText"|"plainText"|"checkBox"|"dropDownList"|"comboBox"|"date"|"picture")
+insert_repeating_section(doc_id, ...)
+list_content_controls(doc_id)
+get_content_control(doc_id, sdt_id)
+update_content_control_text(doc_id, sdt_id, text)
+replace_content_control_content(doc_id, sdt_id, content)
+delete_content_control(doc_id, sdt_id)
+```
+
+SDT ids are auto-allocated via max+1 pattern (scans body + headers + footers + footnotes + endnotes).
+
+### Exporting
+
+```text
+export_text(doc_id)                    → plain text
+export_markdown(doc_id)                → Markdown
+export_revision_summary_markdown(doc_id) → revision summary
+export_comment_threads_markdown(doc_id)  → comment threads
+export_all_images(doc_id, output_dir)
+```
+
+## Tool Categories (218+ total)
+
+### Document Lifecycle
+
+`create_document`, `open_document`, `save_document`, `close_document`, `list_open_documents`, `get_document_info`, `get_document_session_state`, `finalize_document`, `recover_from_autosave`, `revert_to_disk`, `reload_from_disk`, `check_disk_drift`, `checkpoint`
+
+### Document Properties / Theme / Web Settings
+
+`get_document_properties`, `set_document_properties`, `get_theme`, `set_theme`, `update_theme_color`, `update_theme_fonts`, `get_web_settings`, `update_web_settings`, `set_language`
+
+### Content (text + paragraphs)
+
+`get_text`, `get_document_text`, `get_paragraphs`, `get_paragraph_runs`, `get_text_with_formatting`, `insert_paragraph`, `update_paragraph`, `delete_paragraph`, `replace_text`, `replace_text_batch`, `search_text`, `search_text_batch`, `search_text_with_formatting`, `search_by_formatting`, `list_all_formatted_text`
+
+### Formatting
+
+`format_text` (with `as_revision` flag, v3.12.0+), `set_paragraph_format` (with `as_revision` flag), `set_character_spacing`, `set_text_effect`, `set_text_direction`, `set_paragraph_border`, `set_paragraph_shading`
+
+### Styles (v3.10.0+)
+
+`list_styles`, `apply_style`, `create_style`, `update_style`, `delete_style`
+
+### Numbering / Lists (v3.10.0+)
+
+`insert_bullet_list`, `insert_numbered_list`, `set_list_level`, `set_outline_level`
+
+### Sections / Page Setup (v3.10.0+)
+
+`get_section_properties`, `insert_section_break`, `insert_continuous_section_break`, `insert_column_break`, `insert_page_break`, `set_columns`, `set_page_size`, `set_page_margins`, `set_page_orientation`, `set_page_borders`, `set_page_break_before`, `set_keep_lines`, `set_keep_with_next`, `set_widow_orphan`, `set_line_numbers`, `get_word_count_by_section`
+
+### Tables (v3.11.0+)
+
+`insert_table`, `get_tables`, `update_cell`, `add_row_to_table`, `delete_row_from_table`, `add_column_to_table`, `delete_column_from_table`, `merge_cells`, `set_cell_width`, `set_cell_vertical_alignment`, `set_row_height`, `set_header_row`, `set_table_alignment`, `set_table_style`, `delete_table`
+
+### Hyperlinks (v3.11.0+)
+
+`insert_hyperlink`, `update_hyperlink`, `delete_hyperlink`, `list_hyperlinks`, `insert_internal_link`, `insert_cross_reference`
+
+### Headers & Footers (v3.11.0+, even/odd + section map)
+
+`add_header`, `update_header`, `get_header`, `delete_header`, `list_headers`, `add_footer`, `update_footer`, `get_footer`, `delete_footer`, `list_footers`, `insert_page_number`
+
+### Comments
+
+`insert_comment`, `update_comment`, `delete_comment`, `list_comments`, `list_comment_threads`, `get_comment_thread`, `reply_to_comment`, `resolve_comment`, `sync_extended_comments`, `add_person`, `update_person`, `delete_person`, `list_people`
+
+### Track Changes / Revisions (v3.12.0 write side)
+
+`enable_track_changes`, `disable_track_changes`, `get_revisions`, `accept_revision`, `reject_revision`, `accept_all_revisions`, `reject_all_revisions`, `insert_text_as_revision`, `delete_text_as_revision`, `move_text_as_revision`, `export_revision_summary_markdown`
+
+### Content Controls / SDT (v3.9.0+)
+
+`insert_content_control`, `list_content_controls`, `get_content_control`, `update_content_control_text`, `replace_content_control_content`, `delete_content_control`, `insert_repeating_section`, `update_repeating_section_item`, `list_repeating_section_items`, `insert_checkbox`, `insert_dropdown`, `insert_text_field`, `list_custom_xml_parts`
+
+### Images
+
+`insert_image`, `insert_image_from_path`, `insert_floating_image`, `update_image`, `delete_image`, `list_images`, `set_image_style`, `export_image`, `export_all_images`, `insert_drop_cap`
+
+### Footnotes / Endnotes / Equations / Captions
+
+`insert_footnote`, `update_footnote`, `delete_footnote`, `get_footnote`, `list_footnotes`, `insert_endnote`, `update_endnote`, `delete_endnote`, `get_endnote`, `list_endnotes`, `insert_equation`, `update_equation`, `delete_equation`, `get_equation`, `list_equations`, `insert_caption`, `update_caption`, `delete_caption`, `get_caption`, `list_captions`
+
+### Bookmarks / Indexes / TOC / Watermarks
+
+`insert_bookmark`, `delete_bookmark`, `list_bookmarks`, `insert_index`, `insert_index_entry`, `insert_toc`, `insert_table_of_figures`, `insert_watermark`, `insert_image_watermark`, `remove_watermark`, `get_watermark`, `list_watermarks`
+
+### Fields
+
+`insert_date_field`, `insert_page_field`, `insert_sequence_field`, `insert_calculation_field`, `insert_if_field`, `insert_merge_field`, `update_all_fields`
+
+### Layout / Decoration
+
+`insert_horizontal_line`, `insert_symbol`, `insert_tab_stop`, `clear_tab_stops`
+
+### Document Protection
+
+`protect_document`, `unprotect_document`, `set_document_password`, `remove_document_password`, `restrict_editing_region`
+
+### Compare / Export
+
+`compare_documents`, `compare_documents_markdown`, `export_text`, `export_markdown`
+
+## Tips
+
+1. **Track Changes is enforced by default.** `create_document` and `open_document` auto-enable track changes via `enforceTrackChangesIfNeeded`. Pass `track_changes: false` to `open_document` if you need to bypass enforcement (e.g., authoring tooling that controls revisions itself).
+2. **Always save after modifications.** In-memory until `save_document`.
+3. **Use `finalize_document` to save+close in one step** when done.
+4. **Use styles for consistency** — `apply_style` over manual formatting.
+5. **Check structure first** — `get_document_info` / `get_paragraphs` before editing.
+6. **Export for AI processing** — `export_markdown` for easier text analysis.
+7. **Direct Mode for read-only inspection** — pass `source_path`, skip the open/close lifecycle.
+
+## Examples
+
+### Contract Redline (Track Changes write side, v3.12.0)
+
+```text
+1. open_document("/contracts/draft.docx")
+2. enable_track_changes(doc_id, author: "Reviewer A")
+3. insert_text_as_revision(doc_id, paragraph_index: 5, position: 32,
+                           text: " (subject to escalation)")
+4. delete_text_as_revision(doc_id, paragraph_index: 7, start: 23, end: 31)
+5. format_text(doc_id, paragraph_index: 9, bold: true, as_revision: true)
+6. save_document(doc_id, path: "/contracts/draft-redlined.docx")
+
+→ Word opens the file with proper <w:ins>/<w:del>/<w:rPrChange> markup,
+  attributed to "Reviewer A", reviewable in the Review pane.
+```
+
+### Multi-author Review
+
+```text
+1. enable_track_changes(doc_id, author: "Author A")
+2. insert_text_as_revision(...)             # → "Author A"
+
+3. disable_track_changes(doc_id)
+4. enable_track_changes(doc_id, author: "Author B")
+5. insert_text_as_revision(..., author: "Author C")  # explicit override
+6. insert_text_as_revision(...)              # falls back to "Author B"
+```
+
+### Fillable Form with Content Controls
+
+```text
+1. create_document(doc_id: "form")
+2. insert_paragraph(doc_id, text: "Application Form", style: "Heading1")
+3. insert_paragraph(doc_id, text: "Name: ")
+4. insert_content_control(doc_id, paragraph_index: 1, control_type: "plainText",
+                          tag: "applicant_name", placeholder: "Enter name...")
+5. insert_paragraph(doc_id, text: "Date: ")
+6. insert_content_control(doc_id, paragraph_index: 2, control_type: "date",
+                          tag: "submission_date")
+7. save_document(doc_id, path: "/forms/application.docx")
+```
+
+### Extract & Analyze
+
+```text
+1. open_document("/thesis.docx")
+2. get_paragraphs(doc_id) + list_comments(doc_id) + get_revisions(doc_id)
+3. export_markdown(doc_id) → analyze
+4. close_document(doc_id)
+```
diff --git a/plugins/che-xcode-mcp/.claude-plugin/plugin.json b/plugins/che-xcode-mcp/.claude-plugin/plugin.json
index 8e16cfca..ba77435a 100644
--- a/plugins/che-xcode-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-xcode-mcp/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "che-xcode-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "App Store Connect MCP Server — 103 tools across 16 domain managers covering the full ASC API + Xcode Organizer crash logs",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
diff --git a/plugins/che-xcode-mcp/CHANGELOG.md b/plugins/che-xcode-mcp/CHANGELOG.md
new file mode 100644
index 00000000..ed4220c0
--- /dev/null
+++ b/plugins/che-xcode-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.1] - (date unknown — please fill in)
+
+### Changed
+- App Store Connect MCP Server — 103 tools across 16 domain managers covering the full ASC API + Xcode Organizer crash logs
diff --git a/plugins/che-xcode-mcp/bin/che-xcode-mcp-wrapper.sh b/plugins/che-xcode-mcp/bin/che-xcode-mcp-wrapper.sh
index 7e67b43f..7277e38a 100755
--- a/plugins/che-xcode-mcp/bin/che-xcode-mcp-wrapper.sh
+++ b/plugins/che-xcode-mcp/bin/che-xcode-mcp-wrapper.sh
@@ -1,9 +1,21 @@
 #!/bin/bash
-# Auto-download wrapper for CheXcodeMCP
+# Version-aware auto-download wrapper for CheXcodeMCP.
 # Also loads ASC credentials from ~/.appstoreconnect/config
-REPO="kiki830621/che-xcode-mcp"
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheXcodeMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-xcode-mcp"
 BINARY_NAME="CheXcodeMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
 
 # --- Load credentials ---
 CONFIG="$HOME/.appstoreconnect/config"
@@ -12,14 +24,14 @@ if [[ -f "$CONFIG" ]]; then
         [[ "$key" =~ ^#.*$ || -z "$key" ]] && continue
         value="${value#\"}" && value="${value%\"}"
         case "$key" in
-            ASC_KEY_ID)           [[ -z "$ASC_KEY_ID" ]]           && export ASC_KEY_ID="$value" ;;
-            ASC_ISSUER_ID)        [[ -z "$ASC_ISSUER_ID" ]]        && export ASC_ISSUER_ID="$value" ;;
-            ASC_PRIVATE_KEY_PATH) [[ -z "$ASC_PRIVATE_KEY_PATH" ]]  && export ASC_PRIVATE_KEY_PATH="$value" ;;
+            ASC_KEY_ID)           [[ -z "${ASC_KEY_ID:-}" ]]           && export ASC_KEY_ID="$value" ;;
+            ASC_ISSUER_ID)        [[ -z "${ASC_ISSUER_ID:-}" ]]        && export ASC_ISSUER_ID="$value" ;;
+            ASC_PRIVATE_KEY_PATH) [[ -z "${ASC_PRIVATE_KEY_PATH:-}" ]]  && export ASC_PRIVATE_KEY_PATH="$value" ;;
         esac
     done < "$CONFIG"
 fi
 
-if [[ -z "$ASC_KEY_ID" || -z "$ASC_ISSUER_ID" || -z "$ASC_PRIVATE_KEY_PATH" ]]; then
+if [[ -z "${ASC_KEY_ID:-}" || -z "${ASC_ISSUER_ID:-}" || -z "${ASC_PRIVATE_KEY_PATH:-}" ]]; then
     echo "ERROR: ASC credentials not configured!" >&2
     echo "" >&2
     echo "Create ~/.appstoreconnect/config with:" >&2
@@ -34,27 +46,75 @@ fi
 ASC_PRIVATE_KEY_PATH="${ASC_PRIVATE_KEY_PATH/#\~/$HOME}"
 export ASC_PRIVATE_KEY_PATH
 
-# --- Find binary ---
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# --- Version-aware binary management ---
+
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
+
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
+
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
 
-# --- Auto-download if not found ---
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
     if [[ -z "$URL" ]]; then
-        echo "ERROR: No download URL found. Install manually: https://github.com/$REPO/releases" >&2
-        exit 1
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
+    else
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
-    curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-        || { echo "ERROR: Download failed." >&2; exit 1; }
-    BINARY="$INSTALL_DIR/$BINARY_NAME"
-    echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
 fi
 
 exec "$BINARY" "$@"
diff --git a/plugins/che-zotero-mcp/.claude-plugin/plugin.json b/plugins/che-zotero-mcp/.claude-plugin/plugin.json
index ffaf292e..ba2e143f 100644
--- a/plugins/che-zotero-mcp/.claude-plugin/plugin.json
+++ b/plugins/che-zotero-mcp/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "che-zotero-mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Zotero reference manager + academic search + knowledge graph MCP Server",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
diff --git a/plugins/che-zotero-mcp/CHANGELOG.md b/plugins/che-zotero-mcp/CHANGELOG.md
new file mode 100644
index 00000000..d2714155
--- /dev/null
+++ b/plugins/che-zotero-mcp/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.2] - (date unknown — please fill in)
+
+### Changed
+- Zotero reference manager + academic search + knowledge graph MCP Server
diff --git a/plugins/che-zotero-mcp/bin/che-zotero-mcp-wrapper.sh b/plugins/che-zotero-mcp/bin/che-zotero-mcp-wrapper.sh
index 364f861b..564f967a 100755
--- a/plugins/che-zotero-mcp/bin/che-zotero-mcp-wrapper.sh
+++ b/plugins/che-zotero-mcp/bin/che-zotero-mcp-wrapper.sh
@@ -1,31 +1,89 @@
 #!/bin/bash
-# Auto-download wrapper for CheZoteroMCP
-# Reads ZOTERO_API_KEY from macOS Keychain
-REPO="kiki830621/che-zotero-mcp"
+# Version-aware auto-download wrapper for CheZoteroMCP.
+# Reads ZOTERO_API_KEY from macOS Keychain.
+#
+# Design:
+# - Reads desired version from plugin.json (plugin's intended binary version)
+# - Compares against ~/bin/.CheZoteroMCP.version sidecar
+# - Re-downloads when plugin has been updated but binary is stale
+# - Atomic file swap (.tmp + mv) so partial downloads never break things
+# - Falls back to releases/latest if plugin.json unreadable or pinned tag missing
+
+set -u
+
+REPO="PsychQuant/che-zotero-mcp"
 BINARY_NAME="CheZoteroMCP"
 INSTALL_DIR="$HOME/bin"
+BINARY="$INSTALL_DIR/$BINARY_NAME"
+VERSION_FILE="$INSTALL_DIR/.${BINARY_NAME}.version"
 KEYCHAIN_ACCOUNT="che-zotero-mcp"
 
-# Find binary
-BINARY=""
-for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" "$HOME/.local/bin/$BINARY_NAME"; do
-    [[ -x "$loc" ]] && BINARY="$loc" && break
-done
+# Locate plugin root via wrapper's own path (more reliable than $CLAUDE_PLUGIN_ROOT
+# which isn't guaranteed in MCP spawn env). Wrapper lives at PLUGIN_ROOT/bin/*.sh.
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PLUGIN_JSON="$PLUGIN_ROOT/.claude-plugin/plugin.json"
+
+# Read desired version from plugin.json (empty string on any failure → fallback to "latest").
+DESIRED_VERSION=""
+if [[ -f "$PLUGIN_JSON" ]]; then
+    DESIRED_VERSION=$(grep -oE '"version":[[:space:]]*"[^"]+"' "$PLUGIN_JSON" 2>/dev/null \
+        | head -1 | cut -d'"' -f4 || true)
+fi
+
+# Read currently installed version from sidecar (empty string if file missing/unreadable).
+INSTALLED_VERSION=""
+[[ -f "$VERSION_FILE" ]] && INSTALLED_VERSION=$(tr -d '[:space:]' < "$VERSION_FILE" 2>/dev/null || true)
 
-if [[ -z "$BINARY" ]]; then
-    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+# Decide whether to download.
+NEED_DOWNLOAD=false
+REASON=""
+if [[ ! -x "$BINARY" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="binary not installed"
+elif [[ -n "$DESIRED_VERSION" ]] && [[ "$INSTALLED_VERSION" != "$DESIRED_VERSION" ]]; then
+    NEED_DOWNLOAD=true
+    REASON="plugin wants v${DESIRED_VERSION}, installed is v${INSTALLED_VERSION:-unknown}"
+fi
+
+if $NEED_DOWNLOAD; then
+    echo "$BINARY_NAME: $REASON — downloading from $REPO..." >&2
     mkdir -p "$INSTALL_DIR"
-    URL=$(curl -sL "https://api.github.com/repos/$REPO/releases/latest" \
-        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
-        | sed 's/.*"\(https[^"]*\)".*/\1/')
-    if [[ -n "$URL" ]]; then
-        curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
-            || { echo "ERROR: Download failed." >&2; exit 1; }
-        BINARY="$INSTALL_DIR/$BINARY_NAME"
-        echo "Installed $BINARY_NAME to $INSTALL_DIR/" >&2
+
+    # Try pinned tag first, then fall back to latest release.
+    URL=""
+    for API_URL in \
+        "${DESIRED_VERSION:+https://api.github.com/repos/$REPO/releases/tags/v$DESIRED_VERSION}" \
+        "https://api.github.com/repos/$REPO/releases/latest"
+    do
+        [[ -z "$API_URL" ]] && continue
+        URL=$(curl -sL --max-time 30 "$API_URL" 2>/dev/null \
+            | grep '"browser_download_url"' | grep "/$BINARY_NAME\"" | head -1 \
+            | sed 's/.*"\(https[^"]*\)".*/\1/')
+        [[ -n "$URL" ]] && break
+    done
+
+    if [[ -z "$URL" ]]; then
+        if [[ -x "$BINARY" ]]; then
+            echo "$BINARY_NAME: WARNING — no download URL found, keeping existing binary" >&2
+        else
+            echo "$BINARY_NAME: ERROR — no download URL found at $REPO. Install manually: https://github.com/$REPO/releases" >&2
+            exit 1
+        fi
     else
-        echo "No release found. Build from source: https://github.com/$REPO" >&2
-        exit 1
+        if curl -sL --max-time 300 "$URL" -o "${BINARY}.tmp" 2>/dev/null; then
+            chmod +x "${BINARY}.tmp"
+            mv "${BINARY}.tmp" "$BINARY"
+            echo "${DESIRED_VERSION:-unknown}" > "$VERSION_FILE"
+            echo "$BINARY_NAME: installed v${DESIRED_VERSION:-latest}" >&2
+        else
+            rm -f "${BINARY}.tmp" 2>/dev/null
+            if [[ -x "$BINARY" ]]; then
+                echo "$BINARY_NAME: WARNING — download failed, keeping existing binary" >&2
+            else
+                echo "$BINARY_NAME: ERROR — download failed" >&2
+                exit 1
+            fi
+        fi
     fi
 fi
 
diff --git a/plugins/claude-config-guide/.claude-plugin/plugin.json b/plugins/claude-config-guide/.claude-plugin/plugin.json
deleted file mode 100644
index f3046ad1..00000000
--- a/plugins/claude-config-guide/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "name": "claude-config-guide",
-  "version": "1.0.0",
-  "description": "Auto-triggered Skill that forces Claude to WebFetch official docs before answering Claude Code configuration questions",
-  "author": { "name": "Che Cheng" },
-  "license": "MIT",
-  "keywords": ["claude-code", "config", "settings", "mcp", "documentation"]
-}
diff --git a/plugins/claude-config-guide/.mcp.json b/plugins/claude-config-guide/.mcp.json
deleted file mode 100644
index 2c63c085..00000000
--- a/plugins/claude-config-guide/.mcp.json
+++ /dev/null
@@ -1,2 +0,0 @@
-{
-}
diff --git a/plugins/claude-config-guide/README.md b/plugins/claude-config-guide/README.md
deleted file mode 100644
index dbe8ea24..00000000
--- a/plugins/claude-config-guide/README.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# claude-config-guide
-
-Auto-triggered Skill that forces Claude to WebFetch official documentation before answering Claude Code configuration questions.
-
-## Problem
-
-Claude often provides **incorrect file paths** when asked about Claude Code configuration because it relies on memory instead of current documentation.
-
-Example:
-- ❌ Wrong: `~/.claude/settings.json`
-- ✅ Correct: `~/.claude.json` (user scope MCP config)
-
-## Solution
-
-This Skill:
-1. **Auto-triggers** when conversation mentions Claude Code config, MCP, settings, hooks, etc.
-2. **Forces Claude to WebFetch** official documentation instead of answering from memory
-3. **No sub-agent delegation** - main Claude reads docs directly to avoid information loss
-
-## Why Skill instead of Agent?
-
-| Aspect | Agent | Skill |
-|--------|-------|-------|
-| Triggering | Must be explicitly called | **Auto-triggered** by keywords |
-| Information flow | Delegated → summarized → returned | **Direct injection** |
-| Accuracy | May lose details in transfer | **No information loss** |
-
-## Documentation Sources
-
-| Source | URL |
-|--------|-----|
-| Claude Code CLI | https://code.claude.com/docs/en/ |
-| Claude API/SDK | https://platform.claude.com/llms.txt |
-
-## Installation
-
-```bash
-# Add marketplace
-/plugin marketplace add PsychQuant/psychquant-claude-plugins
-
-# Install this plugin
-/plugin install claude-config-guide@PsychQuant/psychquant-claude-plugins
-```
-
-## Related
-
-- GitHub Issue: https://github.com/anthropics/claude-code/issues/18332
-
-## License
-
-MIT
diff --git a/plugins/claude-config-guide/skills/claude-config-guide/SKILL.md b/plugins/claude-config-guide/skills/claude-config-guide/SKILL.md
deleted file mode 100644
index 9b1fb0a1..00000000
--- a/plugins/claude-config-guide/skills/claude-config-guide/SKILL.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-name: claude-config-guide
-description: |
-  Query Claude Code configuration, file locations, MCP settings, and official documentation.
-  Use this skill proactively when the conversation involves:
-  - Claude Code settings, configuration, config, settings
-  - MCP server setup, mcp.json, mcpServers
-  - ~/.claude.json, .mcp.json, settings.json locations
-  - hooks, slash commands, skills configuration
-  - Claude Code features, API, SDK questions
-allowed-tools: WebFetch, Read, Glob, Grep
----
-
-# Claude Config Guide
-
-This Skill queries correct Claude Code configuration information.
-
-## When to Use
-
-When the user asks about or the conversation involves:
-- Claude Code config file locations
-- MCP server configuration
-- Hooks setup
-- Skills/Commands creation
-- Claude Code features
-
-## Execution Steps (IMPORTANT!)
-
-**You MUST WebFetch official documentation - never answer from memory!**
-
-### Step 1: Documentation Sources
-
-**Two primary documentation sources:**
-
-| Source | URL | Purpose |
-|--------|-----|---------|
-| Claude Code CLI docs | https://code.claude.com/docs/en/claude_code_docs_map.md | CLI config, MCP, hooks, skills |
-| Claude API/SDK docs | https://platform.claude.com/llms.txt | API reference, Agent SDK, platform features |
-
-### Step 2: WebFetch the corresponding doc based on question type
-
-**Claude Code CLI documentation:**
-
-| Question Type | Documentation URL |
-|---------------|-------------------|
-| MCP config | https://code.claude.com/docs/en/mcp.md |
-| Settings | https://code.claude.com/docs/en/settings.md |
-| Hooks | https://code.claude.com/docs/en/hooks.md |
-| Skills | https://code.claude.com/docs/en/skills.md |
-| Commands | https://code.claude.com/docs/en/slash-commands.md |
-| IAM/Permissions | https://code.claude.com/docs/en/iam.md |
-
-**Claude API/SDK documentation:**
-
-| Question Type | Documentation URL |
-|---------------|-------------------|
-| Agent SDK | https://platform.claude.com/docs/en/agent-sdk/overview.md |
-| Claude API | https://platform.claude.com/llms.txt (index) |
-| MCP connector (API) | https://platform.claude.com/docs/en/agents-and-tools/mcp-connector.md |
-
-### Step 3: Parse and respond
-
-Extract relevant information from WebFetch results and answer the user directly.
-
-## Important Reminder
-
-**Never answer Claude Code configuration questions from memory!**
-
-### Common Mistakes
-
-| Wrong | Correct |
-|-------|---------|
-| `~/.claude/settings.json` | `~/.claude.json` (user scope MCP config) |
-| | `.mcp.json` (project scope MCP config) |
-
-### Config File Precedence
-
-1. Managed (system-wide)
-2. Command line arguments
-3. Local project settings `.claude/settings.local.json`
-4. Shared project settings `.claude/settings.json`, `.mcp.json`
-5. User global settings `~/.claude.json`, `~/.claude/settings.json`
-
-## Why not use a sub-agent?
-
-Sub-agent responses require paraphrasing, which may cause information loss.
-**Fetch the docs yourself for more direct and accurate information.**
diff --git a/plugins/claude-switch/CHANGELOG.md b/plugins/claude-switch/CHANGELOG.md
new file mode 100644
index 00000000..c571679a
--- /dev/null
+++ b/plugins/claude-switch/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.0] - (date unknown — please fill in)
+
+### Changed
+- Claude Code 多帳號管理：switch（切換帳號）、list（列出帳號）、current（目前帳號）、setup（設定新帳號）
diff --git a/plugins/cli-tools/.claude-plugin/plugin.json b/plugins/cli-tools/.claude-plugin/plugin.json
new file mode 100644
index 00000000..df70b5fa
--- /dev/null
+++ b/plugins/cli-tools/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "cli-tools",
+  "description": "CLI tool lifecycle management — build, deploy, install, upgrade Swift CLI tools via GitHub Releases",
+  "version": "1.1.2",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/cli-tools/CHANGELOG.md b/plugins/cli-tools/CHANGELOG.md
new file mode 100644
index 00000000..1c409ae0
--- /dev/null
+++ b/plugins/cli-tools/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.1.1] - (date unknown — please fill in)
+
+### Changed
+- CLI tool lifecycle management — build, deploy, install, upgrade Swift CLI tools via GitHub Releases
diff --git a/plugins/cli-tools/CLAUDE.md b/plugins/cli-tools/CLAUDE.md
new file mode 100644
index 00000000..64761130
--- /dev/null
+++ b/plugins/cli-tools/CLAUDE.md
@@ -0,0 +1,27 @@
+# cli-tools Plugin
+
+Swift CLI tool lifecycle management — build, deploy, install, upgrade via GitHub Releases.
+
+Counterpart to `mcp-tools` (for MCP servers), this plugin handles CLI tools.
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/cli-tools:cli-deploy` | Build universal binary + GitHub Release + install to ~/bin/ |
+| `/cli-tools:cli-new-app` | Scaffold new Swift CLI project (Package.swift + ArgumentParser) |
+| `/cli-tools:cli-install` | Install CLI tool from GitHub Release to ~/bin/ |
+| `/cli-tools:cli-upgrade` | Check for updates and upgrade installed CLI tools |
+
+## Workflow
+
+```
+cli-new-app → develop → cli-deploy → cli-install (other users)
+                                    → cli-upgrade (existing users)
+```
+
+## Known CLI Tools
+
+| Binary | Repo | Description |
+|--------|------|-------------|
+| gfh | PsychQuant/GiftHub | Git LFS backend with Google Drive |
diff --git a/plugins/cli-tools/rules/tool-readme-sync.md b/plugins/cli-tools/rules/tool-readme-sync.md
new file mode 100644
index 00000000..601bd91a
--- /dev/null
+++ b/plugins/cli-tools/rules/tool-readme-sync.md
@@ -0,0 +1,177 @@
+# CLI Command Surface ↔ README 同步紀律
+
+當 CLI 工具的 subcommand / flag / 參數語義變動時，**必須**在同一個 commit（或同一個 release 週期內）更新 README。
+
+## 為什麼
+
+CLI 的 README 通常包含三種資訊，都容易過時：
+
+| 區塊 | 容易過時原因 |
+|------|------------|
+| Usage / Subcommand 列表 | 新增子命令、或把舊命令 deprecate 了 |
+| Flag / 參數說明 | flag 改名、預設值翻轉、required → optional |
+| 範例命令（複製貼上用的） | 語法變動後範例直接失效 |
+
+使用者習慣複製範例當入門。範例失效 → 使用者第一次跑就報錯 → 信心損失。
+
+## 觸發條件
+
+1. **新增子命令** — 新的 `mytool xxx` 出現
+2. **移除 / deprecate 子命令** — BREAKING，CHANGELOG 也要寫
+3. **重命名子命令** — 舊名別名是否保留？README 要說清楚
+4. **新增 / 移除 flag** — 每個 flag 都是 public contract
+5. **Flag 預設值翻轉** — 例如 `--format` 從 `json` 翻成 `text`（隱性 BREAKING）
+6. **位置參數順序 / 數量改變** — 影響所有 shell 呼叫
+7. **外部依賴改變** — 如需要 `playwright` CLI、`ffmpeg` 等
+
+純實作重構（internal function 改名、效能優化但 flag 不變）不需改 README。
+
+## 必要的 README 改動範圍
+
+| 改動 | README 連動 |
+|------|------------|
+| 加 subcommand | Usage 表格 + Examples section |
+| 改 flag | Flag 說明表 + 所有用到該 flag 的範例 |
+| 預設值翻轉 | 在「Migration / Breaking Changes」註記，避免使用者踩坑 |
+| 新增依賴（playwright 等） | Prerequisites / Installation 區塊 |
+| 新增輸出格式（`--to pdf`） | Format matrix 或「Supported Formats」表 |
+
+## 範例 Walk-through（參考 macdoc）
+
+macdoc CLI 有 `convert --to <fmt>` 這個 single entry point，對應一張 16-row format matrix。每新增一條轉換路由：
+
+```swift
+// MacDoc+Convert.swift 的 switch
+case ("tex", .docx): try convertTexToDocx(inputURL)   // ← 新加的
+```
+
+同一個 PR 必須：
+
+1. 更新 `convert-entry-point.md` 規則的 16 → 17 條路由列表
+2. 更新 README 的 Format matrix 加上 `tex → docx` 那行
+3. 更新 `textutil-compat.md` 的對照表（如果新 format 有 textutil 對應）
+4. CHANGELOG 加 entry
+
+**檢查方式**：grep README 中的 format 清單對照 `switch` 實作，應該一一對應。
+
+## Deploy 前的自我檢查
+
+`cli-deploy` skill 跑完**前**做這個檢查：
+
+```bash
+# 抓 CLI 實際支援的 subcommand 清單
+ACTUAL=$(./mytool --help 2>&1 | grep -oE '^  [a-z-]+' | sort -u)
+
+# 抓 README 裡文件化的 subcommand
+DOCUMENTED=$(grep -oE 'mytool [a-z-]+' README.md | awk '{print $2}' | sort -u)
+
+# diff
+diff <(echo "$ACTUAL") <(echo "$DOCUMENTED") || echo "⚠️ README 與 --help 不一致"
+```
+
+Flag 層級：
+
+```bash
+./mytool subcmd --help 2>&1 | grep -oE '^  --[a-z-]+' | while read flag; do
+  grep -q "\`$flag\`" README.md || echo "⚠️ Flag $flag 未在 README 出現"
+done
+```
+
+## 當 README 已累積落差時的補救
+
+1. **跑 `--help` 做 ground truth dump**，逐一 diff README
+2. 檢查 Examples section 的每一條命令，實際執行看看是否還能跑
+3. 若 repo 有 E2E test，檢查 test 裡的指令與 README 是否一致（通常 test 才是最新）
+4. 雙語 README 記得同步
+
+## GitHub Repo About Metadata（和 README 同等級的使用者第一印象）
+
+README 是 repo 內部文件；**GitHub repo 首頁右側的 About 面板** 是外部的「名片」。Search engine、Topics 瀏覽頁、marketplace 聚合器都讀這塊，不讀 README。
+
+CLI surface 變動時，這三項也要檢查：
+
+| 欄位 | 位置 | CLI 特有的同步時機 |
+|------|------|-----------------|
+| **Description**（~350 字短介紹）| `gh repo view --json description` | 新增 subcommand、新增主要 flag、新增支援格式 / 平台 |
+| **Topics**（最多 20 個標籤）| `gh repo view --json repositoryTopics` | 加了新功能領域（例如原本 PDF 轉檔 → 加了 OCR 能力） |
+| **Homepage URL** | `gh repo view --json homepageUrl` | 通常指 `releases` 頁；改過 binary 發布位置時才動 |
+
+### Description 的三層結構模板
+
+```
+[What] {CLI tool for X} —
+[Differentiator] {native Swift, no Python/Node, single binary} —
+[Features] {Subcmd A, Subcmd B, Subcmd C} —
+[Use case] {Optimized for Y workflow}
+```
+
+範例（假設 macdoc CLI）：
+
+> macOS-native document conversion CLI — Swift-only, no Pandoc. 16 conversion routes (Word, HTML, Markdown, PDF, TeX, SRT, BibLaTeX). Textutil-compatible syntax, streaming converters, OCR pipeline with MLX + Ollama backends. Optimized for academic and thesis document workflows.
+
+### 建議 Topics 數量
+
+- **目標：15-20 個**（GitHub 上限 20）
+- 少於 5 個 = search visibility 等於零
+- `null` / 空陣列 = 完全沒出現在 `topic:xxx` 搜尋頁
+
+### 必備 Topic 類別（CLI 特化）
+
+| 類別 | Topic 範例 |
+|------|----------|
+| 語言 | `swift`, `rust`, `go` |
+| 類型 | `cli`, `command-line`, `command-line-tool`, `terminal` |
+| 平台 | `macos`, `linux`, `cross-platform`, `native` |
+| 發布 | `single-binary`, `homebrew`, `github-releases` |
+| 功能域 | 依 CLI 主要處理對象命名（`pdf`, `markdown`, `ocr`, `video`…） |
+| 用途 | `automation`, `developer-tools`, `productivity` |
+| 生態相容 | `textutil`, `pandoc-alternative`, `jq-like` 等（方便比較搜尋） |
+
+### `gh repo edit` 參考指令
+
+```bash
+# 一次更新 description + homepage
+gh repo edit {OWNER}/{REPO} \
+  --description "..." \
+  --homepage "https://github.com/{OWNER}/{REPO}/releases"
+
+# 加 topics
+gh repo edit {OWNER}/{REPO} \
+  --add-topic cli \
+  --add-topic command-line-tool \
+  --add-topic swift \
+  --add-topic macos
+
+# 查核目前狀態
+gh repo view {OWNER}/{REPO} --json description,homepageUrl,repositoryTopics
+```
+
+### Deploy 前的審計
+
+```bash
+# description 是否反映目前主要能力
+CURRENT_DESC=$(gh repo view --json description -q .description)
+MAJOR_SUBCMDS=$(./$BINARY --help | awk '/SUBCOMMANDS/{f=1;next} f&&/^  [a-z]/{print $1}' | head -5 | xargs)
+for s in $MAJOR_SUBCMDS; do
+    echo "$CURRENT_DESC" | grep -qi "$s" || echo "⚠️ Description 未提到主要 subcommand: $s"
+done
+
+# topics 數量
+TOPIC_COUNT=$(gh repo view --json repositoryTopics -q '.repositoryTopics | length')
+[ "$TOPIC_COUNT" -ge 5 ] || echo "⚠️ Topics 只有 $TOPIC_COUNT 個（建議 15-20）"
+```
+
+## 例外
+
+- 純 bug fix（flag / subcommand / 預設值都沒動）→ CHANGELOG 即可，README / Description / Topics 皆不用
+- 未上架 release 的 development build → 都可以延後；但 tag 前必須齊
+
+## 和其他 skill 的關係
+
+- `cli-deploy` Step 2.6 檢查 README/--help 一致性，不一致時 **BLOCK** 發布
+- `cli-upgrade` 建議加新 flag 時，會提醒「README `Flags` 表格要加 1 行」
+- `cli-new-app` scaffold 直接產出含 Usage + Examples + Flags 三區塊的 README 骨架
+
+## TL;DR
+
+**改了 `--help` 輸出，就改 README；`--help` 和 README 不一致就不要發 release。**
diff --git a/plugins/cli-tools/skills/cli-deploy/SKILL.md b/plugins/cli-tools/skills/cli-deploy/SKILL.md
new file mode 100644
index 00000000..eb34d087
--- /dev/null
+++ b/plugins/cli-tools/skills/cli-deploy/SKILL.md
@@ -0,0 +1,351 @@
+---
+name: cli-deploy
+description: 部署 Swift CLI 工具（編譯 universal binary、建立 GitHub Release、安裝到 ~/bin）。在 Swift CLI 專案目錄中使用。
+argument-hint: [version]
+allowed-tools: Read, Write, Edit, Bash(swift:*), Bash(lipo:*), Bash(file:*), Bash(shasum:*), Bash(git:*), Bash(gh:*), Bash(rm:*), Bash(cp:*), Bash(mkdir:*), Bash(ls:*), Bash(chmod:*), Bash(codesign:*), Bash(xattr:*), Grep, Glob, AskUserQuestion
+disable-model-invocation: true
+---
+
+# CLI Deploy — 部署 Swift CLI 工具
+
+完整的 CLI 工具部署流程：版本更新 → 編譯 universal binary → GitHub Release。
+
+**重要**：必須先 bump version 再 build，否則 binary 內嵌的版本號會是舊的。
+
+## 參數
+
+- `$1` = 版本號（可選，如 `1.0.0`）
+
+---
+
+## Phase 0: 檢測專案
+
+### Step 1: 確認 Swift CLI 專案
+
+```bash
+pwd
+ls Package.swift
+```
+
+**必須存在**：`Package.swift` 且包含 `executableTarget`
+
+### Step 2: 取得 Binary 名稱
+
+**重要**：Binary 名稱由 `products:` 區塊的 `.executable(name: ...)` 決定，**不是** `targets:` 區塊的 `executableTarget.name`。兩者可以不同（例如 `.executable(name: "gfh", targets: ["gfs"])` — binary 是 `gfh`，target 資料夾是 `gfs`）。抓錯的話後面 `lipo` / `curl` 會找不到檔案。
+
+```bash
+# 優先從 products 區塊抓 .executable(name: "X")
+BINARY_NAME=$(grep -E '\.executable\(name:' Package.swift | head -1 | sed 's/.*name: *"\([^"]*\)".*/\1/')
+
+# Fallback：只有當沒有 products 區塊時才用 executableTarget 名稱
+if [ -z "$BINARY_NAME" ]; then
+    BINARY_NAME=$(grep -A2 'executableTarget' Package.swift | grep 'name:' | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+fi
+
+echo "Binary: $BINARY_NAME"
+```
+
+若 `BINARY_NAME` 為空，**停下來**請使用者確認 — 繼續往下做會寫壞路徑。
+
+### Step 3: 取得當前版本
+
+搜尋版本號來源（依優先順序）：
+
+1. `Sources/*/Version.swift` — 找 `static let current = "x.x.x"` 或類似
+2. 最新 git tag：`git describe --tags --abbrev=0 2>/dev/null`
+3. 如果都沒有，預設 `0.1.0`
+
+### Step 4: 確認新版本號
+
+如果提供了 `$1`，使用該版本。否則用 AskUserQuestion 詢問，預設 patch bump。
+
+---
+
+## Phase 1: 更新版本與文檔（先於 build！）
+
+### Step 1: 更新版本號
+
+找到版本號所在的檔案並更新：
+
+- `Sources/*/Version.swift` — 更新版本字串
+- 其他可能的位置由 Step 0.3 決定
+
+### Step 2: 更新 CHANGELOG.md
+
+**先檢查是否已有 `[Unreleased]` 區塊**：
+
+- **若有** `[Unreleased]` 區塊 → 把標題改成 `[{version}] - {date}`（promote 既有內容，避免重複）：
+  ```
+  ## [Unreleased]        →   ## [{version}] - {date}
+  ```
+- **若無** `[Unreleased]` 區塊 → 在 CHANGELOG.md 頂部新增：
+  ```markdown
+  ## [{version}] - {date}
+
+  ### Added
+  - ...
+
+  ### Changed
+  - ...
+
+  ### Fixed
+  - ...
+  ```
+
+在沒有 `[Unreleased]` 的情況下，用 AskUserQuestion 詢問變更摘要。
+
+### Step 3: 更新 README.md（如適用）
+
+如果 README.md 有 Version History 區塊，加入新版本。
+
+**CLI 特化檢查項目**（逐一核對；任何有改動的都必須連動 README）：
+
+| 改動 | README 需要同步的位置 |
+|------|--------------------|
+| 新增 / 移除 subcommand | Usage 表格、Examples section |
+| 改 flag / 預設值翻轉 | Flag 說明表、所有範例命令 |
+| 位置參數順序變 | 所有範例命令 |
+| 新增外部依賴（如 playwright） | Prerequisites / Installation |
+| 新增輸出格式 / format matrix 變動 | Format matrix / Supported Formats 表 |
+
+### Step 3.5: CLI surface ↔ README 一致性檢查（🔴 BLOCKING）
+
+規則見 `rules/tool-readme-sync.md`。
+
+```bash
+# 先 build，能跑 --help 再檢查
+swift build -c release 2>/dev/null || cargo build --release 2>/dev/null || true
+
+# 1. 抓實際 subcommand 集合
+ACTUAL=$(./.build/release/$BINARY_NAME --help 2>&1 | awk '/SUBCOMMANDS|Subcommands|COMMANDS/{flag=1;next} /^$/{flag=0} flag && /^  [a-z]/{print $1}' | sort -u)
+
+# 2. 抓 README 文件化的 subcommand（基於 $BINARY_NAME xxx 這種 pattern）
+DOCUMENTED=$(grep -oE "$BINARY_NAME [a-z-]+" README.md | awk '{print $2}' | sort -u)
+
+# 3. diff
+diff <(echo "$ACTUAL") <(echo "$DOCUMENTED") && echo "✅ README subcommand 對齊" || echo "⚠️ README 與 --help 不一致"
+```
+
+**BLOCKING**：不一致就停止 deploy，要求先更新 README（或使用者明確覆蓋）。
+
+### Step 3.6: GitHub repo About metadata audit（WARN，不 BLOCK）
+
+規則見 `rules/tool-readme-sync.md` 的 GitHub Repo About Metadata 章節。
+
+```bash
+gh auth status >/dev/null 2>&1 || { echo "⚠️ gh 未登入，跳過"; exit 0; }
+
+REPO_SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)
+[ -z "$REPO_SLUG" ] && { echo "⚠️ 非 GitHub repo 或無權限"; exit 0; }
+
+# 1. Description 長度
+DESC=$(gh repo view --json description -q .description)
+DESC_LEN=${#DESC}
+echo "Description ($DESC_LEN chars): $DESC"
+[ "$DESC_LEN" -lt 50 ] && echo "⚠️ Description 太短（<50 chars）"
+
+# 2. Description 是否提及主要 subcommand
+MAJOR_SUBCMDS=$(./.build/release/$BINARY_NAME --help 2>&1 | awk '/SUBCOMMANDS|Subcommands|COMMANDS/{f=1;next} /^$/{f=0} f && /^  [a-z]/{print $1}' | head -3)
+for s in $MAJOR_SUBCMDS; do
+    echo "$DESC" | grep -qi "$s" || echo "💡 Description 未提到主要 subcommand: $s"
+done
+
+# 3. Topics
+TOPIC_COUNT=$(gh repo view --json repositoryTopics -q '.repositoryTopics | length')
+echo "Topics: $TOPIC_COUNT 個"
+[ "$TOPIC_COUNT" -lt 5 ] && echo "⚠️ Topics 太少（$TOPIC_COUNT < 5）"
+[ "$TOPIC_COUNT" -lt 15 ] && echo "💡 建議 15-20 個 topics（CLI 必備：cli, command-line-tool, swift/rust/go, macos/linux）"
+
+# 4. Homepage
+HOMEPAGE=$(gh repo view --json homepageUrl -q .homepageUrl)
+[ -z "$HOMEPAGE" ] && echo "💡 建議設 Homepage = https://github.com/$REPO_SLUG/releases"
+```
+
+發現問題時用 AskUserQuestion 問要不要順手 `gh repo edit`。
+
+---
+
+## Phase 2: 編譯 Universal Binary
+
+### Step 1: 清理舊 build
+
+```bash
+rm -rf .build 2>/dev/null || true
+```
+
+### Step 2: 編譯兩種架構
+
+```bash
+swift build -c release --arch arm64
+swift build -c release --arch x86_64
+```
+
+### Step 3: 建立 Universal Binary
+
+```bash
+mkdir -p .release
+lipo -create \
+    .build/arm64-apple-macosx/release/$BINARY_NAME \
+    .build/x86_64-apple-macosx/release/$BINARY_NAME \
+    -output .release/$BINARY_NAME
+
+# 清除 xattr 汙染（Dropbox 目錄 build 的 binary 帶 com.dropbox.attrs）
+xattr -cr .release/$BINARY_NAME
+
+# 重新簽名（lipo 破壞原始 code signature）
+#
+# 注意：這是 ad-hoc 簽名（`-` = 無 identity），**僅 macOS ≤ 25 dev path**。
+# macOS 26 上 ad-hoc binary 無法觸發 TCC dialog；對外分發需走 Developer ID + notarization。
+#
+# **若 CLI 走 macOS 26 production path**：
+#   1. 確認專案已裝簽章 pipeline（`scripts/sign-and-notarize.sh` 存在?）
+#   2. 沒裝 → 提示使用者跑 `/mcp-tools:mcp-sign-pipeline`（CLI 同樣適用）
+#   3. 已裝 + `DEVELOPER_ID` 已 export → 改呼叫 `./scripts/sign-and-notarize.sh .release/$BINARY_NAME`
+#
+# 偵測邏輯建議：
+#   if [ -f "scripts/sign-and-notarize.sh" ] && [ -n "$DEVELOPER_ID" ]; then
+#       ./scripts/sign-and-notarize.sh .release/$BINARY_NAME
+#   else
+#       codesign --force --sign - .release/$BINARY_NAME  # ad-hoc fallback
+#       echo "⚠ ad-hoc signed; macOS 26 users may see Gatekeeper warning"
+#       echo "  Install signing pipeline: /mcp-tools:mcp-sign-pipeline"
+#   fi
+codesign --force --sign - .release/$BINARY_NAME
+```
+
+### Step 4: 驗證 binary + 內嵌版本
+
+```bash
+file .release/$BINARY_NAME
+lipo -info .release/$BINARY_NAME
+.release/$BINARY_NAME version 2>/dev/null || .release/$BINARY_NAME --version 2>/dev/null
+```
+
+**預期**：
+- `Mach-O universal binary with 2 architectures: [x86_64] [arm64]`
+- 版本號顯示 `{version}`（如果顯示舊版本，表示 Phase 1 的 version bump 沒生效，**停下來檢查**）
+
+---
+
+## Phase 3: 發布到 GitHub
+
+### Step 1: Commit + Push
+
+**只 stage 本次 deploy 實際動過的檔案** — `git add -A` 會把使用者 working tree 裡無關的 modified files（例如 session-start hook 改的 `.claude/*`、`CLAUDE.md`）全部塞進 release commit，污染歷史。
+
+```bash
+# 只 stage Phase 1 改過的檔案
+git add Sources/*/Version.swift CHANGELOG.md
+[ -f README.md ] && git diff --cached --quiet README.md 2>/dev/null || git add README.md 2>/dev/null || true
+
+# 檢查 staging 內容，確認沒混進無關檔案
+git diff --cached --stat
+
+git commit -m "v{version}: {change-summary}"
+git push origin main
+```
+
+如果 `git diff --cached --stat` 顯示了非預期的檔案，停下來檢查 — 可能是 working tree 本來就髒。
+
+### Step 2: 建立 GitHub Release
+
+```bash
+OWNER_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+
+# 建立 Release
+RELEASE_ID=$(gh api repos/$OWNER_REPO/releases --method POST \
+  -f tag_name="v{version}" \
+  -f target_commitish="main" \
+  -f name="v{version}" \
+  -f body="{release-notes}" \
+  -F draft=false \
+  -F prerelease=false \
+  --jq '.id')
+
+echo "Release created: ID=$RELEASE_ID"
+
+# 上傳 Binary（用 curl，支援進度條）
+TOKEN=$(gh auth token)
+curl -L -X POST \
+  -H "Accept: application/vnd.github+json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/octet-stream" \
+  "https://uploads.github.com/repos/$OWNER_REPO/releases/$RELEASE_ID/assets?name=$BINARY_NAME" \
+  --data-binary "@.release/$BINARY_NAME" \
+  --progress-bar -o /dev/null -w "Upload: HTTP %{http_code}, %{size_upload} bytes\n"
+
+# 驗證
+gh release view v{version} --json assets --jq '.assets[] | "\(.name) (\(.size) bytes)"'
+```
+
+Release Notes 模板：
+
+```markdown
+## Install
+
+\```bash
+curl -fsSL https://github.com/{owner}/{repo}/releases/latest/download/{binary} -o ~/bin/{binary} && chmod +x ~/bin/{binary}
+\```
+
+---
+
+{CHANGELOG 內容}
+```
+
+### Step 3: 安裝到本地
+
+```bash
+cp .release/$BINARY_NAME ~/bin/$BINARY_NAME
+chmod +x ~/bin/$BINARY_NAME
+```
+
+驗證：
+
+```bash
+~/bin/$BINARY_NAME version 2>/dev/null || ~/bin/$BINARY_NAME --version 2>/dev/null
+```
+
+### Step 4: 清理
+
+```bash
+rm -rf .release
+```
+
+---
+
+## Phase 4: 完成報告
+
+```markdown
+# CLI Deploy 完成
+
+- **專案**: {project-name}
+- **版本**: v{version}
+- **Binary**: {binary-name} (universal: arm64 + x86_64)
+- **Release**: https://github.com/{owner}/{repo}/releases/tag/v{version}
+- **本地**: ~/bin/{binary-name}
+
+安裝指令（其他使用者）：
+curl -fsSL https://github.com/{owner}/{repo}/releases/latest/download/{binary} -o ~/bin/{binary} && chmod +x ~/bin/{binary}
+```
+
+---
+
+## 快速參考
+
+### 版本號建議
+
+| 變更類型 | 版本變更 | 範例 |
+|---------|---------|------|
+| 新功能 | MINOR +1 | 1.0.0 → 1.1.0 |
+| Bug 修復 | PATCH +1 | 1.0.0 → 1.0.1 |
+| 破壞性變更 | MAJOR +1 | 1.0.0 → 2.0.0 |
+
+### 常見問題
+
+| 問題 | 解決方案 |
+|------|----------|
+| Dropbox 衝突導致 build 失敗 | `rm -rf .build` 後重新編譯 |
+| lipo 失敗 | 確認兩種架構都編譯成功 |
+| gh release create 卡住 | 用 `gh api` + `curl` 分步驟上傳 |
+| codesign 失敗 | `codesign --force --sign -` 用 ad-hoc 簽名 |
+| binary 版本號是舊的 | 確認 Phase 1 已更新 Version.swift 再 build（不能先 build 再 bump） |
diff --git a/plugins/cli-tools/skills/cli-install/SKILL.md b/plugins/cli-tools/skills/cli-install/SKILL.md
new file mode 100644
index 00000000..92b479c8
--- /dev/null
+++ b/plugins/cli-tools/skills/cli-install/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: cli-install
+description: 從 GitHub Release 安裝 CLI 工具到 ~/bin/（下載 binary、設定權限、驗證）
+argument-hint: <owner/repo> [version]
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# CLI Install — 從 GitHub Release 安裝
+
+從 GitHub Release 下載 CLI binary 並安裝到 `~/bin/`。
+
+## 參數
+
+- `$1` = GitHub repo（如 `PsychQuant/GiftHub`）
+- `$2` = 版本號（可選，預設 `latest`）
+
+---
+
+## Phase 0: 解析參數
+
+如果沒有提供 repo，用 AskUserQuestion 詢問。
+
+```bash
+REPO="{owner/repo}"
+VERSION="${2:-latest}"
+```
+
+---
+
+## Phase 1: 取得 Release 資訊
+
+### Latest 版本
+
+```bash
+RELEASE_INFO=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest")
+TAG=$(echo "$RELEASE_INFO" | grep '"tag_name"' | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+')
+```
+
+### 指定版本
+
+```bash
+RELEASE_INFO=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/tags/v$VERSION")
+```
+
+### 列出 Assets
+
+```bash
+echo "$RELEASE_INFO" | grep '"name"' | head -10
+```
+
+找到 binary asset（排除 `.mcpb`、`.zip`、`.tar.gz`）。
+如果有多個 binary，用 AskUserQuestion 讓使用者選。
+
+---
+
+## Phase 2: 下載與安裝
+
+```bash
+BINARY_NAME="{detected-binary-name}"
+DOWNLOAD_URL=$(echo "$RELEASE_INFO" | grep "browser_download_url.*$BINARY_NAME" | grep -oE 'https://[^"]+')
+
+mkdir -p ~/bin
+curl -fsSL "$DOWNLOAD_URL" -o ~/bin/$BINARY_NAME
+chmod +x ~/bin/$BINARY_NAME
+
+# macOS: 清除 quarantine flag
+xattr -cr ~/bin/$BINARY_NAME 2>/dev/null || true
+```
+
+---
+
+## Phase 3: 驗證
+
+```bash
+file ~/bin/$BINARY_NAME
+~/bin/$BINARY_NAME version 2>/dev/null || ~/bin/$BINARY_NAME --version 2>/dev/null
+```
+
+---
+
+## 完成報告
+
+```
+已安裝 {binary-name} {version} 到 ~/bin/
+來源: https://github.com/{owner}/{repo}/releases/tag/{tag}
+```
diff --git a/plugins/cli-tools/skills/cli-new-app/SKILL.md b/plugins/cli-tools/skills/cli-new-app/SKILL.md
new file mode 100644
index 00000000..d5d39eb7
--- /dev/null
+++ b/plugins/cli-tools/skills/cli-new-app/SKILL.md
@@ -0,0 +1,167 @@
+---
+name: cli-new-app
+description: 建立新的 Swift CLI 專案骨架（Package.swift + ArgumentParser + Version.swift + .gitignore）
+argument-hint: <project-name>
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+---
+
+# CLI New App — 建立 Swift CLI 專案
+
+Scaffold 一個新的 Swift CLI 專案，包含完整的開發結構。
+
+## 參數
+
+- `$1` = 專案名稱（kebab-case，如 `my-tool`）
+
+---
+
+## Phase 0: 收集資訊
+
+如果沒有提供專案名稱，用 AskUserQuestion 詢問：
+
+1. **專案名稱**（kebab-case）
+2. **Binary 名稱**（預設同專案名稱）
+3. **描述**（一句話）
+4. **GitHub repo**（預設 `PsychQuant/{project-name}`）
+
+---
+
+## Phase 1: 建立專案結構
+
+```bash
+mkdir -p {project-name}
+cd {project-name}
+```
+
+### Step 1: Package.swift
+
+```swift
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "{ProjectName}",
+    platforms: [
+        .macOS(.v14),
+    ],
+    products: [
+        .executable(name: "{binary-name}", targets: ["{target-name}"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "{target-name}",
+            dependencies: [
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            ]
+        ),
+    ]
+)
+```
+
+### Step 2: Main entry point
+
+`Sources/{target-name}/{ProjectName}.swift`:
+
+```swift
+import ArgumentParser
+
+@main
+struct {ProjectName}: AsyncParsableCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "{binary-name}",
+        abstract: "{description}",
+        subcommands: [Version.self]
+    )
+}
+```
+
+### Step 3: Version.swift
+
+`Sources/{target-name}/Version.swift`:
+
+```swift
+import ArgumentParser
+
+struct Version: ParsableCommand {
+    static let configuration = CommandConfiguration(
+        abstract: "Print version"
+    )
+
+    static let current = "0.1.0"
+
+    func run() {
+        print("{binary-name} \(Version.current)")
+    }
+}
+```
+
+### Step 4: .gitignore
+
+```
+.build/
+.release/
+.swiftpm/
+*.xcodeproj/
+```
+
+### Step 5: README.md
+
+基本的 README，包含安裝指令和使用說明。
+
+---
+
+## Phase 2: 初始化 Git
+
+```bash
+git init
+git add -A
+git commit -m "init: {binary-name} — {description}"
+```
+
+### 建立 GitHub Repo（可選）
+
+用 AskUserQuestion 詢問是否建立 GitHub repo：
+
+```bash
+gh repo create {owner}/{project-name} --public --source=. --push
+```
+
+---
+
+## Phase 3: 驗證
+
+```bash
+swift build
+.build/debug/{binary-name} version
+```
+
+---
+
+## 完成報告
+
+```
+專案 {project-name} 已建立！
+
+結構：
+  {project-name}/
+  ├── Package.swift
+  ├── Sources/{target-name}/
+  │   ├── {ProjectName}.swift
+  │   └── Version.swift
+  ├── .gitignore
+  └── README.md
+
+下一步：
+1. 加入你的 subcommands
+2. `swift build` 測試
+3. （macOS 26 + 公開分發）裝簽章 pipeline：`/mcp-tools:mcp-sign-pipeline`
+   - macOS 26 對 ad-hoc binary 收緊；若要對外分發給其他 macOS 26 使用者，必須走 Developer ID + hardened runtime + notarization
+   - 純自用 / dev-only CLI 不需要（ad-hoc 仍能跑，只會 Gatekeeper warning）
+   - 此 skill 在 mcp-tools plugin 內但對 Swift CLI 同樣適用
+4. `/cli-tools:cli-deploy` 發布
+   - 若已裝 sign-pipeline，可跑 `make release-signed` 產出 signed binary
+```
diff --git a/plugins/cli-tools/skills/cli-upgrade/SKILL.md b/plugins/cli-tools/skills/cli-upgrade/SKILL.md
new file mode 100644
index 00000000..9f657e05
--- /dev/null
+++ b/plugins/cli-tools/skills/cli-upgrade/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: cli-upgrade
+description: 檢查已安裝的 CLI 工具是否有新版本，如有則從 GitHub Release 升級
+argument-hint: [binary-name]
+allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion
+---
+
+# CLI Upgrade — 升級已安裝的 CLI 工具
+
+檢查 `~/bin/` 中的 CLI 工具是否有 GitHub Release 新版本，並升級。
+
+## 參數
+
+- `$1` = Binary 名稱（可選，不指定則掃描全部已知的 CLI）
+
+---
+
+## Phase 0: 識別已安裝的 CLI 工具
+
+### 已知的 CLI 工具對照表
+
+自動偵測：掃描 `~/bin/` 中的 binary，嘗試執行 `{binary} version` 取得版本號，並對應到 GitHub repo。
+
+| Binary | GitHub Repo | 偵測方式 |
+|--------|-------------|---------|
+| gfh | PsychQuant/GiftHub | `gfh version` |
+
+**動態偵測**：對 `~/bin/` 中每個可執行檔：
+
+1. 嘗試 `{binary} version 2>/dev/null` 或 `{binary} --version 2>/dev/null`
+2. 如果有版本輸出，用 `gh api` 搜尋對應的 repo（by binary name）
+
+如果指定了 `$1`，只檢查那一個。
+
+---
+
+## Phase 1: 檢查更新
+
+對每個已知的 CLI 工具：
+
+```bash
+LOCAL_VERSION=$($BINARY version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+LATEST_VERSION=$(curl -fsSL --max-time 5 "https://api.github.com/repos/$REPO/releases/latest" | grep '"tag_name"' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+```
+
+### 比較版本
+
+- 相同 → `✓ {binary} v{version} — up to date`
+- 不同 → `⬆️ {binary} v{local} → v{latest} available`
+- 無法取得 → `? {binary} — cannot check (no repo mapping)`
+
+---
+
+## Phase 2: 升級
+
+如果有更新可用，用 AskUserQuestion 確認：
+
+> 以下工具有新版本：
+> - gfh v0.1.0 → v0.2.0
+>
+> 要全部升級嗎？
+
+確認後：
+
+```bash
+DOWNLOAD_URL=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" \
+  | grep "browser_download_url.*$BINARY_NAME" | grep -oE 'https://[^"]+')
+
+# 備份舊版
+cp ~/bin/$BINARY_NAME ~/bin/$BINARY_NAME.bak
+
+# 下載新版
+curl -fsSL "$DOWNLOAD_URL" -o ~/bin/$BINARY_NAME
+chmod +x ~/bin/$BINARY_NAME
+xattr -cr ~/bin/$BINARY_NAME 2>/dev/null || true
+
+# 驗證
+NEW_VERSION=$(~/bin/$BINARY_NAME version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+echo "✓ $BINARY_NAME upgraded to v$NEW_VERSION"
+
+# 清理備份
+rm ~/bin/$BINARY_NAME.bak
+```
+
+---
+
+## Phase 3: 報告
+
+```
+# CLI Upgrade Report
+
+| Binary | Before | After | Status |
+|--------|--------|-------|--------|
+| gfh    | v0.1.0 | v0.2.0 | ✓ upgraded |
+| other  | v1.0.0 | v1.0.0 | — up to date |
+```
diff --git a/plugins/codex-batch/.claude-plugin/plugin.json b/plugins/codex-batch/.claude-plugin/plugin.json
index 23c8362d..8f21b37d 100644
--- a/plugins/codex-batch/.claude-plugin/plugin.json
+++ b/plugins/codex-batch/.claude-plugin/plugin.json
@@ -1,8 +1,8 @@
 {
   "name": "codex-batch",
   "version": "1.0.0",
-  "description": "Batch content generation using Codex CLI (GPT-5.4) — generate shell scripts for parallel codex exec jobs with large reference documents as context",
+  "description": "Batch content generation using Codex CLI (GPT-5.5) — generate shell scripts for parallel codex exec jobs with large reference documents as context",
   "author": { "name": "Che Cheng" },
   "license": "MIT",
-  "keywords": ["codex", "gpt-5.4", "batch", "parallel", "latex", "solutions", "generation"]
+  "keywords": ["codex", "gpt-5.5", "batch", "parallel", "latex", "solutions", "generation"]
 }
diff --git a/plugins/codex-batch/CHANGELOG.md b/plugins/codex-batch/CHANGELOG.md
new file mode 100644
index 00000000..90865c4f
--- /dev/null
+++ b/plugins/codex-batch/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.0] - (date unknown — please fill in)
+
+### Changed
+- Batch content generation using Codex CLI (GPT-5.5) — generate shell scripts for parallel codex exec jobs with large reference documents as context
diff --git a/plugins/codex-batch/commands/codex-batch.md b/plugins/codex-batch/commands/codex-batch.md
index 526e6c09..b5bb52a7 100644
--- a/plugins/codex-batch/commands/codex-batch.md
+++ b/plugins/codex-batch/commands/codex-batch.md
@@ -1,7 +1,7 @@
 ---
 description: |
   Generate and run batch Codex CLI jobs — split a large reference document into chunks,
-  parallel-execute codex exec (GPT-5.4 xhigh) with structured prompts, monitor progress.
+  parallel-execute codex exec (GPT-5.5 xhigh) with structured prompts, monitor progress.
   Use when: "batch generate", "codex batch", "parallel codex", "generate solutions/summaries/translations for each chapter"
 argument-hint: "[task description]"
 allowed-tools: Bash, Read, Write, Glob, Grep, Agent(general-purpose)
@@ -27,7 +27,7 @@ Ask the user for these parameters (skip any they've already provided in the argu
 4. **Output directory** — where to save results
 
 ### Optional (with defaults)
-5. **Model** — default: `gpt-5.4`
+5. **Model** — default: `gpt-5.5`
 6. **Reasoning effort** — default: `xhigh`
 7. **Output filename pattern** — default: `ch${ch}_output.tex`
 8. **Parallel execution** — default: `true` (all chunks at once)
@@ -135,5 +135,5 @@ output: ch${ch}_summary.tex
 | Network stream disconnection | Delete empty output, `FORCE=1 ./generate.sh <ch>` |
 | Output has `\documentclass` preamble | `sed -i '' '/^\\documentclass/,/^\\begin{document}/d; /^\\end{document}/d'` |
 | Undefined commands from stripped preamble | Find `\newcommand` in deleted preamble, replace usages |
-| codex hangs | Check `~/.codex/config.toml`, try with explicit `-m gpt-5.4` |
+| codex hangs | Check `~/.codex/config.toml`, try with explicit `-m gpt-5.5` |
 | Rate limiting | Reduce parallel count or add delay between launches |
diff --git a/plugins/codex-batch/references/script-template.sh b/plugins/codex-batch/references/script-template.sh
index b8160642..474c0d7b 100644
--- a/plugins/codex-batch/references/script-template.sh
+++ b/plugins/codex-batch/references/script-template.sh
@@ -18,7 +18,7 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REF_FILE="__REF_FILE__"                    # Path to reference document
 OUTPUT_DIR="$SCRIPT_DIR"
 LOG_FILE="$SCRIPT_DIR/progress.log"
-MODEL="__MODEL__"                          # e.g., gpt-5.4
+MODEL="__MODEL__"                          # e.g., gpt-5.5
 REASONING="__REASONING__"                  # e.g., xhigh
 OUTPUT_PATTERN="__OUTPUT_PATTERN__"        # e.g., ch${ch}_solutions.tex
 
diff --git a/plugins/doc-tools/.claude-plugin/plugin.json b/plugins/doc-tools/.claude-plugin/plugin.json
new file mode 100644
index 00000000..e7e7eea4
--- /dev/null
+++ b/plugins/doc-tools/.claude-plugin/plugin.json
@@ -0,0 +1,20 @@
+{
+  "name": "doc-tools",
+  "version": "0.2.0",
+  "description": "v0.2.0: Renamed from changelog-tools to doc-tools — scope expanded from CHANGELOG-only to general documentation lifecycle (CHANGELOG.md / README.md / CLAUDE.md / changelog/ all in scope). NEW Stop hook (doc-update-guard.sh) absorbs the user-level changelog-update.sh hook from che-claude-config: blocks turn-end when HEAD commit changed ≥3 code files but updated none of CHANGELOG.md / README.md / CLAUDE.md / changelog/ — original design rationale preserved (per-commit not per-day because compact-aware; Stop+block intentional because doc updates are clearly actionable; 3-file threshold heuristic for 'significant change'; code-extension allowlist for user's primary languages R/sh/sql/py/ts/swift/go/rs/etc; stop_hook_active=true bypass for infinite-loop protection). Three-tier config injection (precedence high→low): <repo>/.claude/doc-tools.json (per-project) → ~/.cache/doc-tools/config.json (per-machine) → built-in defaults; plus ~/.cache/doc-tools/disabled flag for one-touch kill switch. Config schema: {enabled, min_changed_files, code_extensions[], doc_files[], skip_paths[]}. NEW references/doc-update-design.md captures full rationale including implicit decisions never previously documented (3-file threshold, code-extension list source, 4-doc-files acceptance set, Stop+block trade-off vs PostToolUse warn-only). Old user-level hook in ~/.claude/hooks/changelog-update.sh kept on disk as fallback but unregistered from settings.json to prevent double-fire. v0.1.1: Validator + normalize improvements after PsychQuant marketplace dogfood. Validator's 'description must start with vX.Y.Z:' rule relaxed to 'description must mention vX.Y.Z in first 400 chars' (PsychQuant convention leads with product tagline, not version prefix — 30 false-positive drifts disappear). Version header parser now accepts placeholder dates like '(date unknown — please fill in)' so init-output entries are still parsed; ISO-format check happens separately and reports placeholder as a violation user can fill in later. Normalize mode extended: now also remaps common non-KAC section names (### Changes → ### Changed, ### Migration → ### Changed, ### Bug Fixes → ### Fixed, etc.) and injects KAC preamble if missing. v0.1.0: Original changelog-tools — KAC 1.1.0 enforcement + 3-way sync (CHANGELOG.md / plugin.json / marketplace.json descriptions) + 35-plugin marketplace migration. Skills: changelog-validate (CI exit codes 0/1/2/3/4), changelog-init (bootstrap from plugin.json description with git-pickaxe date resolution), changelog-migrate (batch init across marketplace). Phase 2 (separate release): changelog-add + changelog-release + hooks into plugin-deploy / mcp-deploy / cli-deploy freshness check.",
+  "author": {
+    "name": "Che Cheng"
+  },
+  "license": "MIT",
+  "keywords": [
+    "documentation",
+    "changelog",
+    "keep-a-changelog",
+    "release-notes",
+    "semver",
+    "marketplace",
+    "plugin",
+    "hook",
+    "doc-guardian"
+  ]
+}
diff --git a/plugins/doc-tools/CHANGELOG.md b/plugins/doc-tools/CHANGELOG.md
new file mode 100644
index 00000000..33cd1fde
--- /dev/null
+++ b/plugins/doc-tools/CHANGELOG.md
@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-02
+
+### Changed
+- **Renamed plugin from `changelog-tools` to `doc-tools`** — scope expanded from CHANGELOG-only to general documentation lifecycle. Skill names keep `changelog-` prefix (no need to retrain muscle memory) but plugin invocation changes from `/changelog-tools:*` to `/doc-tools:*`. Migration: `claude plugin uninstall changelog-tools && claude plugin install doc-tools@psychquant-claude-plugins`.
+- Plugin description rewritten to reflect the three concerns (CHANGELOG hygiene + doc-update guardrail + bootstrap migration) instead of CHANGELOG-only positioning.
+
+### Added
+- **NEW Stop hook**: `hooks/doc-update-guard.sh` — absorbs the user-level `~/.claude/hooks/changelog-update.sh` from `che-claude-config`. Blocks turn-end when HEAD commit changed ≥3 code files but updated none of `CHANGELOG.md` / `README.md` / `CLAUDE.md` / `changelog/`. Auto-registered via `hooks/hooks.json` (no manual `~/.claude/settings.json` edit needed). Original design rationale preserved: per-commit (compact-aware), Stop+block (intentional because doc updates are clearly actionable), 3-file threshold (heuristic for significant change), code-extension allowlist (R/sh/sql/py/ts/swift/go/rs/etc — user's primary languages), `stop_hook_active=true` bypass (infinite-loop protection).
+- **NEW three-tier config injection** for the hook (precedence high → low):
+  1. `<repo>/.claude/doc-tools.json` — per-project override
+  2. `~/.cache/doc-tools/config.json` — per-machine override
+  3. Built-in defaults in `scripts/doc-update-config.sh`
+- **NEW kill-switch**: `~/.cache/doc-tools/disabled` flag file — touch to silence the hook entirely (mirrors `archive-first` plugin pattern).
+- **Config schema**: `{enabled, min_changed_files, code_extensions[], doc_files[], skip_paths[]}` — all fields optional, missing keys fall through to defaults. `code_extensions` and `doc_files` use full replace; `skip_paths` appends across layers.
+- **NEW `references/doc-update-design.md`** — full hook design rationale captured for the first time. Covers both originally-documented decisions (per-commit not per-day, Stop+block intentional) AND previously-implicit ones (3-file threshold reasoning, code-extension list source, 4-doc-files acceptance set, lenient pass criterion). Also includes a "Rejected alternatives" table mirroring the `pending-tasks-nudge.py` README convention.
+- `scripts/doc-update-config.sh` — shared config loader sourced by the hook. Uses `jq has()` (not `// empty` which silently swallows the literal `false` value).
+
+### Fixed
+- `_merge_config` JSON loading: switched from `jq -r '.field // empty'` to `jq -r 'if has("field") then .field else empty end'` — the `//` operator falls through on falsy values (`false`, `null`, `0`, `""`), making `{"enabled": false}` config get silently ignored. The `has()` form correctly distinguishes "field absent" from "field is false".
+- Hook BLOCK output: built reason string entirely inside `jq` filter using `\n` escapes instead of passing multi-line shell variable via `--arg`. Resulting JSON now has properly-escaped `\n` (RFC 8259 compliant) instead of literal control characters.
+- Hook git diff: added `--root` flag to `git diff-tree --no-commit-id --name-only -r HEAD` — without it, root commits (no parent) return empty file list, silently passing all checks even when files were committed.
+
+## [0.1.1] - 2026-05-02
+
+### Changed
+- `changelog-validate`: Relaxed the "description must start with `vX.Y.Z:`" check to "description must mention `vX.Y.Z` somewhere in first 400 chars" — PsychQuant convention leads descriptions with product tagline, not version prefix. Drift count drops from ~30 plugins to 0 with this change.
+- `changelog-validate`: Version header parser now accepts placeholder dates like `(date unknown — please fill in)` so init-output entries are still parsed; ISO-format check happens separately and reports placeholder as a violation user can fix later.
+- `changelog-init normalize`: Now also remaps common non-KAC section names (`### Changes` → `### Changed`, `### Migration` → `### Changed`, `### Bug Fixes` → `### Fixed`, etc.) and injects KAC preamble if missing. Three idempotent transforms in one pass: bracket headers + section remap + preamble.
+
+### Fixed
+- `issue-driven-dev` CHANGELOG.md hand-fixed two custom subsection names that don't auto-remap (`### 上下游責任分工` and `### Thesis` → `### Changed` with `<!-- (formerly: ...) -->` comment markers preserving original intent).
+
+## [0.1.0] - 2026-05-02
+
+### Added
+- `changelog-validate` skill — KAC 1.1.0 compliance check + 3-way sync drift detection between `CHANGELOG.md` latest entry, `plugin.json` description, and `marketplace.json` description. Exit codes 0/1/2/3/4 for CI.
+- `changelog-init` skill — bootstrap `CHANGELOG.md` for one plugin from `plugin.json` description. Two modes: `init` (parse `vX.Y.Z` segments → KAC entries) and `normalize` (rewrite non-KAC headers like em-dash format to KAC strict).
+- `changelog-migrate` skill — batch run `changelog-init` across an entire marketplace, producing a markdown migration report at `<marketplace>/.claude-plugin/migration-report-YYYY-MM-DD.md`.
+- `scripts/validate-changelog.py` — KAC parser + 3-way sync checker (Python 3, no external deps).
+- `scripts/init-changelog.py` — description segment parser with major-version filtering (excludes dep-version mid-text noise) and `git log -S` pickaxe date resolution.
+- `scripts/migrate-marketplace.py` — batch orchestrator that calls `init-changelog.py` per plugin and aggregates results into a markdown report.
+- KAC 1.1.0 spec enforcement: six allowed section types (Added / Changed / Deprecated / Removed / Fixed / Security); strict version header format `## [MAJOR.MINOR.PATCH] - YYYY-MM-DD`; preamble must reference Keep a Changelog.
+
+### Changed
+- PsychQuant marketplace migration: 33 plugins gained `CHANGELOG.md` files via `changelog-migrate` first run (only `issue-driven-dev` already had one). `che-word-mcp` extracted 15 historical version segments with all dates resolved via `git log` pickaxe; other plugins extracted 1 segment (current version) since their descriptions only describe the latest release.
diff --git a/plugins/doc-tools/CLAUDE.md b/plugins/doc-tools/CLAUDE.md
new file mode 100644
index 00000000..06b2f10b
--- /dev/null
+++ b/plugins/doc-tools/CLAUDE.md
@@ -0,0 +1,121 @@
+# doc-tools — CLAUDE.md
+
+## Purpose
+
+Documentation lifecycle toolkit for Claude Code plugin marketplaces. Three concerns under one roof:
+
+1. **CHANGELOG hygiene** — enforce [Keep a Changelog](https://keepachangelog.com) 1.1.0 format + three-way sync between `CHANGELOG.md` latest entry ↔ `plugin.json` description ↔ `marketplace.json` description.
+2. **Doc-update guardrail** — Stop hook that blocks turn-end when a commit changes ≥3 code files but updates none of `CHANGELOG.md` / `README.md` / `CLAUDE.md` / `changelog/`.
+3. **Bootstrap migration** — for marketplaces with many legacy plugins lacking `CHANGELOG.md`, batch-init from existing `plugin.json` description run-on prose.
+
+History: started as `changelog-tools` v0.1.x for CHANGELOG-only concerns. Renamed to `doc-tools` in v0.2.0 when the user-level `~/.claude/hooks/changelog-update.sh` got absorbed — its real intent (per the original prompt) was always "update **README/CLAUDE.md/CHANGELOG.md** on big changes," not just CHANGELOG.
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `changelog-validate` | KAC compliance + 3-way sync drift. Exit 0/1/2/3/4 for CI. |
+| `changelog-init` | Bootstrap `CHANGELOG.md` for one plugin from `plugin.json` description (init mode) or rewrite non-KAC headers (normalize mode with section remap + preamble injection). |
+| `changelog-migrate` | Batch run `changelog-init` across an entire marketplace; produces markdown migration report. |
+
+Skill names keep the `changelog-` prefix for clarity even though the plugin is now `doc-tools`. Future doc-related skills (e.g., `doc-validate` checking README/CLAUDE.md staleness) can use other prefixes.
+
+## Hook
+
+| File | Event | Behavior |
+|------|-------|----------|
+| `hooks/doc-update-guard.sh` | `Stop` | Block turn-end when HEAD commit has ≥3 code files but no doc updates. Auto-bypass via `stop_hook_active=true`. |
+
+Full design rationale: [`references/doc-update-design.md`](references/doc-update-design.md). Includes both originally-documented decisions (per-commit not per-day for compact-resilience; Stop+block trade-off vs warn-only) and previously-implicit ones (3-file threshold, code-extension allowlist, 4-doc-files acceptance set).
+
+## Three-Tier Hook Config Injection
+
+Precedence high → low:
+
+```
+1. <repo>/.claude/doc-tools.json    ← per-project (highest)
+2. ~/.cache/doc-tools/config.json   ← per-machine
+3. built-in defaults                ← in scripts/doc-update-config.sh
+```
+
+Plus kill-switch:
+
+```
+~/.cache/doc-tools/disabled         ← touch to silence the hook entirely
+```
+
+Schema (all fields optional, missing keys fall through):
+
+```json
+{
+  "enabled": true,
+  "min_changed_files": 3,
+  "code_extensions": ["py", "ts", "swift", ...],
+  "doc_files": ["CHANGELOG.md", "README.md", "CLAUDE.md", "changelog/"],
+  "skip_paths": ["~/Developer/scratch/**"]
+}
+```
+
+`code_extensions` and `doc_files` use **full replace** (provide complete list); `skip_paths` is **append across layers**.
+
+## Format Spec (KAC 1.1.0)
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.0] - 2026-05-02
+
+### Added
+- New thing
+
+### Fixed
+- Old bug
+```
+
+Six allowed section types: **Added / Changed / Deprecated / Removed / Fixed / Security**.
+
+Version header: `[MAJOR.MINOR.PATCH] - YYYY-MM-DD` (brackets, ISO date). Em-dash format `## 2.37.0 — 2026-05-02` is non-conformant; auto-fix via `changelog-init normalize`.
+
+## Three-Way Sync Rule
+
+`changelog-validate` enforces:
+
+- `plugin.json` `version` == `marketplace.json` plugin entry `version` == latest non-Unreleased entry version in `CHANGELOG.md`
+- `plugin.json` `description` mentions `v<version>` in first 400 chars (relaxed from "must start with" — PsychQuant style leads with product tagline)
+- `marketplace.json` plugin description mentions `v<version>` in first 400 chars
+
+Drift → exit code 3 + readable diff. `changelog-release` (Phase 2) auto-syncs all three.
+
+## Why a Plugin
+
+Could be loose scripts — but as a plugin:
+
+- Skills are discoverable via `/doc-tools:*`
+- Hook auto-registers via `hooks.json` (no manual `~/.claude/settings.json` edit)
+- `claude plugin marketplace update` distributes new validation rules
+- Three-tier config supports per-machine + per-project override without script edits
+- Other marketplace consumers benefit (not just PsychQuant)
+
+## Phase 2 (separate release)
+
+| Skill / Integration | Purpose |
+|---------------------|---------|
+| `changelog-add` | Interactive `[Unreleased]` entry creation. Calls Composio `changelog-generator` for commit parsing. |
+| `changelog-release` | Promote `[Unreleased]` → `vX.Y.Z` + DATE. Auto-bump semver. Sync 3 files. |
+| Hook into `plugin-deploy` / `mcp-deploy` / `cli-deploy` | Deploy-time CHANGELOG freshness check |
+| Absorb `~/.claude/hooks/claude-md-reminder.sh` | Same family as doc-update-guard; consolidate under doc-tools |
+
+## Related
+
+- [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
+- [olivierlacan/keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog)
+- [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
+- [`references/doc-update-design.md`](references/doc-update-design.md) — hook design rationale
+- [`ComposioHQ/awesome-claude-skills/changelog-generator`](https://github.com/ComposioHQ/awesome-claude-skills/tree/master/changelog-generator) — Phase 2 commit-parser integration target
diff --git a/plugins/issue-driven-dev/LICENSE b/plugins/doc-tools/LICENSE
similarity index 100%
rename from plugins/issue-driven-dev/LICENSE
rename to plugins/doc-tools/LICENSE
diff --git a/plugins/doc-tools/README.md b/plugins/doc-tools/README.md
new file mode 100644
index 00000000..790a4cb8
--- /dev/null
+++ b/plugins/doc-tools/README.md
@@ -0,0 +1,119 @@
+# doc-tools
+
+Documentation lifecycle toolkit for Claude Code plugin marketplaces.
+
+## What is this?
+
+Three concerns under one roof:
+
+1. **CHANGELOG hygiene** — enforce [Keep a Changelog](https://keepachangelog.com) 1.1.0 format + three-way sync (`CHANGELOG.md` ↔ `plugin.json` description ↔ `marketplace.json` description)
+2. **Doc-update guardrail** — Stop hook that blocks turn-end when a commit changes ≥3 code files but updates none of `CHANGELOG.md` / `README.md` / `CLAUDE.md` / `changelog/`
+3. **Bootstrap migration** — for marketplaces with many legacy plugins lacking `CHANGELOG.md`, batch-init from existing `plugin.json` description prose
+
+## Why?
+
+Audit of PsychQuant's marketplace surfaced a structural problem: **35 of 36 plugins had no `CHANGELOG.md`**. All release history lived in `plugin.json` `description` as a run-on string spanning 5+ versions, making history unreadable in the marketplace UI. Separately, a user-level Stop hook (`~/.claude/hooks/changelog-update.sh`) enforced "update doc when committing big changes" but only registered globally — every other plugin user had to recreate it.
+
+`doc-tools` consolidates both concerns: skills for CHANGELOG, hook for doc-update enforcement, three-tier config injection so behavior is tunable per-machine and per-project.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `/doc-tools:changelog-validate <plugin-path>` | Check KAC compliance + 3-way sync drift. Exit 0/1/2/3/4 for CI. |
+| `/doc-tools:changelog-init <plugin-path>` | Initialize `CHANGELOG.md` from `plugin.json` description (`init` mode) OR rewrite non-KAC headers to KAC strict (`normalize` mode). |
+| `/doc-tools:changelog-migrate <marketplace-path>` | Batch: run `changelog-init` across an entire marketplace. Migration report per plugin. |
+
+## Hook
+
+| File | Event | Behavior |
+|------|-------|----------|
+| `hooks/doc-update-guard.sh` | `Stop` | Block turn-end when HEAD commit changed ≥3 code files but no doc was updated |
+
+Auto-registered via `hooks/hooks.json` on plugin install — no manual `~/.claude/settings.json` edit needed.
+
+### Three-tier config injection
+
+```
+1. <repo>/.claude/doc-tools.json    ← per-project (highest priority)
+2. ~/.cache/doc-tools/config.json   ← per-machine
+3. built-in defaults                ← ships with the plugin
+```
+
+Plus kill-switch:
+
+```bash
+touch ~/.cache/doc-tools/disabled    # one-touch silence
+```
+
+Schema (all fields optional):
+
+```json
+{
+  "enabled": true,
+  "min_changed_files": 3,
+  "code_extensions": ["py", "ts", "swift"],
+  "doc_files": ["CHANGELOG.md", "README.md"],
+  "skip_paths": ["~/Developer/scratch/**", "/tmp/**"]
+}
+```
+
+Full design rationale: [`references/doc-update-design.md`](references/doc-update-design.md).
+
+## Format spec (strict KAC 1.1.0)
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.0] - 2026-05-02
+
+### Added
+- New thing
+
+### Fixed
+- Old bug
+```
+
+**Six allowed section types**: Added / Changed / Deprecated / Removed / Fixed / Security. Anything else fails `changelog-validate` with exit code 2.
+
+## Quick start
+
+```bash
+# Validate one plugin
+/doc-tools:changelog-validate plugins/issue-driven-dev
+
+# Initialize a CHANGELOG.md from existing plugin.json description
+/doc-tools:changelog-init init plugins/che-word-mcp
+
+# Normalize an existing non-KAC CHANGELOG.md (em-dash format → KAC bracket)
+/doc-tools:changelog-init normalize plugins/issue-driven-dev
+
+# Batch migrate every plugin in a marketplace
+/doc-tools:changelog-migrate /path/to/marketplace-repo
+
+# Disable the hook for this machine
+touch ~/.cache/doc-tools/disabled
+
+# Disable the hook for one repo only
+echo '{"enabled": false}' > .claude/doc-tools.json
+```
+
+## Coming in Phase 2
+
+| Skill / Integration | Purpose |
+|---------------------|---------|
+| `/doc-tools:changelog-add <plugin-path>` | Interactive `[Unreleased]` entry creation. Calls Composio's `changelog-generator` for git-commit parsing. |
+| `/doc-tools:changelog-release <plugin-path>` | Promote `[Unreleased]` → `vX.Y.Z` + DATE. Auto-bump semver from sections. Sync 3 files. |
+| Hooks into `plugin-deploy` / `mcp-deploy` / `cli-deploy` | Deploy-time CHANGELOG freshness check |
+| Absorb `~/.claude/hooks/claude-md-reminder.sh` | Same family as doc-update-guard; consolidate under doc-tools |
+
+## License
+
+MIT
diff --git a/plugins/doc-tools/hooks/doc-update-guard.sh b/plugins/doc-tools/hooks/doc-update-guard.sh
new file mode 100755
index 00000000..cec32cbf
--- /dev/null
+++ b/plugins/doc-tools/hooks/doc-update-guard.sh
@@ -0,0 +1,116 @@
+#!/bin/bash
+# Stop hook: 偵測最近一筆 commit 有重大程式碼變更但沒更新文件時 block
+#
+# Migrated from ~/.claude/hooks/changelog-update.sh (che-claude-config) into the
+# doc-tools plugin so any plugin user gets the same documentation-update guard.
+#
+# 判定方式：
+#   - 檢查 HEAD commit 修改的檔案
+#   - 預設 ≥3 個程式碼檔案被修改（可由 config 覆寫 min_changed_files）
+#   - 但該 commit 沒有更新任一文件（CHANGELOG.md / README.md / CLAUDE.md / changelog/）
+#
+# Why "per-commit" not "per-day":
+#   compact 後 Claude 會忘記先前改了什麼，每筆 commit 都應該獨立檢查。
+#
+# Why Stop event + decision:block:
+#   文件更新是明確可執行動作（不像 task 不確定要標哪個），block 強制 user/Claude
+#   處理；不會卡住流程。infinite-loop 由 stop_hook_active=true bypass 防護。
+#
+# Why ≥3 files threshold:
+#   Heuristic — 1-2 file hot-fix 通常不需要 doc 更新；3+ 已是 "significant
+#   change" 規模。可由 config min_changed_files 覆寫。
+#
+# Why these code extensions:
+#   User 主要工作的程式語言（R / sh / sql / py / ts / swift / go / rs / etc）。
+#   Markdown / JSON / YAML / TXT 不算「code change」（它們可能就是 doc 自己）。
+#
+# Three-tier config injection (high → low priority):
+#   1. <repo>/.claude/doc-tools.json     ← per-project override
+#   2. ~/.cache/doc-tools/config.json    ← per-machine override
+#   3. built-in defaults (this script)
+#
+# One-touch kill switch:
+#   touch ~/.cache/doc-tools/disabled    → hook 完全短路 exit 0
+#
+# 完整 design notes 見 ${CLAUDE_PLUGIN_ROOT}/references/doc-update-design.md
+
+set -u
+
+# Disabled flag — short-circuit before any work
+if [ -f "$HOME/.cache/doc-tools/disabled" ]; then
+  exit 0
+fi
+
+# Load config (sets CFG_ENABLED / CFG_MIN_CHANGED_FILES / CFG_CODE_EXTENSIONS_REGEX / CFG_DOC_FILES_REGEX / CFG_SKIP_PATHS)
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
+# shellcheck source=../scripts/doc-update-config.sh
+source "$PLUGIN_ROOT/scripts/doc-update-config.sh"
+
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+
+# Prevent infinite loop: if Claude is already responding to a hook block, let it through
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$PROJECT_DIR" || exit 0
+
+load_doc_tools_config "$PROJECT_DIR"
+
+# Disabled in config → exit 0
+if [ "$CFG_ENABLED" != "true" ]; then
+  exit 0
+fi
+
+# Skipped path → exit 0
+if is_skipped_path "$PROJECT_DIR"; then
+  exit 0
+fi
+
+# Non-git directory → exit 0
+if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+  exit 0
+fi
+
+# Files changed in HEAD commit (--root makes root commits return all their files instead of empty)
+CHANGED=$(git diff-tree --root --no-commit-id --name-only -r HEAD 2>/dev/null)
+if [ -z "$CHANGED" ]; then
+  exit 0
+fi
+
+# Count significant code changes
+SIG_COUNT=$(echo "$CHANGED" | grep -cE "$CFG_CODE_EXTENSIONS_REGEX" || true)
+
+# Below threshold → not a significant change → exit 0
+if [ "$SIG_COUNT" -lt "$CFG_MIN_CHANGED_FILES" ]; then
+  exit 0
+fi
+
+# Any doc file updated → exit 0 (lenient: any one of the four counts)
+DOC_UPDATED=$(echo "$CHANGED" | grep -cE "$CFG_DOC_FILES_REGEX" || true)
+if [ "$DOC_UPDATED" -gt 0 ]; then
+  exit 0
+fi
+
+# Block with structured JSON. Build reason entirely inside jq using \n escapes
+# so the emitted JSON has properly-escaped newlines (passing the multi-line
+# string via --arg leaks literal control characters into the JSON output, which
+# is technically invalid per RFC 8259).
+jq -n \
+  --argjson count "$SIG_COUNT" \
+  --argjson threshold "$CFG_MIN_CHANGED_FILES" \
+  --arg plugin_root "$PLUGIN_ROOT" \
+  '{
+    decision: "block",
+    reason: (
+      "HEAD commit 有 \($count) 個程式檔案變更（threshold=\($threshold)）但沒有更新文件，請補上：" +
+      "\n- CHANGELOG.md 或 changelog/ 目錄新增變更記錄" +
+      "\n- README.md（如有新功能、API 變更等需反映）" +
+      "\n- CLAUDE.md（如有架構變更、新指令等需反映）" +
+      "\n\n至少更新其中一項文件後即可繼續。" +
+      "\n\nDisable hint: touch ~/.cache/doc-tools/disabled  (one-touch kill switch)" +
+      "\nConfig: see " + $plugin_root + "/references/doc-update-design.md"
+    )
+  }'
diff --git a/plugins/doc-tools/hooks/hooks.json b/plugins/doc-tools/hooks/hooks.json
new file mode 100644
index 00000000..b9c9b6b7
--- /dev/null
+++ b/plugins/doc-tools/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/doc-update-guard.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/doc-tools/references/doc-update-design.md b/plugins/doc-tools/references/doc-update-design.md
new file mode 100644
index 00000000..0ae672c5
--- /dev/null
+++ b/plugins/doc-tools/references/doc-update-design.md
@@ -0,0 +1,220 @@
+# Doc-Update Guard Hook — Design Rationale
+
+Single source of truth for **why** the `doc-update-guard.sh` Stop hook is designed the way it is. Distilled from:
+
+- The original `~/.claude/hooks/changelog-update.sh` docstring (terse, captures explicit decisions)
+- `~/.claude/hooks/README.md` (lists the hook but with no per-hook design notes — only newer hooks have those)
+- `~/.claude/history.jsonl` (early prompts that originated the design)
+- Cross-reference to `pending-tasks-nudge.py` README (its "Rejected alternatives" table illuminates which trade-offs were explicitly considered)
+
+This document captures **both** the decisions originally written down AND the implicit ones that were never previously documented (3-file threshold, code-extension list, 4-doc-files acceptance set, Stop+block trade-off vs warn-only).
+
+---
+
+## What the hook does
+
+On `Stop` event (Claude turn end), look at the most recent commit:
+
+1. If `stop_hook_active=true` → exit 0 (infinite-loop bypass)
+2. If kill-switch flag exists → exit 0
+3. If config-disabled → exit 0
+4. If skip-path matches → exit 0
+5. If not in a git repo → exit 0
+6. If HEAD commit empty → exit 0
+7. Count "code files" changed: matches against `code_extensions` regex
+8. If count `< min_changed_files` → exit 0 (not significant)
+9. If any of `doc_files` was updated in the same commit → exit 0 (lenient pass)
+10. **Otherwise**: emit `decision: "block"` JSON listing what's missing
+
+---
+
+## Decision: per-commit, not per-day
+
+> **From original docstring**: "compact 後 Claude 會忘記先前改了什麼，每筆 commit 都應該獨立檢查。"
+
+Translation: after Claude Code's automatic conversation compaction, the assistant's working memory is partially erased. A "today aggregate" check would silently false-pass because Claude can no longer recall what it changed pre-compact.
+
+Anchoring the check on `HEAD` commit (a stable git artifact, not session memory) is **compaction-resilient**. The trade-off: a series of small commits (1-2 files each) bypasses the check even if they cumulatively cross the threshold. Accepted as cost of compact-resilience.
+
+---
+
+## Decision: Stop event + `decision: "block"`
+
+This is the most contested design choice in the hook system. The newer `pending-tasks-nudge.py` (April 2026) explicitly **rejected** this combination in its "Rejected alternatives" table:
+
+> | Alternative | Why not |
+> |-------------|---------|
+> | `Stop` hook + `decision: "block"` | Hard-blocks the end-of-turn, which interrupts normal flow; also causes infinite loops if Claude can't determine which task to mark. |
+
+Yet the doc-update guard **uses** Stop+block. Why the discrepancy?
+
+| Factor | Doc-update guard | pending-tasks-nudge |
+|--------|-----------------|---------------------|
+| Required action | **Specific** — update README/CLAUDE.md/CHANGELOG.md | **Ambiguous** — which task to mark? |
+| Resolvability | **Always resolvable** — Claude knows what to write | **Sometimes unresolvable** — no clear "done" task |
+| Infinite-loop risk | **Low** — `stop_hook_active=true` bypass + after one update Claude can move on | **High** — Claude could fight hook indefinitely |
+| Severity of skip | **High** — undocumented changes accumulate as tech debt | **Medium** — task drift is annoying but recoverable |
+
+→ Stop+block is appropriate **when the required action is specific and resolvable**. Doc updates fit; task triage doesn't.
+
+---
+
+## Decision: ≥3 code files threshold
+
+Heuristic for "significant change":
+
+- 1 file: hot-fix, typo, single-method tweak — usually no doc impact
+- 2 files: refactor a function + its caller — borderline
+- 3 files: cross-cutting change (function + callers + tests, or new feature spread across modules) — likely needs doc reflection
+
+Not derived from data; chosen as a safe-default that errs on the side of **not annoying**. User can lower to `1` (paranoid mode) or raise to `5` (noisy-mode-resistant) via config.
+
+Override: `min_changed_files` in `~/.cache/doc-tools/config.json` or `<repo>/.claude/doc-tools.json`.
+
+---
+
+## Decision: code extension allowlist
+
+The default set:
+
+```
+R sh sql py ts tsx js jsx css swift go rs kt java c cpp h
+```
+
+Source: user's primary working languages — R (stats), shell (scripting), SQL (analytics), Python (ML/automation), TypeScript/React (frontend), CSS, Swift (macOS/iOS), Go/Rust/Kotlin/Java/C/C++ (systems work).
+
+**Excluded by design**:
+- `.md` — markdown files. Doc files. The whole point of the hook is to require updating these; counting them as "code change" would create perverse incentives.
+- `.json` / `.yaml` / `.toml` — config files. Most config tweaks (version bumps, dep updates) don't need doc reflection.
+- `.txt` — usually unstructured notes, not code.
+
+Override: `code_extensions` array in config. Caller intent on this field is **full replace**, not append (appending creates accidental superset; explicit override safer).
+
+---
+
+## Decision: 4-doc-files acceptance set (lenient pass)
+
+Any **one** of these counts as "doc updated":
+
+- `CHANGELOG.md` — release notes (matches a single file)
+- `README.md` — user-facing overview (matches a single file)
+- `CLAUDE.md` — Claude-facing context (matches a single file)
+- `changelog/` — directory of dated change files (e.g. `docs/changelog/20260502_foo.md`); matches anything containing the substring
+
+> **From original prompt** (`~/.claude/history.jsonl`): "我想要有一個 changelog 資料夾，幫我在 .claude 的 hook 裡面建立**只要大改動就要修正 README.md 跟 CLAUDE.md**"
+
+Translation: the original ask was about README/CLAUDE.md, not just CHANGELOG. The 4-file acceptance set respects multiple repo conventions:
+
+- Some projects use `CHANGELOG.md`
+- Some use `docs/changelog/YYYYMMDD_*.md` directory
+- README.md updates suffice for user-facing changes
+- CLAUDE.md updates suffice for AI-facing changes
+
+Lenient = don't dictate which convention; let the user/repo decide what counts as "doc reflection".
+
+Override: `doc_files` array in config (full replace).
+
+---
+
+## Decision: `stop_hook_active=true` bypass
+
+When Claude triggers a tool call in response to the hook's block message, Claude Code re-fires the Stop hook with `stop_hook_active=true`. Without bypass, the hook would block again → Claude would respond again → infinite loop.
+
+This is **mandatory plumbing**, not a design choice. Documented in Anthropic's hook reference.
+
+---
+
+## Three-tier config injection
+
+Precedence high → low:
+
+```
+1. <repo>/.claude/doc-tools.json    ← per-project (highest)
+2. ~/.cache/doc-tools/config.json   ← per-machine
+3. built-in defaults                ← in scripts/doc-update-config.sh
+```
+
+Plus kill-switch:
+
+```
+~/.cache/doc-tools/disabled         ← touch this file → hook short-circuits exit 0
+```
+
+### Why this layering
+
+- **Per-machine**: ergonomic for "I'm tired of seeing this on side-projects" without modifying every repo
+- **Per-project**: required for legitimate cases — research scratchpads (no docs needed), generated-code repos (auto-generated, doc would lie), monorepo subprojects with different conventions
+- **Kill-switch**: emergency exit. Mirror of `archive-first` plugin's `~/.cache/archive-first/disabled` pattern. One `touch` to silence.
+
+### Config schema
+
+All four keys optional; missing keys fall through to defaults.
+
+```json
+{
+  "enabled": true,
+  "min_changed_files": 3,
+  "code_extensions": ["py", "ts", "swift"],
+  "doc_files": ["CHANGELOG.md", "README.md"],
+  "skip_paths": ["~/Developer/scratch/**", "/tmp/**"]
+}
+```
+
+| Field | Type | Default | Meaning |
+|-------|------|---------|---------|
+| `enabled` | bool | `true` | Master switch (per-machine / per-project disable without touching kill-switch flag) |
+| `min_changed_files` | int | `3` | Trigger threshold |
+| `code_extensions` | string[] | (allowlist above) | Files counted as "code change" |
+| `doc_files` | string[] | (4-set above) | Files counted as "doc updated" |
+| `skip_paths` | string[] | `[]` | Glob patterns; current working directory matched against each — match → exit 0 |
+
+`code_extensions` and `doc_files` use **full replace**, not merge. Provide the complete list you want.
+
+`skip_paths` is **append across layers** (per-machine + per-project both contribute to the skip set).
+
+---
+
+## Rejected alternatives (worth re-stating)
+
+| Alternative | Why not |
+|-------------|---------|
+| `PostToolUse` + warn-only (no block) | Doc updates need enforcement; warning is too easy to ignore. Different severity than task-tracking. |
+| `UserPromptSubmit` hook | Fires on next user message — too late; user has moved on mentally. |
+| File-watcher daemon | Out-of-band complexity; loses the per-commit anchoring (which is the compact-resilience trick). |
+| Strict 1-file threshold | Too noisy on hot-fixes / typos. |
+| Require all 4 doc files updated | Too strict; respects no repo convention. |
+| Hardcode threshold / extensions in script | No per-project flexibility. Three-tier injection added in v0.2.0. |
+
+---
+
+## How the hook compares to other PsychQuant hooks
+
+| Hook | Plugin | Event | Action | Pattern matched |
+|------|--------|-------|--------|----------------|
+| `doc-update-guard.sh` | `doc-tools` | Stop | block | This hook |
+| `claude-md-reminder.sh` | (still in `~/.claude/hooks/`) | PostToolUse(Bash) | warn | Project state drift hint |
+| `pending-tasks-nudge.py` | (still in `~/.claude/hooks/`) | PostToolUse(state-changing) | warn | Pending TaskCreate count |
+| `archive-first` block hooks | `archive-first` | PreToolUse(Bash/Write/Edit) | deny | Destructive ops on `archived/` |
+
+Future migration candidate: `claude-md-reminder.sh` is logically a doc-tools hook (warns about CLAUDE.md drift). Phase 2 may absorb it.
+
+---
+
+## Verification
+
+```bash
+# Mock: HEAD has 4 .py changes, no doc
+git init /tmp/dt-test && cd /tmp/dt-test
+for i in 1 2 3 4; do echo "x" > $i.py; done
+git add -A && git commit -m test --no-verify
+echo '{"stop_hook_active":false}' \
+  | CLAUDE_PROJECT_DIR=/tmp/dt-test bash ~/.claude/plugins/<...>/doc-tools/hooks/doc-update-guard.sh
+# Expect: JSON with decision=block, count=4
+```
+
+---
+
+## Versioning
+
+- v0.2.0 (initial): hook absorbed from `~/.claude/hooks/changelog-update.sh` + 3-tier config injection added + this design doc written.
+- Earlier history (pre-plugin): see `~/.claude/hooks/changelog-update.sh` git history (in `che-claude-config` repo) for the user-level evolution.
diff --git a/plugins/doc-tools/scripts/doc-update-config.sh b/plugins/doc-tools/scripts/doc-update-config.sh
new file mode 100755
index 00000000..217a1e11
--- /dev/null
+++ b/plugins/doc-tools/scripts/doc-update-config.sh
@@ -0,0 +1,149 @@
+#!/bin/bash
+# doc-update-config.sh — shared config loader for doc-tools hooks
+#
+# Three-tier injection (precedence high → low):
+#   1. <repo>/.claude/doc-tools.json    — per-project override
+#   2. ~/.cache/doc-tools/config.json   — per-machine override
+#   3. built-in defaults                — defined in this file
+#
+# Plus kill-switch:
+#   ~/.cache/doc-tools/disabled         — touch this file → hook short-circuits to exit 0
+#
+# Usage (sourced by hook scripts):
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/doc-update-config.sh"
+#   load_doc_tools_config "$CLAUDE_PROJECT_DIR"
+#   # Now exposed:
+#   #   $CFG_ENABLED                — "true" or "false"
+#   #   $CFG_MIN_CHANGED_FILES      — integer
+#   #   $CFG_CODE_EXTENSIONS_REGEX  — pre-built grep regex like "\\.(R|sh|py|...)$"
+#   #   $CFG_DOC_FILES_REGEX        — pre-built grep regex like "(CHANGELOG\\.md|README\\.md|...)"
+#   #   $CFG_SKIP_PATHS             — newline-delimited glob patterns
+#
+# Disabled flag check:
+#   is_doc_tools_disabled && exit 0  # short-circuit pattern
+
+set -u
+
+# ---------------------------------------------------------------------------
+# Defaults — keep in sync with references/doc-update-design.md
+# ---------------------------------------------------------------------------
+
+DEFAULT_ENABLED="true"
+DEFAULT_MIN_CHANGED_FILES=3
+DEFAULT_CODE_EXTENSIONS=(R sh sql py ts tsx js jsx css swift go rs kt java c cpp h)
+DEFAULT_DOC_FILES=(CHANGELOG.md README.md CLAUDE.md changelog/)
+DEFAULT_SKIP_PATHS=()
+
+# ---------------------------------------------------------------------------
+# Public functions
+# ---------------------------------------------------------------------------
+
+is_doc_tools_disabled() {
+  [ -f "$HOME/.cache/doc-tools/disabled" ]
+}
+
+load_doc_tools_config() {
+  local project_dir="${1:-}"
+
+  # Initialize with defaults
+  CFG_ENABLED="$DEFAULT_ENABLED"
+  CFG_MIN_CHANGED_FILES="$DEFAULT_MIN_CHANGED_FILES"
+  local code_exts=("${DEFAULT_CODE_EXTENSIONS[@]}")
+  local doc_files=("${DEFAULT_DOC_FILES[@]}")
+  CFG_SKIP_PATHS=""
+
+  # Layer 2: per-machine config
+  local machine_config="$HOME/.cache/doc-tools/config.json"
+  if [ -f "$machine_config" ]; then
+    _merge_config "$machine_config" code_exts doc_files
+  fi
+
+  # Layer 1: per-project config (highest priority)
+  if [ -n "$project_dir" ] && [ -f "$project_dir/.claude/doc-tools.json" ]; then
+    _merge_config "$project_dir/.claude/doc-tools.json" code_exts doc_files
+  fi
+
+  # Build regex strings consumers will grep against
+  CFG_CODE_EXTENSIONS_REGEX="\\.($(IFS='|'; echo "${code_exts[*]}"))$"
+  CFG_DOC_FILES_REGEX="$(_doc_regex "${doc_files[@]}")"
+}
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+# Merge a JSON config file's values over current variables. Uses jq.
+# Args: $1 = json file path; $2 = code_exts array name; $3 = doc_files array name.
+_merge_config() {
+  local cfg_file="$1"
+  local -n _code_exts_ref="$2"
+  local -n _doc_files_ref="$3"
+
+  if ! command -v jq &>/dev/null; then
+    return 0  # silently skip if jq missing (defaults persist)
+  fi
+
+  # enabled (use has() — `// empty` swallows the literal value `false`)
+  local v
+  v=$(jq -r 'if has("enabled") then .enabled else empty end' "$cfg_file" 2>/dev/null)
+  [ -n "$v" ] && CFG_ENABLED="$v"
+
+  # min_changed_files
+  v=$(jq -r 'if has("min_changed_files") then .min_changed_files else empty end' "$cfg_file" 2>/dev/null)
+  [ -n "$v" ] && CFG_MIN_CHANGED_FILES="$v"
+
+  # code_extensions (replace, not merge — caller intent is full override)
+  v=$(jq -r 'if .code_extensions then .code_extensions | join(" ") else empty end' "$cfg_file" 2>/dev/null)
+  if [ -n "$v" ]; then
+    _code_exts_ref=()
+    # shellcheck disable=SC2206
+    _code_exts_ref=($v)
+  fi
+
+  # doc_files (replace)
+  v=$(jq -r 'if .doc_files then .doc_files | join(" ") else empty end' "$cfg_file" 2>/dev/null)
+  if [ -n "$v" ]; then
+    _doc_files_ref=()
+    # shellcheck disable=SC2206
+    _doc_files_ref=($v)
+  fi
+
+  # skip_paths (newline-delimited; appended across layers)
+  v=$(jq -r 'if .skip_paths then .skip_paths[] else empty end' "$cfg_file" 2>/dev/null)
+  if [ -n "$v" ]; then
+    if [ -z "$CFG_SKIP_PATHS" ]; then
+      CFG_SKIP_PATHS="$v"
+    else
+      CFG_SKIP_PATHS="$CFG_SKIP_PATHS"$'\n'"$v"
+    fi
+  fi
+}
+
+# Build a grep regex that matches any doc file or directory pattern
+_doc_regex() {
+  local parts=()
+  for f in "$@"; do
+    # Escape dots; trailing slash → directory match
+    local escaped="${f//./\\.}"
+    parts+=("$escaped")
+  done
+  local IFS='|'
+  echo "(${parts[*]})"
+}
+
+# Check if current path matches any skip_paths glob
+is_skipped_path() {
+  local pwd_abs="${1:-$PWD}"
+  [ -z "$CFG_SKIP_PATHS" ] && return 1
+
+  while IFS= read -r pattern; do
+    [ -z "$pattern" ] && continue
+    # Expand ~ to $HOME
+    pattern="${pattern/#\~/$HOME}"
+    # shellcheck disable=SC2053
+    if [[ "$pwd_abs" == $pattern ]]; then
+      return 0
+    fi
+  done <<< "$CFG_SKIP_PATHS"
+  return 1
+}
diff --git a/plugins/doc-tools/scripts/init-changelog.py b/plugins/doc-tools/scripts/init-changelog.py
new file mode 100755
index 00000000..b0bc7d86
--- /dev/null
+++ b/plugins/doc-tools/scripts/init-changelog.py
@@ -0,0 +1,500 @@
+#!/usr/bin/env python3
+"""
+init-changelog.py — Bootstrap CHANGELOG.md from plugin.json description
+
+Parses the version segments out of `plugin.json` `description` field (PsychQuant pattern:
+"vX.Y.Z: ... vA.B.C: ...") and emits a Keep a Changelog 1.1.0 compliant CHANGELOG.md.
+
+Modes:
+    init        — generate CHANGELOG.md from scratch (errors if file exists; --force to overwrite)
+    normalize   — read existing non-KAC CHANGELOG.md and rewrite in strict KAC format
+                  (e.g., convert em-dash header `## 2.37.0 — 2026-05-02` → `## [2.37.0] - 2026-05-02`)
+
+Date resolution:
+    1. Try `git log --diff-filter=A --pretty=%ad --date=short -- <plugin.json>` for the line
+       that introduced `vX.Y.Z:` token
+    2. Fallback: '(date unknown — please fill in)'
+
+Output is idempotent in normalize mode; init mode refuses to overwrite without --force.
+
+Usage:
+    init-changelog.py init <plugin-path> [--force] [--dry-run]
+    init-changelog.py normalize <plugin-path> [--dry-run]
+
+Exit codes:
+    0 success / 1 file-already-exists / 2 parse-failure / 4 IO error
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from datetime import date as date_type
+from pathlib import Path
+from typing import Optional
+
+# Match `vX.Y.Z:` or `vX.Y.Z ` at sentence boundaries (start-of-string OR after `. `)
+# We further filter to "own-plugin major version" using current plugin.json version.
+VERSION_SEGMENT_RE = re.compile(
+    r"(?:^|(?<=[.;]\s)|(?<=[.;]\s\s)|(?<=\)\s)|(?<=\)\s\s))v(?P<version>\d+\.\d+\.\d+(?:\.\d+)?)(?::|\s+(?=\S))",
+    re.MULTILINE,
+)
+
+# Markers that hint at section type
+ADDED_MARKERS = re.compile(r"\b(NEW|新增|Added|introduces?|adds?)\b", re.IGNORECASE)
+FIXED_MARKERS = re.compile(r"\b(fix(?:es|ed)?|bug|patch(?:es)?|修[復補])\b", re.IGNORECASE)
+BREAKING_MARKERS = re.compile(r"\b(BREAKING|breaking change)\b", re.IGNORECASE)
+DEPRECATED_MARKERS = re.compile(r"\b(deprecat(?:e|ed|ion))\b", re.IGNORECASE)
+REMOVED_MARKERS = re.compile(r"\b(remov(?:e|ed|al))\b", re.IGNORECASE)
+SECURITY_MARKERS = re.compile(r"\b(security|CVE|vulnerab|patch.*vuln)\b", re.IGNORECASE)
+
+# Existing non-KAC version header in CHANGELOG.md (em-dash / no brackets)
+EM_DASH_HEADER_RE = re.compile(
+    r"^## (?P<version>\d+\.\d+\.\d+(?:\.\d+)?)\s+[—–-]\s+(?P<date>\d{4}-\d{2}-\d{2})\s*$",
+    re.MULTILINE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ParsedSegment:
+    version: str  # e.g. "2.37.0"
+    text: str  # raw prose between this version header and the next
+    date: Optional[str] = None  # ISO date if discoverable
+    sections: dict[str, list[str]] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# plugin.json description parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_description_segments(
+    description: str, plugin_major: Optional[int] = None
+) -> list[ParsedSegment]:
+    """Split run-on description into version segments.
+
+    If plugin_major is given (e.g., 3 for plugin currently on v3.x.x),
+    only versions with that major are treated as segment headers — this
+    filters out dep-version noise (e.g., 'ooxml-swift v0.21.10').
+    """
+    matches = list(VERSION_SEGMENT_RE.finditer(description))
+    if not matches:
+        return []
+
+    # Filter by major if specified
+    if plugin_major is not None:
+        matches = [
+            m for m in matches if int(m.group("version").split(".")[0]) == plugin_major
+        ]
+        if not matches:
+            return []
+
+    # De-dup: keep only first occurrence of each version (cross-references stay inline)
+    seen_versions: set[str] = set()
+    deduped: list[re.Match] = []
+    for m in matches:
+        v = m.group("version")
+        if v not in seen_versions:
+            seen_versions.add(v)
+            deduped.append(m)
+    matches = deduped
+
+    segments: list[ParsedSegment] = []
+    for i, m in enumerate(matches):
+        version = m.group("version")
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(description)
+        text = description[start:end].strip().rstrip(".")
+        text = text.lstrip(":").strip()
+        segments.append(ParsedSegment(version=version, text=text))
+    return segments
+
+
+def categorize_text(text: str) -> dict[str, list[str]]:
+    """Best-effort routing of prose into KAC sections.
+
+    Strategy:
+    - Split into sentences (period-delimited)
+    - Each sentence routed to most specific section that matches its markers
+    - Sentences with no clear marker → Changed (catch-all per KAC convention)
+    """
+    sections: dict[str, list[str]] = {}
+
+    # Sentence-ish split (period followed by space + capital, or end)
+    sentences = re.split(r"(?<=[.!?])\s+(?=[A-Z🆕])", text)
+
+    for s in sentences:
+        s = s.strip()
+        if not s:
+            continue
+
+        # Order matters: most specific first
+        if SECURITY_MARKERS.search(s):
+            sections.setdefault("Security", []).append(s)
+        elif BREAKING_MARKERS.search(s):
+            # BREAKING is signaled in Changed section per KAC convention
+            sections.setdefault("Changed", []).append(f"**BREAKING:** {s}")
+        elif REMOVED_MARKERS.search(s):
+            sections.setdefault("Removed", []).append(s)
+        elif DEPRECATED_MARKERS.search(s):
+            sections.setdefault("Deprecated", []).append(s)
+        elif FIXED_MARKERS.search(s):
+            sections.setdefault("Fixed", []).append(s)
+        elif ADDED_MARKERS.search(s):
+            sections.setdefault("Added", []).append(s)
+        else:
+            sections.setdefault("Changed", []).append(s)
+
+    return sections
+
+
+# ---------------------------------------------------------------------------
+# Git date resolution
+# ---------------------------------------------------------------------------
+
+
+def find_version_introduction_date(
+    repo_root: Path, plugin_json_relpath: str, version: str
+) -> Optional[str]:
+    """Best-effort: find the commit date when `v{version}:` was introduced into plugin.json.
+
+    Uses `git log -S` (pickaxe) on the literal token. Returns ISO date or None.
+    """
+    # Try with colon (issue-driven-dev style) first, fall back to space-suffix
+    for needle in (f"v{version}:", f"v{version} "):
+        try:
+            result = subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    str(repo_root),
+                    "log",
+                    "-S",
+                    needle,
+                    "--pretty=%ad",
+                    "--date=short",
+                    "--",
+                    plugin_json_relpath,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0:
+                lines = [l.strip() for l in result.stdout.splitlines() if l.strip()]
+                if lines:
+                    return lines[-1]  # oldest = earliest introduction
+        except (subprocess.SubprocessError, OSError):
+            continue
+    return None
+    return None
+
+
+def resolve_git_repo(plugin_path: Path) -> Optional[Path]:
+    """Walk up to find .git directory."""
+    p = plugin_path.resolve()
+    for parent in [p] + list(p.parents):
+        if (parent / ".git").exists():
+            return parent
+    return None
+
+
+# ---------------------------------------------------------------------------
+# CHANGELOG rendering
+# ---------------------------------------------------------------------------
+
+
+KAC_PREAMBLE = """# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+"""
+
+
+def render_entry(segment: ParsedSegment) -> str:
+    """Render one ParsedSegment into KAC entry markdown."""
+    date_str = segment.date or "(date unknown — please fill in)"
+    header = f"## [{segment.version}] - {date_str}\n"
+    body_parts = []
+
+    # Stable section order per KAC convention
+    section_order = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
+    for section in section_order:
+        bullets = segment.sections.get(section, [])
+        if not bullets:
+            continue
+        body_parts.append(f"\n### {section}\n")
+        for b in bullets:
+            body_parts.append(f"- {b}\n")
+
+    return header + "".join(body_parts) + "\n"
+
+
+def render_changelog(segments: list[ParsedSegment]) -> str:
+    parts = [KAC_PREAMBLE]
+    for s in segments:
+        parts.append(render_entry(s))
+    return "".join(parts).rstrip() + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Normalize mode (existing non-KAC CHANGELOG → KAC)
+# ---------------------------------------------------------------------------
+
+
+# Common non-KAC section names → KAC equivalents (additive to bracket-header normalize)
+SECTION_REMAP = {
+    "Changes": "Changed",
+    "Change": "Changed",
+    "Migration": "Changed",
+    "Migrations": "Changed",
+    "Breaking": "Changed",  # KAC convention: BREAKING signaled inside Changed
+    "BREAKING": "Changed",
+    "Improvements": "Changed",
+    "Improvement": "Changed",
+    "Bug Fixes": "Fixed",
+    "Bug Fix": "Fixed",
+    "Bugfix": "Fixed",
+    "Bugfixes": "Fixed",
+    "New": "Added",
+    "Features": "Added",
+    "Feature": "Added",
+    "Enhancements": "Changed",
+    "Enhancement": "Changed",
+}
+
+KAC_PREAMBLE_INJECT = """All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+"""
+
+
+def normalize_changelog(text: str) -> str:
+    """Best-effort rewrite of non-KAC format to KAC strict.
+
+    Three transforms (idempotent):
+      1. Version header brackets:   `## 2.37.0 — 2026-05-02` → `## [2.37.0] - 2026-05-02`
+      2. Section remap:             `### Changes` → `### Changed`, `### Migration` → `### Changed`
+                                    (NEW prefixes like `### NEW: foo` become `### Added` with
+                                    description retained as the next line — best-effort)
+      3. Preamble injection:        if missing 'Keep a Changelog' reference, insert standard
+                                    preamble after the `# Changelog` title.
+    """
+    # 1. Version headers (em-dash → bracket)
+    text = EM_DASH_HEADER_RE.sub(r"## [\g<version>] - \g<date>", text)
+
+    # 2. Section remap. Match `### <name>[: optional context]`
+    def remap_section(match: re.Match) -> str:
+        raw = match.group("raw")
+        # Strip "NEW: " etc. prefixes
+        cleaned = raw.strip()
+        # Try direct remap first
+        if cleaned in SECTION_REMAP:
+            return f"### {SECTION_REMAP[cleaned]}"
+        # Try first word
+        first = cleaned.split(":")[0].split()[0] if cleaned else ""
+        if first in SECTION_REMAP:
+            return f"### {SECTION_REMAP[first]}"
+        return match.group(0)  # unchanged
+
+    text = re.sub(
+        r"^### (?P<raw>[^\n]+?)\s*$",
+        remap_section,
+        text,
+        flags=re.MULTILINE,
+    )
+
+    # 3. Preamble injection
+    if "keep a changelog" not in text[:500].lower():
+        # Find the `# Changelog` line and insert preamble after it
+        m = re.match(r"^(# Changelog\s*\n+)", text)
+        if m:
+            text = m.group(1) + KAC_PREAMBLE_INJECT + text[m.end():]
+        else:
+            # No `# Changelog` title — prepend full preamble
+            text = "# Changelog\n\n" + KAC_PREAMBLE_INJECT + text
+
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Main commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_init(plugin_path: Path, force: bool, dry_run: bool) -> int:
+    plugin_json = plugin_path / ".claude-plugin" / "plugin.json"
+    changelog = plugin_path / "CHANGELOG.md"
+
+    if not plugin_json.exists():
+        print(f"ERROR: plugin.json not found: {plugin_json}", file=sys.stderr)
+        return 4
+
+    if changelog.exists() and not force:
+        print(
+            f"ERROR: CHANGELOG.md already exists: {changelog}\n"
+            f"       Use --force to overwrite, or 'normalize' mode to convert in place.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        data = json.loads(plugin_json.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"ERROR: plugin.json invalid JSON: {exc}", file=sys.stderr)
+        return 4
+
+    description = data.get("description", "")
+    if not description.strip():
+        print(
+            f"ERROR: plugin.json description is empty — nothing to migrate", file=sys.stderr
+        )
+        return 2
+
+    # Derive major from plugin.json version to filter out dep-version noise
+    current_version = data.get("version", "0.1.0")
+    try:
+        plugin_major = int(current_version.split(".")[0])
+    except (ValueError, IndexError):
+        plugin_major = None
+
+    segments = parse_description_segments(description, plugin_major=plugin_major)
+    if not segments:
+        print(
+            f"WARN: no version segments matching major v{plugin_major}.x.x found — "
+            f"writing skeleton with current version only",
+            file=sys.stderr,
+        )
+        segments = [
+            ParsedSegment(version=current_version, text=description.strip().rstrip("."))
+        ]
+
+    # Resolve dates via git log on plugin.json
+    repo_root = resolve_git_repo(plugin_path)
+    if repo_root:
+        try:
+            rel = plugin_json.relative_to(repo_root)
+        except ValueError:
+            rel = plugin_json
+        for s in segments:
+            s.date = find_version_introduction_date(repo_root, str(rel), s.version)
+
+    # Categorize each segment's text
+    for s in segments:
+        s.sections = categorize_text(s.text)
+
+    output = render_changelog(segments)
+    date_known = sum(1 for s in segments if s.date)
+
+    if dry_run:
+        print(f"=== DRY RUN: would write {changelog} ===\n", file=sys.stderr)
+        print(output, file=sys.stderr)
+        print(
+            f"=== END DRY RUN ({len(segments)} segments, {date_known} with dates) ===",
+            file=sys.stderr,
+        )
+    else:
+        changelog.write_text(output, encoding="utf-8")
+        print(
+            f"✓ Wrote {changelog}\n"
+            f"  segments: {len(segments)}, dates resolved: {date_known}/{len(segments)}",
+            file=sys.stderr,
+        )
+
+    # JSON summary on stdout regardless of mode (for batch consumers)
+    print(
+        json.dumps(
+            {
+                "plugin_path": str(plugin_path),
+                "changelog_path": str(changelog),
+                "segments": len(segments),
+                "dates_resolved": date_known,
+                "versions": [s.version for s in segments],
+                "dry_run": dry_run,
+            }
+        )
+    )
+    return 0
+
+
+def cmd_normalize(plugin_path: Path, dry_run: bool) -> int:
+    changelog = plugin_path / "CHANGELOG.md"
+
+    if not changelog.exists():
+        print(f"ERROR: CHANGELOG.md not found: {changelog}", file=sys.stderr)
+        print("       Use 'init' mode to create from plugin.json description first.", file=sys.stderr)
+        return 1
+
+    original = changelog.read_text(encoding="utf-8")
+    normalized = normalize_changelog(original)
+
+    if normalized == original:
+        print(f"✓ Already KAC compliant: {changelog}", file=sys.stderr)
+        return 0
+
+    if dry_run:
+        print(f"=== DRY RUN: would normalize {changelog} ===\n")
+        # Show line-level diff via simple comparison
+        for i, (a, b) in enumerate(zip(original.splitlines(), normalized.splitlines()), start=1):
+            if a != b:
+                print(f"line {i}:\n  - {a}\n  + {b}")
+        return 0
+
+    changelog.write_text(normalized, encoding="utf-8")
+    print(f"✓ Normalized {changelog}", file=sys.stderr)
+    print(json.dumps({"plugin_path": str(plugin_path), "normalized": True}))
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="Generate CHANGELOG.md from plugin.json description")
+    p_init.add_argument("plugin_path")
+    p_init.add_argument("--force", action="store_true", help="Overwrite existing CHANGELOG.md")
+    p_init.add_argument("--dry-run", action="store_true", help="Print output without writing")
+
+    p_norm = sub.add_parser(
+        "normalize", help="Rewrite existing non-KAC CHANGELOG.md headers to KAC format"
+    )
+    p_norm.add_argument("plugin_path")
+    p_norm.add_argument("--dry-run", action="store_true")
+
+    args = parser.parse_args(argv)
+    plugin_path = Path(args.plugin_path).resolve()
+
+    if not plugin_path.is_dir():
+        print(f"ERROR: not a directory: {plugin_path}", file=sys.stderr)
+        return 4
+
+    if args.cmd == "init":
+        return cmd_init(plugin_path, args.force, args.dry_run)
+    elif args.cmd == "normalize":
+        return cmd_normalize(plugin_path, args.dry_run)
+    else:
+        parser.print_help()
+        return 4
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/plugins/doc-tools/scripts/migrate-marketplace.py b/plugins/doc-tools/scripts/migrate-marketplace.py
new file mode 100755
index 00000000..f1b6929d
--- /dev/null
+++ b/plugins/doc-tools/scripts/migrate-marketplace.py
@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+migrate-marketplace.py — Batch initialize CHANGELOG.md across an entire marketplace
+
+Walks `<marketplace-path>/plugins/*/`, runs `init-changelog.py init <plugin>` on each
+that lacks a CHANGELOG.md (or all plugins with --force), then writes a migration report.
+
+Usage:
+    migrate-marketplace.py <marketplace-path> [--force] [--dry-run] [--only <name1,name2>]
+                                              [--exclude <name1,name2>] [--report-out PATH]
+
+Exit codes:
+    0 success (all plugins processed; some may have failed individually — see report)
+    4 IO / CLI error
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Optional
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+
+def run_init(
+    plugin_path: Path, force: bool, dry_run: bool
+) -> tuple[int, Optional[dict], str]:
+    """
+    Returns (exit_code, json_summary_dict_or_none, stderr_text)
+    """
+    cmd = [
+        sys.executable,
+        str(SCRIPT_DIR / "init-changelog.py"),
+        "init",
+        str(plugin_path),
+    ]
+    if force:
+        cmd.append("--force")
+    if dry_run:
+        cmd.append("--dry-run")
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    except subprocess.SubprocessError as exc:
+        return 4, None, f"subprocess error: {exc}"
+
+    summary: Optional[dict] = None
+    # JSON summary is the last line of stdout
+    stdout_lines = [l for l in result.stdout.splitlines() if l.strip()]
+    if stdout_lines:
+        try:
+            summary = json.loads(stdout_lines[-1])
+        except json.JSONDecodeError:
+            pass
+
+    return result.returncode, summary, result.stderr
+
+
+def render_report(
+    marketplace_path: Path,
+    plugins_processed: list[dict],
+    today: str,
+    dry_run: bool,
+) -> str:
+    """Render markdown migration report."""
+    total = len(plugins_processed)
+    init_ok = [p for p in plugins_processed if p["status"] == "init_ok"]
+    skipped = [p for p in plugins_processed if p["status"] == "skipped_existing"]
+    failed = [p for p in plugins_processed if p["status"] == "failed"]
+
+    title = "DRY RUN" if dry_run else "Applied"
+    lines = [
+        f"# Migration Report — {marketplace_path.name}",
+        "",
+        f"**Date**: {today}",
+        f"**Mode**: {title}",
+        f"**Total plugins scanned**: {total}",
+        f"**CHANGELOG.md created (or would be)**: {len(init_ok)}",
+        f"**Skipped (already has CHANGELOG.md)**: {len(skipped)}",
+        f"**Failed**: {len(failed)}",
+        "",
+        "## Generated CHANGELOG.md",
+        "",
+    ]
+
+    if init_ok:
+        lines.append("| Plugin | Segments | Dates resolved | Versions |")
+        lines.append("|--------|----------|----------------|----------|")
+        for p in init_ok:
+            s = p["summary"] or {}
+            n_seg = s.get("segments", "?")
+            n_date = s.get("dates_resolved", "?")
+            versions = s.get("versions", []) or []
+            v_str = ", ".join(versions[:5]) + ("..." if len(versions) > 5 else "")
+            lines.append(
+                f"| `{p['plugin']}` | {n_seg} | {n_date}/{n_seg} | {v_str} |"
+            )
+    else:
+        lines.append("(none)")
+
+    lines.extend(["", "## Skipped (existing CHANGELOG.md)", ""])
+    if skipped:
+        for p in skipped:
+            lines.append(f"- `{p['plugin']}`")
+    else:
+        lines.append("(none)")
+
+    lines.extend(["", "## Failed", ""])
+    if failed:
+        for p in failed:
+            err = (p.get("stderr") or "").strip().splitlines()
+            err_first = err[0] if err else "(no error message)"
+            lines.append(f"- `{p['plugin']}` (exit {p['exit_code']}): {err_first}")
+    else:
+        lines.append("(none)")
+
+    lines.extend(
+        [
+            "",
+            "## Manual review needed",
+            "",
+            "Generated CHANGELOG.md files use best-effort categorization. Review each for:",
+            "",
+            "1. Section assignment — `### Added` / `### Changed` / `### Fixed` etc. may need re-categorization",
+            "2. `(date unknown — please fill in)` entries — manually fill from git tags / release notes / memory",
+            "3. Sentence splitting in non-English content (Chinese punctuation `。` not split)",
+            "4. Cross-referenced versions (mentioned multiple times) — content from later mentions absorbed into prior segment",
+            "",
+            "Run `/changelog-tools:changelog-validate <plugin-path>` on each plugin after review.",
+        ]
+    )
+
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "marketplace_path", help="Path to marketplace repo root (containing plugins/)"
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing CHANGELOG.md files (default: skip them)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Don't write files; only render report"
+    )
+    parser.add_argument(
+        "--only",
+        help="Comma-separated list of plugin names to process (default: all)",
+    )
+    parser.add_argument(
+        "--exclude",
+        help="Comma-separated list of plugin names to skip",
+    )
+    parser.add_argument(
+        "--report-out",
+        help="Path to write migration report (default: <marketplace>/.claude-plugin/migration-report-YYYY-MM-DD.md)",
+    )
+    args = parser.parse_args(argv)
+
+    marketplace = Path(args.marketplace_path).resolve()
+    plugins_dir = marketplace / "plugins"
+    if not plugins_dir.is_dir():
+        print(f"ERROR: not a marketplace (missing plugins/): {marketplace}", file=sys.stderr)
+        return 4
+
+    only_set = set(args.only.split(",")) if args.only else None
+    excl_set = set(args.exclude.split(",")) if args.exclude else set()
+
+    plugins_processed: list[dict] = []
+
+    plugin_dirs = sorted([p for p in plugins_dir.iterdir() if p.is_dir()])
+    print(f"Scanning {len(plugin_dirs)} plugin(s) in {plugins_dir}", file=sys.stderr)
+
+    for plugin_dir in plugin_dirs:
+        name = plugin_dir.name
+        if only_set and name not in only_set:
+            continue
+        if name in excl_set:
+            print(f"  - {name}: excluded", file=sys.stderr)
+            continue
+
+        plugin_json = plugin_dir / ".claude-plugin" / "plugin.json"
+        if not plugin_json.exists():
+            print(f"  - {name}: no .claude-plugin/plugin.json — skipping", file=sys.stderr)
+            continue
+
+        changelog = plugin_dir / "CHANGELOG.md"
+        if changelog.exists() and not args.force:
+            print(f"  - {name}: CHANGELOG.md exists — skipped (use --force to overwrite)", file=sys.stderr)
+            plugins_processed.append({"plugin": name, "status": "skipped_existing", "summary": None})
+            continue
+
+        print(f"  - {name}: running init…", file=sys.stderr)
+        exit_code, summary, stderr = run_init(
+            plugin_dir, force=args.force, dry_run=args.dry_run
+        )
+
+        if exit_code == 0:
+            plugins_processed.append(
+                {"plugin": name, "status": "init_ok", "summary": summary}
+            )
+        else:
+            plugins_processed.append(
+                {
+                    "plugin": name,
+                    "status": "failed",
+                    "exit_code": exit_code,
+                    "stderr": stderr,
+                    "summary": summary,
+                }
+            )
+
+    today = date.today().isoformat()
+    report_path = (
+        Path(args.report_out).resolve()
+        if args.report_out
+        else marketplace / ".claude-plugin" / f"migration-report-{today}.md"
+    )
+
+    report = render_report(marketplace, plugins_processed, today, args.dry_run)
+
+    if args.dry_run:
+        print("\n" + report, file=sys.stderr)
+    else:
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(report, encoding="utf-8")
+        print(f"\n✓ Report written: {report_path}", file=sys.stderr)
+
+    # Final JSON summary on stdout
+    print(
+        json.dumps(
+            {
+                "marketplace": str(marketplace),
+                "total": len(plugins_processed),
+                "init_ok": sum(1 for p in plugins_processed if p["status"] == "init_ok"),
+                "skipped": sum(
+                    1 for p in plugins_processed if p["status"] == "skipped_existing"
+                ),
+                "failed": sum(1 for p in plugins_processed if p["status"] == "failed"),
+                "report_path": str(report_path),
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/plugins/doc-tools/scripts/validate-changelog.py b/plugins/doc-tools/scripts/validate-changelog.py
new file mode 100755
index 00000000..cdc5283a
--- /dev/null
+++ b/plugins/doc-tools/scripts/validate-changelog.py
@@ -0,0 +1,429 @@
+#!/usr/bin/env python3
+"""
+validate-changelog.py — Keep a Changelog 1.1.0 compliance + 3-way sync check
+
+Usage:
+    validate-changelog.py <plugin-path> [--marketplace <marketplace-json-path>] [--sync-chars N]
+
+Plugin path conventions (auto-detected):
+    <plugin-path>/CHANGELOG.md
+    <plugin-path>/.claude-plugin/plugin.json
+    <marketplace-json>/.claude-plugin/marketplace.json (optional, omit to skip 3-way check)
+
+Exit codes:
+    0 — pass
+    1 — CHANGELOG.md missing
+    2 — KAC compliance violation (parse + structural rules)
+    3 — 3-way sync drift between CHANGELOG.md, plugin.json, marketplace.json
+    4 — IO / CLI error
+
+Output: human-readable report on stderr, machine-parseable JSON summary on stdout (last line).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# KAC 1.1.0 spec constants
+# ---------------------------------------------------------------------------
+
+# https://keepachangelog.com/en/1.1.0/
+KAC_SECTIONS = {"Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"}
+
+# ## [1.2.3] - 2026-05-02   or   ## [Unreleased]   or   ## [1.2.3] - (date unknown — fill in)
+# Accept any non-empty trailer after `- `; ISO date check happens during validation pass.
+VERSION_HEADER_RE = re.compile(
+    r"^## \[(?P<version>Unreleased|\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\](?: - (?P<date>.+?))?\s*$"
+)
+SECTION_HEADER_RE = re.compile(r"^### (?P<name>\w+)\s*$")
+
+# Non-conformant patterns we want to flag explicitly
+NON_KAC_VERSION_PATTERNS = [
+    # ## 2.37.0 — 2026-05-02   (em-dash, no brackets — PsychQuant's existing freeform style)
+    re.compile(r"^## (\d+\.\d+\.\d+)\s+[—–-]\s+(\d{4}-\d{2}-\d{2})\s*$"),
+    # ## v1.2.3
+    re.compile(r"^## v(\d+\.\d+\.\d+)"),
+    # ## 1.2.3 (no date)
+    re.compile(r"^## (\d+\.\d+\.\d+)\s*$"),
+]
+
+
+@dataclass
+class ChangelogEntry:
+    version: str  # e.g. "1.2.0" or "Unreleased"
+    date: Optional[str]  # ISO date string or None for Unreleased
+    sections: dict[str, list[str]] = field(default_factory=dict)  # section name → bullet lines
+    line_no: int = 0  # 1-indexed line in source file
+    raw_header: str = ""
+
+
+@dataclass
+class ValidationResult:
+    plugin_path: str
+    changelog_path: str
+    plugin_json_path: str
+    marketplace_json_path: Optional[str]
+    has_changelog: bool
+    kac_violations: list[str] = field(default_factory=list)
+    sync_drifts: list[str] = field(default_factory=list)
+    entries: list[ChangelogEntry] = field(default_factory=list)
+    plugin_json_version: Optional[str] = None
+    plugin_json_description: Optional[str] = None
+    marketplace_version: Optional[str] = None
+    marketplace_description: Optional[str] = None
+    exit_code: int = 0
+
+    def to_summary_dict(self) -> dict:
+        return {
+            "plugin_path": self.plugin_path,
+            "exit_code": self.exit_code,
+            "has_changelog": self.has_changelog,
+            "kac_violation_count": len(self.kac_violations),
+            "sync_drift_count": len(self.sync_drifts),
+            "entry_count": len(self.entries),
+            "latest_version_in_changelog": (
+                next((e.version for e in self.entries if e.version != "Unreleased"), None)
+            ),
+            "plugin_json_version": self.plugin_json_version,
+            "marketplace_version": self.marketplace_version,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_changelog(path: Path) -> tuple[list[ChangelogEntry], list[str]]:
+    """
+    Returns (entries, violations).
+    Violations are KAC compliance issues discovered during parse.
+    """
+    violations: list[str] = []
+    entries: list[ChangelogEntry] = []
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+
+    current_entry: Optional[ChangelogEntry] = None
+    current_section: Optional[str] = None
+
+    for i, raw_line in enumerate(lines, start=1):
+        line = raw_line.rstrip()
+
+        # Detect version headers
+        m_v = VERSION_HEADER_RE.match(line)
+        if m_v:
+            if current_entry:
+                entries.append(current_entry)
+            version = m_v.group("version")
+            date = m_v.group("date")
+            if version != "Unreleased" and not date:
+                violations.append(
+                    f"line {i}: '{version}' missing date (expected `## [{version}] - YYYY-MM-DD`)"
+                )
+            current_entry = ChangelogEntry(
+                version=version,
+                date=date,
+                line_no=i,
+                raw_header=line,
+            )
+            current_section = None
+            continue
+
+        # Detect non-KAC version-like headers
+        if line.startswith("## ") and not line.startswith("## ["):
+            # Skip metadata sections at top of file
+            if line in {"## Format", "## Unreleased"}:
+                pass  # tolerated
+            else:
+                for pat in NON_KAC_VERSION_PATTERNS:
+                    if pat.match(line):
+                        violations.append(
+                            f"line {i}: non-KAC version header '{line.strip()}' — expected `## [VERSION] - YYYY-MM-DD`"
+                        )
+                        break
+
+        # Detect section headers (### Added etc.)
+        m_s = SECTION_HEADER_RE.match(line)
+        if m_s and current_entry is not None:
+            section_name = m_s.group("name")
+            if section_name not in KAC_SECTIONS:
+                violations.append(
+                    f"line {i}: non-KAC section '### {section_name}' — allowed: {', '.join(sorted(KAC_SECTIONS))}"
+                )
+            current_section = section_name
+            current_entry.sections.setdefault(section_name, [])
+            continue
+
+        # Bullet content
+        if current_entry is not None and current_section is not None and line.strip():
+            current_entry.sections[current_section].append(line)
+
+    if current_entry:
+        entries.append(current_entry)
+
+    # Header-level validation
+    if not entries:
+        violations.append("no version entries found — file may not be KAC format")
+    else:
+        # First non-Unreleased entry should have a date
+        first_released = next((e for e in entries if e.version != "Unreleased"), None)
+        if first_released and not first_released.date:
+            violations.append(
+                f"latest released entry [{first_released.version}] (line {first_released.line_no}) has no date"
+            )
+
+        # Date format sanity (already enforced by regex but date content)
+        for e in entries:
+            if e.date and not re.match(r"^\d{4}-\d{2}-\d{2}$", e.date):
+                violations.append(
+                    f"line {e.line_no}: date '{e.date}' not ISO 8601 (YYYY-MM-DD)"
+                )
+
+    # File-level KAC preamble check (best effort)
+    head = "\n".join(lines[:10]).lower()
+    if "keep a changelog" not in head:
+        violations.append(
+            "file preamble missing 'Keep a Changelog' reference (recommended for spec compliance)"
+        )
+
+    return entries, violations
+
+
+def load_plugin_json(path: Path) -> tuple[Optional[str], Optional[str], list[str]]:
+    """Returns (version, description, violations)."""
+    if not path.exists():
+        return None, None, [f"plugin.json not found at {path}"]
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return None, None, [f"plugin.json invalid JSON: {exc}"]
+    return data.get("version"), data.get("description"), []
+
+
+def load_marketplace_entry(
+    path: Path, plugin_name: str
+) -> tuple[Optional[str], Optional[str], list[str]]:
+    """Returns (version, description, violations) for the named plugin in marketplace.json."""
+    if not path.exists():
+        return None, None, [f"marketplace.json not found at {path}"]
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return None, None, [f"marketplace.json invalid JSON: {exc}"]
+    entries = [p for p in data.get("plugins", []) if p.get("name") == plugin_name]
+    if not entries:
+        return None, None, [
+            f"plugin '{plugin_name}' not registered in marketplace.json"
+        ]
+    if len(entries) > 1:
+        return None, None, [
+            f"plugin '{plugin_name}' registered {len(entries)} times in marketplace.json (duplicates)"
+        ]
+    return entries[0].get("version"), entries[0].get("description"), []
+
+
+# ---------------------------------------------------------------------------
+# 3-way sync check
+# ---------------------------------------------------------------------------
+
+
+def check_three_way_sync(
+    entries: list[ChangelogEntry],
+    plugin_version: Optional[str],
+    plugin_description: Optional[str],
+    marketplace_version: Optional[str],
+    marketplace_description: Optional[str],
+    sync_chars: int,
+) -> list[str]:
+    drifts: list[str] = []
+    latest = next((e for e in entries if e.version != "Unreleased"), None)
+
+    if not latest:
+        drifts.append("no released entry in CHANGELOG.md to sync against")
+        return drifts
+
+    cv = latest.version
+
+    # Version sync
+    if plugin_version and plugin_version != cv:
+        drifts.append(
+            f"version mismatch: CHANGELOG latest = [{cv}], plugin.json version = {plugin_version}"
+        )
+    if marketplace_version and marketplace_version != cv:
+        drifts.append(
+            f"version mismatch: CHANGELOG latest = [{cv}], marketplace.json version = {marketplace_version}"
+        )
+
+    # Description should mention the latest version somewhere (looser than "starts with")
+    # — PsychQuant-style descriptions often lead with product tagline, not version.
+    expected_token = f"v{cv}"
+    if plugin_description and expected_token not in plugin_description[:400]:
+        drifts.append(
+            f"plugin.json description does not mention '{expected_token}' in first 400 chars "
+            f"— marketplace consumers won't see what's new in this release"
+        )
+    if marketplace_description and expected_token not in marketplace_description[:400]:
+        drifts.append(
+            f"marketplace.json description does not mention '{expected_token}' in first 400 chars"
+        )
+
+    # plugin.json vs marketplace.json description prefix should match (first sync_chars chars)
+    if plugin_description and marketplace_description:
+        a = plugin_description[:sync_chars]
+        b = marketplace_description[:sync_chars]
+        if a != b:
+            drifts.append(
+                f"description prefix mismatch (first {sync_chars} chars) between plugin.json and marketplace.json"
+            )
+
+    return drifts
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def run(plugin_path: Path, marketplace_json: Optional[Path], sync_chars: int) -> ValidationResult:
+    plugin_json = plugin_path / ".claude-plugin" / "plugin.json"
+    changelog = plugin_path / "CHANGELOG.md"
+    plugin_name = plugin_path.name
+
+    result = ValidationResult(
+        plugin_path=str(plugin_path),
+        changelog_path=str(changelog),
+        plugin_json_path=str(plugin_json),
+        marketplace_json_path=str(marketplace_json) if marketplace_json else None,
+        has_changelog=changelog.exists(),
+    )
+
+    if not changelog.exists():
+        result.exit_code = 1
+        return result
+
+    entries, kac_violations = parse_changelog(changelog)
+    result.entries = entries
+    result.kac_violations = kac_violations
+
+    pv, pd, pj_violations = load_plugin_json(plugin_json)
+    result.plugin_json_version = pv
+    result.plugin_json_description = pd
+    result.kac_violations.extend(pj_violations)  # treat plugin.json IO errors as KAC scope
+
+    mv, md = None, None
+    if marketplace_json:
+        mv, md, mp_violations = load_marketplace_entry(marketplace_json, plugin_name)
+        result.marketplace_version = mv
+        result.marketplace_description = md
+        result.kac_violations.extend(mp_violations)
+
+    result.sync_drifts = check_three_way_sync(
+        entries=entries,
+        plugin_version=pv,
+        plugin_description=pd,
+        marketplace_version=mv,
+        marketplace_description=md,
+        sync_chars=sync_chars,
+    )
+
+    if result.kac_violations:
+        result.exit_code = 2
+    elif result.sync_drifts:
+        result.exit_code = 3
+
+    return result
+
+
+def render_report(result: ValidationResult) -> str:
+    lines = [f"=== changelog-validate: {result.plugin_path} ==="]
+    if not result.has_changelog:
+        lines.append(f"❌ MISSING: {result.changelog_path}")
+        lines.append(
+            "→ Run `/changelog-tools:changelog-init` to bootstrap from plugin.json description"
+        )
+        return "\n".join(lines)
+
+    lines.append(f"📄 CHANGELOG.md: {len(result.entries)} entries parsed")
+    if result.entries:
+        latest = next((e for e in result.entries if e.version != "Unreleased"), None)
+        if latest:
+            lines.append(f"   latest released: [{latest.version}] - {latest.date or '(no date)'}")
+        unreleased = next((e for e in result.entries if e.version == "Unreleased"), None)
+        if unreleased:
+            section_count = len([s for s in unreleased.sections if unreleased.sections[s]])
+            lines.append(f"   [Unreleased]: {section_count} non-empty section(s)")
+
+    if result.kac_violations:
+        lines.append("")
+        lines.append(f"❌ KAC violations ({len(result.kac_violations)}):")
+        for v in result.kac_violations:
+            lines.append(f"   • {v}")
+    else:
+        lines.append("✓ KAC compliant")
+
+    if result.sync_drifts:
+        lines.append("")
+        lines.append(f"⚠ 3-way sync drift ({len(result.sync_drifts)}):")
+        for d in result.sync_drifts:
+            lines.append(f"   • {d}")
+    else:
+        lines.append("✓ 3-way sync OK")
+
+    lines.append("")
+    lines.append(f"Exit code: {result.exit_code}  ({_exit_meaning(result.exit_code)})")
+    return "\n".join(lines)
+
+
+def _exit_meaning(code: int) -> str:
+    return {
+        0: "pass",
+        1: "CHANGELOG.md missing",
+        2: "KAC compliance violation",
+        3: "3-way sync drift",
+        4: "IO / CLI error",
+    }.get(code, "unknown")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("plugin_path", help="Path to plugin directory (containing .claude-plugin/plugin.json)")
+    parser.add_argument(
+        "--marketplace",
+        help="Path to marketplace.json file (optional; omit to skip 3-way sync drift on marketplace side)",
+    )
+    parser.add_argument(
+        "--sync-chars",
+        type=int,
+        default=200,
+        help="Number of leading description chars to compare for plugin.json vs marketplace.json sync (default 200)",
+    )
+    parser.add_argument(
+        "--quiet", "-q", action="store_true", help="Skip human report; only print JSON summary"
+    )
+    args = parser.parse_args(argv)
+
+    plugin_path = Path(args.plugin_path).resolve()
+    if not plugin_path.is_dir():
+        print(f"ERROR: not a directory: {plugin_path}", file=sys.stderr)
+        return 4
+
+    marketplace = Path(args.marketplace).resolve() if args.marketplace else None
+
+    result = run(plugin_path, marketplace, args.sync_chars)
+
+    if not args.quiet:
+        print(render_report(result), file=sys.stderr)
+
+    print(json.dumps(result.to_summary_dict()))
+    return result.exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/plugins/doc-tools/skills/changelog-init/SKILL.md b/plugins/doc-tools/skills/changelog-init/SKILL.md
new file mode 100644
index 00000000..4a21cee2
--- /dev/null
+++ b/plugins/doc-tools/skills/changelog-init/SKILL.md
@@ -0,0 +1,139 @@
+---
+name: changelog-init
+description: |
+  為單一 plugin 從 plugin.json description 反向 bootstrap CHANGELOG.md（Keep a Changelog 1.1.0 格式）。
+  Parse description 的 vX.Y.Z 段落（同時支援 colon-style `vX.Y.Z:` 和 space-style `vX.Y.Z `），按 plugin 自己的 major version 過濾掉 dep version 噪音，git log pickaxe 解析每個 version 的引入日期，分類 prose 到 Added/Changed/Deprecated/Removed/Fixed/Security 六個 KAC section。
+  另一個 mode: normalize 把既有非 KAC CHANGELOG.md（如 PsychQuant 的 em-dash 格式 `## 2.37.0 — 2026-05-02`）改寫成 KAC 標準（`## [2.37.0] - 2026-05-02`）。
+  Use when: 你想為一個沒 CHANGELOG.md 的 plugin 補一個；或想把舊格式 normalize 成 KAC 標準。
+  防止的失敗：手寫 KAC entries 太繁瑣 → 索性不寫 CHANGELOG.md；或寫了但格式偏差被 marketplace consumer 解析錯。
+argument-hint: "<init|normalize> <plugin-path> [--force] [--dry-run]"
+allowed-tools:
+  - Bash(python3:*)
+  - Bash(git:*)
+  - Bash(realpath:*)
+  - Read
+  - Write
+---
+
+# /changelog-init — Bootstrap CHANGELOG.md
+
+## Purpose
+
+把 [`scripts/init-changelog.py`](../../scripts/init-changelog.py) 包裝成 skill 入口。Script 做 parse + categorize + render；skill 負責路由 + 互動確認。
+
+## Two modes
+
+### `init` — 從 plugin.json description 產生 CHANGELOG.md
+
+```bash
+/changelog-tools:changelog-init init <plugin-path> [--force] [--dry-run]
+```
+
+行為：
+1. Read `<plugin-path>/.claude-plugin/plugin.json` 的 `description` 欄位
+2. 用正則找出 `vX.Y.Z` segments，按 plugin 自己的 major version 過濾（避免把 dep `v0.21.x` 當成 segment）
+3. 對每個 segment，跑 `git log -S "vX.Y.Z"` 找最早引入時間 → 當該 version 的日期；找不到就 `(date unknown — please fill in)`
+4. 把 prose 用關鍵字 markers（NEW / fixes / BREAKING / deprecated / removed / security）分到六個 KAC section
+5. 寫 KAC 1.1.0 格式 + 預載 `[Unreleased]` placeholder
+6. 預設**拒絕覆寫**既有 CHANGELOG.md，需 `--force`
+
+`--dry-run` 印出 output 不寫檔，方便 review。
+
+### `normalize` — 修既有非 KAC CHANGELOG.md
+
+```bash
+/changelog-tools:changelog-init normalize <plugin-path> [--dry-run]
+```
+
+行為：
+- 把 `## 2.37.0 — 2026-05-02`（em-dash, 無方括號）改寫成 `## [2.37.0] - 2026-05-02`
+- 不動 body content（不重排 section / 不改字）— 只觸版本標題那一行
+- Idempotent — 已是 KAC 格式時印 `✓ Already KAC compliant` 後 exit 0
+
+## Execution
+
+### Step 0: Bootstrap Stage Task List
+
+```
+TaskCreate(name="resolve_mode", description="parse arg → init or normalize")
+TaskCreate(name="resolve_plugin_path", description="realpath + 確認 .claude-plugin/plugin.json 存在")
+TaskCreate(name="dry_run_first", description="先跑 --dry-run 給 user 看 preview（init mode 必要、normalize mode 推薦）")
+TaskCreate(name="ask_confirm", description="AskUserQuestion 確認要實際寫檔，或想先手動 review preview")
+TaskCreate(name="execute", description="跑 init/normalize 不帶 --dry-run")
+TaskCreate(name="route_next", description="提示 changelog-validate 驗證輸出 / 提示手動 review categorization")
+```
+
+### Step 1: Resolve mode + path
+
+```bash
+MODE=$1   # init or normalize
+PLUGIN_PATH=$(realpath "$2")
+[ -d "$PLUGIN_PATH" ] || { echo "ERROR: not a directory: $PLUGIN_PATH"; exit 4; }
+[ -f "$PLUGIN_PATH/.claude-plugin/plugin.json" ] || { echo "ERROR: not a plugin: $PLUGIN_PATH"; exit 4; }
+```
+
+### Step 2: Dry-run first (init mode)
+
+Init mode 一定先跑 `--dry-run` 顯示 preview，再用 AskUserQuestion 確認：
+
+```
+question: "Preview 顯示了 N 個 segment，要實際寫到 {path}/CHANGELOG.md 嗎？"
+options:
+  - "寫入" — 跑 init 不帶 --dry-run
+  - "再跑一次 dry-run" — 重跑 preview（如 user 中途改了 plugin.json）
+  - "手動 review preview" — 把 dry-run 輸出存到 /tmp/CHANGELOG_preview.md，user 自己編輯後 cp 到目的地
+  - "中止" — 不寫檔
+```
+
+### Step 3: Execute
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/scripts/init-changelog.py" "$MODE" "$PLUGIN_PATH" [--force]
+```
+
+### Step 4: Route next
+
+| 完成情境 | 下一步 |
+|---------|-------|
+| init 成功 | → 跑 `/changelog-tools:changelog-validate $PLUGIN_PATH` 驗格式；review section categorization；填補 `(date unknown)` |
+| normalize 成功 | → 跑 `/changelog-tools:changelog-validate` 確認 |
+| init `EXIT=1`（CHANGELOG 已存在） | → 改用 normalize mode；或加 `--force` overwrite |
+
+## Examples
+
+```bash
+# 為 che-word-mcp 補 CHANGELOG.md
+/changelog-tools:changelog-init init plugins/che-word-mcp
+
+# Preview only
+/changelog-tools:changelog-init init plugins/che-word-mcp --dry-run
+
+# Overwrite existing CHANGELOG.md
+/changelog-tools:changelog-init init plugins/che-word-mcp --force
+
+# Normalize issue-driven-dev 的 em-dash format
+/changelog-tools:changelog-init normalize plugins/issue-driven-dev
+```
+
+## Limitations & manual cleanup needed
+
+Init mode 是 **best-effort migration**，產出後通常需要手動 review：
+
+1. **Section categorization 偏差** — keyword markers 不完美，例如「pre-fix three structural defects: (1) deprecated...」可能被歸 Deprecated，實際應在 Fixed。Section 內的 bullet 順序也只是 sentence split，可能切錯。
+2. **Date 缺漏** — `git log -S` pickaxe 只能找 plugin.json 內提到該 version 的 commit；如果 description 沒提到舊版本，就只能 fallback `(date unknown)` 等手填。
+3. **Sentence boundary** — 中文句號 `。` 不會被 split，整個 paragraph 變一條 bullet。可後續手動拆。
+4. **Cross-references 被 dedupe** — 同一個 version 在 description 多次出現（如 v3.16.2 被前後文 cross-reference）只保留第一個 segment header；其他 mention 的內容會吃進前一個 segment。
+
+工具的價值是**結構化 + 大幅省手寫時間**，不是替代人類編輯。
+
+## 鐵律
+
+- **不在 SKILL 裡 inline parsing logic** — 全部在 `scripts/init-changelog.py`
+- **Init 預設不覆寫** — 保護既有 CHANGELOG，需 `--force` 才覆寫
+- **Dry-run 是第一等公民** — init mode 必先 dry-run 給 user 看 preview
+
+## Related
+
+- [`scripts/init-changelog.py`](../../scripts/init-changelog.py) — 實作
+- [`changelog-validate`](../changelog-validate/SKILL.md) — init 後驗格式
+- [`changelog-migrate`](../changelog-migrate/SKILL.md) — batch 跨多 plugin 跑 init
diff --git a/plugins/doc-tools/skills/changelog-migrate/SKILL.md b/plugins/doc-tools/skills/changelog-migrate/SKILL.md
new file mode 100644
index 00000000..b3a9286d
--- /dev/null
+++ b/plugins/doc-tools/skills/changelog-migrate/SKILL.md
@@ -0,0 +1,155 @@
+---
+name: changelog-migrate
+description: |
+  跨整個 Claude Code marketplace 批次跑 changelog-init — 為所有缺 CHANGELOG.md 的 plugin 補上 KAC 1.1.0 格式的檔案，並產出 migration report。
+  Use when: 你的 marketplace 有大量 plugin 沒 CHANGELOG.md（PsychQuant 起初 35/36）；想一次性整頓 changelog 健康度；想看哪些 plugin 的 description 結構好/差（segment 數可作為品質代理指標）。
+  防止的失敗：手動為 N 個 plugin 跑 init 太費時；漏了某些 plugin；migration 結果沒留 audit trail。
+argument-hint: "<marketplace-path> [--force] [--dry-run] [--only name1,name2] [--exclude name1,name2] [--report-out PATH]"
+allowed-tools:
+  - Bash(python3:*)
+  - Bash(realpath:*)
+  - Bash(ls:*)
+  - Read
+  - AskUserQuestion
+---
+
+# /changelog-migrate — Batch CHANGELOG.md initialization
+
+## Purpose
+
+把 [`scripts/migrate-marketplace.py`](../../scripts/migrate-marketplace.py) 包裝成 skill 入口。Script orchestrates per-plugin invocations of `init-changelog.py`，生成 markdown migration report。
+
+## Workflow philosophy
+
+這是**一次性 migration tool**。理想狀態下每個 marketplace 跑一次就完成。後續新增 plugin 用 `changelog-tools:changelog-init` 處理單一 plugin。
+
+## Argument
+
+- `marketplace_path` （必填）— marketplace repo 根目錄（含 `plugins/` 子目錄）
+- `--force` — 對既有 CHANGELOG.md 的 plugin 也跑 init（覆寫）。預設 skip
+- `--dry-run` — 不寫檔，只印 preview 跟 report
+- `--only name1,name2,...` — 只處理列表中的 plugin
+- `--exclude name1,name2,...` — 跳過列表中的 plugin
+- `--report-out PATH` — report 輸出位置（預設 `<marketplace>/.claude-plugin/migration-report-YYYY-MM-DD.md`）
+
+## Execution
+
+### Step 0: Bootstrap Stage Task List
+
+```
+TaskCreate(name="resolve_marketplace", description="realpath + 確認有 plugins/ 子目錄")
+TaskCreate(name="dry_run_first", description="先跑 --dry-run 顯示會處理哪些 plugin、預估 segment 數")
+TaskCreate(name="ask_confirm", description="AskUserQuestion 確認要實際執行 / 調整 --only --exclude / 中止")
+TaskCreate(name="execute_batch", description="跑 migrate 不帶 --dry-run，記錄 report 路徑")
+TaskCreate(name="post_process", description="提示 user 開 report 看哪些 plugin 需手動 review section categorization")
+```
+
+### Step 1: Dry-run preview
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/scripts/migrate-marketplace.py" "$MARKETPLACE" --dry-run
+```
+
+Stderr 印 plugin-by-plugin 處理狀態 + 完整 report；stdout 印 JSON summary（total / init_ok / skipped / failed）。
+
+### Step 2: Confirm
+
+用 AskUserQuestion：
+
+```
+question: "Dry-run 顯示 N plugin 待 init、M 已存在 CHANGELOG.md（將跳過）、K 失敗。要實際寫檔嗎？"
+options:
+  - "全部寫入" — 跑 migrate 不帶 --dry-run
+  - "排除某些 plugin" — 用 --exclude 重跑
+  - "只處理某些 plugin" — 用 --only 重跑
+  - "強制覆寫已存在的 CHANGELOG.md" — 加 --force 重跑（包含 dry-run 確認）
+  - "中止" — 不執行
+```
+
+### Step 3: Execute
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/scripts/migrate-marketplace.py" "$MARKETPLACE" [其他 flags]
+```
+
+執行後：
+- 每個 plugin 的 CHANGELOG.md 寫到 `<marketplace>/plugins/<name>/CHANGELOG.md`
+- Migration report 寫到 `<marketplace>/.claude-plugin/migration-report-YYYY-MM-DD.md`
+- Stdout 一行 JSON summary（CI / 後續腳本可消費）
+
+### Step 4: Post-process
+
+提示 user：
+
+1. **開 migration report** — 看哪些 plugin 已 init / 哪些 segment 數異常少（≤1 表示 description 沒歷史）
+2. **跑 changelog-validate** — `for p in plugins/*/; do /changelog-tools:changelog-validate $p; done`（或 batch 模式 — 留給 Phase 2）
+3. **手動 review categorization** — script 是 best-effort，section 分類常需要調整
+4. **填補 `(date unknown — please fill in)`** — 找不到 git pickaxe match 的版本要手填
+
+## Examples
+
+```bash
+# 標準用法：dry-run preview, confirm, write
+/changelog-tools:changelog-migrate /Users/che/Developer/psychquant-claude-plugins
+
+# 只 migrate IDD-related plugins
+/changelog-tools:changelog-migrate . --only issue-driven-dev,plugin-tools,mcp-tools
+
+# 排除 binary-based plugin（它們的 description 通常很複雜）
+/changelog-tools:changelog-migrate . --exclude che-word-mcp,che-pdf-mcp,che-pptx-mcp
+
+# Dry-run only — 不寫檔，看 preview
+/changelog-tools:changelog-migrate . --dry-run
+
+# 強制覆寫所有 plugin 的 CHANGELOG.md（包括 issue-driven-dev）
+/changelog-tools:changelog-migrate . --force
+```
+
+## Migration report 結構
+
+```markdown
+# Migration Report — psychquant-claude-plugins
+
+**Date**: 2026-05-02
+**Mode**: Applied
+**Total plugins scanned**: 36
+**CHANGELOG.md created**: 33
+**Skipped (already has CHANGELOG.md)**: 1
+**Failed**: 0
+
+## Generated CHANGELOG.md
+
+| Plugin | Segments | Dates resolved | Versions |
+|--------|----------|----------------|----------|
+| `che-word-mcp` | 15 | 15/15 | 3.17.8, 3.17.7, 3.17.6, 3.17.5, 3.17.4... |
+| `agent-cacher` | 1 | 0/1 | 0.1.0 |
+| ...
+
+## Skipped (existing CHANGELOG.md)
+- `issue-driven-dev`
+
+## Failed
+(none)
+
+## Manual review needed
+{4-point reminder}
+```
+
+## 鐵律
+
+- **Idempotent by default** — 第二次跑只會 skip 既有 CHANGELOG.md，不會破壞 manual edits
+- **Report 是 audit trail** — 永遠寫 report 到磁碟（除 dry-run），不在 Claude 對話中遺失
+- **Best-effort migration** — 結構化 + 省手寫，不替代人類編輯
+- **不在 SKILL 裡 inline migration logic** — 全部在 `scripts/migrate-marketplace.py`
+
+## Limitations
+
+- **不跨 marketplace** — 一次只處理一個 marketplace。多個要 loop 呼叫
+- **不處理 binary repo CHANGELOG** — 只處理 plugin marketplace 結構（`plugins/<name>/`）；binary repo（如 `mcp/che-word-mcp/` 直接 git clone 的）要單獨用 `changelog-init`
+- **Section categorization 仍需 review** — 詳見 [changelog-init Limitations](../changelog-init/SKILL.md#limitations--manual-cleanup-needed)
+
+## Related
+
+- [`scripts/migrate-marketplace.py`](../../scripts/migrate-marketplace.py) — 實作
+- [`changelog-init`](../changelog-init/SKILL.md) — 單 plugin 版本
+- [`changelog-validate`](../changelog-validate/SKILL.md) — migrate 完用來驗結果
diff --git a/plugins/doc-tools/skills/changelog-validate/SKILL.md b/plugins/doc-tools/skills/changelog-validate/SKILL.md
new file mode 100644
index 00000000..bf303f2e
--- /dev/null
+++ b/plugins/doc-tools/skills/changelog-validate/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: changelog-validate
+description: |
+  驗證 plugin 的 CHANGELOG.md 是否符合 Keep a Changelog 1.1.0 規範，並檢查三處同步（CHANGELOG.md latest entry ↔ plugin.json description ↔ marketplace.json description）。
+  Exit codes: 0 pass / 1 missing CHANGELOG / 2 KAC violation / 3 sync drift / 4 IO error。CI 友善。
+  Use when: 發 release 前檢查格式對不對；audit 一個 marketplace 的 CHANGELOG 健康度；改完 description 後驗 sync 沒漏。
+  防止的失敗：plugin.json 跟 CHANGELOG 版本不同步（marketplace 顯示舊版）；用了非 KAC section name（### 改進、### Bug Fix 等）；忘記寫日期。
+argument-hint: "<plugin-path> [--marketplace <marketplace-json-path>] [--sync-chars N] [--quiet]"
+allowed-tools:
+  - Bash(python3:*)
+  - Bash(realpath:*)
+  - Bash(ls:*)
+  - Read
+---
+
+# /changelog-validate — 驗證 CHANGELOG
+
+## Purpose
+
+把 [`scripts/validate-changelog.py`](../../scripts/validate-changelog.py) 包裝成 skill 入口。Script 做機械驗證（KAC parse + sync check），skill 負責告訴使用者「下一步該做什麼」。
+
+## Argument
+
+- `plugin_path` （必填）— plugin 目錄絕對路徑（含 `.claude-plugin/plugin.json`）
+- `--marketplace <path>` （選）— `marketplace.json` 絕對路徑；省略則跳過 marketplace 那一邊的 sync drift 檢查
+- `--sync-chars N` （選，預設 200）— plugin.json 跟 marketplace.json description 比對前 N 字
+- `--quiet` （選）— 只輸出 JSON summary（CI 用）
+
+## Execution
+
+### Step 0: Bootstrap Stage Task List
+
+```
+TaskCreate(name="resolve_paths", description="解析 plugin_path → 找 CHANGELOG.md / plugin.json / marketplace.json")
+TaskCreate(name="run_validator", description="跑 validate-changelog.py，蒐集 exit code + JSON summary + human report")
+TaskCreate(name="route_action", description="根據 exit code 給使用者具體下一步指引")
+```
+
+### Step 1: Resolve paths
+
+```bash
+PLUGIN_PATH=$(realpath "$ARG_PLUGIN_PATH")
+[ -d "$PLUGIN_PATH" ] || { echo "ERROR: not a directory: $PLUGIN_PATH"; exit 4; }
+[ -f "$PLUGIN_PATH/.claude-plugin/plugin.json" ] || { echo "ERROR: not a plugin (missing .claude-plugin/plugin.json): $PLUGIN_PATH"; exit 4; }
+
+# Optional marketplace
+if [ -n "$ARG_MARKETPLACE" ]; then
+    MARKETPLACE_FLAG="--marketplace $(realpath "$ARG_MARKETPLACE")"
+else
+    MARKETPLACE_FLAG=""
+fi
+```
+
+### Step 2: Run validator
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/scripts/validate-changelog.py" \
+    "$PLUGIN_PATH" \
+    $MARKETPLACE_FLAG \
+    --sync-chars ${ARG_SYNC_CHARS:-200} \
+    ${QUIET:+--quiet}
+EXIT=$?
+```
+
+The script writes:
+- Human-readable report to **stderr**
+- One-line JSON summary to **stdout** (last line)
+- Exit code 0/1/2/3/4
+
+Capture both for routing.
+
+### Step 3: Route by exit code
+
+| Exit | Meaning | Recommended next action (tell user) |
+|------|---------|------------------------------------|
+| 0 | pass | ✓ 沒事。如要 release，跑 `/changelog-tools:changelog-release` (Phase 2) |
+| 1 | CHANGELOG.md missing | → 跑 `/changelog-tools:changelog-init <plugin-path>` 從 plugin.json description 反向 bootstrap |
+| 2 | KAC violation | → 顯示 violation list；若是 em-dash format（PsychQuant legacy 風格），跑 `/changelog-tools:changelog-init --normalize <plugin-path>`；若是個別 section name 錯誤，手動修 |
+| 3 | sync drift | → 顯示 drift list；通常是 plugin.json / marketplace.json description 沒跟 CHANGELOG 最新 entry 同步；下個 release 時 `/changelog-tools:changelog-release` 會自動同步，現在可手動 Edit |
+| 4 | IO / CLI error | → 報錯給使用者，通常是路徑寫錯 |
+
+## Engine 模式
+
+預設 verbose（人讀）。`--quiet` 切到 JSON-only 模式給 CI / batch 場景（`changelog-migrate` 內部就用這個）。
+
+## Examples
+
+```bash
+# 單一 plugin 驗證（含 marketplace sync）
+/changelog-tools:changelog-validate plugins/issue-driven-dev --marketplace .claude-plugin/marketplace.json
+
+# 只驗 CHANGELOG.md 本身（跳過 sync）
+/changelog-tools:changelog-validate plugins/changelog-tools
+
+# CI mode（only JSON to stdout）
+/changelog-tools:changelog-validate plugins/issue-driven-dev --quiet
+```
+
+## 鐵律
+
+- **不在 SKILL 裡 inline parse logic** — 全部在 `scripts/validate-changelog.py`。SKILL 只 orchestrate。
+- **Exit code 是契約** — 0/1/2/3/4 對應 5 種狀態，呼叫者（CI、其他 skill）依此 branch
+- **Sync drift ≠ KAC violation** — 兩者獨立報、獨立 exit。Drift 不阻擋 KAC pass
+
+## Related
+
+- [`scripts/validate-changelog.py`](../../scripts/validate-changelog.py) — 實作
+- [`changelog-init`](../changelog-init/SKILL.md) — exit 1/2 後的修復路徑
+- [`changelog-migrate`](../changelog-migrate/SKILL.md) — batch 跨多 plugin 用 `--quiet` mode
+- [Keep a Changelog 1.1.0 spec](https://keepachangelog.com/en/1.1.0/)
diff --git a/plugins/docflow/.claude-plugin/plugin.json b/plugins/docflow/.claude-plugin/plugin.json
new file mode 100644
index 00000000..099e033d
--- /dev/null
+++ b/plugins/docflow/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "docflow",
+  "description": "Git-flow analog for documents — semantic synthesis, multi-version comparison, evidence-after-commit workflows for .tex / .md / .ipynb / .docx. v1.0.1 ships doc-synth skill (semantic merge between 2+ document versions, dimension-level take/leave decisions, provenance tracking, 3+ source Pattern α, cross-language edge case spec).",
+  "version": "1.0.1",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/docflow/CLAUDE.md b/plugins/docflow/CLAUDE.md
new file mode 100644
index 00000000..fb8b8d98
--- /dev/null
+++ b/plugins/docflow/CLAUDE.md
@@ -0,0 +1,48 @@
+# docflow — CLAUDE.md
+
+> Git-flow analog for documents — semantic synthesis, multi-version comparison, evidence-after-commit workflows for academic writing & ML notebooks.
+
+## Purpose
+
+把 git 的 mental model（branch / merge / diff / log / blame）套到 document workflow，但作用層是 **semantic 不是 line-level**。
+
+典型場景：學生作業 vs 老師 reference、原 draft vs reviewer 意見、本年 lecture vs 去年 lecture、英中雙語版同步。
+
+**不是 git replacement** — git 已經很會處理 line-level diff/merge；docflow 處理 git 不擅長的「dimension-level semantic blend」。
+
+## Skills
+
+| Skill | 用途 | Status |
+|-------|------|--------|
+| `/docflow:doc-synth` | Semantic synthesis between 2+ document versions（按 dimension 挑優整合） | **v1.0** ✓ |
+| `/docflow:doc-compare` | N-dimensional side-by-side comparison.md 自動產出 | TODO |
+| `/docflow:doc-verdict` | N versions per-question master_verdict.md 表格 | TODO |
+| `/docflow:doc-multiimpl` | 強制 N alternative 都跑完整 implementation 再 commit | TODO |
+
+## Supported formats
+
+- `.tex` — section-based dimension extraction
+- `.md` — heading-based dimension extraction
+- `.ipynb` — cell-based dimension extraction
+- `.docx` — section-based via `che-word-mcp` integration
+
+## Mental model
+
+| Action | git | docflow |
+|---|---|---|
+| Branch | 多 file copy（A.tex / B.tex / C.tex） | 同 |
+| Diff | line-level | dimension-level（section / heading / cell） |
+| **Merge** | line-level auto + conflict markers | **semantic：user 按 dimension 挑 take A / B / hybrid** |
+| Log | commit history | provenance sidecar `<output>.synth.json` |
+| Blame | line → commit | dimension → source doc |
+
+## Development
+
+- Plugin structure: see [official plugin-dev](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/plugin-dev)
+- Update after changes: `/plugin-tools:plugin-update docflow`
+- Health check: `/plugin-tools:plugin-health`
+- Local iterate: `claude --plugin-dir /Users/che/Developer/psychquant-claude-plugins/plugins/docflow`
+
+## 設計起源
+
+`kiki830621/2026-winston` session（ASSG3 retrospective revision + ML HW2 final_v2 won't-fix + 「merge vs synthesis vs revision」術語討論，2026-05-12）。當時手動做了 3 次 comparison.md + 1 次 master_verdict.md + 1 次 multi-impl pilot，發現工作流可以 systematize 成 plugin。
diff --git a/plugins/docflow/skills/doc-synth/SKILL.md b/plugins/docflow/skills/doc-synth/SKILL.md
new file mode 100644
index 00000000..5f36c6ad
--- /dev/null
+++ b/plugins/docflow/skills/doc-synth/SKILL.md
@@ -0,0 +1,337 @@
+---
+name: doc-synth
+description: |
+  Semantic synthesis between 2+ document versions (not git-style line merge).
+  Input: N source docs (.tex / .md / .ipynb / .docx). User specifies dimension-level
+  take/leave decisions (e.g., "structure from A, methodology section from B, conclusion
+  from C"). Plugin produces synthesized output with provenance tracking.
+  Use when: combining advantages from multiple drafts, integrating reviewer suggestions
+  with original draft, merging student work + teacher reference into best-of-both.
+  Differs from: git merge (mechanical line-level), revise (single source improved),
+  ensemble (output averaging — this picks dimensions, not averages outputs).
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+---
+
+# doc-synth — Semantic Synthesis Between Document Versions
+
+## Purpose
+
+把 N 個 document version 的優點按維度 (section / cell / dimension) 整合進一個新版本，**不是 line-level git merge，是 semantic blend**。
+
+典型 use case：
+- ASSG / paper revision：W-tex 的 self-aware caveats + Gong reference 的 procedural strictness → 新版本各取所長
+- ML notebook：W-Py 的 Part 0-4 rubric structure + Gong 的 Pipeline + ColumnTransformer engineering → final.ipynb
+- 報告整合：兩位審稿者意見 + 原 draft → revised draft
+- Lecture handout：去年版 + 今年新加章節 → 完整版
+
+**不適用**：
+- 同一份文件版本演進（用 `git diff` + `Edit` 即可）
+- 完全重寫（沒有「保留 N 個 source 的 dimension」概念，直接用 `perspective-writer` 之類）
+- Pure ensemble（model averaging 不挑 dimension — 用其他工具）
+
+## Vocabulary
+
+| 詞 | 意義 |
+|---|---|
+| **source** | 輸入的某個 document version（A / B / C / ...） |
+| **dimension** | 可獨立挑選的內容單位（.tex section / .md heading / .ipynb cell / .docx section） |
+| **take decision** | per-dimension 決定該維度從哪個 source 來（A only / B only / hybrid / custom） |
+| **provenance** | 輸出 doc 內 metadata，記錄每個 dimension 從哪個 source 來 |
+| **synthesis output** | 整合後的新 doc，附 provenance |
+
+## Execution Steps
+
+### Step 0: Bootstrap Stage Task List（強制）
+
+```
+TaskCreate(name="parse_arguments", description="解析 N 個 source path + 目標輸出格式 + 任何 dimension hint")
+TaskCreate(name="validate_sources", description="檢查 N ≥ 2 個 source 存在 + 格式一致（.tex / .md / .ipynb / .docx）")
+TaskCreate(name="extract_dimensions", description="依格式 dispatch extractor 抽 dimension list（.tex \\section / .md headings / .ipynb cells / .docx sections via che-word-mcp）")
+TaskCreate(name="show_comparison_table", description="per-dimension 印 N 個 source side-by-side preview，user 看完才決定")
+TaskCreate(name="gather_take_decisions", description="AskUserQuestion 或 batch mode：每個 dimension take A / B / hybrid / custom")
+TaskCreate(name="synthesize_output", description="按 take decisions assemble 輸出 doc，每個 dimension 加 provenance comment")
+TaskCreate(name="validate_output", description="格式驗證（.tex 編譯 / .ipynb JSON valid / .md render check）")
+TaskCreate(name="write_provenance_log", description="輸出 sidecar `<output>.synth.json` 記錄完整 take decision log")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+### Step 1: Parse Arguments
+
+支援的呼叫形式：
+
+```
+/docflow:doc-synth                                    # interactive，問所有參數
+/docflow:doc-synth A.tex B.tex                        # 2 source，輸出格式自動偵測
+/docflow:doc-synth A.tex B.tex C.tex --out merged.tex # 3 source 明確輸出
+/docflow:doc-synth A.ipynb B.ipynb --plan synth.json  # batch mode 讀預先寫好的 take decisions
+```
+
+### Step 2: Validate Sources
+
+```bash
+# Check N ≥ 2
+[ "$N_SOURCES" -ge 2 ] || abort "doc-synth requires ≥ 2 source documents"
+
+# Check format consistency
+EXTS=$(echo "$SOURCES" | xargs -n1 basename | sed 's/.*\.//' | sort -u)
+[ "$(echo "$EXTS" | wc -l)" -eq 1 ] || abort "All sources must be same format (got: $EXTS)"
+
+# Check files exist
+for s in $SOURCES; do [ -f "$s" ] || abort "Source not found: $s"; done
+```
+
+### Step 3: Extract Dimensions（per-format dispatch）
+
+| Format | Dimension definition | Extractor |
+|---|---|---|
+| `.tex` | `\section` / `\subsection` 之間的 chunk | regex on `\\(sub)*section\\{[^}]+\\}` |
+| `.md`  | `## H2` / `### H3` 之間的 chunk | regex on `^#+\s+(.+)$` |
+| `.ipynb` | individual cells（markdown + code） | parse JSON `cells[]` |
+| `.docx` | `Heading 1` / `Heading 2` 之間的 chunk | `mcp__plugin_che-word-mcp_word__get_all_sections` |
+
+每個 source 抽完後得到 dimension list:
+
+```python
+{
+  "A.tex": [
+    {"id": "section:Introduction", "title": "Introduction", "content": "..."},
+    {"id": "section:Method", "title": "Method", "content": "..."},
+    ...
+  ],
+  "B.tex": [
+    {"id": "section:Introduction", "title": "Introduction", "content": "..."},
+    ...
+  ]
+}
+```
+
+**Dimension matching**：
+- Identical title (case-insensitive) → match
+- Similar title (Levenshtein < 3) → ask user to confirm
+- Unique to one source → flag as "source-only", user decide keep/drop
+
+### Step 4: Show Comparison Table
+
+對每個 matched dimension 印 side-by-side preview：
+
+```
+Dimension: "Method"
+======================================================
+[A.tex]                          | [B.tex]
+------------------------------------------------------
+We estimate FE using plm,        | We compare Pooled, RE,
+clustering SE on individual...   | FE, FD using plm with
+                                 | cluster-robust SE (HC0)...
+======================================================
+```
+
+User 看完才決定 take。
+
+### Step 5: Gather Take Decisions
+
+對每個 dimension，AskUserQuestion 四選一（或 batch mode 從 plan JSON 讀）：
+
+| Option | 行為 |
+|---|---|
+| `take A` | 完全用 A 的內容 |
+| `take B` | 完全用 B 的內容 |
+| `hybrid` | 進 sub-flow：user 指定怎麼 blend（A 主體 + B 補一段 / 兩邊各取一半 / etc） |
+| `custom` | user 手寫該 dimension 內容（會 spawn `Write` flow） |
+| `skip` | drop 這個 dimension（不進 output） |
+
+把所有 decisions 累積成 plan JSON：
+
+```json
+{
+  "version": "1.0",
+  "created": "2026-05-12T...",
+  "sources": ["A.tex", "B.tex"],
+  "output": "merged.tex",
+  "decisions": [
+    {"dimension": "Introduction", "take": "A", "reason": "A 的 framing 較緊湊"},
+    {"dimension": "Method", "take": "B", "reason": "B 完整 Pooled/RE/FE/FD"},
+    {"dimension": "Discussion", "take": "hybrid", "hybrid_spec": "A 段 1+2 + B 段 3-4 + A 段 5"},
+    ...
+  ]
+}
+```
+
+### Step 6: Synthesize Output
+
+依 plan assemble 輸出 doc。每個 dimension 在 output 前加 provenance comment：
+
+```tex
+% [docflow:doc-synth provenance]
+% dimension: Method
+% source: B.tex
+% take: full
+% timestamp: 2026-05-12T...
+\section*{Method}
+...
+```
+
+`.ipynb` 用 cell metadata（不入內容）：
+
+```json
+{
+  "cell_type": "markdown",
+  "metadata": {
+    "docflow_synth": {
+      "dimension": "Method",
+      "source": "B.ipynb",
+      "take": "full"
+    }
+  },
+  "source": [...]
+}
+```
+
+### Step 7: Validate Output
+
+| Format | Validation |
+|---|---|
+| `.tex` | 試跑 `xelatex -interaction=nonstopmode`，看有沒有 fatal error |
+| `.md`  | render check（用 `cmark` 或 `pandoc -o /dev/null`）|
+| `.ipynb` | JSON parse + `jupyter nbconvert --to notebook --execute --inplace --dry-run`（如果有 kernel）|
+| `.docx` | che-word-mcp `open_document` + `get_document_info`，看 structure intact |
+
+驗證失敗 → 不 abort，把 error log 寫進 `.synth.json`，user 可手動修。
+
+### Step 8: Write Provenance Sidecar
+
+輸出 `<output_name>.synth.json` 完整記錄。**v1 schema reference**（dogfood-validated 2026-05-12）：
+
+```json
+{
+  "schema": "docflow.doc-synth.provenance.v1",
+  "version": "1.0",
+  "created": "ISO-8601 timestamp",
+  "skill": "docflow:doc-synth (v$VERSION) [+ context note]",
+  "sources": [
+    {
+      "label": "human-readable identifier",
+      "path": "relative or absolute path",
+      "sha256": "hex sha256 of source content",
+      "model_choice": "(optional) domain-specific summary, e.g. ARIMA model order",
+      "rationale_in_source": "(optional) why this source made the choice it did",
+      "note": "(optional) caveats, e.g. cross-language source used as reference only"
+    }
+  ],
+  "output": {
+    "path": "...",
+    "sha256": "...",
+    "pdf": "(optional) path to compiled output if applicable",
+    "pdf_pages": "(optional) page count if applicable",
+    "model_choice_adopted": "(optional) domain-specific final decision"
+  },
+  "evidence_chain": {
+    "key": "(optional) paths to supporting analysis scripts / rds / md files"
+  },
+  "decisions": [
+    {
+      "dimension": "section / cell / chunk identifier",
+      "take": "<source-label> | hybrid | custom | skip",
+      "augmentations": "(if hybrid) array of what was added/modified",
+      "reason": "why this take was chosen"
+    }
+  ],
+  "validation": {
+    "<format>_compile": "PASS / FAIL / N/A",
+    "errors": [],
+    "warnings": []
+  },
+  "dogfood_findings": "(optional, only on dogfood runs) limitations encountered + improvement proposals for next version"
+}
+```
+
+未來要 audit「為什麼 merged.tex 的 Method 段是這樣？」直接看 `.synth.json` → 看到「take=B, source=B.tex」就知道。第一次 production run 的 reference instance 在 `kiki830621/2026-winston:Winston_sync/ASSG3/M5373_Assg03_solution_final.synth.json`。
+
+## 3+ Source Mode
+
+v1.0 主要設計 2-source merge（A vs B → output）。3+ source 場景有兩個 pattern，**user 必須明確選**（v1.0 不自動推斷）：
+
+### Pattern α: One base + augmentations from evidence
+- 主要適用：當 N 個 source 角色不對等 — 一個是 base draft，其他是 evidence / reference
+- 行為：base 那份的內容直接 copy 進 output；其他 source 的內容**不 splice**，而是引出 augmentation paragraphs / sections 加進 output
+- 範例 use case：W-tex (base) + W-tex-revised (evidence on alternative model) + Gong-tex (cross-pipeline reference) → output adopts W-tex-revised structure + augments with Gong cross-pipeline note
+- Dogfood instance: ASSG3 final.tex synthesis (2026-05-12)
+
+### Pattern β: Majority vote per dimension
+- 主要適用：當 N 個 source 是 peer drafts（多版本回顧、多評審意見、多語版本）
+- 行為：per-dimension 列 N 個 source 內容，user 投票 / 多數決 / 挑選 winner
+- 未實作 — TODO
+
+**v1.0 default**：N=3+ 觸發時，AskUserQuestion 二選一（α / β）。選 β 時 fall back 到 N=2 sub-merges iteratively（先 merge A+B → 結果再 merge with C）並警告 user：β 的 v1 實作不完整。
+
+## Edge Cases
+
+### N = 1（只 1 個 source）
+Refuse — 用 `Edit` 或 `perspective-writer` 之類 single-source 工具，doc-synth 是 multi-source。
+
+### Sources 格式不一致
+Refuse — 例如 `A.tex` 跟 `B.ipynb` 沒有 well-defined dimension matching。先用 `pandoc` 等 convert 到同格式再來。
+
+### Same format, different natural language（dogfood-discovered 2026-05-12）
+**v1.0 不支援 line-level content merge across languages**。例如 A.tex (English) + B.tex (Chinese) — 兩邊都是 `.tex` 格式，dimension extraction 都跑得起來（`\section{}` regex 不受語言影響），但 take decision 之後要把 Chinese content splice 進 English output 沒辦法（沒 translation step，dimension content type-incompatible）。
+
+**Behavior**：
+- 偵測 source 語言（heuristic：每個 source 取前 200 字元 sample，跑 simple charset detection — Latin chars vs CJK chars）
+- 若兩個 source 主要語言不同 → Warn + 建議降級用法：「該 cross-language source 當 **evidence reference** 用（透過 Pattern α 的 augmentation paragraphs 引述其 findings），不當 **content source** 直接 splice」
+- 不 refuse — 因為 Pattern α 仍可用，只是 content take 受限
+
+**Future v2 augmentation**：integrate translation step（depends on llm-translate skill that doesn't exist yet）。
+
+**Dogfood instance**：ASSG3 synthesis 把 Gong-tex（Chinese）當 evidence reference，augmentation paragraphs 在 Q1c 引述「cross-pipeline note」概念但不 splice Chinese content。
+
+### Dimension 完全 disjoint（無 matching）
+Warn + 全列 source-only，user 決定 keep/drop 順序拼起來。
+
+### `.docx` 沒有 heading structure
+Fall back 到段落層 split（每 N 段一個 dimension），但提醒 user 結構粗略 — 建議先在 Word 內加 heading style。
+
+### `.ipynb` cell 順序不同
+Use cell metadata `id` 而非 index 配對；若兩邊都沒 ID（古早 ipynb），用 cell content hash 配對。
+
+## TODO（v1.0 ship 後）
+
+- [ ] **Batch plan mode**：predefined plan JSON 跳過 interactive
+- [x] **3+ source merge**：v1.0.1 加 Pattern α (one base + augmentations) 規範 + dogfood-validated；Pattern β (majority vote) 仍 TODO
+- [ ] **Hybrid spec DSL**：當前 hybrid 是 free-form text，未來可寫成 `A[1-2] + B[3-4] + A[5]` DSL
+- [ ] **Round-trip**：merged doc 改了之後能 propagate 回 sources（類似 git rebase backwards）
+- [x] **Multi-language source detection**：v1.0.1 加 charset heuristic + 降級為 evidence reference 建議；真正的 translation-based merge 仍 TODO（depends on llm-translate skill）
+- [ ] **Diff visualization**：merge 前印 unified diff（git-style）讓 user 看 dimension-level 改動
+
+## Version History
+
+- **v1.0.1** (2026-05-12) — Dogfood findings from first real synthesis (ASSG3 final.tex):
+  - Provenance sidecar schema formalized as `docflow.doc-synth.provenance.v1`
+  - 3+ Source Mode section added (Pattern α validated, Pattern β TODO)
+  - Cross-language edge case spec'd (charset heuristic + Pattern α fallback)
+  - First production reference instance: `kiki830621/2026-winston:Winston_sync/ASSG3/M5373_Assg03_solution_final.synth.json`
+- **v1.0.0** (2026-05-12) — Initial release (8 execution steps + 5 edge cases + TODO)
+
+## Related skills（future docflow plugin expansion）
+
+| Skill | 用途 | 對應本 session 經驗 |
+|---|---|---|
+| `doc-compare` | 兩版本 N 維度 side-by-side comparison.md 自動產出 | ASSG3 / ASSG4 / ML HW2 comparison.md × 3 |
+| `doc-verdict` | N 版本 per-question master_verdict.md 表格產出 | ASSG3 master_verdict.md |
+| `doc-multiimpl` | 強制 N alternative 都跑完整 implementation 再 commit | #13 IDD 升級 + #15 ASSG3 dogfood |
+| `doc-synth`（本 skill） | semantic merge 整合多 source 優點 | ML HW2 #14 hypothetical final_v2 |
+
+## References
+
+- 設計起源：kiki830621/2026-winston session 對話（ASSG3 retrospective + ML HW2 #14 won't-fix + 「merge vs synthesis vs revision」術語討論）
+- 對應 IDD pattern：`#13` multi-implementation 升級
+- 與 `che-word-mcp` 整合：`.docx` extraction 用 `get_all_sections` / `get_paragraphs`
+- 與 `perspective-writer` 區別：後者單 source 改寫，本 skill 多 source synthesis
diff --git a/plugins/gifthub/.claude-plugin/plugin.json b/plugins/gifthub/.claude-plugin/plugin.json
new file mode 100644
index 00000000..a1bb5000
--- /dev/null
+++ b/plugins/gifthub/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "gifthub",
+  "description": "GiftHub CLI integration — auto-detect GiftHub config (v2 .claude/.gfs/config.json or v1 .gfh.json), inject usage context, auto-install after build",
+  "version": "1.2.0",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/gifthub/.claude-plugin/settings.json b/plugins/gifthub/.claude-plugin/settings.json
new file mode 100644
index 00000000..0fb68826
--- /dev/null
+++ b/plugins/gifthub/.claude-plugin/settings.json
@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $PLUGIN_DIR/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash $PLUGIN_DIR/hooks/auto-install.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/gifthub/CHANGELOG.md b/plugins/gifthub/CHANGELOG.md
new file mode 100644
index 00000000..ae75f675
--- /dev/null
+++ b/plugins/gifthub/CHANGELOG.md
@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.2.0] - 2026-05-10
+
+### Changed
+- **Detect v2 config layout `.claude/.gfs/config.json` first，fallback v1 `.gfh.json`**（與 [`PsychQuant/GiftHub#17`](https://github.com/PsychQuant/GiftHub/issues/17) 配對）
+  - `hooks/session-start.sh`：改 detection logic，inject context 含 `Layout: v1|v2 (path)` 標示
+  - `skills/gfh-import/SKILL.md`：Prerequisites + Step 1 read config 用 v2 priority chain
+  - `plugin.json` description 同步描述
+
+### Coordinated upstream
+- 對應 GiftHub CLI v0.4.0+ 把 default config 寫到 `.claude/.gfs/`。Plugin v1.2 backward-compat 兩 layout，consumer 升 gfh 與 plugin 不需特定順序。
+
+## [1.1.0] - (date unknown — please fill in)
+
+### Changed
+- GiftHub CLI integration — auto-detect .gfh.json, inject usage context, auto-install after build
diff --git a/plugins/gifthub/CLAUDE.md b/plugins/gifthub/CLAUDE.md
new file mode 100644
index 00000000..ea1cb26e
--- /dev/null
+++ b/plugins/gifthub/CLAUDE.md
@@ -0,0 +1,42 @@
+# gifthub Plugin
+
+GiftHub CLI integration for Claude Code.
+
+## What It Does
+
+1. **SessionStart hook**: Detects GiftHub config（v2 `.claude/.gfs/config.json` 優先 / v1 `.gfh.json` fallback）and injects GiftHub usage context (commands, pointer file count, layout 標示)
+2. **Auto-install hook**: After `swift build` succeeds in the GiftHub dev repo, automatically does release build + copies `gfh` to `~/bin/`
+3. **Skills**: `/gifthub:gfh-status` shows repo GiftHub status, `/gifthub:gfh-import` imports Drive files into repo
+
+## Config layout
+
+| Layout | Default since | 路徑 |
+|--------|--------------|-----|
+| **v2** | gfh CLI v0.4.0 + plugin v1.2 | `.claude/.gfs/config.json` + `.claude/.gfs/aliases.json` + `.claude/.gfs/registry.json` |
+| **v1** | gfh CLI ≤ v0.3.x | `.gfh.json` + `lfs-registry-aliases.json` + `lfs-registry.json`（root） |
+
+新 `gfh init` 寫 v2；既有 v1 repo 仍 work（plugin hook + gfh CLI 都偵測 fallback）。
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/gifthub:gfh-status` | Show pointer count, Drive config, hook status |
+| `/gifthub:gfh-import` | Import a Drive file: `gws move` → `gfh link` → `gfh pull` |
+
+## Key Workflow: `gfh link` → `gfh pull`
+
+When a file already exists on Google Drive (e.g., Meet recordings), the optimal import flow is:
+
+1. **`gws drive files update`** — move + rename to GiftHub-LFS folder on Drive
+2. **`gfh link <drive-id> <local-path>`** — compute SHA-256 via streaming, create pointer + alias (no download needed)
+3. **`gfh pull <path>`** — download the actual file from Drive
+
+This avoids the download → upload round-trip of the traditional `git add` → `gfh push` workflow.
+
+## Hooks
+
+| Hook | Trigger | Action |
+|------|---------|--------|
+| `session-start.sh` | SessionStart | Detect v2 (`.claude/.gfs/config.json`) or v1 (`.gfh.json`), inject context with layout label |
+| `auto-install.sh` | PostToolUse (Bash) | After `swift build` in GiftHub repo → release build + install to `~/bin/` |
diff --git a/plugins/gifthub/hooks/auto-install.sh b/plugins/gifthub/hooks/auto-install.sh
new file mode 100755
index 00000000..74f9eea6
--- /dev/null
+++ b/plugins/gifthub/hooks/auto-install.sh
@@ -0,0 +1,39 @@
+#!/bin/bash
+# GiftHub PostToolUse hook — auto-install gfh after successful swift build
+#
+# Triggers on: Bash tool calls containing "swift build" that succeeded
+# Only in the GiftHub development repo
+
+# Read hook data from stdin (JSON)
+HOOK_DATA=$(cat)
+COMMAND=$(echo "$HOOK_DATA" | jq -r '.tool_input.command // empty')
+
+# Only in GiftHub repo
+if [ ! -f "Package.swift" ] || ! grep -q '"GiftHub"' Package.swift 2>/dev/null; then
+  exit 0
+fi
+
+# Check if the command contains swift build
+if ! echo "$COMMAND" | grep -q "swift build"; then
+  exit 0
+fi
+
+# Skip if it was already a release build (avoid infinite loop)
+if echo "$COMMAND" | grep -q "\-c release"; then
+  exit 0
+fi
+
+# Check the build actually succeeded (look for "Build complete" in output)
+TOOL_OUTPUT=$(echo "$HOOK_DATA" | jq -r '.tool_response // empty')
+if ! echo "$TOOL_OUTPUT" | grep -q "Build complete"; then
+  exit 0
+fi
+
+# Do the release build + install
+swift build -c release -q 2>/dev/null
+if [ $? -eq 0 ]; then
+  cp .build/release/gfh "$HOME/bin/gfh"
+  echo "gfh auto-installed to ~/bin/gfh"
+else
+  echo "gfh release build failed — skipping auto-install"
+fi
diff --git a/plugins/gifthub/hooks/session-start.sh b/plugins/gifthub/hooks/session-start.sh
new file mode 100755
index 00000000..746d4299
--- /dev/null
+++ b/plugins/gifthub/hooks/session-start.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+# GiftHub SessionStart hook — detect GiftHub config and inject context
+
+# v0.4.0: detect v2 layout (.claude/.gfs/config.json) first, fallback to v1 (.gfh.json)
+# 任一存在即視為 GiftHub-enabled repo
+if [ -f ".claude/.gfs/config.json" ]; then
+  GFH_LAYOUT="v2"
+  GFH_CONFIG=".claude/.gfs/config.json"
+elif [ -f ".gfh.json" ]; then
+  GFH_LAYOUT="v1"
+  GFH_CONFIG=".gfh.json"
+else
+  exit 0
+fi
+
+GFH_BIN="$HOME/bin/gfh"
+GFH_REPO="PsychQuant/GiftHub"
+UPDATE_MSG=""
+
+if [ -x "$GFH_BIN" ]; then
+  LOCAL_VERSION=$("$GFH_BIN" version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
+
+  # Check for updates (quick, non-blocking)
+  LATEST_VERSION=$(curl -fsSL --max-time 3 "https://api.github.com/repos/$GFH_REPO/releases/latest" 2>/dev/null | grep '"tag_name"' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+
+  if [ -n "$LATEST_VERSION" ] && [ "$LOCAL_VERSION" != "$LATEST_VERSION" ] && [ "$LOCAL_VERSION" != "unknown" ]; then
+    UPDATE_MSG="⬆️  gfh v${LOCAL_VERSION} → v${LATEST_VERSION} available
+   Update: curl -fsSL https://github.com/$GFH_REPO/releases/latest/download/gfh -o $GFH_BIN && chmod +x $GFH_BIN"
+    GFH_STATUS="gfh v$LOCAL_VERSION (update available: v$LATEST_VERSION)"
+  else
+    GFH_STATUS="gfh v$LOCAL_VERSION"
+  fi
+else
+  GFH_STATUS="gfh NOT FOUND"
+  UPDATE_MSG="Install: curl -fsSL https://github.com/$GFH_REPO/releases/latest/download/gfh -o ~/bin/gfh && chmod +x ~/bin/gfh"
+fi
+
+# Count pointer files
+POINTER_COUNT=$(git ls-files 2>/dev/null | while read f; do
+  if [ -f "$f" ] && [ "$(wc -c < "$f" 2>/dev/null)" -lt 200 ]; then
+    head -1 "$f" 2>/dev/null | grep -q "^version https://git-lfs" && echo "$f"
+  fi
+done | wc -l | tr -d ' ')
+
+# Print update notice first (if any)
+if [ -n "$UPDATE_MSG" ]; then
+  echo "$UPDATE_MSG"
+fi
+
+cat <<EOF
+# GiftHub Detected
+
+$GFH_STATUS | Pointers: $POINTER_COUNT | Layout: $GFH_LAYOUT ($GFH_CONFIG)
+
+## Commands
+| Command | Purpose |
+|---------|---------|
+| \`gfh pull [files...]\` | Download LFS objects from Google Drive |
+| \`gfh upload <files...>\` | Upload to Drive + create LFS pointers |
+| \`gfh clone <url>\` | Clone repo + auto-configure + pull |
+| \`gfh dehydrate\` | Replace local files with pointers |
+
+## Note
+- Files < 200 bytes starting with \`version https://git-lfs\` are **LFS pointers** — run \`gfh pull\` to restore
+- \`git push\` is safe (pre-push hook skips LFS upload)
+- Use \`--concurrency N\` for parallel transfers (default 4)
+EOF
diff --git a/plugins/gifthub/skills/gfh-import/SKILL.md b/plugins/gifthub/skills/gfh-import/SKILL.md
new file mode 100644
index 00000000..87337a82
--- /dev/null
+++ b/plugins/gifthub/skills/gfh-import/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: gfh-import
+description: Import a Google Drive file into a GiftHub repo — move to LFS folder, create pointer, and pull. Use when user says "download recording", "import video", "把 Drive 檔案拉下來", "gfh import".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# /gfh-import — Import Drive File into GiftHub
+
+Move a Google Drive file into the GiftHub-LFS folder, create an LFS pointer via `gfh link`, and optionally pull the actual file.
+
+## Prerequisites
+
+- GiftHub config exists：`.claude/.gfs/config.json`（v2 layout，預設）或 `.gfh.json`（v1 layout，backward-compat）
+- `gfh` CLI installed (`~/bin/gfh`)
+- `gws` CLI installed (Google Workspace CLI)
+
+## Execution
+
+### Step 1: Read repo config
+
+```bash
+# v0.4.0+：自動 resolve v2 path 優先，v1 fallback
+if [ -f ".claude/.gfs/config.json" ]; then
+  cat .claude/.gfs/config.json
+elif [ -f ".gfh.json" ]; then
+  cat .gfh.json
+fi
+```
+
+Extract:
+- `driveFolderId` — the GiftHub-LFS folder on Drive
+- `registryPath` / `aliasRegistryPath` — alias file path
+
+### Step 2: Determine source file
+
+**If user provides a Drive file ID or URL:**
+- Extract file ID from URL (format: `https://drive.google.com/file/d/{ID}/...`)
+- Verify file exists: `gws drive files get --params '{"fileId":"ID","fields":"id,name,size,parents"}'`
+
+**If user says "latest Meet recording" or similar:**
+- Read project CLAUDE.md for Meet Recordings folder ID
+- List recent files: `gws drive files list --params '{"q":"FOLDER_ID in parents","fields":"files(id,name,size,createdTime)","orderBy":"createdTime desc","pageSize":5}'`
+- Ask user to confirm which file
+
+### Step 3: Determine local path
+
+**If user provides a local path:** use it directly.
+
+**If not:** ask user. Suggest based on project conventions (e.g., from CLAUDE.md naming patterns).
+
+### Step 4: Move + rename on Drive
+
+Move the file from its current folder to the GiftHub-LFS folder, and rename if needed:
+
+```bash
+gws drive files update \
+  --params '{"fileId":"FILE_ID","addParents":"GFH_FOLDER_ID","removeParents":"SOURCE_FOLDER_ID"}' \
+  --json '{"name":"NEW_NAME.mp4"}'
+```
+
+- `addParents`: GiftHub-LFS folder ID (from config — v2 `.claude/.gfs/config.json` or v1 `.gfh.json`)
+- `removeParents`: the file's current parent folder ID (from Step 2 metadata)
+- `name`: new filename matching project convention
+
+**Skip if file is already in the GiftHub-LFS folder.**
+
+### Step 5: Create LFS pointer via `gfh link`
+
+```bash
+gfh link "FILE_ID" "LOCAL_PATH"
+```
+
+This will:
+1. Stream the file from Drive to compute SHA-256 (no full download needed)
+2. Create a local pointer file (135 bytes)
+3. Register the SHA → Drive ID alias in `lfs-registry-aliases.json`
+
+### Step 6: Pull the actual file
+
+```bash
+gfh pull "LOCAL_PATH"
+```
+
+Downloads the full file from Drive, replacing the pointer.
+
+### Step 7: Git add (optional)
+
+Ask user if they want to stage the file:
+
+```bash
+git add "LOCAL_PATH"
+```
+
+### Step 8: Report
+
+```
+✅ Imported: {filename}
+   Drive ID: {id}
+   Local: {path}
+   Size: {size}
+   Status: hydrated (full file)
+```
+
+## Error Handling
+
+- **`gfh link` fails**: Check if `gfh` version supports `link` (requires v0.3.0+). Suggest `~/bin/gfh version`.
+- **`gfh pull` fails (500 from Drive)**: File may still be processing on Google's side (common with fresh Meet recordings). Suggest waiting 10-30 minutes and retrying, or manual browser download.
+- **File already exists locally**: Ask user whether to overwrite or skip.
+
+## Notes
+
+- `gfh link` is preferred over downloading first + `gfh push`, because it avoids a full download-then-reupload cycle — the file stays on Drive, only the SHA is computed via streaming.
+- Project-specific parameters (Meet folder ID, naming conventions, target directories) come from the project's CLAUDE.md, not this skill. This skill only handles the generic GiftHub import workflow.
diff --git a/plugins/gifthub/skills/gfh-status/SKILL.md b/plugins/gifthub/skills/gfh-status/SKILL.md
new file mode 100644
index 00000000..e4b7ff78
--- /dev/null
+++ b/plugins/gifthub/skills/gfh-status/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: gfh-status
+description: Show GiftHub status — pointer file count, registry info, and Drive connection status. Use when user asks about GiftHub state in current repo.
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# /gfh-status — GiftHub Repo Status
+
+Show the current state of GiftHub in this repo.
+
+## Steps
+
+1. Check `.gfh.json` exists — if not, report "Not a GiftHub repo"
+2. Read `.gfh.json` to get Drive folder ID
+3. Count total files tracked by git: `git ls-files | wc -l`
+4. Count pointer files (< 200 bytes, starts with `version https://git-lfs`)
+5. Count hydrated files (tracked by LFS but not pointers)
+6. Check `~/bin/gfh` exists and get version
+7. Check if pre-push hook is installed: `cat .git/hooks/pre-push`
+
+## Output Format
+
+```
+## GiftHub Status
+
+| Item | Value |
+|------|-------|
+| Drive folder | {id} |
+| gfh version | {version} |
+| Total tracked | {N} files |
+| Pointers | {N} (need `gfh pull`) |
+| Hydrated | {N} |
+| Pre-push hook | installed / missing |
+```
diff --git a/plugins/issue-driven-dev/.claude-plugin/plugin.json b/plugins/issue-driven-dev/.claude-plugin/plugin.json
deleted file mode 100644
index 12e21c94..00000000
--- a/plugins/issue-driven-dev/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "name": "issue-driven-dev",
-  "description": "Issue-driven development methodology: issue → diagnose → implement → verify → close. Every change traces back to an issue, every issue has a verified resolution.",
-  "version": "2.4.2",
-  "author": {
-    "name": "Che Cheng"
-  },
-  "license": "MIT",
-  "keywords": ["github", "issues", "methodology", "tdd", "code-review", "workflow", "codex"]
-}
diff --git a/plugins/issue-driven-dev/CLAUDE.md b/plugins/issue-driven-dev/CLAUDE.md
deleted file mode 100644
index a3d9aeaf..00000000
--- a/plugins/issue-driven-dev/CLAUDE.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# issue-driven-dev — CLAUDE.md
-
-## Purpose
-
-Issue-driven development：每個改動都從 issue 出發，每個 issue 都有驗證過的結案。
-
-Issue 是人和 AI 的介面 — 人負責「什麼是對的」，AI 負責「怎麼做到」。
-
-## Skills
-
-| Skill | 防止的失敗 | 用途 |
-|-------|-----------|------|
-| `idd-issue` | 改了東西卻沒有記錄「為什麼改」 | 建立 well-documented GitHub Issue |
-| `idd-diagnose` | 修了表象，沒修根本原因 | 找 root cause / 分析需求 |
-| `idd-implement` | Scope creep | 按 diagnosis 紀律實作 |
-| `idd-verify` | 自以為修好了 | 用 Codex CLI 獨立驗證 |
-| `idd-close` | 三個月後沒人知道做了什麼 | 寫 closing comment + 關 issue |
-
-## Workflow
-
-```
-issue → diagnose → implement → verify → close
-  ①        ②          ③         ④       ⑤
-
-每個 skill 都吃 #NNN，issue 貫穿全部。
-```
-
-## Configuration
-
-首次使用時會建立 `.claude/issue-driven-dev.local.md`：
-
-```yaml
----
-github_repo: "owner/repo"
-github_owner: "owner"
-attachments_release: "attachments"
----
-```
-
-## 設計哲學
-
-### 五個 Skill = 五個 Checkpoint
-
-每個 skill 是一個強制停頓點：
-
-| Checkpoint | 確認什麼 |
-|-----------|---------|
-| `idd-issue` 之後 | 我們同意問題是什麼了嗎？ |
-| `idd-diagnose` 之後 | 我們理解為什麼了嗎？ |
-| `idd-implement` 之後 | 我們只改了該改的嗎？ |
-| `idd-verify` 之後 | 真的修好了嗎？ |
-| `idd-close` 之後 | 記錄完整嗎？ |
-
-### 與其他方法論的差異
-
-本 plugin 是 **issue-driven**（問題驅動），不是 process-driven（流程驅動）。
-所有決策都圍繞 `#NNN`，不是圍繞流程步驟。
-
-### 參考
-
-- **superpowers** (claude-plugins-official) — 小粒度 skill 設計、verification 獨立化
-- 本 plugin 的優勢：per-project config (`.local.md`)、具體 CLI 指令
-
-## Development
-
-- Update after changes: `/plugin-tools:plugin-update issue-driven-dev`
-- Health check: `/plugin-tools:plugin-health`
diff --git a/plugins/issue-driven-dev/README.md b/plugins/issue-driven-dev/README.md
deleted file mode 100644
index 7381c967..00000000
--- a/plugins/issue-driven-dev/README.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# issue-driven-dev
-
-Human defines the problem, AI solves it.
-
-## What is this?
-
-A Claude Code plugin that enforces issue-driven development as a complete methodology:
-
-1. **Every change starts with an issue** — the single source of truth
-2. **Every issue is diagnosed before implementation** — no guessing
-3. **Every implementation is scope-controlled** — no creep
-4. **Every completion is independently verified** — no "looks good enough"
-5. **Every closure is documented** — knowledge preserved
-
-## Why?
-
-Each skill guards against a specific failure mode:
-
-| Failure | Without this plugin | With this plugin |
-|---------|---------------------|-----------------|
-| No documentation | Changes with no recorded reason | Every change traces to an issue |
-| Surface-level fixes | Patch symptoms, root cause returns | Diagnosis required before implementation |
-| Scope creep | Fix #42, refactor 3 unrelated files | Scope guardian flags unrelated changes |
-| False confidence | "Should work" → ship broken code | Independent AI verification (Codex) |
-| Lost knowledge | "What did we do?" 3 months later | Mandatory closing comment |
-
-## Skills
-
-```
-idd-issue → idd-diagnose → idd-implement → idd-verify → idd-close
-    ①            ②              ③              ④            ⑤
-```
-
-| Skill | Purpose |
-|-------|---------|
-| `idd-issue` | Create well-documented GitHub Issue with original quotes and images |
-| `idd-diagnose` | Find root cause (bug) or analyze requirements (feature/refactor) |
-| `idd-implement` | Scope-disciplined implementation with TDD |
-| `idd-verify` | Independent verification using Codex CLI (gpt-5.4) |
-| `idd-close` | Closing comment documenting problem, root cause, solution, verification |
-
-## Quick Start
-
-```bash
-# Install
-/plugin marketplace add https://github.com/PsychQuant/psychquant-claude-plugins
-/plugin install issue-driven-dev
-
-# Use (auto-completion: type "idd-" to see all skills)
-/idd-issue "upload button doesn't work on mobile"
-/idd-diagnose #42
-/idd-implement #42
-/idd-verify #42
-/idd-close #42
-```
-
-## Configuration
-
-On first use, creates `.claude/issue-driven-dev.local.md`:
-
-```yaml
----
-github_repo: "owner/repo"
-github_owner: "owner"
-attachments_release: "attachments"
----
-```
-
-## Requirements
-
-- `gh` CLI authenticated with GitHub
-- [OpenAI Codex CLI](https://github.com/openai/codex) installed (for `idd-verify`)
-- ChatGPT Pro account (for Codex gpt-5.4)
diff --git a/plugins/issue-driven-dev/skills/idd-close/SKILL.md b/plugins/issue-driven-dev/skills/idd-close/SKILL.md
deleted file mode 100644
index 26cdb7a6..00000000
--- a/plugins/issue-driven-dev/skills/idd-close/SKILL.md
+++ /dev/null
@@ -1,98 +0,0 @@
----
-name: idd-close
-description: |
-  寫 closing comment 並關閉 GitHub Issue。
-  強制記錄做了什麼、怎麼驗證的。
-  Use when: verify 通過後、commit 之後。
-  防止的失敗：修完了但三個月後沒人知道當時做了什麼。
-argument-hint: "#issue e.g. '#42'"
-allowed-tools:
-  - Bash(gh:*)
-  - Bash(git:*)
-  - Read
-  - AskUserQuestion
----
-
-# /close — 結案
-
-寫 closing comment，然後關閉 issue。三分鐘的紀錄，省三十分鐘的考古。
-
-## 核心原則
-
-> 沒有 closing comment 就不關 issue。沒有例外。
-
-## Execution
-
-### Step 1: 檢查前置條件
-
-```bash
-gh issue view $NUMBER --repo $GITHUB_REPO --json state,title,body
-```
-
-確認：
-- Issue 是 open 狀態
-- 有相關的 commit 引用 #NNN
-
-```bash
-git log --oneline --grep="#$NUMBER" | head -10
-```
-
-如果沒有相關 commit，警告使用者：「找不到引用 #NNN 的 commit。確定要關嗎？」
-
-### Step 2: 寫 Closing Comment
-
-根據 issue body、diagnosis、commits 自動生成：
-
-```markdown
-## Closing Summary
-
-### Problem
-{問題是什麼，影響範圍}
-
-### Root Cause
-{為什麼會發生（bug）/ 需求背景（feature）}
-
-### Solution
-{改了什麼，關鍵邏輯}
-
-### Verification
-{怎麼驗證的：verify 結果、測試、截圖}
-
-### Changes
-{相關 commit 列表}
-```
-
-### Step 3: 確認
-
-將 closing comment 顯示給使用者確認。
-
-### Step 4: 發佈並關閉
-
-```bash
-gh issue comment $NUMBER --repo $GITHUB_REPO --body "$CLOSING_COMMENT"
-gh issue close $NUMBER --repo $GITHUB_REPO
-```
-
-> **數學公式格式**：GitHub 支援 `$...$`（inline）和 `$$...$$`（display）。含底線的程式變數名**不放 math mode**，改用 backtick code。
-
-### Step 5: 回報
-
-```
-✓ Issue #NNN closed
-  Closing comment: {URL}
-  Commits: {list}
-```
-
-## Closing Comment 的價值
-
-| 沒有 closing comment | 有 closing comment |
-|---------------------|-------------------|
-| 三個月後：「這個 issue 改了什麼？」→ 翻 git log 猜 | 三個月後：直接看 closing comment |
-| 類似 bug 再出現：「上次怎麼修的？」→ 不知道 | 類似 bug 再出現：參考上次的 root cause + solution |
-| 新人接手：「為什麼這段 code 長這樣？」→ 沒人知道 | 新人接手：issue 裡有完整的脈絡 |
-
-## 鐵律
-
-- **不跳過 closing comment**。即使是小 fix 也要寫。
-- **Closing comment 要有 Root Cause**。「改了 X」不夠，要寫「因為 Y 所以改了 X」。
-- **列出所有相關 commit**。讓 issue 成為這次改動的完整入口。
diff --git a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md b/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md
deleted file mode 100644
index b0574990..00000000
--- a/plugins/issue-driven-dev/skills/idd-diagnose/SKILL.md
+++ /dev/null
@@ -1,155 +0,0 @@
----
-name: idd-diagnose
-description: |
-  對照 GitHub Issue 找 root cause（bug）或分析需求（feature/refactor）。
-  輸出 diagnosis report：原因、影響範圍、修復/實作策略。
-  Use when: issue 建立後、開始寫 code 之前。
-  防止的失敗：修了表象，沒修根本原因。
-argument-hint: "#issue e.g. '#42'"
-allowed-tools:
-  - Bash(gh:*)
-  - Bash(git:*)
-  - Bash(grep:*)
-  - Bash(find:*)
-  - Read
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-# /diagnose — 理解問題
-
-在寫任何一行 code 之前，先確認你真的理解問題。
-
-## 核心原則
-
-> 不理解問題就動手 = 修表象。修表象 = 問題會回來。
-
-## Execution
-
-### Step 1: 讀取 Issue
-
-```bash
-gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels,comments
-```
-
-識別 issue type：bug / feature / refactor / docs。
-
-### Step 2: 依類型診斷
-
-#### Bug → Root Cause Analysis
-
-1. **重現問題**
-   - 找到觸發條件
-   - 如果不能穩定重現 → 蒐集更多資訊，不要猜
-
-2. **Trace 資料流**
-   - 從錯誤訊息 / stack trace 出發
-   - 往上追到源頭：壞的值是從哪裡來的？
-   - 每個環節都確認，不跳過
-
-3. **檢查最近的變更**
-   ```bash
-   git log --oneline -20
-   git diff HEAD~5
-   ```
-   - 什麼改動可能引發這個問題？
-
-4. **找到 working example**
-   - Codebase 裡有沒有類似的、正常運作的 code？
-   - 壞的跟好的差在哪裡？
-
-5. **形成假設**
-   - 明確陳述：「我認為 root cause 是 X，因為 Y」
-   - 一次一個假設，不要同時猜多個
-
-#### Feature → 需求分析
-
-1. **拆解需求**
-   - Issue 要求的每個功能點列出來
-   - 模糊的地方標出來，詢問使用者
-
-2. **影響範圍**
-   - 需要改哪些檔案？
-   - 有沒有既有的 pattern 可以參考？
-
-3. **實作策略**
-   - 有幾種做法？各自的 trade-off？
-   - 推薦哪種？為什麼？
-
-#### Refactor → 現狀分析
-
-1. **為什麼要重構**
-   - 現在的問題是什麼？（效能？可讀性？耦合？）
-
-2. **風險評估**
-   - 改動範圍多大？
-   - 有沒有 test coverage 保護？
-   - 有沒有隱藏的依賴？
-
-3. **重構策略**
-   - 一步到位還是漸進式？
-   - 如何確保行為不變？
-
-### Step 3: 輸出 Diagnosis Report
-
-產生 diagnosis report 並 **comment 到 issue 底下**（預設行為）：
-
-```markdown
-## Diagnosis
-
-### Type
-{bug / feature / refactor}
-
-### Root Cause / Analysis
-{bug: root cause + evidence}
-{feature: requirements breakdown}
-{refactor: current state + problems}
-
-### Impact
-- 影響的檔案：...
-- 影響的使用者流程：...
-
-### Strategy
-{具體的修復 / 實作計畫}
-- [ ] 改 A
-- [ ] 改 B
-- [ ] 加測試 C
-
-### Risks
-{可能出錯的地方}
-```
-
-```bash
-gh issue comment $NUMBER --repo $GITHUB_REPO --body "$DIAGNOSIS_REPORT"
-```
-
-> **數學公式格式**：GitHub 支援 `$...$`（inline）和 `$$...$$`（display）math mode。
-> 含底線的程式變數名（如 `mse_info`）**不放進 math mode** — KaTeX 無法可靠渲染底線跳脫。
-> 改用混合寫法：數學部分用 `$R_I = J \cdot$`，變數名用 backtick code `` `mse_info` ``。
-> 純數學符號（$\theta$, $\hat{d}_J$ 等）放 math mode 沒問題。
-
-> **為什麼 comment 到 issue？** Diagnosis 是 issue 的一部分 — 三個月後回來看，issue 裡就有完整的「問題 → 診斷 → 解法」脈絡，不用翻對話紀錄。
-
-同時在對話中顯示 report，讓使用者可以即時確認。
-
-### Step 4: 確認
-
-詢問使用者：「Diagnosis 已 comment 到 #NNN。正確嗎？要調整策略嗎？」
-
-- 如果要調整 → 修改後用 `gh issue comment` 追加修正
-- 確認後提示下一步：`/issue-driven-dev:idd-implement #NNN`
-
-## 鐵律
-
-- **不跳過 diagnosis**。就算「很明顯」也要做。簡單的問題做 diagnosis 只要 2 分鐘，但省下的是 2 小時的重工。
-- **發現多個問題 → 開新 issue**。一個 issue 修一個問題。
-- **不確定就問**。問使用者比猜測好。
-
-## Next Step
-
-Diagnosis 確認後，進入 `implement`：
-
-```
-/issue-driven-dev:idd-implement #NNN
-```
diff --git a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md b/plugins/issue-driven-dev/skills/idd-implement/SKILL.md
deleted file mode 100644
index debdb2d0..00000000
--- a/plugins/issue-driven-dev/skills/idd-implement/SKILL.md
+++ /dev/null
@@ -1,163 +0,0 @@
----
-name: idd-implement
-description: |
-  按照 diagnosis 的策略實作，嚴格控制 scope。
-  只改 issue 要求的東西，每個 commit 引用 #NNN。
-  Use when: diagnosis 確認後、開始寫 code 時。
-  防止的失敗：scope creep — 改 #42 順手重構了三個不相關的檔案。
-argument-hint: "#issue e.g. '#42'"
-allowed-tools:
-  - Bash(gh:*)
-  - Bash(git:*)
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-# /implement — 紀律實作
-
-按 diagnosis 的策略寫 code，不多做也不少做。
-
-## 核心原則
-
-> 每一行改動都必須能追溯到 #NNN。追溯不到的改動 → 開新 issue。
-
-## Execution
-
-### Step 1: 讀取 Issue + Diagnosis
-
-```bash
-gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels
-```
-
-回顧對話中的 diagnosis report，確認 strategy。
-
-### Step 2: 列出變更清單並 comment 到 issue
-
-根據 diagnosis 的 strategy，列出具體要改的檔案：
-
-```markdown
-## Implementation Plan
-
-- [ ] 修改 src/foo.ts — {改什麼}
-- [ ] 修改 src/bar.ts — {改什麼}
-- [ ] 新增 tests/foo.test.ts — {測什麼}
-```
-
-**Scope check**: 清單裡的每一項都能對應到 issue 的某個要求？
-- 對應不上 → 移除，或開新 issue
-- Issue 的要求沒被覆蓋 → 補上
-
-**Comment 到 issue**（留下實作計畫的紀錄）：
-
-```bash
-gh issue comment $NUMBER --repo $GITHUB_REPO --body "$IMPLEMENTATION_PLAN"
-```
-
-### Step 3: TDD 執行
-
-每個變更項依序執行：
-
-1. **寫測試**（RED）
-   - 測試描述用 issue 的語言
-   - 測 behavior，不測 implementation
-
-2. **跑測試確認失敗**
-   - 失敗原因必須是「功能還沒實作」，不是「測試寫錯」
-
-3. **寫最小實作**（GREEN）
-   - 只寫讓測試通過的 code
-   - 不「順便」優化、重構、加功能
-
-4. **跑測試確認通過**
-   - 全部測試，不只新的
-
-5. **Commit**
-   ```bash
-   git add {changed files}
-   git commit -m "fix: {description} (#NNN)"
-   ```
-
-### Step 4: Scope 守衛
-
-實作過程中發現的問題：
-
-| 發現 | 處理 |
-|------|------|
-| 不相關的 bug | 開新 issue，繼續 #NNN |
-| 不相關的 code smell | 開新 issue，繼續 #NNN |
-| #NNN 的前置依賴 | 確認是否 blocker。是 → 先處理依賴；不是 → 記錄在 issue comment |
-| 比預期更大的改動 | 停下來，回到 diagnosis 重新評估 |
-
-**鐵律**：不在 #NNN 的 branch 上修不相關的東西。
-
-### Step 5: 完成確認並 comment 到 issue
-
-所有變更清單項目完成後：
-
-```bash
-git status --short
-git diff --stat HEAD~{N}
-```
-
-回顧：
-- 每個 commit 都引用了 #NNN？
-- 變更範圍跟 diagnosis 的 strategy 一致？
-- 沒有超出 scope 的改動？
-
-**如果有產出圖表**，上傳到 attachments release：
-
-```bash
-# 讀取 .claude/issue-driven-dev.local.md 的 attachments_release 設定
-gh release upload $ATTACHMENTS_RELEASE {figure_files}.png \
-  --repo $GITHUB_REPO --clobber
-```
-
-圖片 URL 格式：`https://github.com/$GITHUB_REPO/releases/download/$ATTACHMENTS_RELEASE/{filename}.png`
-
-**Comment 實作摘要到 issue**（含圖片）：
-
-```bash
-gh issue comment $NUMBER --repo $GITHUB_REPO --body "$(cat <<'EOF'
-## Implementation Complete
-
-### Changes
-- {commit 1 hash}: {description}
-- {commit 2 hash}: {description}
-
-### Files Changed
-{git diff --stat output}
-
-### Figures (if any)
-![{description}](https://github.com/$GITHUB_REPO/releases/download/$ATTACHMENTS_RELEASE/{filename}.png)
-
-### Scope Compliance
-{是否有超出範圍的改動，如有則說明}
-
-### Next: verification pending
-EOF
-)"
-```
-
-提示下一步：`/issue-driven-dev:idd-verify #NNN`
-
-## Commit 規範
-
-```
-<type>: <description> (#NNN)
-```
-
-- type: fix / feat / refactor / docs / test
-- description: 用 issue 的語言描述改了什麼
-- **必須**包含 `(#NNN)` 或 `#NNN`
-
-## Next Step
-
-實作完成後，進入 `verify`：
-
-```
-/issue-driven-dev:idd-verify #NNN
-```
diff --git a/plugins/issue-driven-dev/skills/idd-issue/SKILL.md b/plugins/issue-driven-dev/skills/idd-issue/SKILL.md
deleted file mode 100644
index 8b580165..00000000
--- a/plugins/issue-driven-dev/skills/idd-issue/SKILL.md
+++ /dev/null
@@ -1,137 +0,0 @@
----
-name: idd-issue
-description: |
-  建立 well-documented GitHub Issue。每個改動的起點。
-  Use when: 報 bug、追蹤需求、任何需要正式記錄的工作。
-  防止的失敗：改了東西卻沒有文件記錄「為什麼改」。
-argument-hint: "[description or path to .docx]"
-allowed-tools:
-  - Bash(gh:*)
-  - Bash(cp:*)
-  - Bash(ls:*)
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-# /issue — 定義問題
-
-每個改動都從 issue 開始。Issue 是人和 AI 的介面。
-
-## Configuration
-
-讀取 `.claude/issue-driven-dev.local.md` frontmatter：
-
-```yaml
----
-github_repo: "owner/repo"
-github_owner: "owner"
-attachments_release: "attachments"
----
-```
-
-如果不存在，詢問使用者並建立。
-
-## Execution
-
-### Step 1: 讀取來源（如果是 .docx）
-
-```
-mcp__che-word-mcp__get_document_text(source_path: "path")
-mcp__che-word-mcp__list_images(source_path: "path")
-```
-
-### Step 2: 蒐集資訊
-
-缺少的話詢問使用者：
-
-1. **Title** — 一句話描述問題
-2. **Type** — bug / feature / refactor / docs
-3. **Priority** — P0（立即）/ P1（本週）/ P2（排程）/ P3（有空再做）
-4. **Description** — 問題描述（bug: 重現步驟 + expected + actual；feature: 需求 + 目的）
-
-### Step 3: 建立 Issue
-
-```bash
-gh issue create \
-  --repo $GITHUB_REPO \
-  --title "$TITLE" \
-  --body "$(cat <<'EOF'
-## Problem
-
-> **Original text**:
-> 「...exact original text...」
-> — Source: {source}
-
-{Plain language interpretation}
-
-## Type
-{bug / feature / refactor / docs}
-
-## Expected
-...
-
-## Actual
-...
-
-## Impact
-...
-EOF
-)" \
-  --label "$TYPE"
-```
-
-> **CRITICAL**: 來自文件的 issue **必須**逐字引用原文。AI 摘要會失真，原文是唯一不會漂移的東西。
-
-> **數學公式格式**：GitHub 支援 `$...$`（inline）和 `$$...$$`（display）。含底線的程式變數名**不放 math mode**，改用 backtick code。混合寫法：`$R_I = J \cdot$` `` `mse_info` ``。
-
-### Step 4: 附加圖片（如果有）
-
-```bash
-# 確保 attachments release 存在
-gh release view $ATTACHMENTS_RELEASE --repo $GITHUB_REPO 2>/dev/null || \
-  gh release create $ATTACHMENTS_RELEASE --repo $GITHUB_REPO \
-    --title "Attachments" --notes "Issue attachments and figures"
-
-# 上傳圖片到 release
-gh release upload $ATTACHMENTS_RELEASE issue_${NUMBER}_${DESC}.png \
-  --repo $GITHUB_REPO --clobber
-
-# 圖片 URL 格式（private 和 public repo 都適用）
-# https://github.com/$GITHUB_REPO/releases/download/$ATTACHMENTS_RELEASE/issue_${NUMBER}_${DESC}.png
-
-# 編輯 issue body 加入圖片連結
-gh issue edit $NUMBER --repo $GITHUB_REPO --body "..."
-```
-
-> **Private repo 圖片渲染**：Release asset URL 在 issue/comment 的 markdown 中可以正常渲染，前提是查看者是 repo 的 collaborator 且已登入 GitHub。不需要把 repo 改成 public。
-
-### Step 5: 回報並停止
-
-輸出：issue number、URL、labels、type。
-
-提示下一步：`/issue-driven-dev:idd-diagnose #NNN`
-
-> **CRITICAL: 建立 issue 後必須停止。不要自動開始 diagnose 或 implement。**
-> Issue 建立是人的決定點 — 人決定優先級、分配、時機。
-> AI 不應該擅自開始解決問題。等使用者明確說「開始做」或呼叫 `idd-diagnose` 才繼續。
-
-## 來源文件規則
-
-### One Point = One Issue
-
-- **每個要點**獨立建一個 issue
-- **不合併** — 類似主題也分開
-- **不跳過** — 重複可以之後關，遺漏 = 遺忘
-- 處理完畢後驗證：`文件要點數 == 建立的 issue 數`
-
-## Next Step
-
-建立 issue 後，進入 `diagnose`：
-
-```
-/issue-driven-dev:idd-diagnose #NNN
-```
diff --git a/plugins/issue-driven-dev/skills/idd-verify/SKILL.md b/plugins/issue-driven-dev/skills/idd-verify/SKILL.md
deleted file mode 100644
index f4d28ad7..00000000
--- a/plugins/issue-driven-dev/skills/idd-verify/SKILL.md
+++ /dev/null
@@ -1,297 +0,0 @@
----
-name: idd-verify
-description: |
-  驗證 uncommitted/committed code 是否滿足 Issue 的所有要求。
-  支援 Codex CLI 或 claude -p 做獨立驗證。可 --loop 自動修到通過。
-  Use when: 實作完成後、commit 之前。
-  防止的失敗：自以為修好了，沒跑驗證。
-argument-hint: "#issue [engine] [--loop [N]] e.g. '#42', '#42 claude', '#42 --loop', '#42 both --loop 5'"
-allowed-tools:
-  - Bash(codex:*)
-  - Bash(claude:*)
-  - Bash(git:*)
-  - Bash(gh:*)
-  - Bash(mktemp:*)
-  - Bash(rm:*)
-  - Bash(wc:*)
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-# /idd-verify — 驗證實作
-
-用獨立的 AI 驗證 code 是否滿足 issue 要求。Claude 修、獨立 AI 驗。
-
-## 核心原則
-
-> 「應該沒問題」不是驗證。跑了驗證、看了輸出、確認通過，才是驗證。
-
-## 參數
-
-```
-/idd-verify #42                     → Codex 驗證（預設）
-/idd-verify #42 claude              → claude -p 驗證
-/idd-verify #42 both                → 兩個都跑，交叉比對
-/idd-verify #42 --loop              → 驗證-修復迴圈（預設最多 3 輪）
-/idd-verify #42 --loop 5            → 最多 5 輪
-/idd-verify #42 claude --loop       → 用 claude -p + 迴圈
-/idd-verify                         → 通用 code review（無 issue）
-```
-
-## Configuration
-
-讀取 `.claude/issue-driven-dev.local.md` frontmatter。如不存在，詢問 `github_repo` 並建立。
-
-## 驗證引擎
-
-| Engine | 工具 | 優勢 | 需求 |
-|--------|------|------|------|
-| `codex`（預設） | Codex CLI + gpt-5.4 | ~1M context、深度推理 | Codex CLI + ChatGPT Pro |
-| `claude` | claude -p | 不需額外工具、可讀本地檔案 | Claude Code 已安裝 |
-| `both` | 兩個都跑 | 交叉比對，覆蓋更廣 | 兩者都需要 |
-
-## Effort Levels
-
-未指定時，依 diff 大小自動選擇 effort level。
-
-| 改動規模 | Level |
-|---------|-------|
-| <50 lines | `medium` |
-| 50-200 lines | `high` |
-| >200 lines | `max`（預設） |
-
-### Effort 設定方式（兩種 engine 語法不同）
-
-| Engine | 語法 | 可用值 |
-|--------|------|-------|
-| **Codex CLI** | `-c "model_reasoning_effort=\"$EFFORT\""` | `medium`, `high`, `xhigh`（Codex 自己的 level 名） |
-| **claude -p** | `--effort $EFFORT` | `low`, `medium`, `high`, `max`（`max` 限 Opus 4.6） |
-
-> **注意**：兩者的 level 名稱不同！Codex 用 `xhigh`，claude -p 用 `max`。
-> 自動選擇時需要做映射：`大改動 → Codex xhigh / claude max`。
-
-## Execution（單次模式）
-
-### Step 1: 檢查是否有改動
-
-```bash
-git status --short
-git diff --stat          # uncommitted changes
-git diff --stat HEAD~1   # last commit (if just committed)
-```
-
-如果沒有 uncommitted 也沒有 recent commit 改動，通知使用者並停止。
-
-> **重要**：如果改動已 committed（`idd-implement` 之後），用 `git diff HEAD~1` 取代 `git diff`。
-> 範本中的 `=== CHANGES ===` 區塊也要改用 `git diff HEAD~1`。
-
-### Step 2: 取得 Issue 內容（如有 #NNN）
-
-```bash
-gh issue view $NUMBER --repo $GITHUB_REPO --json title,body,labels
-```
-
-### Step 3: 執行驗證
-
-#### Engine: Codex
-
-**Issue-focused（有 #NNN）**：
-
-```bash
-PROMPT_FILE=$(mktemp /tmp/codex_review_XXXXX)
-
-{
-  echo "You are reviewing code changes for GitHub Issue #$NUMBER: $TITLE"
-  echo ""
-  echo "Issue requirements:"
-  echo "$BODY"
-  echo ""
-  echo "YOUR PRIMARY TASK:"
-  echo "1. Go through EACH requirement in the issue"
-  echo "2. For each requirement, determine if it is addressed"
-  echo "3. List: FULLY addressed, PARTIALLY addressed, NOT addressed"
-  echo "4. Flag unrelated changes (scope creep)"
-  echo "5. Check for regressions or new bugs introduced"
-  echo ""
-  echo "=== UNCOMMITTED CHANGES ==="
-  git diff
-  git diff --cached
-} > "$PROMPT_FILE"
-
-codex review \
-  -c 'model="gpt-5.4"' \
-  -c "model_reasoning_effort=\"$EFFORT\"" \
-  - < "$PROMPT_FILE"
-
-rm "$PROMPT_FILE"
-```
-
-**General（無 #NNN）**：
-
-```bash
-codex review \
-  -c 'model="gpt-5.4"' \
-  -c "model_reasoning_effort=\"$EFFORT\"" \
-  --uncommitted
-```
-
-#### Engine: claude
-
-```bash
-PROMPT_FILE=$(mktemp /tmp/claude_review_XXXXX)
-
-{
-  echo "You are reviewing code changes for GitHub Issue #$NUMBER: $TITLE"
-  echo ""
-  echo "Issue requirements:"
-  echo "$BODY"
-  echo ""
-  echo "YOUR PRIMARY TASK:"
-  echo "1. Go through EACH requirement in the issue"
-  echo "2. For each requirement: FULLY / PARTIALLY / NOT addressed"
-  echo "3. Flag scope creep and regressions"
-  echo "4. Output as structured markdown"
-  echo ""
-  echo "=== UNCOMMITTED CHANGES ==="
-  git diff
-  git diff --cached
-} > "$PROMPT_FILE"
-
-claude -p "$(cat $PROMPT_FILE)" --output-format text --max-turns 10 --effort $EFFORT
-
-rm "$PROMPT_FILE"
-```
-
-#### Engine: both
-
-依序執行 Codex 和 claude，合併 findings（去重），標註來源。
-
-### Step 4: 呈現結果
-
-```markdown
-## Verify: #NNN — {title}
-
-### Engine
-{codex / claude / both}
-
-### 要求覆蓋率
-X / Y requirements addressed
-
-### Findings
-- [engine] finding description
-
-### Scope Check
-{有沒有超出 issue 範圍的改動}
-```
-
-### Step 5: Comment 驗證結果到 issue
-
-**每次驗證結果都 comment 到 issue**（含 loop 的每輪）：
-
-```bash
-gh issue comment $NUMBER --repo $GITHUB_REPO --body "$VERIFY_REPORT"
-```
-
-這樣 issue 上會有完整的驗證軌跡：哪些通過、哪些沒通過、用了什麼 engine。
-
-### Step 6: 後續動作
-
-| 結果 | 動作 |
-|------|------|
-| 全部通過 | 提示 `idd-close` |
-| 有 findings | 提示修正後再跑，或用 `--loop` 自動修 |
-| Scope creep | 提示開新 issue 或 revert |
-
----
-
-## Loop 模式（驗證-修復迴圈）
-
-加上 `--loop` 後，自動進入修復迴圈：
-
-```
-verify → findings → Claude fixes → verify → findings → fixes → verify → clean ✓
-  ↑ 獨立 AI                ↑ 當前 session
-```
-
-### 迴圈流程
-
-```
-FOR round = 1 to MAX_ROUNDS (預設 3):
-
-  1. 執行驗證（Codex / claude / both）
-  2. 解析 findings
-
-  IF 0 findings:
-    → PASS，結束迴圈
-    → 提示 idd-close
-
-  IF findings 數量 > 上一輪:
-    → STOP：regression detected
-    → 顯示新增的 findings，請人介入
-
-  IF 某個 finding 已出現 3 次:
-    → STOP：recurring finding，自動修不掉
-    → 請人介入
-
-  3. 分類 findings:
-     - IN_SCOPE（跟 #NNN 相關）→ 自動修復
-     - OUT_OF_SCOPE（不相關）→ 標記 SKIPPED
-
-  4. Claude 修復 IN_SCOPE findings
-  5. 進入下一輪
-
-IF 達到 MAX_ROUNDS 仍有 findings:
-  → STOP：列出剩餘 findings
-  → 提示：「超過上限，可能是架構問題」
-```
-
-### 每輪輸出
-
-```markdown
-## Round 1/3 — Engine: codex
-
-### Findings: 3
-- [FIXED] handleUpload() 缺少 null check
-- [FIXED] 測試沒覆蓋空輸入
-- [SKIPPED] 建議加 rate limiting（不在 #42 範圍）
-
-### 修復摘要
-修改了 src/upload.ts、tests/upload.test.ts
-```
-
-### 終止條件
-
-| 條件 | 動作 |
-|------|------|
-| 0 findings | 通過，提示 `idd-close` |
-| 達到上限 | 停止，列出剩餘 findings |
-| Findings 增加 | 停止，警告 regression — 修復引入了新問題 |
-| 同一 finding 出現 3 次 | 停止，這個修不掉，需要人 |
-
-### 安全設計
-
-- **修復者和驗證者是不同的 AI**：Claude 修、Codex/claude -p 驗。避免自我盲點。
-- **Scope 守衛**：迴圈中只修 #NNN 相關的 findings，不相關的標 SKIPPED。
-- **上限 3 輪**：超過 3 輪 = 可能是架構問題，不是 bug。跟 systematic-debugging 的原則一致。
-- **Regression 偵測**：findings 變多 = 修復引入新問題，立即停止。
-
----
-
-## 鐵律
-
-- **不跳過驗證**。「看起來對了」不算。
-- **有 findings 就不 commit**。先修，再 verify，再 commit。
-- **Verify 不是自己驗證自己**。用獨立的 AI 來檢查，避免自我盲點。
-- **Loop 中不修 scope 外的問題**。不在 #NNN 範圍的 → SKIPPED。
-
-## Next Step
-
-驗證通過後，進入 `idd-close`：
-
-```
-/issue-driven-dev:idd-close #NNN
-```
diff --git a/plugins/lean-prover/.claude-plugin/plugin.json b/plugins/lean-prover/.claude-plugin/plugin.json
new file mode 100644
index 00000000..6719a854
--- /dev/null
+++ b/plugins/lean-prover/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "lean-prover",
+  "description": "Lean 4 automated proof grinding — breadth-first sorry elimination with Mathlib API rules, codex-prove-assist, lean-prover agent, and auto-commit",
+  "version": "1.1.0",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/lean-prover/CHANGELOG.md b/plugins/lean-prover/CHANGELOG.md
new file mode 100644
index 00000000..e92cb98d
--- /dev/null
+++ b/plugins/lean-prover/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.1.0] - (date unknown — please fill in)
+
+### Changed
+- Lean 4 automated proof grinding — breadth-first sorry elimination with Mathlib API rules, codex-prove-assist, lean-prover agent, and auto-commit
diff --git a/plugins/lean-prover/CLAUDE.md b/plugins/lean-prover/CLAUDE.md
new file mode 100644
index 00000000..37266826
--- /dev/null
+++ b/plugins/lean-prover/CLAUDE.md
@@ -0,0 +1,71 @@
+# lean-prover — CLAUDE.md
+
+## Purpose
+
+Lean 4 自動證明磨削工具。廣度優先掃描 `.lean` 檔案中的 `sorry`，按難度分類排序，逐一嘗試用 tactic 消除，每成功一個就自動 commit。對於困難的 sorry，委派給 lean-prover agent 或 Codex 做深度嘗試。
+
+## Skills
+
+| Skill | 用途 |
+|-------|------|
+| `/lean-prover:grind` | 主迴圈：掃描、分類、嘗試證明、commit |
+| `/lean-prover:status` | 顯示當前 sorry/axiom 數量和 lake build 狀態 |
+| `/lean-prover:codex-prove-assist` | 智慧分配：Claude 分析 + Codex 暴力搜索 |
+
+## Agent
+
+| Agent | 用途 |
+|-------|------|
+| `lean-prover` | 對單一 sorry 做深度證明嘗試（Mathlib 搜尋、tactic 組合、錯誤分析） |
+
+## Hook
+
+| Hook | 觸發時機 | 行為 |
+|------|----------|------|
+| `lake-build-on-edit` | Edit/Write `.lean` 檔後 | 自動執行 `lake build`，回報錯誤數和 sorry 數 |
+
+## Rules (from Leanist)
+
+| Rule | 內容 |
+|------|------|
+| `mathlib-api.md` | Mathlib v4.28.0 常用 API 速查表（Measure Theory、ENNReal、Bochner 積分、Topology） |
+| `lean-imports.md` | 定理引用規則（只能引用 Ch0 公理 + 同章前面的定理 + Mathlib 基礎） |
+| `lean-references.md` | 引用已證結果必須用 import 不能用 axiom |
+
+## Usage
+
+```bash
+# 查看進度
+/lean-prover:status
+
+# 開始磨削
+/lean-prover:grind /path/to/lean4/project
+
+# 搭配 ralph-loop 持續運行直到全部完成
+/ralph-loop:ralph-loop /lean-prover:grind /path/to/lean4/project --completion-promise 'lake build has zero sorry warnings'
+
+# 限制迭代次數
+/ralph-loop:ralph-loop /lean-prover:grind /path --max-iterations 20
+
+# 用 Codex 暴力搜索
+/lean-prover:codex-prove-assist Hoadley1971.lean --scope sorry
+```
+
+## Design Principles
+
+1. **不破壞**：任何 sorry 如果嘗試失敗，還原為 sorry，不留 broken 的證明
+2. **不刪弱**：不修改定理陳述來降低難度
+3. **不偽裝**：`True := trivial` 不算證明，必須有正確的類型簽名
+4. **axiom 紀律**：axiom 只用於尚未形式化的外部結果，帶來源標註
+5. **分層**：簡單 tactic → lean-prover agent → Codex 暴力搜索
+6. **可追蹤**：`PROGRESS.md` 記錄所有進度和卡住原因
+7. **可中斷**：隨時可以停止，已完成的 commit 不受影響
+
+## Mathlib API 速查
+
+寫證明時先查 `rules/mathlib-api.md`，不要猜 API 名字。常見陷阱：
+
+- `integral_mul_left` **不存在**於 Bochner → 用 `bridge_integral_mul_left`
+- `abs_add` **不存在** → 用 `abs_lt` 分解
+- `Nat.cast`：用 `((n + 1 : ℕ) : ℝ)` 不是 `↑(n + 1)`
+- `div_le_iff` → 用 `div_le_iff₀`（v4.28.0 加了 ₀ suffix）
diff --git a/plugins/lean-prover/agents/lean-prover.md b/plugins/lean-prover/agents/lean-prover.md
new file mode 100644
index 00000000..36c3ce26
--- /dev/null
+++ b/plugins/lean-prover/agents/lean-prover.md
@@ -0,0 +1,141 @@
+---
+name: lean-prover
+description: |
+  Lean 4 proof specialist agent. Attempts to prove a single theorem by
+  searching Mathlib, trying tactic combinations, analyzing type errors,
+  and iterating with lake build feedback. Use for P3/P4 difficulty sorries
+  that simple tactic sweeps cannot solve.
+model: sonnet
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+---
+
+# Lean 4 Proof Agent
+
+You are a Lean 4 proof specialist. Your job is to eliminate a single `sorry` from a Lean 4 file.
+
+## Input
+
+You will receive:
+1. **File path** and **line number** of the sorry
+2. **Full theorem statement** including hypotheses
+3. **Surrounding context** (imports, definitions, related lemmas in the same file)
+4. **Previous attempts** that failed and their error messages
+5. **Mathematical reference** (if available): the corresponding proof from the LaTeX article
+
+## Proof Strategy
+
+### Phase 1: Understand the Goal (DO NOT skip)
+
+1. Read the file to understand the full theorem statement
+2. Identify the **goal type** after the sorry (what needs to be proved)
+3. Identify **available hypotheses** (what you can use)
+4. Check if the theorem has a **mathematical reference** in comments (e.g., `[Hoadley (1971) §3]`)
+5. Read the LaTeX proof if referenced — understand the mathematical argument first
+
+### Phase 2: Search for Tools
+
+1. **Check Mathlib** for relevant lemmas:
+   ```bash
+   # Search by name pattern
+   grep -rn "theorem.*{keyword}" .lake/packages/mathlib/Mathlib/ | head -30
+
+   # Search by type pattern
+   grep -rn "{goal_pattern}" .lake/packages/mathlib/Mathlib/ | head -30
+   ```
+
+2. **Check project imports** — what's already available from Leanist or other files:
+   ```bash
+   grep -rn "theorem\|lemma\|def" IRTDeficiency/*.lean | grep -v sorry
+   ```
+
+3. **Check if `exact?` or `apply?` would work** — mentally trace the types
+
+### Phase 3: Attempt Proof
+
+Try in this order:
+
+#### For algebraic goals (equalities, inequalities):
+```lean
+-- Try these one by one:
+ring
+field_simp; ring
+nlinarith [hypothesis1, hypothesis2]
+linarith [hypothesis1, hypothesis2]
+norm_num
+positivity
+simp [relevant_def]; ring
+calc x = ... := by ring
+     _ = ... := by ring
+```
+
+#### For structural goals (∀, ∃, ∧, cases):
+```lean
+-- Break down the structure:
+intro x hx        -- for ∀
+use witness        -- for ∃
+constructor        -- for ∧
+cases h            -- for ∨ or inductive
+induction n with   -- for ℕ
+| zero => ...
+| succ n ih => ...
+```
+
+#### For Mathlib API goals:
+```lean
+-- When you find the right Mathlib lemma:
+exact Mathlib.Lemma.name
+apply Mathlib.Lemma.name
+refine Mathlib.Lemma.name ?_ ?_  -- fill holes
+convert Mathlib.Lemma.name using 1  -- up to definitional equality
+```
+
+#### For measure theory / analysis goals:
+```lean
+-- Common patterns in this project:
+Filter.Tendsto    -- limits
+MeasureTheory.*   -- integrals, measures
+∀ᵐ ω ∂P          -- almost everywhere
+∫ ω, f ω ∂P      -- Lebesgue integral
+```
+
+### Phase 4: Build and Iterate
+
+After each attempt:
+
+1. Edit the file (replace `sorry` with your proof attempt)
+2. Run `lake build 2>&1 | head -50`
+3. If **success**: done!
+4. If **type mismatch**: read the expected vs actual types carefully, adjust
+5. If **unknown identifier**: search Mathlib for the correct name
+6. If **tactic failed**: try a different approach
+7. If **timeout**: simplify the proof or break into intermediate lemmas
+
+### Phase 5: If Stuck
+
+If you cannot prove it after all attempts:
+
+1. **Restore the original sorry** — do NOT leave a broken proof
+2. **Report** what you learned:
+   - What the goal reduces to after partial progress
+   - Which Mathlib lemmas are close but don't quite fit
+   - What mathematical argument the proof needs
+   - Whether introducing a helper lemma would help
+3. Suggest whether this sorry should be:
+   - Upgraded to an `axiom` with source citation
+   - Broken into smaller lemmas
+   - Left for human mathematician
+
+## Rules
+
+- NEVER leave a file in a state where `lake build` has more errors than before
+- NEVER delete or weaken a theorem statement to make it easier to prove
+- NEVER replace `sorry` with `trivial` unless the goal literally is `True`
+- ALWAYS restore `sorry` if your attempt fails
+- ALWAYS read the mathematical reference before attempting a proof
+- Prefer short proofs (< 10 lines) — if your proof is getting long, you're probably missing a Mathlib lemma
diff --git a/plugins/lean-prover/hooks/hooks.json b/plugins/lean-prover/hooks/hooks.json
new file mode 100644
index 00000000..912c097e
--- /dev/null
+++ b/plugins/lean-prover/hooks/hooks.json
@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE_PATH=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.file_path // empty'); if [[ \"$FILE_PATH\" == *.lean ]] && [[ \"$FILE_PATH\" != *.lake/* ]]; then DIR=$(dirname \"$FILE_PATH\"); while [[ \"$DIR\" != \"/\" ]]; do if [[ -f \"$DIR/lakefile.toml\" ]]; then cd \"$DIR\" && BUILD=$(lake build 2>&1); SORRY=$(echo \"$BUILD\" | grep -c \"uses .sorry.\" || true); ERROR=$(echo \"$BUILD\" | grep -c \"error:\" || true); if [[ $ERROR -eq 0 ]]; then echo \"lake build ok — $SORRY sorry remaining\"; else echo \"lake build failed ($ERROR errors)\"; echo \"$BUILD\" | grep -A 2 'error:' | head -20; fi; break; fi; DIR=$(dirname \"$DIR\"); done; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE_PATH=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.file_path // empty'); if [[ \"$FILE_PATH\" == *.lean ]] && [[ \"$FILE_PATH\" != *.lake/* ]]; then DIR=$(dirname \"$FILE_PATH\"); while [[ \"$DIR\" != \"/\" ]]; do if [[ -f \"$DIR/lakefile.toml\" ]]; then cd \"$DIR\" && BUILD=$(lake build 2>&1); SORRY=$(echo \"$BUILD\" | grep -c \"uses .sorry.\" || true); ERROR=$(echo \"$BUILD\" | grep -c \"error:\" || true); if [[ $ERROR -eq 0 ]]; then echo \"lake build ok — $SORRY sorry remaining\"; else echo \"lake build failed ($ERROR errors)\"; echo \"$BUILD\" | grep -A 2 'error:' | head -20; fi; break; fi; DIR=$(dirname \"$DIR\"); done; fi"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/lean-prover/hooks/lake-build-on-edit.sh b/plugins/lean-prover/hooks/lake-build-on-edit.sh
new file mode 100755
index 00000000..0126b8c2
--- /dev/null
+++ b/plugins/lean-prover/hooks/lake-build-on-edit.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+# PostToolUse hook: auto lake build after editing .lean files
+#
+# Triggered by: Edit, Write tools on *.lean files
+# Returns: lake build output (errors/warnings) for immediate feedback
+#
+# Hook config in plugin.json:
+#   "hooks": [{
+#     "type": "PostToolUse",
+#     "matcher": { "tool": ["Edit", "Write"], "filePath": "*.lean" },
+#     "command": "hooks/lake-build-on-edit.sh"
+#   }]
+
+# Get the edited file path from CLAUDE_TOOL_INPUT
+FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path // .filePath // empty')
+
+# Only trigger for .lean files (not in .lake/)
+if [[ "$FILE_PATH" != *.lean ]] || [[ "$FILE_PATH" == *.lake/* ]]; then
+  exit 0
+fi
+
+# Find project root (directory containing lakefile.toml)
+DIR=$(dirname "$FILE_PATH")
+while [[ "$DIR" != "/" ]]; do
+  if [[ -f "$DIR/lakefile.toml" ]] || [[ -f "$DIR/lakefile.lean" ]]; then
+    PROJECT_ROOT="$DIR"
+    break
+  fi
+  DIR=$(dirname "$DIR")
+done
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+  echo "⚠ No lakefile.toml found — skipping lake build"
+  exit 0
+fi
+
+# Run lake build
+cd "$PROJECT_ROOT"
+OUTPUT=$(lake build 2>&1)
+EXIT_CODE=$?
+
+# Count sorries and errors
+SORRY_COUNT=$(echo "$OUTPUT" | grep -c "declaration uses 'sorry'" || true)
+ERROR_COUNT=$(echo "$OUTPUT" | grep -c "error:" || true)
+
+if [[ $EXIT_CODE -eq 0 ]] && [[ $ERROR_COUNT -eq 0 ]]; then
+  if [[ $SORRY_COUNT -eq 0 ]]; then
+    echo "✓ lake build clean — zero sorry!"
+  else
+    echo "✓ lake build ok — $SORRY_COUNT sorry remaining"
+  fi
+else
+  echo "✗ lake build failed ($ERROR_COUNT errors, $SORRY_COUNT sorry)"
+  echo ""
+  # Show only error lines (not sorry warnings) for conciseness
+  echo "$OUTPUT" | grep -A 2 "error:" | head -30
+fi
diff --git a/plugins/lean-prover/rules/lean-imports.md b/plugins/lean-prover/rules/lean-imports.md
new file mode 100644
index 00000000..0ea1cf09
--- /dev/null
+++ b/plugins/lean-prover/rules/lean-imports.md
@@ -0,0 +1,35 @@
+# Lean 定理引用規則
+
+證明定理時，只能引用以下來源：
+
+1. **Ch0_Foundations.lean** 的公理（A1–A6）和定義
+2. **同一章前面已經證明的定理**（不能引用後面的）
+3. **Mathlib** — 僅限 Ch0 層級的基礎結構（ℝ 的性質、測度空間定義、基本分析）。如果證明過程中發現需要新的 Mathlib 模組，可以加到 Ch0 的 import 作為新的公理層依賴
+
+禁止：
+- 直接從 Mathlib 引用一個跟當前定理等價的結果（那只是索引，不是推導）
+- 跨章往後引用（Ch2 不能引用 Ch3 的東西）
+- 引用未證明的 sorry 定理
+- **Tautological 定理**：假設和結論形式相同（`:= hclt`、`:= hcons`）不算證明。定理的假設必須比結論更弱（更基本的條件），結論是從假設推導出來的。寧可留 sorry 也不要用 tautological 偽裝完成
+- **`True := trivial` stub**：結論型別為 `True` 的定理不算形式化。必須給出正確的 Lean 4 類型簽名（即使 proof body 是 sorry）
+
+# 章節內檔案結構
+
+每章的 `.lean` 檔按以下順序排列：
+
+1. **前置定義**（Preliminary definitions）
+   - 跨小節使用的定義（如 `ConvergesInProb`、`BoundedInProb`、`IsLittleOP`）
+   - 集中在檔案最前面，不依附於特定小節
+
+2. **前置引理**（Preliminary lemmas）
+   - 跨小節依賴的輔助引理（如 `conv_prob_scalar`、`conv_prob_bounded`）
+   - 在書中屬於較後的小節，但被較前的定理引用
+   - 例如：Lemma 2.3.1 (`bounded_times_op1`) 被 Thm 2.1.3 (`conv_prob_mul`) 使用，所以提前放置
+
+3. **各小節定理**（§2.1, §2.2, ...）
+   - 按書的順序排列
+   - 可以引用前置區和同節前面的定理
+
+書中跳過的證明（如 "see Problem X.Y"）表示存在隱含的依賴。在 Lean 裡必須讓被依賴的引理先出現。
+
+Lean 4 從上到下編譯，不允許前向引用。一個定理壞掉 → 之後所有定理都「找不到」。
diff --git a/plugins/lean-prover/rules/lean-references.md b/plugins/lean-prover/rules/lean-references.md
new file mode 100644
index 00000000..287e4bfb
--- /dev/null
+++ b/plugins/lean-prover/rules/lean-references.md
@@ -0,0 +1,50 @@
+# Lean 4 引用規則
+
+## 引用已證結果必須用 import，不能用 axiom
+
+如果一個結果已經在別的 Lean 4 專案裡證明過了，引用它的方式是：
+
+1. **用 `lake` dependency** 把那個專案加進 `lakefile.toml`
+2. **用 `import`** 在 `.lean` 檔裡引入
+3. **直接使用** 已證明的 theorem/lemma
+
+禁止：
+- 把已證結果重新聲明為 `axiom` — 這不是引用，是偷懶
+- 把已證結果的結論寫成 `True` 然後 `trivial` — 這是假裝
+- 複製貼上別的專案的證明 — 應該用 dependency
+
+## 可引用的專案
+
+| 專案 | 路徑 | 內容 |
+|------|------|------|
+| Leanist | `~/Academic/projects/active/formal_verification/Leanist` | Lehmann (1999) 大樣本理論 |
+| Mathlib | lake dependency | 數學庫 |
+
+## 加入 lake dependency 的方式
+
+```toml
+# lakefile.toml
+[[require]]
+name = "leanist"
+path = "../../../formal_verification/Leanist"
+```
+
+然後在 `.lean` 檔裡：
+```lean
+import Leanist.LargeSampleTheory.Ch0_Foundations
+```
+
+## axiom 的正確使用時機
+
+- 結果尚未在任何 Lean 4 專案中證明
+- 結果來自教科書/論文，且標註來源（作者、年份、頁碼）
+- 結果是深層的數學事實（如 Neveu 的 UI 定理），不是已有形式化的重複
+
+## 來源標註格式
+
+```lean
+/-- [Neveu (1965) p.54, Thm A.1]
+    [Hoadley (1971) Appendix, p. 1988]
+    [Lehmann (1999) Ch2 Thm 2.7.1 — formalized in Leanist] -/
+axiom some_result ...
+```
diff --git a/plugins/lean-prover/rules/mathlib-api.md b/plugins/lean-prover/rules/mathlib-api.md
new file mode 100644
index 00000000..18513119
--- /dev/null
+++ b/plugins/lean-prover/rules/mathlib-api.md
@@ -0,0 +1,106 @@
+# Mathlib v4.28.0 常用 API 速查
+
+寫 Lean 證明時先查這裡，不要猜 API 名字。
+
+## Measure Theory (ENNReal)
+
+| 用途 | API | 備註 |
+|------|-----|------|
+| P(Ω) = 1 | `measure_univ` | for `IsProbabilityMeasure` |
+| P(∅) = 0 | `measure_empty` | |
+| P(A) ≤ P(B) | `measure_mono (h : A ⊆ B)` | |
+| P(A∪B) ≤ P(A)+P(B) | `measure_union_le A B` | subadditivity |
+| P(Aᶜ) = P(univ) - P(A) | `measure_compl (hA : MeasurableSet A) (h : P A ≠ ⊤)` | |
+| (E∩F)ᶜ = Eᶜ∪Fᶜ | `Set.compl_inter` | De Morgan |
+| S∪Sᶜ = univ | `Set.union_compl_self _` | |
+| {f ≤ g} measurable | `measurableSet_le (hf : Measurable f) (hg : Measurable g)` | 注意順序 |
+
+## ENNReal 運算
+
+| 用途 | API | 備註 |
+|------|-----|------|
+| a - (a - b) ≤ b | `tsub_tsub_le` | 截斷減法 |
+| a ≤ b → c - b ≤ c - a | `tsub_le_tsub_left` | |
+| a - (a - b) = b | `ENNReal.sub_sub_cancel (ha : a ≠ ⊤) (hb : b ≤ a)` | |
+| η/2 + η/2 = η | `ENNReal.add_halves η` | |
+| Tendsto f → Tendsto (c*f) | `ENNReal.Tendsto.const_mul hm (Or.inr h)` | h : c ≠ ⊤ |
+| Tendsto f → Tendsto (f-g) | `ENNReal.Tendsto.sub hf hg (Or.inl h)` | h : a ≠ ⊤ |
+| ofReal a ≤ ofReal b ↔ a ≤ b | `ENNReal.ofReal_le_ofReal_iff (hb : 0 ≤ b)` | 條件在 b |
+| Tendsto → ∀ε∃N∀n≥N f≤ε | `ENNReal.tendsto_atTop_zero` | iff 版本 |
+| ℝ → ENNReal | `ENNReal.ofReal` | 負數映射到 0 |
+| ENNReal → ℝ | `.toReal` | ∞ 映射到 0 |
+| ℝ 的 Tendsto → ENNReal | `ENNReal.tendsto_ofReal` | |
+
+## Bochner 積分 (ℝ 值)
+
+| 用途 | API | 備註 |
+|------|-----|------|
+| ∫ c dP = c | `bridge_integral_const P c` | **Ch0 bridge** |
+| ∫ (c*f) = c * ∫ f | `bridge_integral_mul_left P c f` | **Ch0 bridge** |
+| ∫ (f+g) = ∫f + ∫g | `bridge_integral_add P hf hg` | **Ch0 bridge**, 需要 Integrable |
+| 0 ≤ ∫ f | `integral_nonneg (fun ω => h ω)` | 當 f ≥ 0 |
+| ∫ f ≤ ∫ g | `integral_mono hf_int hg_int hle` | pointwise f ≤ g |
+| ofReal(∫ f) = ∫⁻ ofReal(f) | `bridge_ofReal_integral_eq_lintegral P hint hnn` | **Ch0 bridge** |
+| Integrable (c*f) | `hint.const_mul c` | |
+| Integrable const | `integrable_const c` | |
+| Integrable (f+g) | `hf.add hg` | |
+
+**注意**：`integral_mul_left` 不存在於 Bochner！用 `bridge_integral_mul_left`。
+**注意**：`integral_const` 回傳 `P.real Set.univ • c`，不是 `c`！用 `bridge_integral_const`。
+
+## Topology / Filters
+
+| 用途 | API | 備註 |
+|------|-----|------|
+| squeeze | `tendsto_of_tendsto_of_tendsto_of_le_of_le hg hh hgf hfh` | g ≤ f ≤ h |
+| squeeze_zero | `squeeze_zero hnn hle hupper` | 0 ≤ f ≤ g → 0 |
+| const → const | `tendsto_const_nhds` | |
+| f₁ = f₂ → Tendsto 轉換 | `Filter.Tendsto.congr (h : ∀ x, f₁ x = f₂ x) ht` | 注意參數順序 |
+| Eventually ∀ | `Eventually.of_forall` | |
+| ContinuousAt 定義 | `ContinuousAt` = `Tendsto f (nhds a) (nhds (f a))` | |
+| ContinuousAt ε-δ | `Metric.continuousAt_iff` | |
+| dist on ℝ | `Real.dist_eq : dist x y = \|x - y\|` | |
+| ContinuousAt (H∘L) → H | `bridge_continuousAt_of_affine_comp hb hcont` | **Ch0 bridge**, L affine |
+
+## 實數 / 絕對值
+
+| 用途 | API | 備註 |
+|------|-----|------|
+| \|x\| < a ↔ -a < x ∧ x < a | `abs_lt` | **常用！** |
+| \|a-b\| < c ↔ a-b < c ∧ b-a < c | `abs_sub_lt_iff` | **注意**：`.1` 是 `a-b<c`，`.2` 是 `b-a<c` |
+| \|x\| = \|x\| | `abs_abs` | |
+| ‖x‖ = \|x\| | `Real.norm_eq_abs` | |
+| 0 ≤ x² | `sq_nonneg x` | |
+| \|x*y\| = \|x\|*\|y\| | `abs_mul x y` | |
+| a/b * b = a | `mul_div_cancel_left₀ (b) (ha : a ≠ 0) : a * b / a = b` | 注意：b 是第一個顯式參數 |
+| x ≠ 0 from 0 < x | `hx.ne'` | 不是 `ne_of_gt` |
+
+## 不存在或改名的 API
+
+| 你可能會猜的名字 | 實際情況 | 替代方案 |
+|------------------|---------|---------|
+| `abs_add` | **不存在** | 用 `abs_lt` 分解兩邊 |
+| `integral_mul_left` (Bochner) | **不存在** | `bridge_integral_mul_left` |
+| `ENNReal.one_toReal` | **不存在** | `show (1:ENNReal).toReal = 1 from rfl` |
+| `Measurable.abs` | **不存在** | `Measurable.comp measurable_norm` |
+| `AEStronglyMeasurable.pow_const` | **不存在** | `bridge_aestronglyMeasurable_sq` |
+| `Finset.nonempty_range_succ` | **改名** | `Finset.nonempty_range_add_one` |
+| `Finset.sup` on ℝ | **需要 OrderBot** | 用 `⨆ i ∈ range n, ...` |
+| `λ` (lambda) | **保留字** | 用 `fun` |
+
+## Ch0 Bridge Lemmas 總覽
+
+```
+bridge_norm_eq_abs          : ‖x‖ = |x|
+bridge_integral_eq_lintegral : ∫ f = (∫⁻ f).toReal (nonneg)
+bridge_ofReal_integral_eq_lintegral : ofReal(∫ f) = ∫⁻ ofReal(f)
+bridge_abs_set_eq_enorm_set : {ε ≤ |f|} = {ofReal ε ≤ ‖f‖ₑ}
+bridge_integral_const       : ∫ c dP = c
+bridge_integral_mul_left    : ∫ (c*f) = c * ∫ f
+bridge_integral_add         : ∫ (f+g) = ∫ f + ∫ g
+bridge_aestronglyMeasurable_sq : f ASM → f² ASM
+bridge_integrable_sq_of_bound : f² ≤ c·g²+d, g² integrable → f² integrable
+bridge_continuousAt_of_affine_comp : ContinuousAt (H∘L) x → ContinuousAt H (Lx)
+A5_markov_sq                : ε²·P{|f|≥ε} ≤ ∫⁻ f²
+A3_compl, A3_union_le, A3_mono, A3_range, A3_compl_tendsto_zero, A3_sub_sub_cancel
+```
diff --git a/plugins/lean-prover/skills/codex-prove-assist/SKILL.md b/plugins/lean-prover/skills/codex-prove-assist/SKILL.md
new file mode 100644
index 00000000..a9734479
--- /dev/null
+++ b/plugins/lean-prover/skills/codex-prove-assist/SKILL.md
@@ -0,0 +1,250 @@
+---
+name: codex-prove-assist
+description: |
+  智慧分配 Lean 4 定理證明工作給 Codex。
+  我（Claude）先分析 sorry/stub，判斷 Codex 適合做什麼，
+  只把「Codex 擅長」的部分派給他，其餘自己處理。
+  Use when: 有 sorry 或 True := trivial 需要處理、想利用 Codex 的暴力搜索能力。
+argument-hint: "FILE [--scope all|sorry|stubs] e.g. 'Ch4_Estimation.lean', 'Ch3:145', 'all --scope stubs'"
+allowed-tools:
+  - Bash(codex:*)
+  - Bash(lake:*)
+  - Bash(grep:*)
+  - Bash(sed:*)
+  - Bash(cat:*)
+  - Bash(mktemp:*)
+  - Bash(rm:*)
+  - Bash(wc:*)
+  - Bash(head:*)
+  - Bash(tail:*)
+  - Bash(git:*)
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# /codex-prove-assist — 智慧分配 Lean 4 證明工作
+
+我先分析，判斷什麼該派給 Codex、什麼該自己做，然後協調執行。
+
+## 核心原則
+
+> **我是 orchestrator，Codex 是 worker。** 我負責架構決策、bridge 設計、axiom 紀律；Codex 負責 tactic 暴力搜索和 statement 生成。
+
+### 分工矩陣
+
+| 任務類型 | 誰做 | 原因 |
+|---------|------|------|
+| `True := trivial` → 正式 theorem statement | **Codex** | 擅長從書的描述生成 Lean 4 類型 |
+| 純 tactic 證明（`simp`/`linarith`/`omega` 組合） | **Codex** | xhigh 深度推理 + 暴力搜索 |
+| CDF set equality 類型的代數證明 | **Codex** | 機械性 `ring`/`field_simp` 操作 |
+| 需要新 Ch0 bridge 的證明 | **我** | 需要架構判斷 |
+| 涉及 `IsProbabilityMeasure` instance 的 | **我** | Codex 不理解 Lean 4 type class |
+| `Nat.cast` / coercion 問題 | **我** | Lean 4 特有的 elaboration 問題 |
+| axiom 設計和放置 | **我** | axiom 只能在 Ch0 |
+| 跨章節依賴分析 | **我** | 需要全局視野 |
+
+### 公理紀律（CRITICAL）
+
+> **axiom 只能放在 Ch0_Foundations.lean。** Codex 的 prompt 必須明確禁止在其他檔案新增 axiom。
+
+- Codex 回傳的結果如果包含 `axiom`（在非 Ch0 檔案）→ **立即拒絕**
+- 證不出來 → **留 sorry**，我來分析需要什麼 Ch0 bridge
+- 需要新 bridge → **我在 Ch0 加 bridge，然後重新派 Codex**
+
+## 執行流程
+
+### Phase 0: 掃描與分類
+
+```
+1. 讀取目標檔案
+2. 找出所有 sorry 和 True := trivial
+3. 對每個目標分類：
+   - STUB: True := trivial → 需要生成 theorem statement
+   - TACTIC: 有完整 signature，缺 proof body → 需要 tactic 證明
+   - BRIDGE: 需要新 Ch0 infrastructure → 我先處理
+4. 輸出分類表給用戶確認
+```
+
+### Phase 1: Codex 生成 Theorem Statements（STUB 類型）
+
+適用：`True := trivial` 需要變成正式 Lean 4 theorem。
+
+**Prompt 構成**：
+- 書的對應章節描述（從 docstring `/-- ... -/` 提取）
+- Ch0 已有的定義和類型（ConvergesInProb, ConvergesInLaw, etc.）
+- 同章前面已有的 theorem signatures（作為風格參考）
+- **明確指示**：只生成 signature + sorry body，不要嘗試證明
+
+```bash
+OUTPUT_FILE=$(mktemp /tmp/codex_stmt_XXXXX)
+
+codex exec \
+  -c 'model="gpt-5.5"' \
+  -c 'model_reasoning_effort="xhigh"' \
+  -c 'service_tier="fast"' \
+  -s read-only \
+  -o "$OUTPUT_FILE" \
+  --ephemeral \
+  "$(cat $CONTEXT_FILE)"
+```
+
+**驗證**：`lake env lean $FILE` 確認 signature 類型正確（sorry 警告 OK）。
+
+### Phase 2: 我分析 Bridge 需求
+
+對每個 TACTIC 目標：
+1. 讀取 theorem signature
+2. 分析需要什麼 Mathlib/Ch0 工具
+3. 檢查 `.claude/rules/mathlib-api.md` 是否有對應 API
+4. 判斷：
+   - 現有 bridge 足夠 → 標記為 CODEX_READY
+   - 需要新 bridge → 我自己加到 Ch0，然後標記為 CODEX_READY
+   - 需要改 theorem statement（加假設）→ 我修改後標記為 CODEX_READY
+   - 本質上太難（需要深層 Mathlib 構造）→ 標記為 MANUAL
+
+### Phase 3: Codex 證明（CODEX_READY 類型）
+
+**Prompt 構成**：
+```
+=== TASK ===
+Replace the 'sorry' with a complete proof.
+The proof MUST compile with Lean 4 v4.28.0 + Mathlib v4.28.0.
+Return ONLY the proof body (after ':= by'), no markdown, no explanation.
+
+CRITICAL RULES:
+- Do NOT add axiom, sorry, or admit anywhere
+- Do NOT modify the theorem signature
+- Use ONLY the API names listed in the reference below
+- If you cannot prove it, return exactly: CANNOT_PROVE
+
+=== THEOREM ===
+{theorem with sorry}
+
+=== AVAILABLE BRIDGES (Ch0) ===
+{bridge lemma list from Ch0}
+
+=== MATHLIB API REFERENCE ===
+{from mathlib-api.md}
+
+=== PRECEDING DECLARATIONS ===
+{last 10 declarations before the theorem}
+
+=== FILE HEADER ===
+{first 30 lines: imports, namespace, variables}
+```
+
+如果是 loop 模式，加上：
+```
+=== PREVIOUS ATTEMPT FAILED ===
+{build errors from last round}
+
+Common Lean 4 / Mathlib v4.28.0 issues:
+- ₀ suffix: div_le_iff₀, pow_le_pow_left₀
+- Nat.cast: use ((n + 1 : ℕ) : ℝ) not ↑(n + 1)
+- field_simp needs non-zero hypotheses
+- abs_neg : |-(x)| = |x|
+- nlinarith can't handle division — use explicit mul_div_cancel₀
+```
+
+### Phase 4: 驗證與修復迴圈
+
+```
+FOR round = 1 to MAX_ROUNDS (default 3):
+  1. Codex 執行 → 取得 proof
+  2. 檢查 proof 是否含 axiom/sorry/admit → 拒絕
+  3. 檢查 proof 是否為 CANNOT_PROVE → 標記為 MANUAL，跳過
+  4. 插入到檔案（先 git stash 備份）
+  5. lake env lean $FILE 驗證
+
+  IF 通過且無 sorry:
+    → 成功！
+    → BREAK
+
+  IF 失敗:
+    → 提取 build errors
+    → 我先看錯誤：
+      - Nat.cast 問題 → 我自己修
+      - IsProbabilityMeasure 問題 → 我自己修
+      - API 名字錯 → 附錯誤給 Codex 再試
+      - 邏輯錯誤 → 附錯誤給 Codex 再試
+    → 還原檔案
+    → 繼續下一輪
+```
+
+### Phase 5: 收尾
+
+```
+FOR each MANUAL target:
+  → 我自己嘗試證明
+  → 如果需要新 bridge，加到 Ch0
+  → 如果證不出，留 sorry + 報告缺什麼
+
+最後輸出 summary table
+```
+
+## 輸出格式
+
+```markdown
+## codex-prove-assist: {file}
+
+### Scan Results
+| # | Theorem | Type | Assignment | Status |
+|---|---------|------|------------|--------|
+| 1 | thm_xyz | STUB | Codex | ✅ statement generated |
+| 2 | lemma_abc | TACTIC | Codex | ✅ proved (round 2) |
+| 3 | thm_def | BRIDGE | Me+Codex | ✅ added Ch0 bridge, Codex proved |
+| 4 | thm_ghi | MANUAL | Me | ⏳ needs bridge_xxx |
+
+### Ch0 Changes
+- Added: bridge_foo, bridge_bar
+
+### Sorry Remaining
+{count and list}
+
+### Codex Stats
+- Statements generated: N
+- Proofs attempted: M
+- Proofs succeeded: K (round avg: X.Y)
+- CANNOT_PROVE: J
+```
+
+## Codex CLI 參考
+
+```bash
+# 非互動模式（用於 STUB 和 TACTIC）
+codex exec \
+  -c 'model="gpt-5.5"' \
+  -c 'model_reasoning_effort="xhigh"' \
+  -c 'service_tier="fast"' \
+  -s read-only \
+  -o "$OUTPUT_FILE" \
+  --ephemeral \
+  "prompt text here"
+```
+
+- `-c` 值是 TOML 格式：字串要 `"quoted"`
+- `-s read-only` 只讀沙盒
+- `-o` 將回覆寫入檔案
+- `--ephemeral` 不保存 session
+- 如需讀 repo 檔案：`-s workspace-write`
+
+## 安全設計
+
+- **每輪都還原**：`git stash` 或 `git checkout -- $FILE`
+- **axiom 檢查**：Codex 輸出經過 `grep -c "axiom"` 過濾
+- **不動其他檔案**：只修改目標 .lean 檔
+- **Build 驗證**：`lake env lean` 是唯一的成功標準
+- **我先看錯誤**：Lean 4 type system 問題由我修，不浪費 Codex round
+
+## 鐵律
+
+- **Codex 產出 ≠ 證明**。只有 Lean type checker 通過才算。
+- **axiom 只在 Ch0**。Codex 回傳的 axiom 一律拒絕。
+- **我是 gatekeeper**。Codex 的每個 output 都由我審查。
+- **分工要明確**。不要把需要架構判斷的工作丟給 Codex。
+- **錯誤是資訊**。build error 是下一輪最重要的 context。
+- **Codex 說 CANNOT_PROVE → 我接手**，不是放棄。
diff --git a/plugins/lean-prover/skills/grind/SKILL.md b/plugins/lean-prover/skills/grind/SKILL.md
new file mode 100644
index 00000000..b85a80b3
--- /dev/null
+++ b/plugins/lean-prover/skills/grind/SKILL.md
@@ -0,0 +1,212 @@
+---
+name: grind
+description: |
+  Lean 4 自動證明磨削。廣度優先掃描所有 sorry，按難度排序，
+  逐一嘗試證明，每解一個就 commit。搭配 lean-prover agent 做深度嘗試。
+  當用戶說「開始證明」、「grind」、「消除 sorry」、「prove all」時觸發。
+argument-hint: "[lean_project_path] [--max-attempts N] [--dry-run]"
+---
+
+# Lean 4 Proof Grinder
+
+自動化消除 Lean 4 專案中的 `sorry`，直到 `lake build` 零錯誤或所有可解的 sorry 都已消除。
+
+## Arguments
+
+- `lean_project_path`：Lean 4 專案根目錄（含 `lakefile.toml`），預設為當前目錄
+- `--max-attempts N`：每個 sorry 最多嘗試次數（預設 8）
+- `--dry-run`：只掃描和分類，不修改檔案
+
+## Execution Steps
+
+### Step 1: Discover Project
+
+```bash
+# 找到 lakefile.toml 確認是 Lean 4 專案
+# 確認 lake build 可以執行（即使有 sorry，不應有語法錯誤）
+cd "$LEAN_PROJECT_PATH"
+lake build 2>&1
+```
+
+如果有非 sorry 的編譯錯誤，先修那些。sorry 本身不算錯誤（Lean 會 warning）。
+
+### Step 2: Scan All Sorries
+
+掃描所有 `.lean` 檔案，收集每個 sorry 的：
+
+1. **位置**：檔案路徑 + 行號
+2. **上下文**：所在的 theorem/lemma 名稱和完整陳述
+3. **類型**：
+   - `algebraic`：目標是等式/不等式，可能用 `ring`, `field_simp`, `nlinarith`, `linarith`, `norm_num` 解
+   - `api-bridge`：需要找到正確的 Mathlib API（如 UI 定義橋接）
+   - `structural`：需要構造性證明（歸納、case split）
+   - `deep`：需要複雜的數學推理（測度論、拓撲）
+   - `placeholder`：結論是 `True` 或 `trivial`，需要重寫定理陳述
+4. **依賴**：是否依賴其他 sorry 的結果
+
+```bash
+# 掃描 sorry
+grep -rn "sorry" --include="*.lean" "$LEAN_PROJECT_PATH" | grep -v "^.*:.*--.*sorry"
+
+# 掃描 axiom（非 Mathlib 的）
+grep -rn "^axiom " --include="*.lean" "$LEAN_PROJECT_PATH"
+
+# 掃描 trivial placeholder
+grep -rn ": True :=" --include="*.lean" "$LEAN_PROJECT_PATH"
+```
+
+### Step 3: Classify and Prioritize
+
+按以下優先級排序（廣度優先）：
+
+| 優先級 | 類型 | 預期策略 |
+|--------|------|----------|
+| P0 | `placeholder`（`: True`） | 重寫定理陳述為真正的命題 |
+| P1 | `algebraic` | `ring`, `field_simp`, `nlinarith`, `norm_num`, `positivity`, `omega` |
+| P2 | `structural` | `induction`, `cases`, `simp`, `exact`, `apply` |
+| P3 | `api-bridge` | 搜尋 Mathlib，找到對應的 lemma/theorem |
+| P4 | `deep` | 需要 lean-prover agent 深度嘗試 |
+
+輸出分類結果到 `PROGRESS.md`。
+
+### Step 4: Grind Loop
+
+對每個 sorry（按優先級順序）：
+
+```
+for sorry in sorted_sorries:
+    attempt = 0
+    while attempt < MAX_ATTEMPTS:
+        attempt += 1
+
+        1. 讀取 sorry 所在的完整定理和上下文
+        2. 根據類型選擇策略：
+           - algebraic → 嘗試 tactic 組合
+           - api-bridge → 用 Grep 搜尋 Mathlib 或 `exact?`, `apply?`
+           - structural → 分析目標結構，嘗試 induction/cases
+           - deep → 啟動 lean-prover agent（subagent）
+           - placeholder → 重寫陳述，然後按新類型處理
+        3. Edit .lean 檔案，替換 sorry
+        4. lake build（hook 會自動觸發，但這裡也要手動確認）
+        5. 如果成功：
+           - git commit -m "prove: {theorem_name} — eliminate sorry"
+           - 更新 PROGRESS.md
+           - break
+        6. 如果失敗：
+           - 讀取 lake build 錯誤訊息
+           - 分析錯誤類型（type mismatch, unknown identifier, tactic failed）
+           - 調整策略重試
+
+    if all attempts failed:
+        記錄到 PROGRESS.md：
+        - 定理名稱
+        - 嘗試過的策略
+        - 最後的錯誤訊息
+        - 建議的人工介入方向
+        還原 sorry（不要留 broken 的證明）
+```
+
+### Step 5: Tactic Strategies（按類型）
+
+#### P1: Algebraic
+
+嘗試順序：
+1. `norm_num`
+2. `ring`
+3. `field_simp; ring`
+4. `nlinarith` / `linarith`
+5. `positivity`
+6. `omega`（自然數/整數）
+7. `field_simp; nlinarith`
+8. 組合：`simp only [...]; ring`
+
+#### P2: Structural
+
+1. 讀取目標類型
+2. 如果是 `∀`：`intro`
+3. 如果是 `∃`：`exact ⟨witness, proof⟩` 或 `use witness`
+4. 如果是 `A ∧ B`：`constructor`
+5. 如果是 `A ∨ B`：`left` 或 `right`
+6. 如果假設有 `A ∨ B`：`cases h`
+7. 歸納類型：`induction` 或 `cases`
+8. 最後嘗試 `simp [relevant_lemmas]`
+
+#### P3: API Bridge
+
+1. 從錯誤訊息或目標中提取關鍵概念
+2. 搜尋 Mathlib：
+   ```bash
+   grep -rn "theorem.*{keyword}" ~/.elan/toolchains/leanprover-lean4-v4.*/lib/lean4/library/
+   # 或在 Mathlib source 中搜尋
+   ```
+3. 嘗試 `exact?`（在本地 Lean LSP 中）
+4. 如果找到候選，嘗試 `exact Mathlib.Theorem.name`
+5. 如果型別不完全匹配，用 `apply` + 填補 arguments
+
+#### P4: Deep
+
+啟動 `lean-prover` agent（見 agents/lean-prover.md），給它：
+- 完整的定理陳述
+- 周圍的定義和相關 lemma
+- 之前失敗的嘗試和錯誤
+- 參考的數學證明（如果在 LaTeX 中有對應的 proof）
+
+### Step 6: Report
+
+完成後輸出：
+
+```markdown
+## Grind Report
+
+- 初始 sorry 數：N
+- 已消除：M
+- 仍然卡住：K（列表 + 原因）
+- axiom 數（預期保留）：A
+- placeholder 數（需重寫）：P
+- lake build 狀態：✓ / ✗
+
+### 卡住的 sorry
+
+| 定理 | 檔案:行 | 類型 | 嘗試次數 | 最後錯誤 | 建議 |
+|------|---------|------|----------|----------|------|
+| ... | ... | ... | ... | ... | ... |
+```
+
+### Step 7: Update PROGRESS.md
+
+在 Lean 專案根目錄維護 `PROGRESS.md`：
+
+```markdown
+# Proof Progress
+
+Last grind: {date}
+Status: {N}/{Total} sorries eliminated
+
+## Completed
+- [x] `rasch_deficiency_neg` — `nlinarith` (2025-04-02)
+- [x] `thm3_deficiency_formula` — `field_simp; linarith` (2025-04-02)
+
+## In Progress
+- [ ] `thm1_second_order_separation` — needs MLE variance expansion (P4)
+
+## Blocked
+- [ ] `hoadley_thm1_consistency` — depends on A.3 + A.4 (P4)
+
+## Intentional Axioms (not sorry)
+- `thmA1_sufficient_ui` — Neveu (1965), standard measure theory
+- `loeve_markov_wlln` — Loève (1960), p. 275
+```
+
+## Integration with Other Tools
+
+- **lean-prover agent**：P4 類型的 sorry 會委派給 agent 做深度嘗試
+- **PostToolUse hook**：每次 Edit `.lean` 檔後自動 `lake build`
+- **codex:rescue**：如果 agent 也卡住，可以 escalate 給 Codex
+- **ralph-loop**：可以用 `/ralph-loop:ralph-loop` 包裝本 skill 做持續運行
+
+## Notes
+
+- 不要刪除有意保留的 `axiom`——它們是文章引用的外部結果
+- 結論是 `True` 的定理（placeholder）需要先重寫陳述再證明
+- 每次 commit message 格式：`prove: {theorem_name} — eliminate sorry`
+- 如果 `lake build` 有非 sorry 的錯誤，優先修那些
diff --git a/plugins/lean-prover/skills/status/SKILL.md b/plugins/lean-prover/skills/status/SKILL.md
new file mode 100644
index 00000000..7b80335e
--- /dev/null
+++ b/plugins/lean-prover/skills/status/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: status
+description: |
+  顯示 Lean 4 專案的證明進度：sorry/axiom 數量、已證明定理、lake build 狀態。
+  當用戶說「proof status」、「進度」、「還剩多少 sorry」時觸發。
+argument-hint: "[lean_project_path]"
+---
+
+# Lean 4 Proof Status
+
+快速掃描 Lean 4 專案，回報證明完成度。
+
+## Execution Steps
+
+### Step 1: Locate Project
+
+找到 `lakefile.toml` 所在的目錄。如果引數為空，從當前目錄向上搜尋。
+
+### Step 2: Scan
+
+用 Grep 掃描所有 `.lean` 檔案（排除 `.lake/` 目錄）：
+
+```bash
+# sorry 數量（排除註解中的）
+grep -rn "sorry" --include="*.lean" . | grep -v "\.lake/" | grep -v "^.*:.*--.*sorry"
+
+# axiom 數量（自定義的，非 Mathlib）
+grep -rn "^axiom " --include="*.lean" . | grep -v "\.lake/"
+
+# placeholder（結論是 True）
+grep -rn ": True :=" --include="*.lean" . | grep -v "\.lake/"
+
+# 已完成的 theorem（有 := by ... 且沒有 sorry）
+# 這個比較複雜，用多行 grep 或讀取每個檔案分析
+```
+
+### Step 3: Build Check
+
+```bash
+lake build 2>&1 | tail -20
+```
+
+回報：
+- 是否有非 sorry 的錯誤
+- warning 數量（sorry 會產生 warning）
+
+### Step 4: Report
+
+```markdown
+## Proof Status — {project_name}
+
+| 指標 | 數量 |
+|------|------|
+| sorry | N |
+| axiom（預期保留） | A |
+| placeholder（`: True`） | P |
+| 已證明定理 | T |
+| lake build | ✓ / ✗ |
+
+### sorry 位置
+
+| 檔案 | 行 | 定理 | 類型 |
+|------|-----|------|------|
+| Article.lean | 112 | thm1_second_order_separation | deep |
+| ... | ... | ... | ... |
+
+### axiom 位置（預期保留）
+
+| 檔案 | 行 | 名稱 | 來源 |
+|------|-----|------|------|
+| Hoadley1971.lean | 236 | thmA1_sufficient_ui | Neveu (1965) |
+| ... | ... | ... | ... |
+```
+
+### Step 5: PROGRESS.md
+
+如果專案根目錄有 `PROGRESS.md`，讀取並顯示最近的 grind 記錄。
diff --git a/plugins/macdoc/.claude-plugin/plugin.json b/plugins/macdoc/.claude-plugin/plugin.json
new file mode 100644
index 00000000..2a205cd2
--- /dev/null
+++ b/plugins/macdoc/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "macdoc",
+  "description": "macOS 原生文件處理 CLI — 格式轉換、VLM OCR（含 host profile 設定）、SRT 處理",
+  "version": "1.1.0",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/macdoc/CHANGELOG.md b/plugins/macdoc/CHANGELOG.md
new file mode 100644
index 00000000..e5b1099a
--- /dev/null
+++ b/plugins/macdoc/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.1.0] - (date unknown — please fill in)
+
+### Changed
+- macOS 原生文件處理 CLI — 格式轉換、VLM OCR（含 host profile 設定）、SRT 處理
diff --git a/plugins/macdoc/skills/macdoc/SKILL.md b/plugins/macdoc/skills/macdoc/SKILL.md
new file mode 100644
index 00000000..e6af40f6
--- /dev/null
+++ b/plugins/macdoc/skills/macdoc/SKILL.md
@@ -0,0 +1,312 @@
+---
+name: macdoc
+description: |
+  macOS 原生文件處理 CLI 工具的使用指南。
+  當需要做格式轉換（SRT→HTML、MD→HTML、DOCX→MD）、
+  VLM OCR（PDF/圖片→文字）、或 SRT 逐字稿處理時使用。
+  觸發詞：「macdoc」「轉換格式」「OCR」「逐字稿轉HTML」
+  「手寫筆記辨識」「PDF轉文字」
+---
+
+# macdoc — macOS 原生文件處理 CLI
+
+安裝位置：`~/bin/macdoc`（或 `/usr/local/bin/macdoc`）
+原始碼：`/Users/che/Developer/macdoc`
+
+## 子命令總覽
+
+| 子命令 | 用途 | 常用場景 |
+|--------|------|---------|
+| `convert` | 格式轉換 | SRT→HTML、MD→HTML、DOCX→MD |
+| `ocr` | VLM OCR | PDF/圖片→文字（手寫筆記辨識） |
+| `config` | 設定管理 | AI CLI 工具、OCR host/model 預設值 |
+| `pdf` | PDF→LaTeX | 學術 PDF 處理（較少用） |
+| `bib` | BibLaTeX→APA | 參考文獻格式轉換 |
+
+---
+
+## convert — 格式轉換
+
+```bash
+macdoc convert --to <format> [options] <input>
+```
+
+### 支援格式
+
+| --to | 說明 | 範例 |
+|------|------|------|
+| `html` | 轉 HTML | SRT→逐字稿網頁、MD→講義網頁 |
+| `md` | 轉 Markdown | DOCX→MD |
+| `docx` | 轉 Word | MD→DOCX |
+| `pdf` | 轉 PDF | MD→PDF（透過 textutil） |
+| `json` | 轉 JSON | SRT→結構化 JSON |
+
+### 常用選項
+
+| 選項 | 說明 |
+|------|------|
+| `--output <path>` | 輸出檔案路徑 |
+| `--full` | 輸出完整 HTML 文件（含 `<head>`），不只是 fragment |
+| `--css light` | SRT 轉 HTML 時用淺色主題 |
+| `--css dark` | SRT 轉 HTML 時用深色主題 |
+| `--hard-breaks` | 軟換行視為硬換行 |
+| `--frontmatter` | 包含 YAML frontmatter |
+| `--html-extensions` | MD 中保留 `<u>/<sup>/<sub>/<mark>` |
+
+### 常用工作流
+
+#### SRT → 可搜尋的逐字稿 HTML
+
+```bash
+# 1. 轉換
+macdoc convert --to html --css light --full --output transcript.html input.srt
+
+# 2. 注入搜尋和說話者篩選功能（需要 inject-search.py）
+python3 inject-search.py transcript.html --speakers "鄭老師:鄭老師,學生名:學生名"
+```
+
+`inject-search.py` 位於每個 handout 目錄下。
+
+#### MD → 講義 HTML
+
+```bash
+macdoc convert --to html --full --output lecture.html notes.md
+```
+
+產出的是裸 HTML，需要手動替換 `<head>` 加入 CSS 連結和 lecture-header。
+
+#### DOCX → Markdown
+
+```bash
+macdoc convert --to md --output output.md input.docx
+```
+
+---
+
+## ocr — VLM OCR
+
+```bash
+macdoc ocr <input> [options]
+```
+
+用 Vision Language Model 做 OCR，支援手寫筆記、印刷文件、截圖。
+
+### Backend 選擇
+
+| Backend | 選項 | 說明 |
+|---------|------|------|
+| **Ollama**（預設） | `--backend ollama` | 透過 Ollama HTTP API，需要先啟動 Ollama |
+| **MLX**（本地） | `--backend mlx` | 用 mlx-swift-lm 本地推理（⚠️ 目前有 upstream bug） |
+
+### Ollama host 設定（v1.1+）
+
+**推薦流程**：用 `config ocr` 設定好 host profile，之後就不用每次傳 `--host`。
+
+```bash
+# 一次性設定（本機或遠端 Kyle）
+macdoc config ocr add-host kyle localhost:11435   # 先建 SSH tunnel 到 kyle
+macdoc config ocr add-host local localhost:11434  # 本機 Ollama
+macdoc config ocr set-default kyle                # 設為預設
+
+# 之後直接 OCR，不用 --host
+macdoc ocr handwritten.pdf
+```
+
+**`--host` 解析規則**：先當 profile 名查 config，找不到才當原始地址。
+
+```bash
+macdoc ocr file.pdf                       # 用 default profile
+macdoc ocr file.pdf --host local          # 切換到 local profile
+macdoc ocr file.pdf --host 192.168.1.50:11434  # 不是 profile,當原始地址
+```
+
+### SSH tunnel 到 Kyle
+
+Kyle 的 Mac Studio（M4 Max/128GB）上有 Ollama + glm-ocr：
+
+```bash
+# 建 SSH tunnel（Kyle's Ollama 預設只聽 localhost）
+ssh -fN -L 11435:localhost:11434 kyle
+
+# 確認連線
+curl -s http://localhost:11435/api/tags | python3 -m json.tool
+
+# OCR（如果已設 default=kyle）
+macdoc ocr notes.pdf --output notes.md
+
+# 長時間 OCR 記得用 caffeinate 防電腦睡眠（SSH tunnel 會斷）
+caffeinate -i -- macdoc ocr large.pdf --output large.md
+```
+
+### 可用模型
+
+| 模型 | 用途 | --model 值 |
+|------|------|-----------|
+| **glm-ocr**（預設） | 中文手寫/印刷 OCR | `glm-ocr` |
+| qwen3-vl | 多語言 VLM | `qwen3-vl` |
+| minicpm-v | 輕量 VLM | `minicpm-v` |
+
+### 常用範例
+
+```bash
+# 手寫筆記 PDF（指定頁碼）
+macdoc ocr notes.pdf --pages 1-3 --output notes.md
+
+# 大型 PDF 分段 OCR(避免長時間 tunnel 斷線)
+macdoc ocr big.pdf --pages 1-60  --output part1.md
+macdoc ocr big.pdf --pages 61-120 --output part2.md
+cat part1.md part2.md > full.md
+
+# 單張圖片
+macdoc ocr screenshot.png
+
+# 指定模型(覆寫 config default)
+macdoc ocr document.pdf --model qwen3-vl
+```
+
+### 已知問題
+
+- **MLX backend crash**:mlx-swift-lm 有 upstream bug(ml-explore/mlx-swift-lm#191),所有 VLM 模型都會 crash。暫時只能用 Ollama。
+- **SSH tunnel 長時間會斷**:連線超過 2-3 小時會 timeout。解法是分段 OCR(`--pages`)或用 `caffeinate -i`。
+- **大頁面**:超過 8000px 的頁面會被自動縮小。
+
+### 批次與並行(77 PDF 轉學考實戰累積)
+
+當要 OCR 數十張 PDF 或數百頁時,單檔順序跑會花太久。下面是實戰整理出來的 pattern。
+
+#### 為什麼先拆 PNG 再 OCR
+
+直接 `macdoc ocr file.pdf` 在某些 PDF 上會漏頁首 — 模型內部的 PDF→image 路徑可能用低解析度。改成預先用 `pdftoppm` 拆 PNG 再逐頁 OCR,單頁可控、可平行、漏頁可重跑。
+
+```bash
+# Step 1: 拆 PNG (200 DPI 對手寫/印刷都夠)
+mkdir -p out
+pdftoppm -r 200 -png file.pdf out/page
+
+# Step 2: 逐 PNG OCR (見下面 xargs -P pattern)
+
+# Step 3: 合併
+cat out/page-*.md > full.md
+```
+
+#### Ollama 並發環境變數
+
+跑遠端 Ollama(SSH tunnel 連 Kyle 等)時這幾個變數顯著影響吞吐:
+
+| 變數 | 建議 | 說明 |
+|------|------|------|
+| `OLLAMA_NUM_PARALLEL` | 4~8 | 同 model 並發請求數;太高會 OOM |
+| `OLLAMA_MAX_LOADED_MODELS` | 1 | 單 model 任務維持 1,避免 thrash |
+| `OLLAMA_FLASH_ATTENTION` | 1 | Apple Silicon Metal 後端免費加速 |
+
+設定方式:在 Ollama server 端的 `~/Library/LaunchAgents/com.ollama.server.plist` 加 `EnvironmentVariables`,或啟動前 `export`,然後 `ollama serve`。
+
+#### `xargs -P` 並行 pattern
+
+```bash
+# N=4 並行 (對應 OLLAMA_NUM_PARALLEL=4)
+find out -name "page-*.png" | xargs -P 4 -I{} \
+  macdoc ocr {} --output "{}.md" --host kyle --model glm-ocr
+
+# 失敗重試 (找出無 .md 的 png 重跑)
+find out -name "page-*.png" | while read png; do
+  [ -f "${png}.md" ] || echo "$png"
+done | xargs -P 2 -I{} macdoc ocr {} --output "{}.md" --host kyle
+```
+
+#### SSH tunnel 維持
+
+長時間批次 OCR(>2 小時)tunnel 會斷。三種策略:
+
+```bash
+# (a) 簡易 — 跑前重建 tunnel,搭配 caffeinate 防 mac sleep
+ssh -fN -L 11435:localhost:11434 kyle
+caffeinate -i -- xargs -P 4 ... < pages.txt
+
+# (b) autossh — 自動重連
+brew install autossh
+autossh -fN -M 0 -L 11435:localhost:11434 kyle
+
+# (c) Health check loop — 中途斷 tunnel 自動重建
+while true; do
+  curl -s --max-time 5 http://localhost:11435/api/tags >/dev/null \
+    || ssh -fN -L 11435:localhost:11434 kyle
+  sleep 60
+done &
+```
+
+實戰建議:走 (b) autossh + `caffeinate -i`,踩坑成本最低。
+
+#### 與 CLI `--parallel` 的整合(roadmap)
+
+`PsychQuant/macdoc#73` 追蹤把 `--parallel N` 整合進 macdoc CLI(內建 `xargs -P` 邏輯 + 失敗重試 + tunnel health check)。CLI 落地後上面那段 pattern 會被取代成:
+
+```bash
+macdoc ocr-batch out/*.png --parallel 4 --host kyle  # roadmap, 尚未實作
+```
+
+在那之前,沿用 `xargs -P` 即可。另一個正在被討論的方向是新建 `batch-ocr` plugin 把 PDF→PNG→OCR→merge 整個 pipeline 包成 single command,見 PsychQuant/psychquant-claude-plugins#6。
+
+---
+
+## config — 設定管理
+
+設定檔存在 `~/.config/macdoc/config.json`。
+
+### config ai — AI CLI 工具設定
+
+```bash
+macdoc config ai detect                  # 偵測本機已安裝的 codex/claude/gemini
+macdoc config ai list                    # 顯示目前設定
+macdoc config ai set transcription codex # 設定 one-shot 轉寫預設後端
+macdoc config ai set agent claude        # 設定 agentic 後端
+```
+
+### config ocr — OCR host/model 設定（v1.1+）
+
+| 子命令 | 用途 |
+|--------|------|
+| `list` | 顯示目前 OCR 設定（含 profile 列表） |
+| `add-host <name> <addr>` | 新增/更新 host profile |
+| `remove-host <name>` | 移除 profile |
+| `set-default <name>` | 設定預設 host |
+| `set-model <model>` | 設定預設模型（如 glm-ocr） |
+| `set-backend <ollama\|mlx>` | 設定預設後端 |
+
+```bash
+# 完整範例：設定 kyle 遠端 + local 兩個 profile
+ssh -fN -L 11435:localhost:11434 kyle  # 建 tunnel
+macdoc config ocr add-host kyle localhost:11435
+macdoc config ocr add-host local localhost:11434
+macdoc config ocr set-default kyle
+macdoc config ocr set-model glm-ocr
+
+# 查看
+macdoc config ocr list
+# === OCR 設定 ===
+# backend: ollama
+# model:   glm-ocr
+# default host: kyle → localhost:11435
+#
+# === Host Profiles ===
+#   kyle → localhost:11435 ★
+#   local → localhost:11434
+```
+
+---
+
+## 與其他工具的搭配
+
+| 場景 | 工具組合 |
+|------|---------|
+| 手寫筆記 → TikZ 圖 | `macdoc ocr` → 辨識內容 → 寫 TikZ → `xelatex` 編譯 |
+| SRT → handout 網頁 | `macdoc convert --to html` → `inject-search.py` |
+| PDF 筆記 → PNG | `pdftoppm -png -r 200`（不是 macdoc，是 poppler） |
+| 學生作業 .docx → 閱讀 | 用 che-word-mcp 的 `get_document_text`（不需要 macdoc） |
+
+---
+
+## 版本紀錄
+
+- **1.1.0**：新增 `config ocr` 子命令組,支援具名 host profile(`--host kyle` 等),預設 host/model 可存 config
+- **1.0.0**：初版
diff --git a/plugins/math-tools/.claude-plugin/plugin.json b/plugins/math-tools/.claude-plugin/plugin.json
new file mode 100644
index 00000000..eb2d8750
--- /dev/null
+++ b/plugins/math-tools/.claude-plugin/plugin.json
@@ -0,0 +1,16 @@
+{
+  "name": "math-tools",
+  "version": "0.1.0",
+  "description": "v0.1.0: Scaffolding for academic math article editing — covers 4 scopes: (1) propositions extraction + R1-R8 mechanical validation (validate-propositions.py with normalize_for_match resilient substring containment, R1 prop-subset / R2 cite-resolve / R3 DAG / R6 sentence-clause-index / R7 UUID v7 / R8 unique-ids); (2) proofread workflow — JSONL-driven L1-L5 + location-drift 6-layer per-prop checklist (.proofread/<file>.md atomic granularity, 286-prop full-manuscript walk demonstrated); (3) manuscript audit R1-R4 with PR-side CI gate (audit-symbols / audit-citations / audit-code-manuscript per manuscript-consistency-audit.md SOP); (4) cross-doc sync rules — manuscript-jsonl-sync (prop-level main.tex <-> jsonl), manuscript-consistency-audit (audit-time SOP), code-and-manuscript-sync (repo-level cluster PR scope). Dogfood origin: PsychQuantHsu/psychophysical_representations #107 proofread workflow experiment (3 pilots, 5 findings shipped). v0.1.0 ships skeleton SKILL.md bodies + 3 frozen baseline rules; skill execution bodies + scripts remain in source repo until per-skill iteration extracts them. Use /plugin-tools:plugin-update math-tools after each skill body refinement.",
+  "author": {
+    "name": "Che Cheng"
+  },
+  "keywords": [
+    "math",
+    "manuscript",
+    "latex",
+    "propositions",
+    "proofread",
+    "audit"
+  ]
+}
diff --git a/plugins/math-tools/.gitignore b/plugins/math-tools/.gitignore
new file mode 100644
index 00000000..161e7f69
--- /dev/null
+++ b/plugins/math-tools/.gitignore
@@ -0,0 +1,5 @@
+# Local-only reference materials — do not commit textbooks / PDFs / other
+# user-side library content into marketplace git history.
+references/*.pdf
+references/*.epub
+references/*.mobi
diff --git a/plugins/math-tools/CLAUDE.md b/plugins/math-tools/CLAUDE.md
new file mode 100644
index 00000000..2f9e16f1
--- /dev/null
+++ b/plugins/math-tools/CLAUDE.md
@@ -0,0 +1,64 @@
+# math-tools — CLAUDE.md
+
+## Purpose
+
+Academic math article editing — propositions extraction + R1-R8 mechanical validation, JSONL-driven 6-layer proofread workflow, R1-R4 cross-doc audit gate, and 3 frozen sync rules. Dogfood origin: `PsychQuantHsu/psychophysical_representations` #107 proofread workflow experiment (3 pilots, 286-prop full L4 walk demonstrated).
+
+## Skills
+
+| Skill | 用途 |
+|-------|------|
+| `/math-tools:propositions` | Extract atomic props from .tex → JSONL + run R1-R8 mechanical gate (v0.1.0 scaffolding, scripts in source repo) |
+| `/math-tools:proofread` | JSONL-driven 6-layer L1-L5 + location-drift per-prop walk;produces `.proofread/<file>.md` checklist (v0.1.0 scaffolding) |
+| `/math-tools:manuscript-audit` | Cross-doc R1-R4 drift detection (working-file path leak, cite drift, code-manuscript symbol drift, prop-iso bijection) (v0.1.0 scaffolding) |
+
+## Rules (auto-injected when `.tex` files present)
+
+| Rule | What it enforces |
+|------|------------------|
+| `manuscript-jsonl-sync.md` | Prop-level main.tex ↔ JSONL sync HARD RULE (6 scenarios) |
+| `manuscript-consistency-audit.md` | Audit-time R1-R4 SOP + PR-side CI gate enforcement |
+| `code-and-manuscript-sync.md` | Repo-level cluster PR scope discipline (manuscript submodule + upper repo paired commits) |
+
+## v0.1.0 limitations
+
+Skill execution bodies are SCAFFOLDING ONLY. Source-of-truth lives in `PsychQuantHsu/psychophysical_representations` until iteration extracts:
+
+- `scripts/validate-propositions.py` (R1-R8 mechanical gate)
+- `scripts/refresh-prop-locations.py` (location-drift one-shot fix)
+- `scripts/audit-symbols.py` / `audit-citations.py` / `audit-code-manuscript.py`
+- `scripts/run-audit.sh` (orchestrator)
+- `.github/workflows/manuscript-audit.yml` (CI template)
+
+If you install this plugin in another math-article repo today, **most skill commands won't execute** — they describe methodology and point to the source repo. Treat as documentation + rules-loading until v0.2.0.
+
+## Development
+
+- Plugin structure: see [psychquant-claude-plugins doc-tools](../doc-tools/) for layout reference
+- Update after changes: `/plugin-tools:plugin-update math-tools`
+- Health check: `/plugin-tools:plugin-health`
+- First dogfood: this session's `#107` workflow itself (psychophysic_representations was the testbed)
+
+## Roadmap (v0.2.0+ targets)
+
+| Item | Status |
+|------|--------|
+| Extract `scripts/validate-propositions.py` into plugin | TODO |
+| Extract `scripts/refresh-prop-locations.py` into plugin | TODO |
+| Extract `scripts/audit-*.py` + `run-audit.sh` into plugin | TODO |
+| Per-project config `.claude/math-tools.json` for path parameterization | TODO |
+| Generalize rules (remove source-repo-specific refs) | TODO |
+| Skill execution bodies (replace SCAFFOLDING with working logic) | TODO |
+| First external dogfood (different math article repo) | TODO |
+
+## Cross-link
+
+- Source dogfood: PsychQuantHsu/psychophysical_representations
+  - #42 audit SOP
+  - #78 CI gate
+  - #106 location drift
+  - #107 proofread workflow experiment (closing summary contains full methodology annotation)
+- Sister plugins:
+  - `docflow` for multi-version document semantic synthesis (different concept space — version merge, not single-version audit)
+  - `doc-tools` for software-doc lifecycle (CHANGELOG / README — not academic articles)
+  - `perspective-writer` for prose voice simulation (not math)
diff --git a/plugins/math-tools/README.md b/plugins/math-tools/README.md
new file mode 100644
index 00000000..51385ae7
--- /dev/null
+++ b/plugins/math-tools/README.md
@@ -0,0 +1,44 @@
+# math-tools
+
+> Academic math article editing — propositions extraction, JSONL-driven proofread workflow, cross-doc audit gates, sync rules.
+
+## What it does (v0.1.0)
+
+Bundles 3 skills + 3 frozen baseline rules for the workflow demonstrated in `PsychQuantHsu/psychophysical_representations` issue #107:
+
+- **Mechanical gate** (`/math-tools:propositions`) — R1-R8 on `manuscript/propositions/main.jsonl` (verbatim, cite DAG, UUID v7, unique IDs, sentence/clause index)
+- **Semantic walk** (`/math-tools:proofread`) — 6-layer L1-L5 + location-drift per-prop checklist with hybrid coverage strategy (deep walk proof body + sample mid-density + heuristic scan commentary)
+- **Cross-doc audit** (`/math-tools:manuscript-audit`) — R1-R4 SOP catching working-file path leaks, cite drift, code-manuscript symbol drift, prop-iso bijection failures
+- **3 rules** — auto-loaded to enforce edit-time + audit-time + repo-level sync discipline
+
+## v0.1.0 scope
+
+**Scaffolding release.** Skill bodies + scripts live in the source repo until iteration extracts. Install today to get rules + methodology docs; expect v0.2.0 for working skill execution.
+
+## Why ship it now
+
+Per closing summary of #107:
+
+> 3 pilots 累積足夠 UX data,下次值得 build skill。已標 [-] deferred。
+
+This release captures the working methodology while fresh. Generalization (path parameterization, script extraction, external repo dogfood) comes after.
+
+## Install
+
+```bash
+claude plugin marketplace add PsychQuant/psychquant-claude-plugins
+claude plugin install math-tools@psychquant-claude-plugins
+```
+
+## Sister plugins
+
+- `docflow` — multi-version document semantic synthesis (different concept space)
+- `doc-tools` — software-doc lifecycle (CHANGELOG / README)
+- `perspective-writer` — prose voice simulation
+- `lean-prover` — Lean 4 automated proof grinding (different math area)
+
+None of these cover **academic math article editing + audit** as a coherent workflow — that's the gap `math-tools` fills.
+
+## License
+
+See [LICENSE](LICENSE) (TBD — match parent marketplace).
diff --git a/plugins/math-tools/references/mcs.md b/plugins/math-tools/references/mcs.md
new file mode 100644
index 00000000..a3a120ec
--- /dev/null
+++ b/plugins/math-tools/references/mcs.md
@@ -0,0 +1,32 @@
+# mcs.pdf — Mathematics for Computer Science (pointer)
+
+This directory may contain `mcs.pdf` — a local-only copy of Lehman / Leighton / Meyer, *Mathematics for Computer Science*, MIT OpenCourseWare textbook for 6.042J.
+
+## Status
+
+`mcs.pdf` is **git-ignored** (see [`../.gitignore`](../.gitignore)). Marketplace installs of this plugin do NOT bundle the PDF — only this pointer file is shipped.
+
+If you want the PDF locally:
+
+```bash
+# Free download from MIT OCW (CC BY-NC-SA 4.0):
+curl -o ~/Downloads/mcs.pdf \
+  https://ocw.mit.edu/courses/6-042j-mathematics-for-computer-science-spring-2015/resources/mit6_042js15_textbook/
+# Or browse: https://ocw.mit.edu/courses/6-042j-mathematics-for-computer-science-spring-2015/
+# Then drop it here:
+cp ~/Downloads/mcs.pdf <this-plugin>/references/mcs.pdf
+```
+
+`.gitignore` ensures the binary stays out of marketplace git history regardless.
+
+## Why this convention
+
+13 MB textbook × 39 plugins in the marketplace = git history bloat that hurts everyone. CC BY-NC-SA license also requires attribution + share-alike preservation, which is fragile when distributing through a marketplace. Local-only + pointer is the cleanest compromise.
+
+## License (if you redistribute)
+
+Lehman, Eric, F. Thomson Leighton, and Albert R. Meyer. *Mathematics for Computer Science*. MIT OpenCourseWare. License: CC BY-NC-SA 4.0. Source: <https://ocw.mit.edu>.
+
+## Use cases inside math-tools
+
+This pointer exists in case future skill bodies (v0.2.0+) want to cite MCS as a methodology reference (e.g. discrete math foundations for propositions extraction, induction proof patterns for L4 walk). v0.1.0 scaffolding doesn't yet — keep this pointer minimal for now.
diff --git a/plugins/math-tools/rules/README.md b/plugins/math-tools/rules/README.md
new file mode 100644
index 00000000..6acbdc05
--- /dev/null
+++ b/plugins/math-tools/rules/README.md
@@ -0,0 +1,37 @@
+# math-tools rules — v0.1.0 frozen baseline
+
+The 3 rules in this directory are **verbatim copies** from `PsychQuantHsu/psychophysical_representations/.claude/rules/` as of 2026-05-15 (dogfood origin of this plugin, see issue #107 closing comment for full pilot history).
+
+## Files
+
+| Rule | Origin | Scope |
+|------|--------|-------|
+| `manuscript-jsonl-sync.md` | psychophysic_representations#106 | Prop-level main.tex ↔ JSONL sync HARD RULE (edit-time prevention) |
+| `manuscript-consistency-audit.md` | psychophysic_representations#42 + #78 | Audit-time R1-R4 detection SOP (post-hoc + CI gate) |
+| `code-and-manuscript-sync.md` | psychophysic_representations (per `code-and-manuscript-sync.md` §歷史成因) | Repo-level cross-repo cluster PR scope discipline |
+
+## v0.1.0 limitations
+
+These rules currently reference **source-repo-specific** paths and identifiers:
+
+- Path conventions: `manuscript/main.tex`, `manuscript/propositions/*.jsonl`, `analysis/`, `references/*.tex`, `correspondence/`
+- Issue refs: `PsychQuantHsu/psychophysical_representations#NNN`
+- Tool paths: `scripts/validate-propositions.py`, `scripts/audit-symbols.py`, `scripts/refresh-prop-locations.py`
+
+If you install `math-tools` in another math-article repo, these references **will not auto-resolve**. Treat them as illustrative until v0.2.0 generalizes:
+
+- v0.2.0 target: parameterize paths via `.claude/math-tools.json` per-project config
+- v0.2.0 target: extract issue refs into generic dogfood-origin pointers
+- v0.2.0 target: bundle scripts inside this plugin (not link out to source repo)
+
+## Why ship frozen baseline first
+
+Per `#107` proofread workflow experiment closing summary §改進空間:
+
+> Skill systematization — 3 pilots 累積足夠 UX data,下次值得 build skill。已標 [-] deferred。
+
+This plugin is the **first step** toward that systematization — capture the working content now while the methodology is fresh; generalize after 2-3 more repos prove the pattern transfers.
+
+## Loading
+
+These rules are auto-injected into every Claude Code session that has the `math-tools` plugin installed and enabled in a math-article repo (file extension heuristic: `.tex` in working tree). Per `psychquant-claude-plugins` marketplace convention.
diff --git a/plugins/math-tools/rules/code-and-manuscript-sync.md b/plugins/math-tools/rules/code-and-manuscript-sync.md
new file mode 100644
index 00000000..7b9ef861
--- /dev/null
+++ b/plugins/math-tools/rules/code-and-manuscript-sync.md
@@ -0,0 +1,149 @@
+# Code-and-Manuscript Sync — 改一邊必改另一邊
+
+## 規則(HARD RULE)
+
+本專案的「**程式碼**」(`analysis/`)、「**參考文獻**」(`references/`)、「**manuscript**」(`manuscript/docs/` + `manuscript/*.tex`)是**單一 deliverable 的三面**,不是三個獨立 deliverable。
+
+任何 IDD 改動(`/idd-diagnose` → `/idd-implement`)若觸及其中一面,**必須**在同一個 PR / commit cluster 內審視並改動所有受影響的另外兩面。**禁止**把跨面 propagation 標為「out-of-scope follow-up」並另開 PR 處理。
+
+## 為什麼
+
+學術論文的程式碼產出餵進 manuscript 的 theorem / proof;manuscript 的推導依賴 references/ 的 source paper;references 又是 code 命名與算法 spec 的源頭。三者構成 source-of-truth 三角:
+
+```
+references/*.tex  ←→  analysis/*.py
+       ↓                  ↓
+       └──→ manuscript/docs/*.md ←──┘
+            manuscript/*.tex
+```
+
+任一面改動而另兩面未同步 = source-of-truth drift。具體危害:
+
+- **Reviewer**:看到 manuscript 引用已不存在的 reference paper / 已不存在的 analysis function → 無法 reproduce。
+- **下次來開發的 AI / 合作者**:讀 manuscript 想對照 code,grep 不到對應函數 → 誤以為 code base 不完整或 manuscript 是 stale。
+- **Submission 階段**:Late-stage 才發現「程式 omit Form B 但 manuscript 還有 50 行 Form B 推導」→ 大幅 rework 或撤稿風險。
+
+## Submodule 邊界 ≠ IDD scope 邊界
+
+`manuscript/` 是獨立 git repo(`PsychQuantHsu/psychophysical_representations_manuscript`),掛為上層 submodule。**這個 repo boundary 不該成為 IDD scope 邊界。**
+
+正確流程:
+
+```bash
+# 1. 在 manuscript submodule 內 commit manuscript 改動
+cd manuscript
+git checkout -b idd/cluster-19-22-manuscript-scope
+# ...edit docs/formB_*.md / *.tex...
+git commit -m "refactor(manuscript): remove Form B docs (Refs PsychQuantHsu/psychophysical_representations#19)"
+git push -u origin idd/cluster-19-22-manuscript-scope
+gh pr create --repo PsychQuantHsu/psychophysical_representations_manuscript ...
+
+# 2. 上層 repo bump submodule pointer 到 manuscript branch HEAD,在同 cluster PR
+cd ..
+git add manuscript
+git commit -m "chore: bump manuscript submodule pointer (Refs #19 #22 cluster scope)"
+```
+
+兩個 PR 互相 cross-link(上層 PR refs manuscript PR;manuscript PR refs 上層 issue + PR)。**不可**讓上層 PR merge 後才打開 manuscript PR — 那是「split scope」反 pattern,違反本規則。
+
+## 例外(rare,需明示理由)
+
+容許 split scope 的唯一情境:
+
+- **Overleaf 端衝突 in-flight**:user 正在 Overleaf 改 `manuscript/*.tex`,沒辦法在 AI session 內安全 edit。此時:
+  - 仍**列**所有受影響的 manuscript files 在 PR body
+  - 標 `OVERLEAF-WAIT`(不是 `OUT-OF-SCOPE`)
+  - PR body 給 follow-up issue link + 期望 sync 時點
+  - `idd-close` 前必須 verify manuscript 已 sync
+
+- **Manuscript 影響 unclear**:diagnosis 階段就告訴 user「不確定 manuscript 是否受影響」,AskUserQuestion 確認後才寫成 out-of-scope。**禁止** AI 自行判斷「manuscript 應該不太需要動」就 split。
+
+## Within-file frozen subregion exception(v1.2, 2026-05-12)
+
+某些 living docs(例如 `manuscript/docs/review-summary.md`)結構上**混合 current-state + historical log**:檔案的頭部是 living 內容(top scope-update note、currently-active section),body 是 frozen historical iteration log(rounds 1-N 的 history)。對這種「within-file frozen subregion」混合檔案:
+
+- **頭部 living 部分** — sync 要求**完全適用**(must update with current scope changes)
+- **body frozen iteration log** — 視為「within-file frozen subregion」,sync 要求**不適用**(歷史 log 的 value 是不被修改的時間順序紀錄)
+
+實務 marker(at least one needed for within-file exception to apply):
+
+1. 檔案頭部明確 section header 標示「historical」/「audit trail」/「iteration log」/「scope-update note above」,且該 section 之後的 body 都是 frozen 內容
+2. Living portion 主動 forward-link 到 #N(scope decision)讓 reader 知道 body 內容是 pre-decision 狀態
+3. 檔案被 idd-issue / idd-implement / idd-verify cycle 明確標記為 「partial-sync」(在 PR body 列出)
+
+不滿足 marker = 整檔視為 living,sync 要求完全適用。
+
+混淆風險:若 living portion 沒有明確 "scope-update note above + frozen section below" 結構,容易讓 reader 誤把 frozen log 當 current state。**Diagnose 階段必補檢查**:對 partial-sync 檔案,確認 marker 存在 + frozen subregion 對外有明示 boundary。
+
+## Frozen historical record exception(v1.1, 2026-05-12)
+
+以下 paths 是 **frozen historical records**,本規則的 sync 要求**不適用**;若這些 path 內仍有對已刪 / 已改 symbol 的引用,**不**視為 dangling consumer,但需在當前的 living docs(`docs/review-summary.md`、`docs/STATE.md` 等)中加 scope-update 註記指向新決策:
+
+- `manuscript/docs/rounds/*.md` — 個別 review round 的 audit log,frozen at the time of review
+- `manuscript/docs/legacy/*` — 已 retire 的 working drafts
+- `correspondence/*` — email archive 與歷史 thread,frozen at receipt time
+- 任何 `archived/` / `archive/` directory(已有 archive-first plugin 守護)
+
+**為什麼例外**:這些 path 的 value 是 audit trail(「什麼時候誰決定了什麼」)。Retroactive editing 會 destroy 這個 value — 三個月後 reviewer 想看「Form B 當時是怎麼被討論的」會看到 sanitized 版本而非真實當時 state。修改 frozen records = 改變歷史。
+
+**邊界**:`manuscript/docs/STATE.md`、`README.md`、`docs/README.md`、`cover-letter-template.md`、`reviewer-reply-template.md`、`review-summary.md` 等 living docs **不在例外範圍** — 它們 represent current state,sync 要求**完全適用**。
+
+**Diagnosis check 必補一句**:對被 grep 到的引用,explicit 區分 (a) frozen record(免 sync,標 audit-update 在 living docs)vs (b) living doc(必 sync)。混 (a) 與 (b) = 規則 violation。
+
+## Diagnosis 階段必檢
+
+`/idd-diagnose` 對任何 code / references 改動,**必須**在 Strategy / Impact 段顯式回答:
+
+1. 此 code 改動會 invalidate 哪些 `manuscript/docs/*.md` 的推導 / 引用?(用 `grep -rln "<deleted-symbol>" manuscript/docs/`)
+2. 此 code 改動會 invalidate 哪些 `manuscript/*.tex` 的 theorem / proof?
+3. 上述受影響檔案是否在本 cluster 的 implementation plan 內?如否,**升級** scope 或 abort 重新 diagnose。
+
+回答「**N/A — 純 IDD tooling 改動,manuscript 不影響**」是合法答案(例如改 `.mail/` config),但必須**明示寫出**這個判斷,不能省略。
+
+## Verification 階段必檢
+
+`/idd-verify` 的 Regression Reviewer 必須額外驗證:
+
+- diff 中刪除的 symbol / 檔案,grep manuscript/docs/ + manuscript/*.tex 有無遺漏引用
+- 若 manuscript 仍引用已刪內容 → **blocking finding**,PR 不能 PASS
+
+## 歷史成因
+
+本規則 2026-05-12 加入,起因為 cluster PR #25 (`#19` Form B omission + `#22` references housekeeping):AI 把 `manuscript/docs/` 10 個 Form B docs 標為 `out-of-scope follow-up` 並另期 PR 處理。User 介入指正:此 split 違反 source-of-truth 三角約束,manuscript edits 應在同 cluster 完成。
+
+完整原則(來自 user 2026-05-12 對話):
+> 「我發現你好像忽略了改的時候 manuscripts 也都要一併修改,不是只有程式」
+
+## 與 issue-routing.md 的關係
+
+[`.claude/rules/issue-routing.md`](issue-routing.md):「所有 issue 都開上層 repo」— 這是 **GitHub issue tracking** 的紀律。
+**本規則**:「所有 implementation 都跨 code + manuscript」— 這是 **PR scope** 的紀律。
+
+兩者互補。同一 issue 可以驅動上層 repo PR + manuscript submodule PR 兩條,只要 cross-link + 同 cluster + 同步 merge。
+
+## See also
+
+[`manuscript-consistency-audit.md`](manuscript-consistency-audit.md) — **audit-time detection** SOP,互補於本規則的 **PR-time prevention**。
+
+| Rule | 何時運作 | 防範什麼 |
+|------|----------|----------|
+| 本規則 `code-and-manuscript-sync.md` | PR-time(改一邊時) | 避免單 PR 內 code 改但 manuscript 沒同步 |
+| `manuscript-consistency-audit.md` | Audit-time(大改稿後 / 投稿前) | 偵測歷史 drift 累積後的不一致(working-file leak、citation drift、symbol drift) |
+| `.github/workflows/manuscript-audit.yml`(CI gate, #78) | PR-side machine enforcement | 把 audit SOP 自動跑在每個 PR;R1/R2/R4 blocking → PR 紅燈無法 merge |
+
+兩者**並非**取代關係:hard rule(本規則)是 prevention,SOP(audit)是 detection,CI gate(#78)是兩者的 machine-side enforcement。即使 hard rule 嚴格執行,drift 仍可能在 review back-and-forth、concurrent editing、scope-split mistakes 等情境下累積,需要 audit pass 補抓 + CI gate 把 audit 自動化。
+
+## GH Actions CI gate (PR-side enforcement, #78)
+
+從 #78 開始,`.github/workflows/manuscript-audit.yml` 成為本規則的 **PR-time prevention** 機械補強層。本規則(prevention by author discipline)+ CI gate(prevention by machine enforcement)+ audit SOP(detection)三層 defense-in-depth:
+
+| 層級 | Enforcement | 失敗時 |
+|------|-------------|--------|
+| 本規則 `code-and-manuscript-sync.md`(human-side) | Reviewer / author 自我紀律 | PR open 即被 reviewer 標 "scope split" 然後 author 補 |
+| `.githooks/pre-commit`(author-side machine) | R1 + R2 + R4 fast passes | Commit aborts(`git commit --no-verify` bypass for emergency) |
+| `.github/workflows/manuscript-audit.yml`(PR-side machine) | Full R1 + R2 + R3 + R4 on every PR | PR 紅燈 `manuscript-audit / run` = FAILURE,無法 merge |
+| `./scripts/run-audit.sh manuscript/`(on-demand) | Per SOP §5 trigger(大改稿 / 投稿前 / 新階段) | Author 自決修不修 |
+
+CI gate 確保即使 author 跳過 pre-commit hook、或外部 contributor 從未裝過 hook,只要 PR open / push to main 就會被 audit。Cross-repo private submodule auth via `MANUSCRIPT_TOKEN` PAT secret(see README "CI gate" subsection)。
+
+CI gate 不取代本規則 — 本規則的「manuscript 同步必須在同 PR」紀律,CI 只能驗 audit 過,不能驗 author intent。但 CI 抓 R1/R2/R4 drift 後拒絕 merge (R3 視為 informational baseline,不阻 merge — 詳見 `manuscript-consistency-audit.md` §8 + §9 Pattern 7/8),等於把「scope split 偷渡」的 escape hatch 關掉。
diff --git a/plugins/math-tools/rules/manuscript-consistency-audit.md b/plugins/math-tools/rules/manuscript-consistency-audit.md
new file mode 100644
index 00000000..08a268bf
--- /dev/null
+++ b/plugins/math-tools/rules/manuscript-consistency-audit.md
@@ -0,0 +1,345 @@
+# Manuscript Consistency Audit SOP
+
+> Audit-time detection of inconsistencies that accumulate in the manuscript over multi-author / multi-iteration editing.
+
+## §1 Scope & purpose
+
+本 SOP 是 audit-time detection 工具，互補於 `code-and-manuscript-sync.md`(PR-time prevention)。前者防止單一 PR 內 code/manuscript drift；本 SOP 處理「歷史 drift 已累積後」的補救。
+
+**何時跑本 SOP**
+
+- 大改稿後(例如某次大幅 rewrite section、新增 theorem、整體 reorganize)
+- 投稿前最後一輪檢查
+- Manuscript 進新階段(initial submission、major revision、camera-ready)前
+
+**何時不跑**
+
+- 每個 PR 都跑 → 太重(60K manuscript full audit 估 30-60s)。Pre-PR lightweight diff 是 #44 範圍
+- Minor commit 後(typo、單詞替換)→ 不必
+
+## §2 Inconsistency types & detection coverage
+
+| Type | 例子 | 自動偵測 | 覆蓋 rule |
+|------|------|----------|-----------|
+| 符號 / 變數命名 drift | 第 2 節用 $\theta$ 第 4 節變 $\beta$;`analysis/` 用 `mse_diff` 但 manuscript 寫 `MSE_d` | 部分(R1 抓 `\texttt{}` working-file leak;R3 抓 code/manuscript symbol drift) | R1, R3 |
+| 定義 / 假設邏輯矛盾 | 某處定義 $X$ 為連續變數,另一處推導當作離散 | 不(語意層必人工) | 無 |
+| code/manuscript drift | `analysis/` 改了但 `manuscript/docs/` 未同步 | 是(R3) | R3 |
+| Citation / reference drift | `\cite{Smith2020}` 但 `refs.bib` 是 `Smith2021`;漏 bib 條目;LaTeX label 當 published reference | 是(R2 + R2-bis) | R2, R2-bis |
+| Narrative / wording 跳接 | 段落間邏輯接不上;術語在不同章節用不同中譯 | 不(語意層必人工) | 無 |
+| Working-file path leak | `main.tex` 引用 `\texttt{analysis/foo.py}` 或 `\texttt{manuscript/docs/note.md}` | 是(R1) | R1 |
+| Proposition ↔ tex drift | `.tex` 新增 prop 對應段落但 `propositions/main.jsonl` 沒同步;mechanical contradiction (e.g. boundary axiom 違反 — see #60 / #68) | 是(R4 — Phase 1 prop-subset-check + PATTERN-A/B mechanical-contradiction) | R4 |
+
+自動覆蓋率約 60-70%(types 1, 3, 4, 6 子集 + type 7)。語意層 inconsistency(types 2, 5)必人工處理,本 SOP 不取代但提供 symbol table 索引輔助快速定位。R4 是 Locke-project 衍生 — 僅當 manuscript 有 `propositions/main.jsonl`(或 legacy `main.json`)才跑。
+
+## §3 Excluded paths
+
+以下路徑屬 frozen historical record，audit 不掃:
+
+- `manuscript/docs/rounds/` — Review round audit log,frozen at the time of review
+- `manuscript/docs/legacy/` — 已 retire 的 working drafts
+- `correspondence/` — Email archive,frozen at receipt time
+- `references/*.tex` — 歷史 reference papers,frozen
+- 任何 `archive/` / `archived/` 目錄(已由 archive-first plugin 守護)
+
+理由與 `code-and-manuscript-sync.md` Frozen historical record exception 一致:這些路徑的 value 是 audit trail,retroactive editing 會 destroy 該 value。詳見 [code-and-manuscript-sync.md](code-and-manuscript-sync.md) Frozen exception 段落。
+
+## §4 Pass-level vs Finding-level task model
+
+Audit 採 **hybrid two-layer task** model:
+
+### Pass-level(per inconsistency type，掃全文建索引)
+
+固定 small N(~3 pass)。每 pass 對應一條 rule:
+
+1. **Pass R1**: 掃 `main.tex` 所有 `\texttt{}` token,抓 working-file path leak
+2. **Pass R2**: 掃 `\cite*{}` keys + parse `refs.bib`,做 label leak detection + bib cross-check
+3. **Pass R3**(Phase 2): 比對 `analysis/*.py` AST vs `manuscript/docs/*.md` backtick code
+
+Pass 之間 independent,可 parallel 跑(`run-audit.sh` 預設 serial,簡化 output ordering)。
+
+### Finding-level(per detected conflict，deep dive)
+
+Variable N(典型 5-30)。Pass 跑完後,**每個 definite + likely finding 開一個 task** 處理:
+
+- 確認是真衝突還是 false positive
+- 決定 fix 方向(改 manuscript / 改 code / mark white-list)
+- 若 critical(影響 published claim 的正確性)→ 開 `audit-finding` issue 走 IDD 流程
+
+純 per-paragraph(每段一個 task)**不採用** — 不一致性本質是「A 段 vs B 段」cross-reference 關係,單看一段抓不到。
+
+## §5 Trigger 時機
+
+| 階段 | Trigger | Audit 範圍 | 處理 |
+|------|---------|------------|------|
+| 大改稿後 | 手動 `./scripts/run-audit.sh manuscript/` | Full(R1 + R2 + R3) | 產生 `manuscript/docs/audit/audit-YYYY-MM-DD.md`;critical findings 開 issue |
+| 投稿前 | 手動同上 | Full | 同上,要求 zero definite finding 才送投 |
+| 每個 PR(touching `main.tex`/`analysis/`/`refs.bib`) | pre-commit hook(由 #44 實作) | Lightweight diff(only changed symbol cross-check) | 阻擋 commit if definite finding |
+
+**Precondition(SOP §8)**: audit 前必確認 working tree state,避免 concurrent editing race。
+
+## §6 Output 形式
+
+### Audit report
+
+- 落地路徑:`manuscript/docs/audit/audit-YYYY-MM-DD.md`
+- 在 manuscript submodule 內(報告 reference manuscript 內容 → 跟 manuscript 一起 frozen 在歷史)
+- `.gitignore` 排除自動產出檔(`audit-20[2-9][0-9]-[0-1][0-9]-[0-3][0-9].md` ISO date pattern),只保留目錄結構(`.gitkeep`)
+- Severity 分級:
+  - **definite**: 確定違例,必修(e.g. working-file path leak、citation key 不在 bib)
+  - **likely**: 80%+ 機率違例(e.g. citation label leak、symbol drift candidate)
+  - **suspicious**: 50-80%(e.g. 不在 white-list 的少見 `\texttt{}` 用法)
+  - **FYI**: < 50%(e.g. bib orphan、code-only symbol 未在 manuscript 提)
+
+### Critical finding → GitHub issue
+
+- definite + likely 開 issue,label `audit-finding` + `scope:manuscript`
+- 走 IDD 流程修復(`/idd-diagnose` → `/idd-implement`)
+- suspicious + FYI 只進 audit report 不發 issue,避免 noise
+
+### 不自動 PATCH manuscript
+
+- audit 是 read-only。Findings 的 fix 決定權在 author(可能不同 finding 用不同策略,e.g. 改 manuscript / 改 code / mark intentional)
+
+## §7 Audit report 格式 spec
+
+```markdown
+# Manuscript Consistency Audit — YYYY-MM-DD
+
+**Manuscript snapshot**: <git rev-parse HEAD of manuscript repo>
+**Audit tool versions**: audit-symbols.py vX.Y / audit-citations.py vX.Y / audit-code-manuscript.py vX.Y
+
+## Summary
+
+- Definite: N findings
+- Likely: M findings
+- Suspicious: K findings
+- FYI: J findings
+- Total: N+M+K+J
+
+## Findings
+
+### Definite
+
+#### F1: <one-line description>
+- **Rule**: R1 / R2 / R2-bis / R3
+- **Location**: `<file>:<line>`
+- **Context**: <surrounding ±2 lines>
+- **Proposed fix**: <suggestion>
+- **Tracking issue**: #NNN (if opened)
+
+(repeat per finding)
+
+### Likely
+
+(same format)
+
+### Suspicious / FYI
+
+(condensed table format)
+```
+
+## §8 Run instructions
+
+### Pre-flight
+
+```bash
+# 1. Ensure working tree clean (avoid concurrent-editing race)
+cd /path/to/psychophysic_representations
+git status --short  # must be empty
+git submodule status  # ensure manuscript pointer matches expected
+
+# 2. Pull latest (avoid auditing stale state)
+git pull --rebase
+cd manuscript && git pull --rebase && cd ..
+```
+
+### Run
+
+```bash
+# Phase 1 only (Rule R1 + R2):
+python3 scripts/audit-symbols.py --manuscript-root manuscript/ --report-format md
+python3 scripts/audit-citations.py --manuscript-root manuscript/ --report-format md
+
+# Phase 2 full audit (adds R3 + R4 + orchestration):
+./scripts/run-audit.sh manuscript/
+# → 產生 manuscript/docs/audit/audit-$(date +%F).md
+# R4 (proposition-iso) 只在 manuscript 有 propositions/main.jsonl 時才跑
+# (legacy single-file propositions/main.json 仍接受作為 fallback)
+
+# 單跑 R4 (proposition-iso bijection check, Locke project):
+python3 scripts/validate-propositions.py \
+  --jsonl manuscript/propositions/main.jsonl \
+  --meta manuscript/propositions/_meta.json \
+  --tex manuscript/main.tex
+
+# Legacy fallback (mid-migration repos still on single-file JSON):
+python3 scripts/validate-propositions.py \
+  --json manuscript/propositions/main.json \
+  --tex manuscript/main.tex
+```
+
+### Three enforcement layers (#78)
+
+| Layer | When | What |
+|-------|------|------|
+| `.githooks/pre-commit` (author-side) | Per-commit, when staged paths match audit-relevant globs | Fast R1+R2+R4 (R3 too slow per-commit) |
+| `./scripts/run-audit.sh manuscript/` (manual full) | Per SOP §5 trigger (大改稿 / 投稿前 / 新階段) | Full R1+R2+R3+R4 |
+| `.github/workflows/manuscript-audit.yml` (PR-side, GitHub Actions) | Every PR + push to main, paths-filtered | Full R1+R2+R3+R4; fails on R1/R2/R4 blocking, R3 informational |
+
+CI gate (third layer) catches external contributors / forgotten pre-commit hook. After first green run, mark `manuscript-audit / run` as required status check on `main` branch (Settings → Branches → Branch protection rule).
+
+### Exit codes
+
+- `0`: clean (zero findings of any severity)
+- `1`: at least one finding (any severity)
+- `2`: tool error (script crash, missing file, etc.)
+
+### Post-flight
+
+- Review report,definite + likely findings 開 `audit-finding` issue 走 IDD
+- 把 `.claude/.idd/audit-history.log` 加一行(或類似 trail)記錄 audit datestamp、commit hash、finding counts(方便 trend tracking,未實作)
+
+## §9 Examples / known patterns
+
+### Pattern 1: working-file path leak in `\texttt{}` (Rule R1)
+
+**Bad** (caught by R1):
+```latex
+Sympy substitution verifications are provided in
+\texttt{analysis/verify\_eta\_fs.py} (companion derivation
+in \texttt{manuscript/docs/gc\_iverson\_eta\_fs.md}).
+```
+
+**Fix**: delete the sentence(formal manuscript 不該引用內部 working scripts)
+
+**Good**(white-listed):
+```latex
+\bibliography{refs.bib}  % whitelisted: bibliography reference
+% \texttt{old_var}      % comment, not rendered
+```
+
+### Pattern 2: citation label leak (Rule R2)
+
+**Bad** (caught by R2):
+```latex
+\citet[Theorem~\texttt{main\_thm\_ess}]{DobleHsu2020}
+```
+
+(`main_thm_ess` 是 DobleHsu 2020 source 的 LaTeX `\label{}` ID,不是 published theorem 編號)
+
+**Fix**: 改成 content-based description:
+```latex
+\citet[Theorem on $\eta = f(s)$ case]{DobleHsu2020}
+```
+
+或直接刪除 parenthetical(如果 surrounding sentence 已說明 theorem context)。
+
+### Pattern 3: working-note file reference (Rule R1)
+
+**Bad** (caught by R1):
+```latex
+\item ... (working note, file
+\texttt{note (Hsu 2024-02).tex}, line $\sim$173). The note isolates ...
+```
+
+**Fix**: 刪 parenthetical,保留 sub-section 標籤(若 label 仍有 trace 價值):
+```latex
+\item ... The note isolates ...
+```
+
+### Pattern 4: companion working doc reference (Rule R1)
+
+**Bad** (caught by R1, 2026-05-13 example):
+```latex
+... \texttt{manuscript/docs/note-2024-02-audit.md}.
+```
+
+**Fix**: 改成 content-based description:
+```latex
+... as catalogued in our companion working documentation.
+```
+
+或刪除(若 context 已足夠)。
+
+### Pattern 5: bib orphan (Rule R2-bis)
+
+**Bad**(caught by R2-bis):
+```latex
+\cite{Missing2020}  % but Missing2020 not in refs.bib
+```
+
+**Fix**: 加 bib 條目,或修正 cite key typo。
+
+### Pattern 6: code symbol drift (Rule R3, Phase 2)
+
+**Bad**(caught by R3):
+```latex
+% manuscript/docs/foo.md:
+... computed via `mse_diff` ...
+
+% but analysis/foo.py defines `mse_difference`, not `mse_diff`
+```
+
+**Fix**: 對齊命名,改 code 或改 manuscript(端視哪邊已 published)。
+
+### Pattern 7: False positive suppression / calibration
+
+**症狀**: R3 對 real manuscript 跑出大量 `definite` findings,點開看全是 LaTeX `\label{}` ID、`\cite{}` key、bib entry key。
+
+**根因**: backtick code refs `` `X` `` 在 manuscript context 不僅可能是 Python symbol,也常是:
+- LaTeX label(`\label{thm:foo}` → `` `thm:foo` ``)
+- Citation key(`\cite{Smith2020}` → `` `Smith2020` ``)
+- Bibliography entry(`@article{Smith2020, ...}`)
+- Filename(`` `note.tex` ``)
+
+R3 預設只比對 Python AST symbol,不認識這些 LaTeX-domain 名稱。
+
+**解法**(已 implement,自 v0.2):
+
+`audit-code-manuscript.py` 內建 `collect_latex_allowlist()` 自動 scan:
+- `<manuscript-root>/**/*.tex` 的 `\label{}` 與 `\cite{}` keys
+- `<manuscript-root>/**/*.bib` 的 entry keys(只認可 BibTeX 標準 type,不抓 `@string`/`@comment`/`@preamble`)
+- Sibling `<manuscript-root>/../references/**/*.tex`(working note .tex,自動發現)
+
+可額外用 `--latex-source-root <path>` 加入其他 directory(例如 Overleaf 共筆夾)。
+
+**Allowlist hit 處理**: severity 從 `definite` demoted 到 `FYI`,不開 issue,只 informational。`audit-code-manuscript.py:179-200` 內 `in_latex_domain` 判斷邏輯。
+
+**Calibration baseline**: `psychophysic_representations` repo first audit 2026-05-13 在 v0.1 報 86 definite + 25 FYI;v0.2 fix 後降到 18 definite(全部都是 real drift:hallucinated label `basic_fe_phil`、stale check function references)+ 93 FYI。
+
+**仍 leak 通常代表 real drift**:
+- 引用 `lem_Foo` 但任何 `.tex` / `.bib` 都沒有此 label → 可能是 hallucinated reference
+- 引用 `check_bar` 但 `analysis/*.py` 沒此 function → 可能是 stale doc 引用已移除的 helper
+
+不要把 v0.2 後仍 leak 的 finding 當 noise — review-summary.md 內已有先例(`basic_fe_phil` hallucinated)。
+
+### Pattern 8: First-audit calibration workflow
+
+新 manuscript 第一次跑 audit 預期 noise > 0,即使本 SOP fix 後:
+
+1. 跑 `./scripts/run-audit.sh manuscript/`
+2. Definite 數量看 R1 + R2 + R3:
+   - R1 (working-file leak):應 ≤ 2(若 > 5,review baseline manual audit)
+   - R2 (label leak):應 ≤ 1(同上)
+   - R3 (code drift):依 codebase 複雜度,2-20 為 healthy range;> 30 仍 noisy → 可能需要 extra `--latex-source-root`
+3. 對每個 definite finding,先判 category:
+   - **真 drift**(symbol typo / rename / removed)→ 開 `audit-finding` issue
+   - **R3 allowlist miss**(label/cite/bib 在 import 之外的 file)→ 加 `--latex-source-root` 涵蓋,或 file enhancement issue
+   - **R3 真陽性 但 manuscript-side 是 deliberate 內部 reference**(罕見)→ 加 `audit-ignore` 機制(目前 v0.2 未實作,屬 future enhancement)
+4. SOP §9 Pattern 7 + 8 是首跑教學;熟練後跳過
+
+## §10 Relationship to other rules / skills
+
+- [`code-and-manuscript-sync.md`](code-and-manuscript-sync.md) — PR-time prevention,本 SOP audit-time detection,互補
+- [`issue-routing.md`](issue-routing.md) — `audit-finding` issue 一律開上層 repo,加 `scope:manuscript` label
+- `/spectra-verify` — spec-driven verify 不取代本 SOP;前者驗 spec contract,後者驗內部一致性
+- Pre-commit hook integration + skill orchestration — 由 #44 (sister concern of #42) 追蹤
+
+## Changelog
+
+- 2026-05-13: initial version,covers Phase 1 (R1 + R2 + R2-bis);R3 + orchestration 在 Phase 2 補
+- 2026-05-13 (v0.2): R3 calibration hot-patch — LaTeX label / cite / bib entry allowlist,
+  auto-discover sibling `references/`,severity demoted from `definite` → `FYI` for allowlist hits.
+  Also: BibTeX `@string`/`@comment`/`@preamble` no longer mis-classified as bib entries.
+  `ast.parse` failure now warns instead of silent empty set. §9 Pattern 7/8 added.
+  Addresses verify findings F-R3-Cal, F-Logic-C2, F-Codex-F6. See #42 PR #49 verify comment.
diff --git a/plugins/math-tools/rules/manuscript-jsonl-sync.md b/plugins/math-tools/rules/manuscript-jsonl-sync.md
new file mode 100644
index 00000000..1df21cc7
--- /dev/null
+++ b/plugins/math-tools/rules/manuscript-jsonl-sync.md
@@ -0,0 +1,176 @@
+# Manuscript ↔ JSONL Sync — 改一邊必改另一邊（prop-level）
+
+## 規則 (HARD RULE)
+
+本專案的 `manuscript/main.tex` 與 `manuscript/propositions/main.jsonl` (+ `_stage2/*.jsonl` + `_pilot/*.jsonl`) 是**單一 source of truth 的兩面**，不是兩個獨立 deliverable。
+
+任何 `main.tex` 內容改動（rewording / restructure / 加減 sentence / line shift）都**必須**在同一個 commit / change cluster 內審視並更新對應的 propositions JSONL props。**禁止**「先改 main.tex 等之後再 sync jsonl」— 那等於把 R1 drift 變成 latent debt。
+
+對應的 macro-level rule 是 [`code-and-manuscript-sync.md`](code-and-manuscript-sync.md)（manuscript ↔ code 跨 repo PR scope）。本 rule 是 **finer-grained**：manuscript 內部 main.tex ↔ JSONL sync。兩條 rule 互補不重疊。
+
+## 為什麼
+
+JSONL 結構是 **manuscript 的 structural representation** — 每個 prop 對應 main.tex 一句 / 一段論述，攜帶 `text`（verbatim from .tex）+ `location`（line range）+ `cites`（內部依賴 UUID）+ `asserts`（原子化 claim）+ `claim_type` + `evidence_class`。下游消費者包括：
+
+- `validate-propositions.py` R1-R8 audit gate（驗 verbatim match / DAG / 唯一性）
+- `manuscript-consistency-audit.md` SOP 的 R3 code-↔-manuscript drift detection
+- 校稿 workflow（per `#107` proofread experiment）— 利用 jsonl 結構做 per-prop 檢核
+- 未來 `idd-verify` 可能讀 jsonl 做 propositional verification
+
+若 main.tex 改了但 jsonl 沒同步：
+
+| 漂移類型 | 後果 |
+|---------|------|
+| **prop.text drift** | R1 prop-subset-check FAIL（validator gate 紅燈） |
+| **location drift** | R1 substring match 可能仍 PASS，但 `location` field 失準 → human-navigate-by-line 跳到錯誤行 → 重新 audit / proofread 時 false location reports（per #106 / pilot 1 + 2） |
+| **新增 sentence 沒對應 prop** | R1.5 surjective coverage WARN（某些 main.tex 段落沒 prop 覆蓋） |
+| **刪除 sentence 但 prop 留著** | R1 FAIL（prop.text 找不到） |
+| **cite chain 對應錯誤** | R3 DAG check 可能仍 PASS（內部 UUID 引用），但語意上 prop A 不再 derive 自 prop B（main.tex 已 restructure 依賴關係） |
+
+## Sync 範圍 — 改動類型 × 對應 jsonl action
+
+### 1. Wording change（micro-edit，不動結構）
+
+例：typo fix、`\sigma$ continuous` → `\sigma$ continuous and nonzero`。
+
+| Action | Required |
+|--------|----------|
+| 找出包含該段的 prop（grep `prop.text` 與更新前段落首句相符） | ✓ |
+| Update prop.text to new wording verbatim | ✓ |
+| Re-run `python3 scripts/validate-propositions.py --jsonl ... --tex ...` 確認 R1 PASS | ✓ |
+| Update asserts if semantic changed | conditional |
+
+### 2. Line shift（contents 不變但 line range 改變）
+
+例：在 L100 area 加 5 行，後面所有 line 都 +5。
+
+| Action | Required |
+|--------|----------|
+| Run `scripts/refresh-prop-locations.py --jsonl <file>` to refresh `location` fields | ✓ |
+| Validate R1 still PASS post-refresh | ✓ |
+| Update `_meta.json` line ranges if sections shifted | conditional |
+
+### 3. Add sentence / paragraph
+
+例：新增 footnote 補強說明。
+
+| Action | Required |
+|--------|----------|
+| 對新增內容寫 1+ 新 prop（依 granularity convention） | ✓ |
+| 新 prop 用 UUID v7（per `EXTRACTION-PROMPT.md` + SCHEMA v1.2+） | ✓ |
+| 設適當 cites field（內部 dependency UUID）+ claim_type + evidence_class | ✓ |
+| Append to appropriate JSONL file (`main.jsonl` for paper body / `_stage2/*.jsonl` for Theorem 1 staging) | ✓ |
+| Re-validate R1-R8 | ✓ |
+
+### 4. Delete sentence / paragraph
+
+例：撤回一段 commentary。
+
+| Action | Required |
+|--------|----------|
+| 找對應 prop（grep main.jsonl + _stage2/*.jsonl） | ✓ |
+| 刪除該 prop | ✓ |
+| Grep `cites` field of remaining props for the deleted UUID — strip if any | ✓ |
+| Re-validate R3 (no dangling cite reference) | ✓ |
+
+### 5. Restructure（reorder sentences / split paragraph / merge sentences）
+
+例：把 Cases A/B/C/D 的 γ formulas 從 inline 改成 align*。
+
+| Action | Required |
+|--------|----------|
+| Read affected prop range; reassess granularity（new structure 可能需要 prop split or merge） | ✓ |
+| Update prop.text + location + sentence_index/clause_index | ✓ |
+| Cite chain may need re-anchoring（restructured dependencies） | ✓ |
+| Re-validate R1+R3+R6 | ✓ |
+
+### 6. Cite chain modification (jsonl only, no main.tex change)
+
+例：本 rule 範例 #1 — proofread workflow 發現 P91 漏 cite Iverson similarity equation 的 Setup prop。
+
+| Action | Required |
+|--------|----------|
+| Update prop.cites field with missing UUID | ✓ |
+| Re-validate R2 cite-resolve + R3 DAG | ✓ |
+| **No main.tex change** required（cite is jsonl metadata，不出現在 paper body） | — |
+
+## Diagnosis 階段必檢
+
+`/idd-diagnose` 對任何 `manuscript/main.tex` 改動 (`scope:manuscript` label) **必須**在 Strategy 段顯式回答：
+
+1. 此 main.tex 改動會 invalidate 哪些 `manuscript/propositions/*.jsonl` 的 props？(grep prop.text 對應段落)
+2. 此改動屬於上方哪種 sync 範圍類型（wording / line shift / add / delete / restructure / cite-only）？
+3. 對應的 sync action 是否在本 cluster 的 implementation plan 內？如否，**升級** scope 或 abort 重新 diagnose。
+
+回答「**N/A — 純 cite-chain edit，不動 main.tex**」是合法答案（情境 6），但必須明示寫出該判斷。
+
+## Implementation 階段必檢
+
+`/idd-implement` 對 manuscript edit + propositions edit 的 cluster：
+
+1. 在 staging（pre-commit）先跑 `python3 scripts/validate-propositions.py --jsonl ... --tex ...` 確認 R1 PASS
+2. 若 location shifted → 跑 `scripts/refresh-prop-locations.py --jsonl ...`（per #106 fix）
+3. Commit 同時納入 main.tex changes + jsonl changes，**不**拆 2 commits（intermediate state validator FAIL）
+
+## Verification 階段必檢
+
+`/idd-verify` 的 Regression Reviewer **必須**額外驗證：
+
+- diff 中 main.tex 的改動 line range，grep `manuscript/propositions/*.jsonl` 的 `location` field 看是否有對應 prop
+- 若 main.tex shifted N lines (insert/delete) — 確認 jsonl 內後段 props 的 `location` 已對應 shift
+- R1 prop-subset-check：所有 props 仍 verbatim found in updated main.tex
+- 若 manuscript edit cluster 沒有 jsonl 對應 commit → **blocking finding**，verify FAIL
+
+## 自動化（partial）
+
+`scripts/validate-propositions.py` 提供 mechanical-level enforcement:
+
+- R1 catches text drift
+- R3 catches dangling cite from deleted props
+- R6 catches sentence/clause-index invariant violation
+- R8 catches duplicate UUID after add/delete
+
+但**不**catch：
+
+- semantic drift（main.tex reworded but jsonl still semantically valid — only human review catches this）
+- line-anchor drift（R1 使用 substring containment over whole file，不檢查 location 字面）— per #106, 需要 `scripts/refresh-prop-locations.py` 或 future R9
+- claim_type / evidence_class 漂移 — schema-aware heuristics 需要 calibration（per #107 proofread experiment）
+
+## 例外
+
+容許 main.tex edit 不立即 sync jsonl 的唯一情境：
+
+- **Pre-extraction phase**: manuscript 剛起草，尚未開始任何 propositions extraction（pre-#69 / pre-#77 state）。此情境下 jsonl 不存在或非 active artifact，不適用 sync rule。
+- **Author works in Overleaf concurrently**: 若 author 在 Overleaf 改稿，AI 本機 session 看到 working tree 仍 stale。此情境下 AI **必須**在 diagnose 階段 explicit 註記「Overleaf-side 改動可能 in-flight」+ `OVERLEAF-WAIT` 標籤，per `code-and-manuscript-sync.md` § Overleaf 衝突 in-flight 例外。
+
+## 歷史成因
+
+本 rule 2026-05-15 加入，起因：
+
+1. **#60 Path C revert (commit `35c964a`)** main.tex 改 75 行，propositions sync 需要刪 6 + 7 props + update 3 props + strip 5 dangling cites — 過程中 R-3 risk (high) 已 mitigated 在 plan，但實作中差點漏掉。
+2. **#106 location drift audit-finding**：13 props 在 `_stage2/theorem1.jsonl` `location` field 與實際 main.tex 不對應，因 Path C content edits 後沒 refresh location。屬於 line-shift sync 缺口的 latent debt。
+3. **#107 proofread workflow pilot**：將 jsonl 升格為 校稿 checklist source 後，prop-level 對應到 main.tex 的精確性變成 first-class 需求 — R1 substring match 不夠。
+4. **Pilot 2 L4 alignment walk (Step 1, 7 props)**：surface 2 個 L3 cite-completeness gap (P91 漏 Iverson eq cite, P94 漏 Setup interval cite) — 屬於情境 6 (cite-only edit) 但前一輪 extraction 沒抓到，需要 prop-level discipline 而非整段 audit。
+
+## 與其他 rules 的關係
+
+| Rule | Scope | When fires |
+|------|-------|-----------|
+| [`code-and-manuscript-sync.md`](code-and-manuscript-sync.md) | repo-level（upper repo ↔ manuscript submodule cross-repo PR） | macro: cluster PR cross-link discipline |
+| [`manuscript-consistency-audit.md`](manuscript-consistency-audit.md) | audit-time（drift detection across long timespan） | post-hoc: 大改稿 / 投稿前掃描 R1-R4 |
+| **本 rule** `manuscript-jsonl-sync.md` | edit-time（每次 main.tex edit 同時 jsonl sync） | per-commit: 每個 manuscript change |
+
+三者互補:
+- 本 rule 是 **prevention** at edit time
+- consistency-audit 是 **detection** post-hoc
+- code-and-manuscript-sync 是 **cluster PR scope** discipline
+
+## See also
+
+- [`code-and-manuscript-sync.md`](code-and-manuscript-sync.md) — macro-level cross-repo sync
+- [`manuscript-consistency-audit.md`](manuscript-consistency-audit.md) — audit-time detection SOP
+- `manuscript/propositions/SCHEMA.md` — JSONL schema reference
+- `manuscript/propositions/EXTRACTION-PROMPT.md` — prop extraction discipline
+- `scripts/validate-propositions.py` — R1-R8 mechanical gate
+- `scripts/refresh-prop-locations.py` (#106) — one-shot location refresh
+- #107 — proofread workflow experiment (this rule's first concrete consumer beyond IDD)
diff --git a/plugins/math-tools/skills/manuscript-audit/SKILL.md b/plugins/math-tools/skills/manuscript-audit/SKILL.md
new file mode 100644
index 00000000..087ebe77
--- /dev/null
+++ b/plugins/math-tools/skills/manuscript-audit/SKILL.md
@@ -0,0 +1,159 @@
+---
+name: manuscript-audit
+description: |
+  Audit-time cross-doc drift detection for math manuscript. Runs R1 (working-file path leak in \texttt{}),
+  R2 (citation key drift / bib orphan), R3 (code symbol drift between analysis/ and manuscript/docs/),
+  R4 (proposition-jsonl iso-bijection check, optional when manuscript has propositions/main.jsonl).
+
+  Different from `propositions` skill (R1-R8 mechanical gate on JSONL alone) and `proofread` skill
+  (L4 semantic walk per-prop). This skill checks the **cross-artifact consistency** between
+  manuscript/main.tex + propositions/*.jsonl + analysis/*.py + references/*.tex + refs.bib.
+
+  Use when: 大改稿後 / 投稿前 / 新階段 (initial submission / major revision / camera-ready).
+  NOT for per-PR (use `code-and-manuscript-sync.md` rule + pre-commit hook).
+
+  v0.1.0 SCAFFOLDING — execution body TODO. Source scripts currently at
+  PsychQuantHsu/psychophysical_representations/scripts/audit-*.py + run-audit.sh.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Manuscript Audit — Cross-Doc Drift Detection
+
+## Status (v0.1.0)
+
+**Scaffolding only.** Source-of-truth orchestrator + scripts at:
+
+```
+PsychQuantHsu/psychophysical_representations/
+├── scripts/
+│   ├── run-audit.sh                  # Orchestrator (R1+R2+R3+R4 in order)
+│   ├── audit-symbols.py              # R1: working-file path leak in \texttt{}
+│   ├── audit-citations.py            # R2: cite-key drift, bib orphan
+│   ├── audit-code-manuscript.py      # R3: code <-> manuscript symbol drift
+│   └── validate-propositions.py      # R4: prop-subset-check + R1-R8 (re-used)
+└── .github/workflows/manuscript-audit.yml   # PR-side CI gate (#78)
+```
+
+3-layer enforcement (per `manuscript-consistency-audit.md` §8):
+
+| Layer | Enforcement | Failure mode |
+|-------|-------------|--------------|
+| `.githooks/pre-commit` (author-side) | Fast R1+R2+R4 on staged paths | Commit aborts (--no-verify bypass for emergency) |
+| `./scripts/run-audit.sh manuscript/` (manual) | Full R1+R2+R3+R4 | Author decides whether to fix |
+| `.github/workflows/manuscript-audit.yml` (PR-side CI) | Full audit on every PR + push to main | PR red light, blocks merge for R1/R2/R4; R3 informational |
+
+## R1-R4 Coverage (frozen contract)
+
+| Rule | Detects | Allowlist (auto) |
+|------|---------|------------------|
+| **R1** | `\texttt{path/to/working/file.ext}` working-file leak in main.tex | `\bibliography{refs.bib}` (whitelisted), commented `% ...` |
+| **R2** | `\cite{X}` where X not in refs.bib; cite-label leak (`\citet[Theorem~\texttt{main_thm_ess}]{Foo2020}` referring to source label not published thm number) | bib entries (`@article{X,...}` keys auto-scanned + `--latex-source-root` for sibling working notes) |
+| **R3** | Backtick code refs `` `foo_func` `` in `manuscript/docs/*.md` not found in `analysis/*.py` AST | LaTeX `\label{}` + `\cite{}` keys + `@article` BibTeX keys + sibling `references/**/*.tex` |
+| **R4** | Proposition-jsonl iso-bijection failure (PATTERN-A boundary-axiom contradiction) | Only when `manuscript/propositions/main.jsonl` exists; legacy `main.json` accepted as fallback |
+
+## Excluded Paths (frozen historical record)
+
+These are **frozen audit trail**, never modified retroactively:
+
+- `manuscript/docs/rounds/` — Review round audit log
+- `manuscript/docs/legacy/` — Retired drafts
+- `correspondence/` — Email archive
+- `references/*.tex` — Historical reference papers
+- `archive/` / `archived/` (archive-first plugin守護)
+
+## Execution Steps (v0.2.0 target — TODO)
+
+### Step 0: Bootstrap Stage Task List
+
+```
+TaskCreate parse_args / pre_flight_clean_check / pull_latest /
+            run_audit / parse_findings / classify (definite/likely/suspicious/FYI) /
+            decide_per_finding_action (file audit-finding issue / fix inline / mark intentional / suppress) /
+            generate_report_md
+```
+
+### Step 1: Pre-flight
+
+```bash
+git status --short          # MUST be empty (avoid concurrent-editing race)
+git pull --rebase
+cd manuscript && git pull --rebase && cd ..
+```
+
+### Step 2: Run orchestrator
+
+```bash
+./scripts/run-audit.sh manuscript/
+# Produces manuscript/docs/audit/audit-$(date +%F).md
+```
+
+Exit codes: `0` clean / `1` ≥1 finding / `2` tool error.
+
+### Step 3: Report format spec
+
+Frozen per `manuscript-consistency-audit.md` §7:
+
+```markdown
+# Manuscript Consistency Audit — YYYY-MM-DD
+
+**Manuscript snapshot**: <git rev-parse HEAD>
+**Audit tool versions**: ...
+
+## Summary
+- Definite: N
+- Likely: M
+- Suspicious: K
+- FYI: J
+
+## Findings
+### Definite
+#### F1: <one-line>
+- **Rule**: R1 / R2 / R3 / R4
+- **Location**: `file:line`
+- **Context**: ±2 lines
+- **Proposed fix**: <suggestion>
+- **Tracking issue**: #NNN (if filed)
+```
+
+### Step 4: Per-finding triage (AskUserQuestion when batch ≥ 10)
+
+| Severity | Auto-action |
+|----------|-------------|
+| Definite + Likely | File `audit-finding` issue with `scope:manuscript` label (per `issue-routing.md`) |
+| Suspicious | Audit report only, no issue |
+| FYI | Audit report only |
+
+**False-positive suppression** (per Pattern 7/8 in audit SOP):
+- LaTeX `\label{}` / `\cite{}` / bib keys → auto-allowlist (v0.2 calibration: definite drops 86→18 after fix)
+- Sibling `references/*.tex` → auto-discover
+- Use `--latex-source-root <path>` for additional dirs
+
+## Trigger Cadence
+
+Per `manuscript-consistency-audit.md` §5:
+
+| Stage | Trigger | Frequency |
+|-------|---------|-----------|
+| 大改稿後 | manual `./scripts/run-audit.sh manuscript/` | episode-based |
+| 投稿前 | manual | episode-based |
+| Per-PR (touches main.tex / analysis / refs.bib) | pre-commit hook | per-commit |
+| Per-PR (any change) | GitHub Actions CI | per-PR |
+
+## When NOT to Use
+
+- Per-line edit → hook + R1-R8 validator faster
+- Pure code-only PR (no manuscript change) → CI auto-skip via paths filter
+- Pre-extraction phase (no propositions/main.jsonl) → R4 inactive but R1/R2/R3 still useful
+
+## Cross-link
+
+- Source: PsychQuantHsu/psychophysical_representations #42 (audit SOP), #78 (CI gate)
+- Rule: [`../../rules/manuscript-consistency-audit.md`](../../rules/manuscript-consistency-audit.md) — full SOP
+- Sister skill: `/math-tools:propositions` for in-file JSONL validation
+- Sister skill: `/math-tools:proofread` for L4 semantic walk
diff --git a/plugins/math-tools/skills/proofread/SKILL.md b/plugins/math-tools/skills/proofread/SKILL.md
new file mode 100644
index 00000000..96a1f14e
--- /dev/null
+++ b/plugins/math-tools/skills/proofread/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: proofread
+description: |
+  JSONL-driven 6-layer proofread workflow for math manuscript. Each prop in main.jsonl becomes
+  a [ ] checklist item in manuscript/.proofread/<file>.md; walk through L1-L5 + location-drift
+  per prop; mark [x] (CLEAN) / [~] (finding) / [-] (out of scope).
+
+  L1 = text-claim match (asserts truly atomic + faithful paraphrase)
+  L2 = claim_type fit (axiom non-derivable / definition has equality / commentary not derived / etc.)
+  L3 = cite completeness (all external refs declared)
+  L4 = cite validity (each cited prop logically implies this prop's asserts)
+  L5 = evidence_class fit (derived needs cites / axiomatic truly axiom / etc.)
+  +location drift (claimed line range matches main.tex actual)
+
+  Use when: pre-submission final polish, post large rewrite, Hsu-approval-pending area,
+  validating prop-extraction quality. NOT for daily micro-edit (use sync rule + validator).
+
+  v0.1.0 SCAFFOLDING — execution body TODO. Methodology frozen in
+  PsychQuantHsu/psychophysical_representations/manuscript/.proofread/main_jsonl_l4_walk.md.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - AskUserQuestion
+---
+
+# Proofread — 6-Layer Walk
+
+## Status (v0.1.0)
+
+**Scaffolding only.** Methodology demonstrated + frozen at:
+
+- `PsychQuantHsu/psychophysical_representations/manuscript/.proofread/main_jsonl.md` (637-line checklist source)
+- `manuscript/.proofread/main_jsonl_l4_walk.md` (Pilot 3 full L4 walk ledger, 286-prop coverage)
+
+3 pilots completed (#107):
+
+| Pilot | Scope | Findings | Status |
+|-------|-------|----------|--------|
+| 1 | `_stage2/theorem1.jsonl` (23 props) | 13 location-drift | escalated → #106 closed |
+| 2 | `main.jsonl` thm:eta-s (46 props) | 2 L3 + 2 COMPRESS + 1 mild L3 | all fixed in commit 9e85198 |
+| 3 | Full `main.jsonl` (286 props, hybrid 115 deep + 20 sample + 151 heuristic) | 0 additional | ledger frozen |
+
+## The 6 Layers
+
+| Layer | Check | Detection difficulty |
+|-------|-------|----------------------|
+| L1 | prop.text真的 claim 出 asserts 列項? (atomic + faithful paraphrase) | Mostly mechanical via R1 substring match |
+| L2 | claim_type matches text semantic? (axiom non-derivable / definition has equality / commentary not derived / restatement truly re-states / case_split truly partitions) | Semi-mechanical — heuristic on bullet pattern |
+| L3 | All external refs in prop.text declared in cites field? | **LLM-required** — load-bearing reference detection is semantic |
+| L4 | Does each cited prop logically imply this prop's asserts? (mathematical correctness given cites) | **LLM-required** — derivation chain verification |
+| L5 | evidence_class consistent with claim_type? (derived needs cites; axiomatic truly axiom; verified has external proof) | Schema-aware heuristic + LLM judgment |
+| location | location.line range matches actual main.tex line range | Mechanical via `scripts/refresh-prop-locations.py` |
+
+## ROI Cliff (from Pilot 3 data)
+
+- Proof body / derivation chain: **~2.6% finding rate** (3/115 deep walk)
+- Theorems 2-4 + Synthesis: **0%** (0/20 sampled)
+- Commentary / Discussion: **0% mechanical anomalies** (0/151 heuristic)
+
+→ **Hybrid coverage strategy**: deep walk proof body + sample mid-density sections + heuristic scan commentary.
+
+## Execution Steps (v0.2.0 target — TODO)
+
+### Step 0: Bootstrap Stage Task List
+
+```
+TaskCreate generate_checklist_md / decide_coverage_strategy /
+            per_prop_walk (L1-L5+location) / classify_finding /
+            update_ledger / decide_escalation (audit-finding issue / inline note / camera-ready candidate) /
+            commit_with_jsonl_sync
+```
+
+### Step 1: Generate `.proofread/<file>.md` checklist from JSONL
+
+For each prop, emit:
+```markdown
+- [ ] **P{seq}** `{uuid_short}` [{claim_type}] @L{start}-L{end} — "{first 80 chars of text}..." (asserts: {N}, cites: {N})
+```
+
+Group by `containing_block` field. Add hyperlink to git blame for audit trail.
+
+### Step 2: Coverage decision (AskUserQuestion 4-option)
+
+| Strategy | Use case | Time |
+|----------|----------|------|
+| By section (e.g. Theorem 1 ~40 props) | Section-cohesive review | 20-30 min |
+| By claim_type | Foundational props first | variable |
+| By priority area (recent-change cluster) | Post-PR follow-up | 25-40 min |
+| Full manuscript (~2-3h) | Pre-submission gate | 2-3h |
+
+### Step 3: Per-prop L4 walk
+
+For each prop, present:
+- prop.text (raw)
+- prop.asserts (atomic list)
+- prop.cites (UUID list — resolve each via main.jsonl lookup)
+- prop.claim_type / evidence_class
+
+Ask coordinator to verify:
+- L1: do asserts faithfully decompose text?
+- L2: does claim_type fit?
+- L3: is anything cited in text but not in cites field?
+- L4: does each cited prop's asserts logically imply this prop's asserts?
+- L5: is evidence_class consistent?
+- location: spot-check main.tex line N — does prop.text start there?
+
+Mark `[x]` (CLEAN all 6), `[~]` (finding noted, detail in § Findings), `[-]` (out of scope).
+
+### Step 4: Findings ledger
+
+Hybrid mode: inline § Findings table in `.proofread/*.md` for severity < L3-blocking; escalate severity ≥ L3 cite-completeness OR ≥ 10 props affected to separate `audit-finding` GitHub issue (per `code-and-manuscript-sync.md` cluster discipline).
+
+### Step 5: Fix-shipping (if findings)
+
+Per `manuscript-jsonl-sync.md` scenario routing:
+- L1/L3 cite-completeness → scenario 6 (jsonl-only edit, add UUID)
+- L2 misclassification → fix prop.claim_type + re-validate R6
+- L4 COMPRESS (camera-ready candidate) → scenario 1 (wording expand in main.tex) + scenario 2 (prop.text sync)
+- L5 mismatch → fix evidence_class + verify schema
+
+Coordinator commits with cross-link to .proofread ledger entry.
+
+## When NOT to Use
+
+- Daily micro-edit → use R1-R8 validator + sync rule (cheaper)
+- Pre-extraction phase (jsonl doesn't exist yet) → run `propositions` skill first
+- Commentary-only sections → heuristic scan is enough; deep walk ROI low
+
+## Cross-link
+
+- Source dogfood: PsychQuantHsu/psychophysical_representations #107 (3 pilots done)
+- Rule: [`../../rules/manuscript-jsonl-sync.md`](../../rules/manuscript-jsonl-sync.md) — sync discipline after L3/L4 fix
+- Sister skill: `/math-tools:propositions` for mechanical R1-R8 gate
+- Sister skill: `/math-tools:manuscript-audit` for cross-doc R1-R4 drift
diff --git a/plugins/math-tools/skills/propositions/SKILL.md b/plugins/math-tools/skills/propositions/SKILL.md
new file mode 100644
index 00000000..d0a25880
--- /dev/null
+++ b/plugins/math-tools/skills/propositions/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: propositions
+description: |
+  Extract atomic propositions from a math manuscript .tex file into a JSONL structural representation,
+  then run R1-R8 mechanical validation. Each prop carries text (verbatim from .tex), location (line range),
+  cites (internal UUID dependency DAG), asserts (atomic claims), claim_type, and evidence_class.
+
+  Use when: starting propositions side-file for a new manuscript, re-extracting after large rewrite,
+  or running mechanical gate before audit. NOT for L4 semantic walk — that's the /proofread skill.
+
+  v0.1.0 SCAFFOLDING — execution body TODO. Source-of-truth scripts currently in
+  PsychQuantHsu/psychophysical_representations/scripts/validate-propositions.py.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - AskUserQuestion
+---
+
+# Propositions — Extract + Validate
+
+## Status (v0.1.0)
+
+**Scaffolding only.** Execution body deferred to v0.2.0+. Until then, run the source-of-truth scripts directly:
+
+```bash
+# Validate (R1-R8 mechanical gate)
+python3 scripts/validate-propositions.py \
+  --jsonl manuscript/propositions/main.jsonl \
+  --meta manuscript/propositions/_meta.json \
+  --tex manuscript/main.tex
+# Exit 0 = all pass; exit 1 = at least one rule fail
+
+# Refresh location field after main.tex line shift
+python3 scripts/refresh-prop-locations.py --jsonl manuscript/propositions/main.jsonl
+```
+
+Both scripts live at `PsychQuantHsu/psychophysical_representations/scripts/` (will be extracted to this plugin in v0.2.0).
+
+## R1-R8 Coverage (frozen contract)
+
+| Rule | What it checks | False-negative pitfall |
+|------|----------------|------------------------|
+| R1 | prop.text verbatim found in main.tex (via `normalize_for_match`) | substring containment is line-anchor-blind → location-drift silent (use R9-pending or refresh script) |
+| R1.5 | surjective coverage — every .tex paragraph covered by ≥1 prop | informational, not blocking; WARN-only |
+| R2 | every cite UUID resolves to an existing prop | catches typo / deletion gaps |
+| R3 | cite graph is a DAG (no cycles) | structural, not semantic — DAG ≠ logical implication (L4 walk needed) |
+| R4 | mechanical-contradiction PATTERN-A/B | catches boundary-axiom violations like #60 #68 |
+| R6 | sentence/clause-index v1.1 invariants hold | catches granularity drift |
+| R7 | every prop.id is canonical UUID v7 (RFC 9562 §5.7) | gates id-format compliance |
+| R8 | unique-ids within file | catches paste-clone errors |
+
+## Execution Steps (v0.2.0 target — TODO)
+
+### Step 0: Bootstrap Stage Task List
+
+```
+TaskCreate parse_args / detect_jsonl_path / run_validator / parse_exit_code /
+            classify_finding / decide_fix_path (refresh-locations / re-extract /
+            split-prop / escalate-issue) / write_audit_summary
+```
+
+### Step 1: Resolve manuscript root + JSONL paths
+
+Walk up from `cwd` to find `manuscript/propositions/main.jsonl` (canonical) + optional `_stage2/*.jsonl` (staging area like Theorem 1 in source repo).
+
+### Step 2: Run validator, parse output
+
+(TODO: structured-output mode for validate-propositions.py — feature request once script extracted)
+
+### Step 3: Triage findings → AskUserQuestion routing
+
+| Finding | Likely fix | Route |
+|---------|------------|-------|
+| R1 fail (text drift) | manuscript-jsonl-sync.md scenario 1 (wording) — update prop.text verbatim | inline edit |
+| R1 PASS but location stale | scenario 2 (line shift) — refresh-prop-locations.py | one-shot script |
+| R2 dangling | scenario 4 (delete) — strip cites referencing deleted UUIDs | inline edit |
+| R3 cycle | structural error — likely circular dependency in newly-added prop | escalate |
+| R4 PATTERN-A | boundary-axiom contradiction | escalate to audit-finding issue |
+| R6 / R7 / R8 | schema violation — re-run EXTRACTION-PROMPT.md against affected section | re-extract |
+
+## Cross-link
+
+- Source dogfood: PsychQuantHsu/psychophysical_representations #107 (proofread workflow experiment, 3 pilots)
+- Rule: [`../../rules/manuscript-jsonl-sync.md`](../../rules/manuscript-jsonl-sync.md) — prop-level sync HARD RULE
+- Sister skill: `/math-tools:proofread` for L4 alignment walk (semantic, not mechanical)
+- Sister skill: `/math-tools:manuscript-audit` for R1-R4 cross-doc drift detection
diff --git a/plugins/mcp-tools/.claude-plugin/plugin.json b/plugins/mcp-tools/.claude-plugin/plugin.json
index ed4f42e5..88eb3078 100644
--- a/plugins/mcp-tools/.claude-plugin/plugin.json
+++ b/plugins/mcp-tools/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "mcp-tools",
-  "version": "1.12.0",
-  "description": "MCP Server \u958b\u767c\u5de5\u5177\u96c6\uff1amcp-new-app\uff08\u5efa\u7acb\u5c08\u6848\uff09\u3001mcp-deploy\uff08\u90e8\u7f72\u767c\u5e03+Plugin\uff09\u3001mcp-install\uff08\u5f9e GitHub \u5b89\u88dd\uff09\u3001mcp-upgrade\uff08\u5347\u7d1a\u5efa\u8b70\uff09\u3001mcp-clone\uff08Clone \u53c3\u8003 repo + \u81ea\u52d5\u5206\u6790\uff09\u3001mcp-clone-references\uff08\u641c\u5c0b\u7af6\u54c1\u6279\u6b21 clone\uff09\u3001mcp-sync\uff08Binary \u540c\u6b65\uff09\u3001mcp-diagnose\uff08\u9023\u7dda\u8a3a\u65b7\uff09\u3001mcp-debug\uff08\u529f\u80fd\u9664\u932f\uff09\u3001mcp-test\uff08\u5b8c\u6574\u6e2c\u8a66\uff09\u3001mcp-publish\uff08Registry \u767c\u5e03\uff09\u3001mcp-to-plugin\uff08Skill: MCP\u2192Plugin \u8f49\u63db + Keychain \u5bc6\u9470\u7ba1\u7406\uff09",
+  "version": "1.16.0",
+  "description": "MCP Server 開發工具集：mcp-new-app（建立專案）、mcp-deploy（部署發布+Plugin）、mcp-install（從 GitHub 安裝）、mcp-upgrade（升級建議）、mcp-sign-pipeline（macOS 26 簽章+notarization pipeline）、mcp-clone（Clone 參考 repo + 自動分析）、mcp-clone-references（搜尋競品批次 clone）、mcp-sync（Binary 同步）、mcp-diagnose（連線診斷）、mcp-debug（功能除錯）、mcp-test（完整測試）、mcp-publish（Registry 發布）、mcp-to-plugin（Skill: MCP→Plugin 轉換 + Keychain 密鑰管理）",
   "author": {
     "name": "Che Cheng"
   },
diff --git a/plugins/mcp-tools/CHANGELOG.md b/plugins/mcp-tools/CHANGELOG.md
new file mode 100644
index 00000000..5e198f9d
--- /dev/null
+++ b/plugins/mcp-tools/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.15.1] - (date unknown — please fill in)
+
+### Added
+- MCP Server 開發工具集：mcp-new-app（建立專案）、mcp-deploy（部署發布+Plugin）、mcp-install（從 GitHub 安裝）、mcp-upgrade（升級建議）、mcp-clone（Clone 參考 repo + 自動分析）、mcp-clone-references（搜尋競品批次 clone）、mcp-sync（Binary 同步）、mcp-diagnose（連線診斷）、mcp-debug（功能除錯）、mcp-test（完整測試）、mcp-publish（Registry 發布）、mcp-to-plugin（Skill: MCP→Plugin 轉換 + Keychain 密鑰管理）
diff --git a/plugins/mcp-tools/README.md b/plugins/mcp-tools/README.md
index 01990c74..e14b75d3 100644
--- a/plugins/mcp-tools/README.md
+++ b/plugins/mcp-tools/README.md
@@ -319,6 +319,15 @@ open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
 
 | Version | Date | Changes |
 |---------|------|---------|
+| v1.15.1 | 2026-04-22 | tool-readme-sync rule 擴充到 GitHub repo About metadata（跨 mcp-tools / cli-tools / plugin-tools 共用規則）|
+| v1.15.0 | 2026-04-22 | tool-readme-sync rule（codify tool list ↔ README sync 規則）|
+| v1.14.0 | 2026-04-17 | Step 0 TaskCreate bootstrap across all 13 skills（每個 skill 強制建 stage-level todo list）|
+| v1.13.1 | 2026-04-14 | hooks.json 改用 record 格式（從 array 遷移）|
+| v1.13.0 | 2026-03-29 | PostToolUse hook 提醒 git push 後跑 mcp-deploy |
+| v1.12.0 | 2026-03-19 | 新增 mcp-issue skill（在 MCP repo 快速開 GitHub issue）|
+| v1.11.0 | 2026-03-14 | mcp-to-plugin 改 reference plugin-tools 做 marketplace deploy |
+| v1.10.0 | 2026-03-14 | 重構：plugin-update 抽出獨立 plugin-tools plugin（解耦 MCP-only vs plugin-lifecycle）|
+| v1.9.0 | 2026-03-07 | mcp-publish 加入版本更新流程 + Glama / 第三方平台支援；指令前綴統一改成 `mcp-` |
 | v1.8.0 | 2026-02-20 | 新增 clone 命令（給 URL 直接 clone + 自動分析可升級功能）；新增 mcp-clone-references 命令（搜尋競品批次 clone）|
 | v1.7.0 | 2026-02-01 | 新增 mcpb-sync 命令；mcp-deploy 加入 Phase 3.5 Binary 一致性驗證；mcp-upgrade 加入 Binary 檢查；debug 重建後自動同步 |
 | v1.6.0 | 2026-01-27 | mcp-deploy 新增 Plugin 發布；mcp-upgrade 可串接 deploy |
diff --git a/plugins/mcp-tools/hooks/hooks.json b/plugins/mcp-tools/hooks/hooks.json
new file mode 100644
index 00000000..5b0d760a
--- /dev/null
+++ b/plugins/mcp-tools/hooks/hooks.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/post-push-deploy-reminder.sh\" \"$TOOL_INPUT\""
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/mcp-tools/hooks/post-push-deploy-reminder.sh b/plugins/mcp-tools/hooks/post-push-deploy-reminder.sh
new file mode 100755
index 00000000..ad3be602
--- /dev/null
+++ b/plugins/mcp-tools/hooks/post-push-deploy-reminder.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+# PostToolUse hook: remind to deploy after pushing MCP project changes
+# Triggers on: Bash commands containing "git push"
+# Condition: cwd has both Package.swift (or pyproject.toml/package.json) AND mcpb/ directory
+
+TOOL_INPUT="$1"
+
+# Only trigger on git push commands
+if ! echo "$TOOL_INPUT" | grep -q "git push"; then
+  exit 0
+fi
+
+# Check if we're in an MCP project (has mcpb/ directory)
+if [ ! -d "mcpb" ]; then
+  exit 0
+fi
+
+# Check if it's a code project (not just docs)
+if [ ! -f "Package.swift" ] && [ ! -f "pyproject.toml" ] && [ ! -f "package.json" ]; then
+  exit 0
+fi
+
+# Get project name
+PROJECT_NAME=$(basename "$(pwd)")
+
+cat <<EOF
+[mcp-tools] Detected git push in MCP project: $PROJECT_NAME
+
+If you changed server functionality, consider running:
+  /mcp-tools:mcp-deploy — build, package mcpb, create GitHub Release, update Plugin
+  /mcp-tools:mcp-publish — publish to MCP Registry + Glama
+EOF
diff --git a/plugins/mcp-tools/rules/tool-readme-sync.md b/plugins/mcp-tools/rules/tool-readme-sync.md
new file mode 100644
index 00000000..96a4a250
--- /dev/null
+++ b/plugins/mcp-tools/rules/tool-readme-sync.md
@@ -0,0 +1,156 @@
+# MCP Tool List ↔ README 同步紀律
+
+當 MCP Server 的 tool 集合（`tools/list` 所回傳的項目）變動時，**必須**在同一個 commit（或同一個 release 週期內）更新 README。
+
+## 為什麼
+
+MCP server 的 README 是 **使用者契約**。它同時被三種讀者消費：
+
+| 讀者 | 讀 README 的目的 |
+|------|----------------|
+| 人類開發者 | 決定要不要裝、裝完知道能做什麼 |
+| AI agent / LLM | 計劃任務時判斷此 MCP 有沒有提供它需要的 tool |
+| Plugin / marketplace index | 自動生成 tool 列表、keywords、description |
+
+README 和實際 `tools/list` 脫鉤造成的後果：
+
+- 使用者在 README 找得到的 tool 實際不存在 → bug report 湧入
+- 實際存在的 tool 沒列在 README → LLM agent 永遠不會嘗試呼叫它（資源浪費）
+- Tool 數量過時（「146 tools」寫到半年後才改成 165）→ 在比較表上給競品空間
+
+## 觸發條件（必須同步 README）
+
+滿足任一條件即啟動：
+
+1. **新增 tool** — `tools/list` 多出一個 name
+2. **移除 tool** — name 消失（BREAKING，CHANGELOG 也要寫）
+3. **重命名 tool** — name 改變
+4. **Schema 實質改變** — 必填欄位增減、behavior 反轉（如 track_changes 預設值翻轉）
+5. **tool 總數改變** — README 開頭或 comparison table 的數字要跟著動
+
+僅內部重構（private helper 改名、implementation 重寫但對外介面不變）→ 不需要 README。
+
+## 必要的 README 改動範圍
+
+| 改動 | README 連動 |
+|------|------------|
+| 加/減/改 tool | 對應的工具表格那一列 |
+| tool 總數變 | Features 列表、Comparison table、Available Tools heading |
+| 新增工具分類（如加了 Session State API 這一整類） | 新增一個獨立 section + 更新目錄 |
+| 重大版本（v2.0.0 / v3.0.0） | Version History 表新增一列，註明 BREAKING |
+| Dependencies 改了 | Technical Details → Dependencies 區塊 |
+
+## Deploy 前的自我檢查
+
+`mcp-deploy` skill 跑完**前**做這個檢查：
+
+```bash
+# 跑起來後用 JSON-RPC 抓實際 tool count
+TOOL_COUNT=$(echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+  ./CheXxxMCP | python3 -c "import sys,json; print(len(json.load(sys.stdin)['result']['tools']))")
+
+# 抓 README 宣稱的 tool count
+README_COUNT=$(grep -oE '[0-9]+ MCP Tools' README.md | head -1 | grep -oE '[0-9]+')
+
+# 不一致就警告
+[ "$TOOL_COUNT" = "$README_COUNT" ] || echo "⚠️ README 宣稱 $README_COUNT, 實際 $TOOL_COUNT"
+```
+
+## 當多個版本累積才發現 README 落後時
+
+像 che-word-mcp v2.0.0 → v3.1.0 累積 8 個版本都沒更新 README 的情況，補救方式：
+
+1. **批量更新 Version History 表** — 不要只補最新一版，把中間被漏掉的全部補回（讓歷史可追溯）
+2. **工具表按 category 重新掃一次** — 不要只加新 tool，檢查舊 tool 的描述是否還正確（可能有 BREAKING 沒記）
+3. **Comparison table / feature bullets 全面重掃** — 這些是最容易過時的位置
+4. **雙語版同步** — 如果有 README_zh-TW.md 或其他語言，一次全改
+
+## GitHub Repo About Metadata（和 README 同等級的使用者第一印象）
+
+README 是 repo 內部文件；**GitHub repo 首頁右側的 About 面板** 是外部的「名片」。Search engine、Topics 瀏覽頁、marketplace 聚合器都讀這塊，不讀 README。
+
+Tool 集合變動時，**這三項也要檢查**：
+
+| 欄位 | 位置 | 應該同步的時機 |
+|------|------|-------------|
+| **Description**（~350 字短介紹）| `gh repo view --json description` | Tool 總數改變、加了新 category（如 session state、readback）、或 BREAKING 變更 |
+| **Topics**（最多 20 個標籤）| `gh repo view --json repositoryTopics` | 加了新功能領域（例如原本純 MCP → 加了 manuscript-review 類 tool）|
+| **Homepage URL** | `gh repo view --json homepageUrl` | 通常指 `releases` 頁；改過 binary 發布位置時才動 |
+
+### Description 的三層結構模板
+
+```
+[What] {Swift-native MCP server for X with N tools} —
+[Differentiator] {first direct OOXML library / native EventKit / no X process required} —
+[Features] {Feature A, Feature B, Feature C, Feature D} —
+[Use case] {Optimized for Y workflow}
+```
+
+範例（che-word-mcp v3.1.0）：
+
+> Swift-native MCP server for Microsoft Word (.docx) with 165 tools — first direct OOXML library (no Microsoft Word process required). Text-anchor insert, batch replace/search, session state with SHA256 drift detection, F9-equivalent field recount, OMML math AST, Caption/Equation CRUD. Optimized for thesis and manuscript review workflows.
+
+### 建議 Topics 數量
+
+- **目標：15-20 個**（GitHub 上限 20）
+- 少於 5 個 = search visibility 等於零
+- `null` / 空陣列 = 完全沒出現在 `topic:xxx` 搜尋頁
+
+### 必備 Topic 類別
+
+| 類別 | Topic 範例 |
+|------|----------|
+| 語言 | `swift`, `rust`, `typescript`, `python` |
+| 協議 | `mcp`, `mcp-server`, `model-context-protocol` |
+| 客戶端 | `claude`, `claude-ai`, `claude-code`, `claude-desktop` |
+| 平台 | `macos`, `linux`, `native`, `cross-platform` |
+| 功能域 | 依 MCP 主要操作對象命名（`docx`, `calendar`, `pdf`, `markdown`…）|
+| 用途 | `ai-tools`, `automation`, `productivity`, `developer-tools` |
+| 競品/生態 | `microsoft-word`, `office`, `apple-notes` 等（方便比較搜尋）|
+
+### `gh repo edit` 參考指令
+
+```bash
+# 一次更新 description + homepage
+gh repo edit {OWNER}/{REPO} \
+  --description "..." \
+  --homepage "https://github.com/{OWNER}/{REPO}/releases"
+
+# 加 topics（可累積多次呼叫）
+gh repo edit {OWNER}/{REPO} \
+  --add-topic swift \
+  --add-topic mcp \
+  --add-topic mcp-server \
+  --add-topic claude-code
+
+# 查核目前狀態
+gh repo view {OWNER}/{REPO} --json description,homepageUrl,repositoryTopics
+```
+
+### Deploy 前的審計
+
+```bash
+# description 長度 + 是否包含最新 tool 總數
+CURRENT_DESC=$(gh repo view --json description -q .description)
+TOOL_COUNT=$(...從 source 或 tools/list 抓)
+echo "$CURRENT_DESC" | grep -q "$TOOL_COUNT tools" || echo "⚠️ Description 未反映 $TOOL_COUNT tools"
+
+# topics 數量
+TOPIC_COUNT=$(gh repo view --json repositoryTopics -q '.repositoryTopics | length')
+[ "$TOPIC_COUNT" -ge 5 ] || echo "⚠️ Topics 只有 $TOPIC_COUNT 個（建議 15-20）"
+```
+
+## 例外
+
+- 純 bug fix（patch release，tool 集合完全沒動）→ 只需 CHANGELOG，README / Description / Topics 皆不用
+- 私有測試版本（未上架 release）→ 都可以延後，但 release 前必須補
+
+## 和其他 skill 的關係
+
+- `mcp-deploy` Step 2.6 會檢查 README/tool-count 一致性，不一致時 **BLOCK** 發布
+- `mcp-upgrade` 若建議加新 tool，也會在建議清單末尾提醒「README 要補第 X 段」
+- `mcp-new-app` 的 scaffold 會直接生成含正確 tool count placeholder 的 README 骨架
+
+## TL;DR
+
+**動了 `tools/list`，就動 README；沒動 README 就不要發 release。**
diff --git a/plugins/mcp-tools/skills/mcp-clone-references/SKILL.md b/plugins/mcp-tools/skills/mcp-clone-references/SKILL.md
index d4a6f353..4eda0b3e 100644
--- a/plugins/mcp-tools/skills/mcp-clone-references/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-clone-references/SKILL.md
@@ -19,6 +19,23 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="detect_project", description="Phase 0: 確認 MCP 專案 + 推斷搜尋關鍵字")
+TaskCreate(name="search_competitors", description="Phase 1: GitHub 搜尋 + 補充搜尋 + 讓使用者選")
+TaskCreate(name="setup_references_folder", description="Phase 2: 建 references/ + .gitignore")
+TaskCreate(name="clone_selected_repos", description="Phase 3: 逐一 clone + 驗證")
+TaskCreate(name="competitor_analysis", description="Phase 4 (可選): 分析競品")
+TaskCreate(name="report", description="Phase 5: 完成報告")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 檢測專案
 
 ### Step 1: 確認目前在 MCP 專案目錄
diff --git a/plugins/mcp-tools/skills/mcp-clone/SKILL.md b/plugins/mcp-tools/skills/mcp-clone/SKILL.md
index c261df86..375e9c5f 100644
--- a/plugins/mcp-tools/skills/mcp-clone/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-clone/SKILL.md
@@ -22,6 +22,21 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="locate_target", description="Phase 0: 解析 GitHub URL + 確認目標 + 驗證存在")
+TaskCreate(name="clone_to_references", description="Phase 1: 建 references/ + .gitignore + clone + 驗證")
+TaskCreate(name="create_readme", description="Phase 2: 寫 references/README.md 記錄 ref repo 資訊")
+TaskCreate(name="auto_analyze", description="Phase 3: 快速掃描 ref + 比對自己的 MCP 專案")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 定位目標 MCP 專案
 
 ### Step 1: 解析 GitHub URL
diff --git a/plugins/mcp-tools/skills/mcp-debug/SKILL.md b/plugins/mcp-tools/skills/mcp-debug/SKILL.md
index 44c66b54..ba0a9398 100644
--- a/plugins/mcp-tools/skills/mcp-debug/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-debug/SKILL.md
@@ -19,6 +19,21 @@ allowed-tools: Bash(sdef:*), Bash(osascript:*), Bash(claude mcp:*), Bash(pkill:*
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="quick_diagnose", description="Phase 0: 建除錯日誌目錄 + 檢查連線 + 快速測試 + 錯誤分析")
+TaskCreate(name="identify_framework", description="Phase 1: 找原始碼 + 判斷框架（Swift/Python/TS）")
+TaskCreate(name="diagnosis_report", description="Phase 2: 產生報告 + 儲存")
+TaskCreate(name="post_fix_verify", description="Phase 3: 若修復了，重新 build + sync binary 驗證")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 快速診斷
 
 ### Step 0: 建立除錯日誌目錄
diff --git a/plugins/mcp-tools/skills/mcp-deploy/SKILL.md b/plugins/mcp-tools/skills/mcp-deploy/SKILL.md
index 764bb921..18396fb7 100644
--- a/plugins/mcp-tools/skills/mcp-deploy/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-deploy/SKILL.md
@@ -18,6 +18,26 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 stage-level todo list：
+
+```
+TaskCreate(name="detect_project", description="Phase 0: 確認 MCP 專案目錄 + 識別語言 + 讀當前版本 + 確認新版本號")
+TaskCreate(name="compile_binary", description="Phase 1: 編譯（Swift/Python/TS），Swift 要做 universal binary + codesign")
+TaskCreate(name="update_version_and_package", description="Phase 2: manifest.json + CHANGELOG + README + 打包 .mcpb + 驗證格式")
+TaskCreate(name="publish_to_github", description="Phase 3: git commit/push + gh release create + curl upload assets（大 binary 必須 curl）")
+TaskCreate(name="verify_binary_consistency", description="Phase 3.5 (Swift only)：hash 比對 + 架構確認")
+TaskCreate(name="publish_plugin", description="Phase 4 (可選)：發布為 Claude Code Plugin，更新 marketplace.json + cache 同步")
+TaskCreate(name="report_completion", description="Phase 5: 輸出版本資訊、Release URL、下一步提示")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：mcp-deploy 有 5+ phases、每個 phase 有多個 step（總共 ~30 sub-steps），沒 task list 很容易漏步——特別是 Phase 3.5 binary consistency check 和 Phase 4 Phase 4 的 plugin sync（兩者都是 silent failure 的常見點）。
+
+---
+
 ## Phase 0: 檢測專案
 
 ### Step 1: 確認目前在 MCP 專案目錄
@@ -95,6 +115,25 @@ lipo -create \
 xattr -cr mcpb/server/$BINARY_NAME
 
 # 重新簽名（lipo 會破壞原始 code signature，未簽名會被 macOS SIGKILL）
+#
+# 注意：這裡是 ad-hoc 簽名（`-` 表示無 identity），**僅適用 macOS ≤ 25 dev/test**。
+# macOS 26 上 ad-hoc binary 無法觸發 Calendar / Reminders / AppleEvents 等 TCC dialog；
+# 若 MCP 會打到隱私 API，必須走 Developer ID 簽章 + notarization。
+#
+# **若你的 MCP 走 macOS 26 production path**：
+#   1. 確認專案已裝簽章 pipeline（`scripts/sign-and-notarize.sh` 存在?）
+#   2. 沒裝 → 提示使用者跑 `/mcp-tools:mcp-sign-pipeline` 補裝（一次性 setup）
+#   3. 已裝 → 改成呼叫 `./scripts/sign-and-notarize.sh mcpb/server/$BINARY_NAME`
+#      (要求 `DEVELOPER_ID` + `NOTARY_PROFILE` env vars 已設)
+#
+# 偵測邏輯建議：
+#   if [ -f "scripts/sign-and-notarize.sh" ] && [ -n "$DEVELOPER_ID" ]; then
+#       ./scripts/sign-and-notarize.sh mcpb/server/$BINARY_NAME
+#   else
+#       codesign --force --sign - mcpb/server/$BINARY_NAME  # ad-hoc fallback
+#       echo "⚠ ad-hoc signed; macOS 26 users will hit TCC blockage"
+#       echo "  Install signing pipeline: /mcp-tools:mcp-sign-pipeline"
+#   fi
 codesign --force --sign - mcpb/server/$BINARY_NAME
 ```
 
@@ -256,6 +295,81 @@ chmod +x mcpb/server/run.sh
 
 **提醒**：所有語言版本的 README 都要同步更新。
 
+### Step 4.6: Tool-list ↔ README 一致性檢查（🔴 BLOCKING）
+
+規則見 `rules/tool-readme-sync.md`。這步是上兩步 README 更新的**驗證**，不是重複。
+
+```bash
+# 1. 實際 tool count（從 Server source 數，或啟動後打 tools/list）
+ACTUAL_COUNT=$(grep -oE 'name:\s*"[a-z_]+"' Sources/*/Server.swift 2>/dev/null | sort -u | wc -l | tr -d ' ')
+# 若 Python / TS project，改用對應抓法
+
+# 2. README 宣稱的 count
+README_COUNT_EN=$(grep -oE '[0-9]+ (MCP )?[Tt]ools' README.md | head -1 | grep -oE '[0-9]+')
+README_COUNT_ZH=$(grep -oE '[0-9]+ 個 MCP 工具' README_zh-TW.md 2>/dev/null | head -1 | grep -oE '[0-9]+')
+
+echo "Actual: $ACTUAL_COUNT / README EN: $README_COUNT_EN / README zh-TW: $README_COUNT_ZH"
+
+# 3. Comparison table 的數字
+grep -E 'Tools Count|工具數量' README*.md
+```
+
+**BLOCKING**：如果 actual ≠ README（任何一種語言），**停止 deploy**，要求先更新 README。
+使用者可明確覆蓋（「我知道這次 tool count 沒變」）才繼續。
+
+補救清單（出現不一致時）：
+- [ ] Features 列表的 "X MCP Tools"
+- [ ] Available Tools (X Total) heading
+- [ ] 分類工具表格每一列（新增的 tool）
+- [ ] Comparison table 的 Tools Count 行
+- [ ] 雙語 README 同步
+
+### Step 4.7: GitHub repo About metadata audit（WARN，不 BLOCK）
+
+規則見 `rules/tool-readme-sync.md` 的 GitHub Repo About Metadata 章節。
+非 BLOCKING，但 minor / major bump 時強烈建議同步；patch 一般可略。
+
+```bash
+# 先確認 gh 已登入，且這個 repo 在 GitHub 上
+gh auth status >/dev/null 2>&1 || { echo "⚠️ gh 未登入，跳過 metadata audit"; exit 0; }
+
+REPO_SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)
+[ -z "$REPO_SLUG" ] && { echo "⚠️ 非 GitHub repo 或無權限"; exit 0; }
+
+# 1. Description 長度與時效
+DESC=$(gh repo view --json description -q .description)
+DESC_LEN=${#DESC}
+echo "Description ($DESC_LEN chars): $DESC"
+[ "$DESC_LEN" -lt 50 ] && echo "⚠️ Description 太短（<50 chars），建議補到 200-350 chars"
+
+# 2. Description 是否反映目前 tool count
+TOOL_COUNT=$(grep -oE 'name:\s*"[a-z_]+"' Sources/*/Server.swift 2>/dev/null | sort -u | wc -l | tr -d ' ')
+if [ "$TOOL_COUNT" -gt 0 ]; then
+    echo "$DESC" | grep -qE "$TOOL_COUNT (MCP |tools|tool)" || echo "⚠️ Description 未反映 $TOOL_COUNT tools"
+fi
+
+# 3. Topics
+TOPIC_COUNT=$(gh repo view --json repositoryTopics -q '.repositoryTopics | length')
+echo "Topics: $TOPIC_COUNT 個"
+[ "$TOPIC_COUNT" -lt 5 ] && echo "⚠️ Topics 太少（$TOPIC_COUNT < 5），search visibility 幾乎是零"
+[ "$TOPIC_COUNT" -lt 15 ] && echo "💡 建議補到 15-20 個 topics"
+
+# 4. Homepage URL
+HOMEPAGE=$(gh repo view --json homepageUrl -q .homepageUrl)
+[ -z "$HOMEPAGE" ] && echo "💡 建議設 Homepage = https://github.com/$REPO_SLUG/releases"
+```
+
+發現問題時，詢問使用者要不要順手 `gh repo edit` 更新：
+
+```bash
+AskUserQuestion "Repo metadata 和 README 不一致，要順便更新嗎？"
+  - 是，現在更新（我提供新 description + topics 草案）
+  - 否，deploy 後手動處理
+  - Dry run 看草案再決定
+```
+
+AI 草擬 description + topics 時的模板見 `rules/tool-readme-sync.md`。
+
 ### Step 5: 清理舊的 mcpb 檔案
 
 ```bash
diff --git a/plugins/mcp-tools/skills/mcp-diagnose/SKILL.md b/plugins/mcp-tools/skills/mcp-diagnose/SKILL.md
index 75434733..fa642658 100644
--- a/plugins/mcp-tools/skills/mcp-diagnose/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-diagnose/SKILL.md
@@ -15,9 +15,23 @@ allowed-tools: Bash(ls:*, file:*, claude:mcp*), Read, Grep, mcp__*
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="setup_log_dir", description="建立 logs/mcptools/debug/ 目錄")
+TaskCreate(name="check_connection", description="Step 1: 檢查 MCP Server 連線狀態")
+TaskCreate(name="basic_functional_test", description="Step 2: 跑 3 個讀取類 tool 快速測試")
+TaskCreate(name="analyze_errors", description="Step 3: 錯誤訊息分析（若有）")
+TaskCreate(name="output_report", description="Step 4: 輸出診斷報告到 logs")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
 ## 診斷流程
 
-### Step 0: 建立診斷日誌目錄
+### Step 0.5: 建立診斷日誌目錄
 
 在專案根目錄建立 `logs/mcptools/debug/` 結構（diagnose 報告也存在 debug 目錄）：
 
diff --git a/plugins/mcp-tools/skills/mcp-install/SKILL.md b/plugins/mcp-tools/skills/mcp-install/SKILL.md
index 0d76d99a..8de50af1 100644
--- a/plugins/mcp-tools/skills/mcp-install/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-install/SKILL.md
@@ -21,6 +21,21 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="detect_project", description="Phase 0: 確認 MCP 專案目錄 + 讀專案資訊 + 確認 GitHub repo")
+TaskCreate(name="version_selection", description="Phase 1: 選版本（latest / 指定 / list）")
+TaskCreate(name="download_and_install", description="Phase 2: 確認 ~/bin + 取 binary 名 + 下載 + 設權限 + 驗證")
+TaskCreate(name="report", description="Phase 3: 輸出完成報告")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 檢測專案
 
 ### Step 1: 確認目前在 MCP 專案目錄
diff --git a/plugins/mcp-tools/skills/mcp-issue/SKILL.md b/plugins/mcp-tools/skills/mcp-issue/SKILL.md
index f577effa..5dc3bd45 100644
--- a/plugins/mcp-tools/skills/mcp-issue/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-issue/SKILL.md
@@ -16,6 +16,19 @@ allowed-tools: Bash(gh:*, ls:*, cat:*), Read, Grep, Glob
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="locate_repo", description="Step 1: 從 MCP Server 名稱推斷 GitHub repo")
+TaskCreate(name="categorize_issue", description="Step 2: 分類 issue type（bug/feature/improvement）+ 決定 label")
+TaskCreate(name="create_issue", description="Step 3: gh issue create 含標題、body、label")
+TaskCreate(name="report_result", description="Step 4: 回報 issue number + URL")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
 ## 流程
 
 ### Step 1: 找到 MCP Server 的 GitHub repo
diff --git a/plugins/mcp-tools/skills/mcp-new-app/SKILL.md b/plugins/mcp-tools/skills/mcp-new-app/SKILL.md
index ac48372c..c69b2960 100644
--- a/plugins/mcp-tools/skills/mcp-new-app/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-new-app/SKILL.md
@@ -18,6 +18,21 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="collect_info", description="Phase 0: 確認專案名稱 + 收集資訊 + 確認位置")
+TaskCreate(name="create_structure", description="Phase 1: 建立專案結構（Package.swift + Sources + Tests + mcpb）")
+TaskCreate(name="setup_git_and_mcpb", description="Phase 2: Git init + .gitignore + .gitattributes + mcpb/manifest + PRIVACY + README + CHANGELOG + LICENSE")
+TaskCreate(name="report", description="Phase 3: 完成報告")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 收集專案資訊
 
 ### Step 1: 確認專案名稱
@@ -625,8 +640,13 @@ SOFTWARE.
    - Swift: `swift build`
    - Python: `pip install -e .`
    - TypeScript: `npm install && npm run build`
-3. **部署**：使用 `/mcp-tools:mcp-deploy`
+3. **若 MCP 會用到 macOS 隱私 API**（EventKit / AppleEvents / Photos / Mic / Camera / Full Disk Access）→ **裝簽章 pipeline**：使用 `/mcp-tools:mcp-sign-pipeline`
+   - macOS 26 的 TCC 不再對 ad-hoc 簽章的 binary 開放 permission dialog；若要 outside-MAS distribution 必須走 Developer ID + hardened runtime + notarization
+   - 此 skill 會自動把 `scripts/sign-and-notarize.sh` + `Makefile release-signed` + `Sources/<Target>/Entitlements.plist` + README + CHANGELOG 補進你新建的 MCP
+   - 純檔案 I/O / HTTP / 字串處理 MCP 不需要（簽章只影響 Gatekeeper warning，不影響功能）
+4. **部署**：使用 `/mcp-tools:mcp-deploy`
    - 會自動編譯、打包 .mcpb、發布到 GitHub Release
+   - 若已裝 sign-pipeline，可用 `make release-signed` 跑 signed release（macOS 26 必要）
 ```
 
 ---
diff --git a/plugins/mcp-tools/skills/mcp-publish/SKILL.md b/plugins/mcp-tools/skills/mcp-publish/SKILL.md
index 2fec86cc..33be1ef8 100644
--- a/plugins/mcp-tools/skills/mcp-publish/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-publish/SKILL.md
@@ -18,6 +18,22 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="env_check", description="Phase 0: 確認專案 + 檢查 GitHub Release + 安裝 mcp-publisher + Registry 狀態")
+TaskCreate(name="create_server_json", description="Phase 1 (首次): 收集資訊 + 算 SHA-256 + 寫 server.json + Registry API 驗證")
+TaskCreate(name="update_server_json", description="Phase 1-U (更新): 讀現有 server.json + 取新版本 binary 資訊")
+TaskCreate(name="publish_to_registry", description="Phase 2: 實際 publish 到 MCP Registry")
+TaskCreate(name="verify_publication", description="Phase 3: 驗證已上架 + 測試安裝")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 環境檢查
 
 ### Step 1: 確認專案目錄
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/SKILL.md b/plugins/mcp-tools/skills/mcp-sign-pipeline/SKILL.md
new file mode 100644
index 00000000..1b2d0723
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/SKILL.md
@@ -0,0 +1,268 @@
+---
+name: mcp-sign-pipeline
+description: Apply Developer ID signing + notarization pipeline to a Swift MCP / CLI project. Required for macOS 26 — ad-hoc signed binaries can no longer trigger TCC permission dialogs. Use when creating new MCP/CLI (mcp-new-app / cli-new-app integration) OR upgrading an existing project that needs to ship signed releases. Templates are extracted from che-ical-mcp PR #44 (production-verified on macOS 26.4.1) and parameterized for any Swift binary project.
+---
+
+# mcp-sign-pipeline — Apply signing + notarization pipeline
+
+## When this skill triggers
+
+User says any of:
+- "簽章 / sign / notarize / Developer ID / macOS 26 TCC"
+- "我的 MCP/CLI 在 macOS 26 上不工作了"
+- "TCC dialog 不出現"
+- "Gatekeeper 拒絕我的 binary"
+- Building a new Swift MCP/CLI that touches TCC-protected APIs (EventKit, AppleEvents, Photos, Mic, Camera, Full Disk Access)
+
+This skill installs the full signing + notarization pipeline into the target project. It's the productionized version of `che-ical-mcp` PR #44.
+
+## Scope
+
+**Installs**:
+- `Sources/<TargetName>/Entitlements.plist` (empty `<dict/>` — minimal entitlements)
+- `scripts/sign-and-notarize.sh` (with pre-flight cert + notarytool checks, mktemp + trap, fail-soft submission ID extraction)
+- Modifies `scripts/build-mcpb.sh` (or equivalent build script) — adds `[3.5/N]` sign step gated by `SKIP_CODESIGN` / `REQUIRE_CODESIGN`
+- Modifies `Makefile` — new `release-signed` target with fail-fast on missing env vars; `install:` target gets `rm -f` prefix (#62 inode-cache trap fix)
+- Updates `README.md` — adds "Signing & Notarization" subsection under "Release Process"
+- Updates `CHANGELOG.md` — adds "Distribution" entry under current version
+
+**Does NOT do**:
+- Apply for Developer ID Application cert (manual, via developer.apple.com)
+- Set up notarytool keychain profile (manual, requires app-specific password)
+- Verify on macOS 26 hardware (manual end-to-end test)
+- GitHub Actions CI integration (out of MVP scope; defer to follow-up issue)
+
+## Prerequisites (the user must have these — skill does not create them)
+
+1. **Apple Developer Program enrollment** ($99/yr)
+2. **Developer ID Application certificate** in login keychain
+   - Verify: `security find-identity -p codesigning -v` shows `Developer ID Application: ...`
+3. **`notarytool` keychain profile** (any name; this skill uses `$NOTARY_PROFILE` env var)
+   - Create with: `xcrun notarytool store-credentials <profile-name> --apple-id <id> --team-id <team-id>` (interactive — NOT `--password`)
+4. **App-specific password** generated at <https://account.apple.com> → Sign-In and Security → App-Specific Passwords
+
+The skill emits friendly error messages from the install scripts pointing users to these prereqs if any are missing.
+
+## Execution
+
+### Step 0: Bootstrap Stage Task List (mandatory)
+
+```
+TaskCreate(name="resolve_target_project", description="Determine target project: --target flag OR current dir's Package.swift OR ask")
+TaskCreate(name="probe_project_shape", description="Detect: Swift Package? Target name? Existing scripts/? Existing Makefile? README format? CHANGELOG format?")
+TaskCreate(name="check_prereqs_env", description="Optional: probe DEVELOPER_ID + cert + notarytool profile and warn early if missing")
+TaskCreate(name="apply_entitlements_plist", description="Write Sources/<Target>/Entitlements.plist (empty <dict/>)")
+TaskCreate(name="apply_sign_script", description="Write scripts/sign-and-notarize.sh (chmod +x)")
+TaskCreate(name="apply_build_script_changes", description="Modify scripts/build-mcpb.sh (or build-cli.sh) — add [3.5/N] step, REQUIRE_CODESIGN gating")
+TaskCreate(name="apply_makefile_changes", description="Modify Makefile — add release-signed target with fail-fast; rm -f in install: target")
+TaskCreate(name="apply_readme_section", description="Inject Signing & Notarization subsection into README.md Release Process")
+TaskCreate(name="apply_changelog_entry", description="Inject Distribution subsection into CHANGELOG.md current version")
+TaskCreate(name="present_diff_summary", description="Show diff stats; AskUserQuestion to confirm before commit")
+TaskCreate(name="commit_and_recommend_next", description="git commit (conventional fix:) + recommend manual macOS 26 verification + tag")
+```
+
+### Step 1: Resolve target project
+
+Args:
+- `--target /path/to/repo` (preferred — explicit)
+- `--target-name <Name>` (Sources/<Name>/Entitlements.plist needs this)
+- No flag → use $PWD; ask `--target-name` via AskUserQuestion
+
+Probe:
+
+```bash
+TARGET="${TARGET:-$PWD}"
+[[ ! -f "$TARGET/Package.swift" ]] && abort "Not a Swift Package: no Package.swift found"
+
+# Auto-detect target name from Package.swift if not given
+if [[ -z "$TARGET_NAME" ]]; then
+    TARGET_NAME=$(grep -oE '\.executable\(name:\s*"[^"]+"' "$TARGET/Package.swift" | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+    [[ -z "$TARGET_NAME" ]] && AskUserQuestion "What's the target name? (will be used in Sources/<Name>/Entitlements.plist)"
+fi
+```
+
+### Step 2: Probe project shape
+
+Detect existing artifacts to know what to edit vs create:
+
+```bash
+HAS_BUILD_SCRIPT=$([ -f "$TARGET/scripts/build-mcpb.sh" ] || [ -f "$TARGET/scripts/build-cli.sh" ] && echo "yes" || echo "no")
+BUILD_SCRIPT_PATH=$([ -f "$TARGET/scripts/build-mcpb.sh" ] && echo "scripts/build-mcpb.sh" || echo "scripts/build-cli.sh")
+HAS_MAKEFILE=$([ -f "$TARGET/Makefile" ] && echo "yes" || echo "no")
+HAS_README=$([ -f "$TARGET/README.md" ] && echo "yes" || echo "no")
+HAS_CHANGELOG=$([ -f "$TARGET/CHANGELOG.md" ] && echo "yes" || echo "no")
+HAS_ENTITLEMENTS=$([ -f "$TARGET/Sources/$TARGET_NAME/Entitlements.plist" ] && echo "yes" || echo "no")
+HAS_SIGN_SCRIPT=$([ -f "$TARGET/scripts/sign-and-notarize.sh" ] && echo "yes" || echo "no")
+```
+
+Report what exists vs what will be added.
+
+### Step 3: Apply files (one bash call per concern)
+
+Use the templates in `templates/` directory (see Templates section below).
+
+#### Step 3.1: Entitlements.plist
+
+```bash
+mkdir -p "$TARGET/Sources/$TARGET_NAME"
+cp "$SKILL_DIR/templates/Entitlements.plist" "$TARGET/Sources/$TARGET_NAME/Entitlements.plist"
+```
+
+#### Step 3.2: sign-and-notarize.sh
+
+Template needs no parameterization — it's already env-var driven (DEVELOPER_ID, NOTARY_PROFILE, ENTITLEMENTS).
+
+```bash
+mkdir -p "$TARGET/scripts"
+cp "$SKILL_DIR/templates/sign-and-notarize.sh" "$TARGET/scripts/sign-and-notarize.sh"
+chmod +x "$TARGET/scripts/sign-and-notarize.sh"
+```
+
+#### Step 3.3: Modify build script (build-mcpb.sh / build-cli.sh)
+
+Insert `[3.5/N]` sign step after the universal binary creation, before `mcpb pack` (or equivalent final step).
+
+Three insertion points to find:
+1. Variable `UNIVERSAL_BINARY` (or equivalent — the path to the built binary)
+2. After `lipo -create ... -output "$UNIVERSAL_BINARY"`
+3. Before any packaging step
+
+Template snippet at `templates/build-script-step-3.5.sh`. Inject between the lipo step and the next major step.
+
+For `build-mcpb.sh` ad-hoc trap fix: also add `rm -f "$UNIVERSAL_BINARY"` BEFORE `lipo -create` (#62 fix).
+
+If user already has Step 3.5 installed (e.g. they're upgrading mid-cycle), detect via `grep "REQUIRE_CODESIGN" "$BUILD_SCRIPT_PATH"` and abort with "already installed".
+
+#### Step 3.4: Makefile changes
+
+Two changes:
+
+1. **Add `release-signed` target**:
+```makefile
+.PHONY: build release release-signed install clean test
+# ... existing ...
+release-signed:
+	@echo "⚠ macOS 26 TCC behavior on the resulting binary remains unverified."
+	@echo "  Manual test required before tagging — install on macOS 26 and run --setup."
+	@echo ""
+	@: $${DEVELOPER_ID:?DEVELOPER_ID not set. See README 'Signing & Notarization' for setup.}
+	@: $${NOTARY_PROFILE:?NOTARY_PROFILE not set. See README 'Signing & Notarization' for setup.}
+	REQUIRE_CODESIGN=1 ./scripts/build-mcpb.sh
+```
+
+2. **Modify `install:` target** to add `rm -f` prefix (#62 fix):
+```makefile
+install: release
+	rm -f ~/bin/$(BINARY_NAME)
+	cp .build/release/$(BINARY_NAME) ~/bin/$(BINARY_NAME)
+	chmod +x ~/bin/$(BINARY_NAME)
+	codesign --force --sign - ~/bin/$(BINARY_NAME)
+	@echo "Installed: ~/bin/$(BINARY_NAME) (ad-hoc signed — dev only)"
+```
+
+If `install:` target doesn't exist, create it. If exists, only add `rm -f` line at the start of recipe.
+
+#### Step 3.5: README "Signing & Notarization" subsection
+
+Append to README.md, ideally under "Release Process (for maintainers)" section. If no Release Process section, append at end.
+
+Template at `templates/README-signing-section.md`. Substitutions:
+- `{{TARGET_NAME}}` → e.g. `CheICalMCP`
+- `{{NOTARY_PROFILE_DEFAULT}}` → e.g. `che-ical-mcp` (suggested name based on target lowercase)
+
+#### Step 3.6: CHANGELOG entry
+
+Find current version's section in CHANGELOG.md (e.g. `## [1.7.1]`). Inject `### Distribution` subsection at the top of the section's body.
+
+Template at `templates/changelog-distribution.md`.
+
+If user is currently on `[Unreleased]` only, ask whether to inject there or pin to a specific version.
+
+### Step 4: Present diff summary
+
+```
+=== mcp-sign-pipeline applied to {target} ===
+NEW:
+  Sources/{TargetName}/Entitlements.plist            (5 lines)
+  scripts/sign-and-notarize.sh                       (~150 lines)
+MODIFIED:
+  scripts/build-mcpb.sh                              (+~30 lines: REQUIRE_CODESIGN gate)
+  Makefile                                           (+~12 lines: release-signed target)
+  README.md                                          (+~70 lines: Signing & Notarization)
+  CHANGELOG.md                                       (+~10 lines: Distribution entry)
+
+NEXT STEPS for user:
+  1. Verify cert: security find-identity -p codesigning -v
+  2. Set up notarytool profile: xcrun notarytool store-credentials <name>
+  3. export DEVELOPER_ID='Developer ID Application: <Your Name> (<TeamID>)'
+  4. export NOTARY_PROFILE='<your-profile-name>'
+  5. make release-signed (will fail-fast if any prereq missing)
+  6. Test on macOS 26 hardware: install + ~/bin/<TargetName> --setup
+```
+
+### Step 5: Commit & recommend next
+
+```bash
+git add Sources/$TARGET_NAME/Entitlements.plist scripts/sign-and-notarize.sh scripts/build-mcpb.sh Makefile README.md CHANGELOG.md
+git commit -m "feat: add Developer ID signing + notarization pipeline (macOS 26 TCC)
+
+Applied via mcp-sign-pipeline skill. Required on macOS 26 — ad-hoc
+signed binaries can no longer trigger Calendar/Reminders/AppleEvents
+TCC permission dialogs.
+
+Components:
+- Sources/<Target>/Entitlements.plist (empty <dict/>; hardened runtime
+  is the macOS 26 TCC trigger; no entitlement keys needed)
+- scripts/sign-and-notarize.sh (codesign + verify + notarize +
+  pre-flight checks + friendly error messages)
+- scripts/build-mcpb.sh: new [3.5/N] sign step; REQUIRE_CODESIGN=1
+  gates canonical release path; auto-skip with warning otherwise
+- Makefile: new release-signed target; install: gets rm -f to prevent
+  inode-cache SIGKILL trap on upgrades
+- README/CHANGELOG: Signing & Notarization docs + entry
+
+Manual macOS 26 verification gates first signed release."
+```
+
+### Step 6: Auto-update integration (optional)
+
+If invoked from `mcp-new-app` or `cli-new-app`, return control to the parent skill. If invoked standalone, recommend:
+
+```
+/idd-issue [bug] add manual macOS 26 verification test (TCC dialog appears, permissions persist)
+```
+
+so the human verification step has a tracking issue.
+
+## Templates (in templates/)
+
+- `Entitlements.plist` — empty `<dict/>` plist
+- `sign-and-notarize.sh` — full script (verbatim from che-ical-mcp PR #44 c2d0db5; env-var driven, no hardcoded identity)
+- `build-script-step-3.5.sh` — bash snippet to insert into build-mcpb.sh / build-cli.sh
+- `Makefile-release-signed.snippet` — Make target snippet
+- `README-signing-section.md` — README subsection with `{{TARGET_NAME}}` placeholders
+- `changelog-distribution.md` — CHANGELOG entry snippet
+
+## Iron rules
+
+- **Never hardcode `DEVELOPER_ID` default**. Always require it via env var. The c-ical-mcp Round 1 vs Round 2 verify caught this exact regression.
+- **Always inject `REQUIRE_CODESIGN=1` in `make release-signed`** so canonical release path fails fast if env unset (Codex P1 finding from che-ical-mcp Round 2).
+- **Always install `rm -f` in `install:` target** (#62 inode-cache trap fix; affects 100% of upgrade users).
+- **Always recommend manual macOS 26 test** as a follow-up. spctl + codesign passing does NOT mean TCC dialog actually appears — that's a separate Apple gate.
+- **Skill never installs cert / notarytool profile**. Those are user-side prereqs. Install scripts emit friendly errors if missing.
+
+## Provenance
+
+Templates extracted from `che-ical-mcp` PR #52 (2026-05-04, squash `f04fdf8`):
+- 4 commits via 3 rounds of cross-model verify (5 Claude reviewers + Codex gpt-5.5)
+- Round 2 caught silent-degrade antipattern (Codex P1 + Devil's Advocate P2 cross-confirmed)
+- End-to-end verified on macOS 26.4.1: `spctl -t install` returns `accepted`, `--setup` grants Calendar + Reminders, real EventKit calls succeed
+
+This is the productionized template, not a draft.
+
+## Next step suggestions
+
+After applying:
+- `/idd-issue` — file follow-up for manual macOS 26 verification gate
+- `/idd-issue` — file follow-up for GitHub Actions CI signing (deferred from MVP)
+- Manual: `make release-signed && install + verify on macOS 26 hardware`
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/Entitlements.plist b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/Entitlements.plist
new file mode 100644
index 00000000..0c67376e
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/Entitlements.plist
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict/>
+</plist>
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/Makefile-release-signed.snippet b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/Makefile-release-signed.snippet
new file mode 100644
index 00000000..71a96af2
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/Makefile-release-signed.snippet
@@ -0,0 +1,20 @@
+# Distribution release: builds universal binary, signs with Developer ID,
+# notarizes via xcrun notarytool, and packages into .mcpb (or final artifact).
+# Requires Developer ID Application cert in keychain + notarytool keychain
+# profile (see README "Signing & Notarization" for one-time setup).
+#
+# REQUIRE_CODESIGN=1 makes signing mandatory — missing DEVELOPER_ID, missing
+# cert, or missing notarytool profile will fail-fast instead of silently
+# producing an unsigned artifact. This is the canonical release-cut command;
+# use plain `./scripts/build-mcpb.sh` (without the flag) for fork-friendly
+# unsigned dev builds.
+release-signed:
+	@echo "⚠ macOS 26 TCC behavior on the resulting binary remains unverified."
+	@echo "  Manual test required before tagging — install on macOS 26 and run --setup."
+	@echo ""
+	@: $${DEVELOPER_ID:?DEVELOPER_ID not set. See README 'Signing & Notarization' for setup.}
+	@: $${NOTARY_PROFILE:?NOTARY_PROFILE not set. See README 'Signing & Notarization' for setup.}
+	REQUIRE_CODESIGN=1 ./scripts/build-mcpb.sh
+
+# NOTE: Add 'release-signed' to your .PHONY line, e.g.:
+# .PHONY: build release release-signed install clean test
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/README-signing-section.md b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/README-signing-section.md
new file mode 100644
index 00000000..87f0e968
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/README-signing-section.md
@@ -0,0 +1,94 @@
+#### Signing & Notarization (required for macOS 26+)
+
+Starting v{{NEXT_VERSION}}, release binaries are signed with a Developer ID Application certificate and notarized via Apple's `notarytool`. This is **required** on macOS 26 — ad-hoc signed binaries cannot trigger Calendar / Reminders / AppleEvents TCC permission dialogs there.
+
+**Prerequisites** (one-time setup):
+
+1. Apple Developer Program enrollment.
+2. Developer ID Application certificate installed in login keychain.
+   - Verify with: `security find-identity -p codesigning -v` (must show `Developer ID Application: <Your Name> (<TeamID>)`).
+   - Your Team ID is your own — find it at <https://developer.apple.com/account> → Membership Details.
+3. `notarytool` keychain profile (any name; suggest `{{NOTARY_PROFILE_DEFAULT}}`).
+   - Create interactively (recommended — keeps password out of shell history):
+     ```bash
+     xcrun notarytool store-credentials {{NOTARY_PROFILE_DEFAULT}} --apple-id <your-apple-id> --team-id <your-team-id>
+     # notarytool will prompt for the app-specific password
+     ```
+   - App-specific password: generate at <https://account.apple.com> → Sign-In and Security → App-Specific Passwords. Use a single-purpose password (named e.g. `{{NOTARY_PROFILE_DEFAULT}}`); revoke + regenerate if leaked. **Never** pass it via `--password` on the command line — it lands in `~/.zsh_history`.
+4. Export your identity for the build script:
+   ```bash
+   export DEVELOPER_ID='Developer ID Application: <Your Name> (<TeamID>)'
+   export NOTARY_PROFILE='{{NOTARY_PROFILE_DEFAULT}}'   # match what you set up in step 3
+   ```
+   Persist these in `~/.zshrc` or a project-local `.envrc` (gitignored). The script intentionally has **no defaults** for these, so a fresh fork doesn't fail with errors referring to the maintainer's identity.
+
+**Per-release flow**:
+
+```bash
+make release-signed     # builds → signs + notarizes → packages
+gh release create vX.Y.Z <path-to-binary> [<path-to-mcpb>] --notes "..."
+```
+
+`make release-signed` runs `scripts/build-mcpb.sh` (or `build-cli.sh`) with `REQUIRE_CODESIGN=1` so missing prerequisites fail-fast. After universal binary creation, `scripts/sign-and-notarize.sh` performs codesign + notarization. Notarization typically takes 1–15 minutes (`notarytool submit --wait` blocks until Apple finishes).
+
+**Verification** after build (run all three to confirm end-to-end):
+
+```bash
+# 1. Signature properties (cert + hardened runtime + team ID)
+codesign -dv --verbose=2 path/to/{{TARGET_NAME}}
+# Expected:
+#   Authority=Developer ID Application: <Your Name> (<TeamID>)
+#   TeamIdentifier=<TeamID>
+#   flags=0x10000(runtime)
+
+# 2. Signature integrity
+codesign --verify --deep --strict --verbose=2 path/to/{{TARGET_NAME}}
+# Expected: exit 0, no warnings
+
+# 3. Notarization end-to-end (this is the real "Gatekeeper would accept" gate)
+spctl -a -vvv -t install path/to/{{TARGET_NAME}}
+# Expected: <binary>: accepted; source=Notarized Developer ID
+#
+# Note on flag choice (verified empirically on macOS 26.4.1):
+#   -t execute → rejected "code is valid but does not seem to be an app"
+#                (Apple's "execute" type expects a .app bundle structure,
+#                 not raw Mach-O CLI binaries)
+#   -t install → accepted; source=Notarized Developer ID  ← use this
+#
+# Apple's Code Signing Guide describes -t execute as the assessment type for
+# "applications and tools", but on macOS 26 raw Mach-O binaries fall through
+# the .app bundle check. -t install is the documented assessment type for
+# software being installed (which describes how a CLI binary lands in ~/bin),
+# and is the type that returns the actual notarization verdict in practice.
+# Re-test if Apple changes this behavior in a future macOS update.
+```
+
+**Local dev iteration** without signing latency:
+
+```bash
+SKIP_CODESIGN=1 ./scripts/build-mcpb.sh   # ad-hoc signed; do NOT ship the result
+make install                              # installs ad-hoc to ~/bin (dev only)
+```
+
+The build script also **auto-skips signing** when `DEVELOPER_ID` is unset OR the cert isn't in your keychain — so contributors / CI / forks can build a working unsigned artifact for testing without manually setting `SKIP_CODESIGN`. (You'll see a clear "Skipping codesign" warning when this happens.) `make release-signed` enforces signing via `REQUIRE_CODESIGN=1` and fails fast if anything is missing.
+
+**Signing identity environment**:
+
+| Env var | Default | Required for |
+|---------|---------|--------------|
+| `DEVELOPER_ID` | _(unset — auto-skip signing)_ | Signed release |
+| `NOTARY_PROFILE` | _(unset — fail-fast in `sign-and-notarize.sh`)_ | Signed release |
+| `ENTITLEMENTS` | `Sources/{{TARGET_NAME}}/Entitlements.plist` | Custom entitlements file |
+| `SKIP_CODESIGN` | _(unset)_ | Force-skip signing even with cert present (set to `1` or `true`) |
+| `REQUIRE_CODESIGN` | _(unset)_ | Fail-fast if signing prerequisites missing (set to `1` by `make release-signed`) |
+
+**Known limitation — no stapling**: `stapler staple` does not support raw Mach-O binaries (only `.app` / `.pkg` / `.dmg` bundles). After notarization, Gatekeeper will online-check the binary on first launch instead of reading a stapled ticket. End users behind air-gapped networks may see "cannot verify developer" warnings; one launch with network resolves it (Apple caches the verdict). Mitigation: `xcrun stapler staple` on a future `.pkg` wrapper if needed.
+
+**Upgrade trap (if shipping over an existing install)**: If users have an older version of `{{TARGET_NAME}}` already installed (e.g. ad-hoc signed prior version), they should `rm -f` the old binary before replacing it. macOS caches code-signature hashes per-inode; copying a new binary over an inode held open by a still-running old process leaves a stale cache that causes the kernel to kill the new binary on exec with "load code signature error 2". The `Makefile install:` target and the user-facing install instructions both use `rm -f` defensively.
+
+**Troubleshooting**:
+
+- Notarization rejected? `xcrun notarytool log <submission-id> --keychain-profile $NOTARY_PROFILE` shows Apple's reason. The signing script prints the submission ID on every run.
+- `codesign` complains about missing identity? `security find-identity -p codesigning -v` to confirm cert is present + valid; `xcrun notarytool history --keychain-profile $NOTARY_PROFILE` to confirm the profile works.
+- Cert expired? Re-issue at <https://developer.apple.com/account/resources/certificates>, install, re-export `DEVELOPER_ID`.
+- Security warning: don't unlock signing keychain on shared / untrusted machines. The cert + private key signing artifact is supply-chain critical.
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/build-script-step-3.5.sh b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/build-script-step-3.5.sh
new file mode 100644
index 00000000..43a93f92
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/build-script-step-3.5.sh
@@ -0,0 +1,47 @@
+# Step 3.5: Sign + notarize for distribution.
+# Required for releases: macOS 26 TCC rejects ad-hoc binaries; Developer ID
+# signing + hardened runtime + notarization is the only way Calendar/Reminders/
+# AppleEvents permission dialogs appear for end users.
+#
+# Behavior:
+#   SKIP_CODESIGN=1 (or "true") → skip unconditionally (local iteration override)
+#   REQUIRE_CODESIGN=1 → fail-fast if signing prerequisites missing
+#     (used by `make release-signed` — canonical release path must not
+#      silently produce unsigned artifacts)
+#   No DEVELOPER_ID env or no cert in keychain → auto-skip with warning
+#     (default fork-friendly behavior for direct script invocation)
+#   Otherwise → run sign-and-notarize.sh
+echo ""
+SHOULD_SIGN=true
+SKIP_REASON=""
+if [[ "${SKIP_CODESIGN:-}" == "1" || "${SKIP_CODESIGN:-}" == "true" ]]; then
+    SHOULD_SIGN=false
+    SKIP_REASON="SKIP_CODESIGN=$SKIP_CODESIGN"
+elif [[ -z "${DEVELOPER_ID:-}" ]]; then
+    SHOULD_SIGN=false
+    SKIP_REASON="DEVELOPER_ID env not set"
+elif ! security find-identity -p codesigning -v 2>/dev/null | grep -qF "$DEVELOPER_ID"; then
+    SHOULD_SIGN=false
+    SKIP_REASON="codesigning identity '$DEVELOPER_ID' not in keychain"
+fi
+
+if [[ "$SHOULD_SIGN" == "false" ]]; then
+    if [[ "${REQUIRE_CODESIGN:-}" == "1" || "${REQUIRE_CODESIGN:-}" == "true" ]]; then
+        # Canonical release path — refuse to produce unsigned artifact silently
+        echo "[3.5/N] ✗ Refusing to skip signing: REQUIRE_CODESIGN=$REQUIRE_CODESIGN" >&2
+        echo "        Reason: $SKIP_REASON" >&2
+        echo "        Fix: set DEVELOPER_ID + NOTARY_PROFILE, install Developer ID Application" >&2
+        echo "             cert, and ensure cert is in your login keychain." >&2
+        echo "        See README 'Signing & Notarization' for one-time setup." >&2
+        exit 1
+    fi
+    # Fork-friendly auto-skip: warn + continue with unsigned binary
+    echo "[3.5/N] Skipping codesign + notarize."
+    echo "  Reason: $SKIP_REASON"
+    echo "  ⚠ Resulting binary is ad-hoc signed; suitable for local dev only."
+    echo "  ⚠ To produce a release-quality artifact on macOS 26: set DEVELOPER_ID +"
+    echo "    NOTARY_PROFILE, install Developer ID Application cert, then run \`make release-signed\`."
+else
+    echo "[3.5/N] Signing + notarizing for distribution..."
+    "$SCRIPT_DIR/sign-and-notarize.sh" "$UNIVERSAL_BINARY"
+fi
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/changelog-distribution.md b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/changelog-distribution.md
new file mode 100644
index 00000000..b02b5404
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/changelog-distribution.md
@@ -0,0 +1,9 @@
+### Distribution
+- **macOS 26 codesigning + notarization**: release binary is now signed with Developer ID Application + hardened runtime + notarized via `xcrun notarytool`. macOS 26 tightened TCC such that ad-hoc signed binaries can no longer trigger Calendar / Reminders / AppleEvents permission dialogs — Developer ID + hardened runtime + notarization is the only path that lets end users grant access without manually re-signing the binary themselves.
+  - New `scripts/sign-and-notarize.sh` wraps the codesign + ditto-zip + notarytool submit flow with pre-flight checks (cert in keychain, notarytool keychain profile configured) and friendly error messages including the submission ID for `xcrun notarytool log` post-mortem.
+  - New `scripts/build-mcpb.sh` (or build-cli.sh) step `[3.5/N]` calls the signing script automatically. Auto-skips when `DEVELOPER_ID` env var is unset OR cert isn't in the keychain (so contributors / CI / forks can build a working unsigned artifact for testing without manually setting `SKIP_CODESIGN=1`).
+  - New `Makefile` target `release-signed` is the canonical release-cut command; uses `REQUIRE_CODESIGN=1` to fail-fast if prerequisites missing.
+  - `Sources/{{TARGET_NAME}}/Entitlements.plist` (empty `<dict/>`) — minimal entitlements; hardened runtime alone is what macOS 26 requires for TCC. Add specific entitlement keys here only if hardened runtime breaks a specific API at runtime.
+  - **Known limitation**: stapling skipped (raw Mach-O doesn't support `xcrun stapler staple`); Gatekeeper online-checks notarization on first launch, requiring one-time network access.
+  - **Upgrade trap fix**: `Makefile install:` and the user-facing install instructions both use `rm -f` before write, to prevent the inode-cache code-signature trap when upgrading over a previous install.
+  - README "Release Process" gains a "Signing & Notarization" subsection with prerequisites, per-release flow, end-to-end verification (`spctl -a -vvv -t install`), and troubleshooting.
diff --git a/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/sign-and-notarize.sh b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/sign-and-notarize.sh
new file mode 100755
index 00000000..e2e16f61
--- /dev/null
+++ b/plugins/mcp-tools/skills/mcp-sign-pipeline/templates/sign-and-notarize.sh
@@ -0,0 +1,156 @@
+#!/bin/bash
+# Sign and notarize the CheICalMCP universal binary for outside-App-Store distribution.
+#
+# macOS 26 tightened TCC: ad-hoc signed binaries can no longer trigger
+# Calendar / Reminders permission grants. Distribution-quality binaries must
+# be signed with a Developer ID Application cert + hardened runtime + notarized.
+#
+# Stapling is NOT performed: stapler staple does not support raw Mach-O
+# binaries (only .app/.pkg/.dmg). Gatekeeper online-checks at first launch
+# instead — this requires the user's machine to be online once when first
+# running the binary.
+#
+# Usage:
+#   scripts/sign-and-notarize.sh <path/to/binary>
+#
+# Required env vars (no defaults — fork-friendly, no maintainer PII in error messages):
+#   DEVELOPER_ID    — codesigning identity, e.g. "Developer ID Application: Your Name (TEAMID)"
+#   NOTARY_PROFILE  — notarytool keychain profile name (set up via: xcrun notarytool store-credentials <name> ...)
+#
+# Optional env var:
+#   ENTITLEMENTS    — entitlements .plist path (default: "Sources/CheICalMCP/Entitlements.plist")
+
+set -euo pipefail
+
+BINARY="${1:?Usage: $0 <path/to/binary>}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+ENTITLEMENTS="${ENTITLEMENTS:-$PROJECT_DIR/Sources/CheICalMCP/Entitlements.plist}"
+
+# Pre-flight: required env vars
+if [[ -z "${DEVELOPER_ID:-}" ]]; then
+    echo "Error: DEVELOPER_ID is not set." >&2
+    echo "       Export your Developer ID Application identity:" >&2
+    echo "       export DEVELOPER_ID='Developer ID Application: Your Name (TEAMID)'" >&2
+    echo "       Find available identities: security find-identity -p codesigning -v" >&2
+    exit 1
+fi
+
+if [[ -z "${NOTARY_PROFILE:-}" ]]; then
+    echo "Error: NOTARY_PROFILE is not set." >&2
+    echo "       Export your notarytool keychain profile name:" >&2
+    echo "       export NOTARY_PROFILE='your-profile-name'" >&2
+    echo "       Set up profile (one-time): xcrun notarytool store-credentials <name> --apple-id <id> --team-id <team-id>" >&2
+    echo "       (notarytool will prompt for app-specific password — do NOT pass it on the command line)" >&2
+    exit 1
+fi
+
+if [[ ! -f "$BINARY" ]]; then
+    echo "Error: binary not found at $BINARY" >&2
+    exit 1
+fi
+
+if [[ ! -f "$ENTITLEMENTS" ]]; then
+    echo "Error: entitlements file not found at $ENTITLEMENTS" >&2
+    exit 1
+fi
+
+# Pre-flight: verify cert exists in keychain (avoids cryptic codesign error mid-flow)
+if ! security find-identity -p codesigning -v 2>/dev/null | grep -qF "$DEVELOPER_ID"; then
+    echo "Error: codesigning identity not found in keychain: $DEVELOPER_ID" >&2
+    echo "       Available identities:" >&2
+    security find-identity -p codesigning -v 2>&1 | grep -E '"[^"]*"' | sed 's/^/         /' >&2
+    exit 1
+fi
+
+# Pre-flight: verify notarytool keychain profile exists (avoids submit-then-fail)
+if ! xcrun notarytool history --keychain-profile "$NOTARY_PROFILE" >/dev/null 2>&1; then
+    echo "Error: notarytool keychain profile '$NOTARY_PROFILE' not configured." >&2
+    echo "       Set up with: xcrun notarytool store-credentials $NOTARY_PROFILE \\" >&2
+    echo "                      --apple-id <your-apple-id> --team-id <your-team-id>" >&2
+    exit 1
+fi
+
+# Use mktemp for /tmp zip + trap to ensure cleanup on any exit (including SIGINT/SIGTERM/error)
+ZIP_PATH=""
+cleanup() {
+    [[ -n "$ZIP_PATH" && -f "$ZIP_PATH" ]] && rm -f "$ZIP_PATH"
+}
+trap cleanup EXIT INT TERM
+
+echo "=== sign-and-notarize: $BINARY ==="
+echo "  Identity:      $DEVELOPER_ID"
+echo "  Profile:       $NOTARY_PROFILE"
+echo "  Entitlements:  $ENTITLEMENTS"
+echo ""
+
+# Step 1: codesign with hardened runtime
+echo "[1/4] Signing with Developer ID + hardened runtime..."
+codesign --force \
+    --options runtime \
+    --entitlements "$ENTITLEMENTS" \
+    --sign "$DEVELOPER_ID" \
+    "$BINARY"
+
+# Step 2: verify signature locally
+# Note: this is a gating verify (codesign --verify exit code is checked); the |head -5
+# is for output trimming only. Under set -o pipefail, if codesign verify fails it will
+# write to stderr and exit non-zero, propagating up because head reads <= 5 lines and
+# closes its stdin → codesign gets SIGPIPE → pipeline exit non-zero → set -e aborts.
+echo ""
+echo "[2/4] Verifying signature..."
+codesign --verify --deep --strict --verbose=2 "$BINARY" 2>&1 | head -5
+
+# Step 3: notarize (requires zip wrapper for raw Mach-O)
+# Capture submission output so we can extract submission ID for post-mortem debug
+# if the wait fails. notarytool prints "  id: <UUID>" line on success and failure.
+echo ""
+echo "[3/4] Submitting for notarization (this typically takes 1-15 minutes)..."
+ZIP_PATH="$(mktemp -t notarize-XXXXXXXX).zip"
+ditto -c -k --keepParent "$BINARY" "$ZIP_PATH"
+
+# tee output so user sees progress while we capture submission ID
+SUBMIT_LOG="$(mktemp -t notarize-log-XXXXXXXX)"
+trap 'cleanup; rm -f "$SUBMIT_LOG"' EXIT INT TERM
+
+# Helper: extract submission UUID from notarytool log; never aborts under set -e
+# (grep returns 1 if no match → would abort; trailing || true makes it fail-soft)
+extract_submission_id() {
+    grep -m1 -E '^[[:space:]]*id:' "$1" 2>/dev/null | awk '{print $2}' || true
+}
+
+if ! xcrun notarytool submit "$ZIP_PATH" \
+        --keychain-profile "$NOTARY_PROFILE" \
+        --wait 2>&1 | tee "$SUBMIT_LOG"; then
+    SUBMISSION_ID="$(extract_submission_id "$SUBMIT_LOG")"
+    echo "" >&2
+    echo "Error: notarization failed (or notarytool errored)." >&2
+    if [[ -n "$SUBMISSION_ID" ]]; then
+        echo "       To see Apple's rejection reason:" >&2
+        echo "         xcrun notarytool log $SUBMISSION_ID --keychain-profile $NOTARY_PROFILE" >&2
+    else
+        echo "       (no submission ID captured — full notarytool output above; if format changed," >&2
+        echo "        run: xcrun notarytool history --keychain-profile $NOTARY_PROFILE)" >&2
+    fi
+    exit 1
+fi
+
+SUBMISSION_ID="$(extract_submission_id "$SUBMIT_LOG")"
+if [[ -n "$SUBMISSION_ID" ]]; then
+    echo "Submission ID: $SUBMISSION_ID"
+else
+    echo "(submission accepted but ID not captured — notarytool output format may have changed)"
+fi
+
+# Step 4: print final state for visual confirmation
+# || true: this is informational only; if codesign output format changes and grep
+# doesn't match, we don't want to fail the whole script.
+echo ""
+echo "[4/4] Final signature state:"
+codesign -dv --verbose=2 "$BINARY" 2>&1 | grep -E "Authority|TeamIdentifier|flags|Signature" || true
+
+echo ""
+echo "=== sign-and-notarize: DONE ==="
+echo "Note: stapling skipped (raw Mach-O binaries don't support stapler)."
+echo "      Gatekeeper will online-check on first launch."
+echo "      To verify notarization end-to-end: spctl -a -vvv -t install $BINARY"
diff --git a/plugins/mcp-tools/skills/mcp-sync/SKILL.md b/plugins/mcp-tools/skills/mcp-sync/SKILL.md
index af960653..57acb9d7 100644
--- a/plugins/mcp-tools/skills/mcp-sync/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-sync/SKILL.md
@@ -30,6 +30,22 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="detect_project", description="Phase 0: 確認 MCP 專案 + 取 binary 名 + 偵測三位置 binary")
+TaskCreate(name="consistency_check", description="Phase 1: hash + 架構比對 + 輸出一致性報告")
+TaskCreate(name="execute_sync", description="Phase 2: 從 source of truth 同步到其他位置")
+TaskCreate(name="repackage_mcpb", description="Phase 2.5: 刪舊 .mcpb + 重新打包 + 驗證")
+TaskCreate(name="post_sync_verify", description="Phase 3: 最終驗證")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 偵測專案
 
 ### Step 1: 確認在 MCP 專案目錄
diff --git a/plugins/mcp-tools/skills/mcp-test/SKILL.md b/plugins/mcp-tools/skills/mcp-test/SKILL.md
index 7200eba3..5d0ad239 100644
--- a/plugins/mcp-tools/skills/mcp-test/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-test/SKILL.md
@@ -17,6 +17,21 @@ allowed-tools: Bash(claude mcp:*), Bash(grep:*), Read, Grep, Glob
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="prepare", description="Phase 0: 檢查連線 + 識別框架 + 建測試日誌目錄")
+TaskCreate(name="tool_discovery", description="Phase 1: 提取所有 tools + 自動分類 + 產生清單")
+TaskCreate(name="run_unit_tests", description="Phase 2: 執行單元測試（逐一呼叫 tools）")
+TaskCreate(name="generate_report", description="Phase 3: 產生測試報告 + 儲存")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 準備
 
 ### Step 1: 檢查連線
diff --git a/plugins/mcp-tools/skills/mcp-to-plugin/SKILL.md b/plugins/mcp-tools/skills/mcp-to-plugin/SKILL.md
index 5531e3ec..752eed9a 100644
--- a/plugins/mcp-tools/skills/mcp-to-plugin/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-to-plugin/SKILL.md
@@ -38,6 +38,24 @@ Plugin 解決以上所有問題：wrapper script 從 Keychain 讀密鑰、hook 
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="gather_info", description="Phase 0: 識別 MCP server + 確認 plugin 參數 + 多 MCP 合併（若需）")
+TaskCreate(name="create_plugin_structure", description="Phase 1: 建目錄 + plugin.json + .mcp.json")
+TaskCreate(name="migrate_keychain_secrets", description="Phase 2: 儲存密鑰到 Keychain + 驗證 + 提醒使用者")
+TaskCreate(name="create_wrapper_script", description="Phase 3: 寫 bin/*-wrapper.sh（含 auto-download from release）")
+TaskCreate(name="create_session_hook", description="Phase 4: 寫 hooks/session-start.sh")
+TaskCreate(name="generate_commands", description="Phase 5: 建 commands/ 骨架")
+TaskCreate(name="sync_marketplace", description="更新 marketplace.json + 安裝")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 蒐集資訊
 
 開始之前，需要確定以下資訊。如果能從 `~/.claude.json` 或專案目錄自動偵測就用偵測的，偵測不到的用 AskUserQuestion 問。
diff --git a/plugins/mcp-tools/skills/mcp-upgrade/SKILL.md b/plugins/mcp-tools/skills/mcp-upgrade/SKILL.md
index 78f56378..7ca21538 100644
--- a/plugins/mcp-tools/skills/mcp-upgrade/SKILL.md
+++ b/plugins/mcp-tools/skills/mcp-upgrade/SKILL.md
@@ -23,6 +23,23 @@ disable-model-invocation: true
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="project_analysis", description="Phase 0: 確認專案位置 + 識別語言/框架 + 收集資訊")
+TaskCreate(name="dependency_analysis", description="Phase 1: 依賴分析（過時、安全漏洞、版本差距）")
+TaskCreate(name="structure_analysis", description="Phase 2: 目錄結構 + 程式碼品質 + Binary 一致性（Swift only）")
+TaskCreate(name="feature_analysis", description="Phase 3: 現有工具 + API 能力對比 + 建議新功能")
+TaskCreate(name="generate_upgrade_report", description="Phase 4: 彙整報告，列出所有建議 + 優先級")
+TaskCreate(name="await_approval_and_execute", description="Phase 5: AskUserQuestion 讓使用者挑選後執行")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
 ## Phase 0: 專案分析
 
 ### Step 1: 確認專案位置
diff --git a/plugins/parallel-ai-agents/.claude-plugin/plugin.json b/plugins/parallel-ai-agents/.claude-plugin/plugin.json
new file mode 100644
index 00000000..bf3cac42
--- /dev/null
+++ b/plugins/parallel-ai-agents/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "parallel-ai-agents",
+  "description": "平行派發任務給多個 AI agent（Claude + Codex），獨立執行後交叉比對結果。Codex 改走直接 HTTP wrapper（bin/codex-call，Swift script）取代 codex exec subprocess，解決 hang 問題且避開 Python 版本飄移",
+  "version": "2.5.1",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/parallel-ai-agents/CHANGELOG.md b/plugins/parallel-ai-agents/CHANGELOG.md
new file mode 100644
index 00000000..effaaadb
--- /dev/null
+++ b/plugins/parallel-ai-agents/CHANGELOG.md
@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [2.3.0] - 2026-05-07
+
+### Added
+- **`--auto-iterate` mode for `/ensemble-academic-review` (#34)**: round → fix → round 自治收斂迴圈,內部沿用 mix N 的 alternating independent/hybrid pattern,但加上每輪結束的:
+  - **Verdict parsing**: Codex prompt 強制要求 `<verdict>PERMANENT_CONVERGENCE | CONVERGED | NEEDS_ITER_N</verdict>` 結構化 tag,skill 用 regex 解析,不靠語意判斷
+  - **HIGH-only fix application**: 從 `review-round-{N}.md` 解 HIGH-severity findings 自動套到 working tree;ambiguous fix skip + log to `skipped_fixes.log`
+  - **Auto-commit per round**: `iter-{N}: apply HIGH fixes from ensemble round {N}`,user 可隨時 `git revert iter-{N}`
+  - **Rotate-focus heuristic**: 連續 K=3 同 focus CONVERGED 才 switch (focus pool: method-section / proofs / typography / cross-references / boundary-cases)
+  - **Stop conditions**: 達 `--converge-on` (default `PERMANENT_CONVERGENCE`) 或 `--max-rounds` (default 12, max 30)
+- **8 cumulative methodological lessons** in SKILL.md tail — 來自實戰 23-round campaign (`PsychQuantHsu/psychophysic_representations_manuscript/docs/rounds/INDEX.md`),作為 rare-audited section / hypothesis-inheritance / verdict-tier 等坑的 reference
+
+### Notes
+- Self-contained Bash while + state machine,**不**依賴 ralph-loop 的 Stop-hook 機制
+- 與 ralph-loop 同時跑時 skill 偵測並警告(雙 Stop-hook 衝突風險)
+- Spec-only PR — agent 讀 SKILL.md 後在 user 顯式傳 `--auto-iterate` 才觸發,既有 mode 行為不變
+
+## [2.2.0] - 2026-05-03
+
+### Added
+- **`number-verifier` reviewer**: 5th ensemble reviewer that checks every
+  number in a doc against ground-truth artifacts (`.rds`, `.npz`, `.csv`,
+  R/Python scripts). Catches hallucinated numbers that other reviewers
+  miss. Verified by ASSG3 review pipeline (Canadian GDP ARIMA + Australian
+  yields VAR/VECM) where it caught wrong y_T, drift omission, Ljung-Box
+  fitdf errors, and ARIMA(1,1,1) reference p-value mistakes across 4 rounds.
+- `--no-numeric` flag to disable number-verifier (pure theoretical papers)
+- `--no-references` flag to disable reference-verifier (technical notes)
+- Auto-detect: number-verifier enables when `analysis/`, `*.rds`, `*.ipynb`,
+  `*.Rmd`, or `data/*.csv` are present near the doc
+- Hybrid mode: `prior_number_issues` watch list passed to number-verifier
+  in subsequent rounds (analogous to `prior_ref_issues`)
+
+### Changed
+- Reviewer count: 4 → 5 Claude teammates + Codex
+- Tool-call rule: "5 calls in one message" → "N+1 calls (N ∈ {3,4,5})"
+- Ironclad rules: HIGH-priority bucket now includes hallucinated numbers
+  alongside hallucinated references
+
+## [2.1.1] - (date unknown — please fill in)
+
+### Changed
+- 平行派發任務給多個 AI agent（Claude + Codex），獨立執行後交叉比對結果
diff --git a/plugins/parallel-ai-agents/CLAUDE.md b/plugins/parallel-ai-agents/CLAUDE.md
new file mode 100644
index 00000000..bd610bd3
--- /dev/null
+++ b/plugins/parallel-ai-agents/CLAUDE.md
@@ -0,0 +1,74 @@
+# parallel-ai-agents — CLAUDE.md
+
+## Purpose
+
+平行派發任務給多個 AI agent，獨立執行後交叉比對結果。使用 Claude orchestrated teams + Codex 實現跨模型、跨角色的盲驗。
+
+## Skills
+
+| Skill | 用途 | 架構 |
+|-------|------|------|
+| `/parallel-ai-agents:ensemble-review` | 審閱文件/程式碼，交叉比對產出共識/盲點報告 | 4 Claude teammates (team) + 1 Codex |
+
+## 審閱架構
+
+```
+ensemble-review
+├── Claude Team（4 teammates，orchestrated）
+│   ├── architecture — 設計、API、依賴
+│   ├── correctness — 邏輯、bug、edge case
+│   ├── security — 攻擊者視角
+│   └── devils-advocate — 反駁前 3 人
+└── Codex（gpt-5.5，跨模型盲驗）
+```
+
+## 依賴
+
+- Claude Code orchestrated teams（TeamCreate、SendMessage）
+- **Codex OAuth token**（`~/.codex/auth.json`）— 由 codex CLI 在首次登入時建立。本 plugin 自帶 wrapper `bin/codex-call` 直接讀這個檔案、走 OAuth refresh + HTTP 直連 `chatgpt.com/backend-api`，不再 spawn `codex exec` subprocess（避免 stdin/stdout pipe 互鎖造成的 hang）
+- Swift toolchain（Xcode CLT 內建；用 `#!/usr/bin/env swift` shebang，第一次跑會 compile cache）
+
+## bin/codex-call
+
+Swift script wrapper，取代原本的 `codex exec --full-auto`。設計目的：
+
+| 問題 | `codex exec` | `codex-call` (Swift) |
+|------|-------------|---------------------|
+| Subprocess hang | 偶發 | ✗ 純 URLSession，無 subprocess |
+| Hard timeout | 不可靠 | ✓ URLSession + DispatchSemaphore wait timeout |
+| OAuth refresh | CLI 自動 | 自帶 refresh + flock 防 race |
+| 計費 | ChatGPT 訂閱 | ChatGPT 訂閱（同一條 OAuth）|
+| service_tier=fast | CLI 接受（內部翻譯成 priority）| **接受 `fast`/`priority`/`flex`**，內部翻譯與 codex CLI 一致 |
+| Cold start | ~50ms (subprocess) | ~1.5s（swift compile + cache）|
+| 依賴 | `codex` CLI 安裝 | macOS 內建 swift（Xcode CLT）|
+
+範例：
+
+```bash
+codex-call \
+  --output result.md \
+  --model gpt-5.5 \
+  --effort xhigh \
+  --max-time 600 \
+  --instructions "你是嚴謹 reviewer。" \
+  --prompt-file prompt.txt
+```
+
+或 stdin：
+
+```bash
+echo "..." | codex-call --output out.md --model gpt-5.5 --effort xhigh
+```
+
+Wrapper 在 plugin 安裝時自動加入 PATH（透過 `bin/`），所以直接呼叫名字即可，不需要絕對路徑。
+
+### 為什麼 Swift script 不是 Python
+
+Python 在 macOS 上版本飄移：`/usr/bin/python3` 是 stub（要 Xcode CLT 才有真 binary）；版本可能是 3.9 / 3.10 / 3.11 / 3.13，新語法（如 `dict | None`）需 3.10+ 不一定可用。Swift script 用 Xcode CLT 內建的 swift 5+，shebang 直接跑，無版本兼容問題。
+
+不走 Swift binary（che-mcps notarize 模式）的理由：這 wrapper 不需 TCC 權限（只發 HTTPS），開新 repo + notarize 流程過度工程化。Swift script 的 1-2s cold start 對 ensemble 場景（5-15s LLM response 為主）是可接受的雜訊。
+
+## Development
+
+- 測試：`claude --plugin-dir ./plugins/parallel-ai-agents`
+- 更新：`/plugin-tools:plugin-update parallel-ai-agents`
diff --git a/plugins/parallel-ai-agents/bin/codex-call b/plugins/parallel-ai-agents/bin/codex-call
new file mode 100755
index 00000000..4a8231e0
--- /dev/null
+++ b/plugins/parallel-ai-agents/bin/codex-call
@@ -0,0 +1,386 @@
+#!/usr/bin/env swift
+
+// codex-call — direct HTTP wrapper for chatgpt.com/backend-api
+//
+// Replaces `codex exec --full-auto -o output "prompt"` with a clean HTTP call
+// that bypasses the codex CLI subprocess (which can hang on stdin/stdout pipes).
+//
+// Usage:
+//   codex-call --output FILE [--model gpt-5.5] [--effort xhigh]
+//              [--service-tier ""] [--max-time 600]
+//              [--instructions TEXT] [--prompt-file FILE | PROMPT]
+//
+// Reads OAuth token from ~/.codex/auth.json (codex CLI's token store).
+// Auto-refreshes access_token if within 5 min of expiry. Refresh uses a file
+// lock to prevent concurrent races during parallel ensemble runs.
+
+import Foundation
+#if canImport(Darwin)
+import Darwin
+#endif
+
+// MARK: - Configuration
+
+let HOME_DIR = FileManager.default.homeDirectoryForCurrentUser
+let AUTH_FILE = HOME_DIR.appendingPathComponent(".codex/auth.json").path
+let LOCK_FILE = HOME_DIR.appendingPathComponent(".codex/.token-refresh.lock").path
+let TOKEN_URL = URL(string: "https://auth.openai.com/oauth/token")!
+let CODEX_URL = URL(string: "https://chatgpt.com/backend-api/codex/responses")!
+let CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+let REFRESH_THRESHOLD_SEC: Int = 300
+
+// MARK: - Helpers
+
+func die(_ msg: String, code: Int32 = 1) -> Never {
+    FileHandle.standardError.write(Data("error: \(msg)\n".utf8))
+    exit(code)
+}
+
+func log(_ msg: String) {
+    FileHandle.standardError.write(Data("[codex-call] \(msg)\n".utf8))
+}
+
+// MARK: - JWT exp
+
+func jwtExp(_ token: String) -> Int {
+    let parts = token.split(separator: ".")
+    guard parts.count >= 2 else { return 0 }
+    var payload = String(parts[1])
+        .replacingOccurrences(of: "-", with: "+")
+        .replacingOccurrences(of: "_", with: "/")
+    while payload.count % 4 != 0 { payload += "=" }
+    guard let data = Data(base64Encoded: payload),
+          let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+          let exp = json["exp"] as? Int
+    else { return 0 }
+    return exp
+}
+
+// MARK: - Auth file
+
+func loadAuthRaw() throws -> [String: Any] {
+    let data = try Data(contentsOf: URL(fileURLWithPath: AUTH_FILE))
+    guard let obj = try JSONSerialization.jsonObject(with: data) as? [String: Any]
+    else { throw NSError(domain: "codex-call", code: 1,
+                         userInfo: [NSLocalizedDescriptionKey: "auth.json is not an object"]) }
+    return obj
+}
+
+func saveAuthRaw(_ auth: [String: Any]) throws {
+    let data = try JSONSerialization.data(withJSONObject: auth, options: [.prettyPrinted, .sortedKeys])
+    let tmp = AUTH_FILE + ".tmp"
+    try data.write(to: URL(fileURLWithPath: tmp), options: .atomic)
+    _ = chmod(tmp, 0o600)
+    if rename(tmp, AUTH_FILE) != 0 {
+        throw NSError(domain: "codex-call", code: 2,
+                      userInfo: [NSLocalizedDescriptionKey: "rename failed: \(String(cString: strerror(errno)))"])
+    }
+}
+
+// MARK: - OAuth refresh
+
+func httpFormPost(url: URL, fields: [String: String], timeout: TimeInterval = 30) throws -> Data {
+    var req = URLRequest(url: url, timeoutInterval: timeout)
+    req.httpMethod = "POST"
+    req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
+    let body = fields.map { (k, v) in
+        let ek = k.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? k
+        let ev = v.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? v
+        return "\(ek)=\(ev)"
+    }.joined(separator: "&")
+    req.httpBody = body.data(using: .utf8)
+
+    let sem = DispatchSemaphore(value: 0)
+    var result: Data?
+    var error: Error?
+    var status: Int = 0
+    URLSession.shared.dataTask(with: req) { data, resp, err in
+        status = (resp as? HTTPURLResponse)?.statusCode ?? 0
+        result = data
+        error = err
+        sem.signal()
+    }.resume()
+    sem.wait()
+
+    if let err = error { throw err }
+    guard status == 200, let data = result else {
+        let body = result.flatMap { String(data: $0, encoding: .utf8) } ?? "(no body)"
+        throw NSError(domain: "codex-call", code: status,
+                      userInfo: [NSLocalizedDescriptionKey: "HTTP \(status): \(body.prefix(500))"])
+    }
+    return data
+}
+
+func refreshIfNeeded(_ auth: inout [String: Any]) throws {
+    guard var tokens = auth["tokens"] as? [String: Any],
+          let access = tokens["access_token"] as? String,
+          let refresh = tokens["refresh_token"] as? String
+    else { throw NSError(domain: "codex-call", code: 3,
+                          userInfo: [NSLocalizedDescriptionKey: "auth.json missing tokens.access_token/refresh_token"]) }
+
+    let now = Int(Date().timeIntervalSince1970)
+    if jwtExp(access) - now > REFRESH_THRESHOLD_SEC { return }
+
+    // file lock
+    try FileManager.default.createDirectory(
+        at: URL(fileURLWithPath: LOCK_FILE).deletingLastPathComponent(),
+        withIntermediateDirectories: true)
+    let fd = open(LOCK_FILE, O_CREAT | O_WRONLY, 0o600)
+    if fd < 0 {
+        throw NSError(domain: "codex-call", code: 4,
+                      userInfo: [NSLocalizedDescriptionKey: "open lock failed: \(String(cString: strerror(errno)))"])
+    }
+    defer { close(fd) }
+    if flock(fd, LOCK_EX) != 0 {
+        throw NSError(domain: "codex-call", code: 5,
+                      userInfo: [NSLocalizedDescriptionKey: "flock failed: \(String(cString: strerror(errno)))"])
+    }
+    defer { _ = flock(fd, LOCK_UN) }
+
+    // Re-read after acquiring lock — another process may have refreshed
+    auth = try loadAuthRaw()
+    if let t = auth["tokens"] as? [String: Any],
+       let a = t["access_token"] as? String,
+       jwtExp(a) - now > REFRESH_THRESHOLD_SEC {
+        return
+    }
+    tokens = auth["tokens"] as? [String: Any] ?? tokens
+
+    let respData = try httpFormPost(url: TOKEN_URL, fields: [
+        "grant_type": "refresh_token",
+        "refresh_token": refresh,
+        "client_id": CLIENT_ID,
+    ])
+    guard let json = try JSONSerialization.jsonObject(with: respData) as? [String: Any],
+          let newAccess = json["access_token"] as? String
+    else { throw NSError(domain: "codex-call", code: 6,
+                          userInfo: [NSLocalizedDescriptionKey: "refresh response missing access_token"]) }
+
+    tokens["access_token"] = newAccess
+    if let newRefresh = json["refresh_token"] as? String { tokens["refresh_token"] = newRefresh }
+    if let newId = json["id_token"] as? String { tokens["id_token"] = newId }
+    auth["tokens"] = tokens
+
+    let fmt = ISO8601DateFormatter()
+    fmt.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+    auth["last_refresh"] = fmt.string(from: Date())
+
+    try saveAuthRaw(auth)
+    log("token refreshed")
+}
+
+// MARK: - SSE streaming
+
+final class StreamCollector: NSObject, URLSessionDataDelegate {
+    var accumulated = ""
+    var buffer = ""
+    var statusCode: Int = 0
+    var streamError: Error?
+    let done = DispatchSemaphore(value: 0)
+    var firstBytes: Data?
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask,
+                    didReceive response: URLResponse,
+                    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void) {
+        statusCode = (response as? HTTPURLResponse)?.statusCode ?? 0
+        completionHandler(.allow)
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        if statusCode != 200 {
+            // Buffer error body for reporting
+            firstBytes = (firstBytes ?? Data()) + data
+            return
+        }
+        guard let chunk = String(data: data, encoding: .utf8) else { return }
+        buffer += chunk
+        while let range = buffer.range(of: "\n\n") {
+            let event = String(buffer[buffer.startIndex..<range.lowerBound])
+            buffer.removeSubrange(buffer.startIndex..<range.upperBound)
+            processEvent(event)
+            if streamError != nil { return }
+        }
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        if statusCode != 200 {
+            let body = firstBytes.flatMap { String(data: $0, encoding: .utf8) } ?? "(no body)"
+            streamError = NSError(domain: "codex-call", code: statusCode,
+                                  userInfo: [NSLocalizedDescriptionKey: "HTTP \(statusCode): \(body.prefix(500))"])
+        } else if let err = error, streamError == nil {
+            streamError = err
+        }
+        done.signal()
+    }
+
+    func processEvent(_ event: String) {
+        let dataLines = event.split(separator: "\n", omittingEmptySubsequences: false)
+            .compactMap { line -> String? in
+                guard line.hasPrefix("data:") else { return nil }
+                return String(line.dropFirst(5)).trimmingCharacters(in: .whitespaces.subtracting(.newlines))
+            }
+        let payload = dataLines.joined()
+        if payload.isEmpty || payload == "[DONE]" { return }
+        guard let data = payload.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let type = json["type"] as? String
+        else { return }
+
+        switch type {
+        case "response.output_text.delta":
+            if let delta = json["delta"] as? String { accumulated += delta }
+        case "error", "response.failed":
+            let msg = (json["message"] as? String)
+                ?? ((json["response"] as? [String: Any])?["error"] as? [String: Any])?["message"] as? String
+                ?? "Codex error"
+            streamError = NSError(domain: "codex-call", code: -1,
+                                   userInfo: [NSLocalizedDescriptionKey: msg])
+        default:
+            break
+        }
+    }
+}
+
+func streamCodex(prompt: String, outputFile: String, model: String, effort: String,
+                 serviceTier: String, maxTime: Int, instructions: String) throws {
+    var auth = try loadAuthRaw()
+    try refreshIfNeeded(&auth)
+    guard let tokens = auth["tokens"] as? [String: Any],
+          let access = tokens["access_token"] as? String
+    else { throw NSError(domain: "codex-call", code: 7,
+                          userInfo: [NSLocalizedDescriptionKey: "post-refresh: tokens missing"]) }
+    let accountId = (tokens["account_id"] as? String) ?? ""
+
+    var body: [String: Any] = [
+        "model": model,
+        "store": false,
+        "stream": true,
+        "instructions": instructions,
+        "input": [["role": "user", "content": [["type": "input_text", "text": prompt]]]],
+        "text": ["verbosity": "medium"],
+        "include": ["reasoning.encrypted_content"],
+        "tool_choice": "auto",
+        "parallel_tool_calls": true,
+        "reasoning": ["effort": effort, "summary": "auto"],
+    ]
+    // Translate legacy/friendly names to backend wire values.
+    // Mirrors codex-rs ServiceTier::request_value(): Fast→priority, Flex→flex.
+    // Backend rejects "fast" with HTTP 400; codex CLI does this translation internally.
+    let wireTier: String = {
+        switch serviceTier.lowercased() {
+        case "fast", "priority": return "priority"
+        case "flex":             return "flex"
+        case "":                 return ""
+        default:                 return serviceTier  // pass through unknown values
+        }
+    }()
+    if !wireTier.isEmpty { body["service_tier"] = wireTier }
+
+    var req = URLRequest(url: CODEX_URL, timeoutInterval: TimeInterval(maxTime))
+    req.httpMethod = "POST"
+    req.setValue("Bearer \(access)", forHTTPHeaderField: "Authorization")
+    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+    req.setValue("responses=experimental", forHTTPHeaderField: "OpenAI-Beta")
+    req.setValue("codex_cli_rs", forHTTPHeaderField: "originator")
+    req.setValue(accountId, forHTTPHeaderField: "chatgpt-account-id")
+    req.setValue("text/event-stream", forHTTPHeaderField: "Accept")
+    req.httpBody = try JSONSerialization.data(withJSONObject: body)
+
+    let collector = StreamCollector()
+    let config = URLSessionConfiguration.default
+    config.timeoutIntervalForRequest = TimeInterval(maxTime)
+    config.timeoutIntervalForResource = TimeInterval(maxTime)
+    let session = URLSession(configuration: config, delegate: collector, delegateQueue: nil)
+
+    session.dataTask(with: req).resume()
+    let waitResult = collector.done.wait(timeout: .now() + .seconds(maxTime + 5))
+    session.invalidateAndCancel()
+
+    if waitResult == .timedOut {
+        throw NSError(domain: "codex-call", code: 408,
+                      userInfo: [NSLocalizedDescriptionKey: "Hard timeout after \(maxTime)s"])
+    }
+    if let err = collector.streamError { throw err }
+
+    try collector.accumulated.write(toFile: outputFile, atomically: true, encoding: .utf8)
+    log("wrote \(collector.accumulated.count) chars to \(outputFile)")
+}
+
+// MARK: - Argument parsing
+
+struct Args {
+    var output: String?
+    var model: String = "gpt-5.5"
+    var effort: String = "xhigh"
+    var serviceTier: String = ""
+    var maxTime: Int = 600
+    var instructions: String = "You are a careful, rigorous reviewer. Respond in the user's language."
+    var promptFile: String?
+    var prompt: String?
+}
+
+func parseArgs() -> Args {
+    var a = Args()
+    var args = Array(CommandLine.arguments.dropFirst())
+    while !args.isEmpty {
+        let head = args.removeFirst()
+        func next() -> String {
+            guard !args.isEmpty else { die("missing value for \(head)") }
+            return args.removeFirst()
+        }
+        switch head {
+        case "--output", "-o": a.output = next()
+        case "--model": a.model = next()
+        case "--effort": a.effort = next()
+        case "--service-tier": a.serviceTier = next()
+        case "--max-time": a.maxTime = Int(next()) ?? a.maxTime
+        case "--instructions": a.instructions = next()
+        case "--prompt-file": a.promptFile = next()
+        case "--help", "-h":
+            print("""
+            codex-call — direct HTTP wrapper for chatgpt.com/backend-api
+
+            Usage:
+              codex-call --output FILE [--model gpt-5.5] [--effort xhigh]
+                         [--service-tier ""] [--max-time 600]
+                         [--instructions TEXT]
+                         [--prompt-file FILE | PROMPT]
+
+            If no PROMPT and no --prompt-file is given, reads prompt from stdin.
+
+            Auth: reads ~/.codex/auth.json (auto-refreshes if expired).
+            """)
+            exit(0)
+        default:
+            if a.prompt == nil { a.prompt = head }
+            else { die("unexpected positional argument: \(head)") }
+        }
+    }
+    return a
+}
+
+// MARK: - Main
+
+let a = parseArgs()
+guard let output = a.output else { die("--output is required") }
+
+let prompt: String
+if let pf = a.promptFile {
+    do { prompt = try String(contentsOfFile: pf, encoding: .utf8) }
+    catch { die("cannot read prompt file: \(error.localizedDescription)") }
+} else if let p = a.prompt {
+    prompt = p
+} else {
+    let stdinData = FileHandle.standardInput.readDataToEndOfFile()
+    prompt = String(data: stdinData, encoding: .utf8) ?? ""
+}
+if prompt.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+    die("empty prompt")
+}
+
+do {
+    try streamCodex(prompt: prompt, outputFile: output, model: a.model, effort: a.effort,
+                    serviceTier: a.serviceTier, maxTime: a.maxTime, instructions: a.instructions)
+} catch {
+    die(error.localizedDescription)
+}
diff --git a/plugins/parallel-ai-agents/skills/ensemble-academic-review/skill.md b/plugins/parallel-ai-agents/skills/ensemble-academic-review/skill.md
new file mode 100644
index 00000000..c7fb66bd
--- /dev/null
+++ b/plugins/parallel-ai-agents/skills/ensemble-academic-review/skill.md
@@ -0,0 +1,714 @@
+---
+name: ensemble-academic-review
+description: |
+  學術論文 ensemble 審閱：methodology、writing、reference verification、number-verification、devils-advocate。
+  用 che-zotero-mcp 驗證文獻真實性（抓幻覺文獻）、用 R/Python 重跑 ground-truth 抓幻覺數字，用 perspective-writer 審查寫作風格。
+  三種模式：independent（獨立單輪）、hybrid（DA 看前輪的單輪）、mix N（交替 N 輪）。
+  Use when: 碩博論文、期刊投稿、學術報告、計量／實證作業需要嚴格審閱。
+argument-hint: "FILE [--mode independent|hybrid|mix] [--rounds N] [--prior summary.md] [--focus 'topic'] [--no-numeric|--no-references]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - TeamCreate
+  - SendMessage
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - TaskGet
+  - AskUserQuestion
+  - Skill
+  - mcp__plugin_che-zotero-mcp_zotero__zotero_search
+  - mcp__plugin_che-zotero-mcp_zotero__zotero_search_by_doi
+  - mcp__plugin_che-zotero-mcp_zotero__academic_search
+  - mcp__plugin_che-zotero-mcp_zotero__academic_lookup_doi
+  - mcp__plugin_che-zotero-mcp_zotero__academic_get_references
+  - mcp__plugin_che-zotero-mcp_zotero__academic_get_citations
+---
+
+# /ensemble-academic-review — 學術論文 Ensemble 審閱
+
+5 個 Claude teammates（學術審閱角色）+ 1 個 Codex（gpt-5.5）各自獨立審閱，合成比較表找共識和盲點。
+
+> **原理同 Ensemble OCR**：不同角色的錯誤模式不重疊。5 個 Claude 以不同學術審閱角度審閱且互相挑戰，Codex 提供跨模型盲驗。
+
+## 五個 reviewer 角色
+
+| 角色 | 任務 | 預設啟用 |
+|------|------|---------|
+| **methodology** | 研究設計、統計方法、推論邏輯 | ✅ 永遠 |
+| **writing** | 論述結構、學術語氣、APA、文法 | ✅ 永遠 |
+| **reference-verifier** | 用 zotero-mcp 逐一驗證引用文獻，抓幻覺文獻 | ✅ doc 內偵測到 References / Bibliography 區塊；可 `--no-references` 關閉 |
+| **number-verifier** | 用 R/Python 重跑原始計算 artifact，逐位驗證 doc 中每個數字 vs ground truth，抓幻覺數字 | ✅ 偵測到 `analysis/`、`data/`、`notebooks/`、`.ipynb`、`.Rmd` 或 doc 路徑旁有 `*.rds` / `*.csv`；可 `--no-numeric` 關閉 |
+| **devils-advocate** | 對抗性驗證；hybrid 輪看所有前輪結果，挑戰其他 reviewer 的 PASS/LOW 判決 | ✅ 永遠 |
+
+**何時可關掉 reference-verifier**：純技術筆記、計量作業、無學術引用之文件 → `--no-references`
+**何時可關掉 number-verifier**：純理論論文、無實證計算結果之文件 → `--no-numeric`
+
+兩者皆關 = 退化為 3 reviewer + Codex（保留核心 4 角色 + Codex）。
+
+## 四種模式
+
+| 模式 | 說明 | 適用情境 |
+|------|------|---------|
+| **independent**（預設） | 所有審閱者從零開始，不知道前輪結果 | 第一輪審閱、或想要完全獨立的第二意見 |
+| **hybrid** | 3 reviewer + Codex 獨立審閱，**只有 devil's advocate 看得到前輪結果** | 在前一輪基礎上挖更深，同時避免 anchoring bias |
+| **mix N** | 自動交替 independent → hybrid → independent → hybrid... 共 N 輪 | 最完整的審閱，每輪都是完整 ensemble，用 tasks 追蹤進度 |
+| **`--auto-iterate`**(v2.3.0+,#34) | round → fix → round 自治收斂迴圈,直到 Codex 標 `<verdict>PERMANENT_CONVERGENCE</verdict>` 或 `--max-rounds` 到上限 | 反覆審閱 + 修正直至 reviewer 全綠;適用稿件最終 polish |
+
+### mix N 的運作邏輯
+
+```
+mix 4 thesis.md
+│
+├── Round 1: independent — 全新獨立審閱
+│   → 產出 review-round-1.md
+│
+├── Round 2: hybrid — DA 看到 Round 1 結果，找盲點
+│   → 產出 review-round-2.md（標記 🆕 新發現）
+│
+├── Round 3: independent — 再一次全新獨立（不看 Round 1-2）
+│   → 產出 review-round-3.md
+│
+├── Round 4: hybrid — DA 看到 Round 1-3 所有結果，找盲點
+│   → 產出 review-round-4.md（標記 🆕 新發現）
+│
+└── Final: 合併所有輪次 → review-summary.md
+    - 跨輪共識（多輪都指出）
+    - 每輪獨有的新發現
+    - 收斂趨勢（第 N 輪新發現數量遞減 = 審閱飽和）
+```
+
+**為什麼交替？**
+- independent 輪：不受前輪汙染，能從完全不同的角度發現新問題，也能驗證/修正前輪結論
+- hybrid 輪：devil's advocate 帶著所有前輪知識，專門挖前面所有輪次都沒發現的盲點
+- 交替進行：每一輪都有獨立發現的機會，也有針對性深挖的機會
+
+### hybrid 模式的資訊分配
+
+| 角色 | 看到什麼 | 為什麼 |
+|------|---------|--------|
+| methodology | 什麼都不看 | 避免 anchoring，獨立發現新問題 |
+| writing | 什麼都不看 | 同上 |
+| Codex | 什麼都不看 | 跨模型盲驗必須獨立 |
+| reference-verifier | 前輪的可疑文獻 watch list | 重點檢查 + 獨立全面查核 |
+| number-verifier | 什麼都不看（每輪都要從 ground-truth 重跑）| 防止前輪錯數抄來抄去 |
+| **devil's advocate** | **所有前輪的完整結果** | 專攻盲點、升/降級前輪判斷 |
+
+## 審閱架構
+
+```
+/ensemble-academic-review FILE [--mode independent|hybrid|mix] [--rounds N] [--no-numeric|--no-references] [--auto-iterate [--max-rounds N] [--converge-on VERDICT]]
+│
+├── Claude Team（最多 5 teammates）
+│   ├── methodology — 研究設計、統計方法（永遠獨立）
+│   ├── writing — 論述結構、學術語氣、APA（永遠獨立）
+│   ├── reference-verifier — 逐一查文獻（hybrid 時收到 watch list）— 可關
+│   ├── number-verifier — 逐一驗證數字 vs 原始計算 artifact（永遠獨立）— 可關
+│   └── devils-advocate — 反駁（hybrid 時看得到所有前輪結果）
+│
+└── Codex（gpt-5.5，永遠獨立）
+
+→ 每輪產出獨立的 review-round-{N}.md
+→ mix 模式最後合併所有輪次 → review-summary.md
+```
+
+## 執行流程
+
+### Phase 0: 解析輸入
+
+```
+Arguments:
+  FILE — 要審閱的學術論文檔案（.md, .tex, .docx, .pdf, .ipynb, .Rmd）
+  --mode — independent（預設）、hybrid、mix
+  --rounds — mix 模式的輪數（預設 2）
+  --prior — hybrid 模式的前輪摘要檔案（mix 模式自動管理）
+  --focus — 審閱重點（可選）
+  --no-numeric — 關閉 number-verifier（純理論論文、無實證計算）
+  --no-references — 關閉 reference-verifier（純技術筆記、無學術引用）
+  --auto-iterate — v2.3.0+,啟動自治 round → fix → round 收斂迴圈(見下方 § auto-iterate 模式)
+  --max-rounds N — `--auto-iterate` 的上限,default 12,clamp [1, 30]
+  --converge-on VERDICT — `--auto-iterate` 的停止條件,default `PERMANENT_CONVERGENCE`,
+                           其他可選: `CONVERGED` (寬鬆 — 任一輪 Codex 給就停)
+
+如果沒有 FILE，問使用者。
+如果 --mode hybrid 但沒有 --prior，自動搜尋同目錄下的 review-round-*.md。
+如果是 .docx，用 che-word-mcp 的 get_document_text 讀取。
+如果是 .pdf，用 macdoc convert --to md 轉換後讀取。
+
+#### Auto-detect reviewer 啟用
+
+掃 FILE 同層及上層 1-2 級目錄：
+- 找到 `analysis/*.rds`、`data/*.csv`、`*.ipynb`、`output/*.npz`、`scripts/*.{R,py}` → number-verifier ON
+- doc 內含 `\bibliography{}`、`References` / `参考文献` 標題下 5+ 條引用 → reference-verifier ON
+- 兩者都沒：fallback 到 methodology+writing+devils-advocate（3 reviewer + Codex）
+
+使用者可用 `--no-numeric` / `--no-references` 強制關閉。
+```
+
+### Phase 0.5: Mix 模式的 Task 建立（僅 mix 模式）
+
+用 TaskCreate 建立所有輪次的 tasks，作為進度追蹤：
+
+```
+TaskCreate: "Round 1/N: independent review"
+TaskCreate: "Round 2/N: hybrid review"
+TaskCreate: "Round 3/N: independent review"
+...
+TaskCreate: "Final: merge all rounds"
+```
+
+每完成一輪就 TaskUpdate 為 completed，然後開始下一輪。
+**每一輪都是完整的 Phase 1-4 流程，不可偷工減料。**
+
+### Phase 1: 讀取文件 + 準備 context
+
+1. 讀取論文全文
+2. 提取所有引用文獻（References / Bibliography 區塊）
+3. 準備 context 字串，包含：檔案路徑、全文內容、文獻列表、ground-truth artifact 清單、focus 指示
+4. （hybrid 模式）讀取前輪結果，提取：
+   - `prior_ref_issues` — 可疑/幻覺文獻清單（給 reference-verifier）
+   - `prior_number_issues` — 可疑/幻覺數字清單（給 number-verifier）
+   - `prior_full_report` — 所有前輪的完整結果（只給 devil's advocate）
+
+### Phase 2: 平行啟動 Claude Team + Codex
+
+**CRITICAL: 所有 tool calls（TeamCreate + Codex Bash）必須在同一個 message 送出。不可分步驟。**
+
+**啟用的 reviewer 數依設定變動**：預設 5（含 number+reference verifier），加 `--no-numeric` 變 4，再加 `--no-references` 變 3。Codex 永遠跑。一個 message 內 = (啟用 reviewer 數) Agent + 1 Bash。
+
+**CRITICAL: Teammates 必須用 `subagent_type: "general-purpose"`。不可用 `Explore`。**
+
+#### 2a. Claude Team（4 reviewers）
+
+用 TeamCreate 建立 team，然後在**同一個 message** 啟動 4 個 Agent + 1 個 Codex Bash（共 5 個 tool calls）：
+
+```
+TeamCreate:
+  name: "academic-review-{timestamp}-round{N}"
+  description: "Academic review round {N} for {FILE}"
+```
+
+**Agent 1: methodology**
+```
+Agent:
+  name: "methodology"
+  subagent_type: "general-purpose"
+  team_name: "academic-review-{timestamp}-round{N}"
+  prompt: |
+    你是 Methodology Reviewer，專門審閱學術研究方法。
+    審閱論文：{FILE}
+    {context}
+
+    你的任務：
+    1. 研究設計是否合理（實驗設計、對照組、隨機化）
+    2. 統計方法是否正確（假設檢定、效果量、信賴區間）
+    3. 樣本量是否足夠（power analysis）
+    4. 推論邏輯是否成立（因果 vs 相關、過度推論）
+    5. 研究限制是否充分討論
+    6. 分析流程是否可重現
+
+    {focus_instruction}
+
+    用 Read 工具讀取論文相關段落確認。
+    用中文逐點列出問題和建議。每個問題標注嚴重性（HIGH/MEDIUM/LOW）。
+    最後給整體評價（一段話）。
+```
+
+**Agent 2: writing**
+```
+Agent:
+  name: "writing"
+  subagent_type: "general-purpose"
+  team_name: "academic-review-{timestamp}-round{N}"
+  prompt: |
+    你是 Writing Quality Reviewer，專門審閱學術寫作品質。
+    審閱論文：{FILE}
+    {context}
+
+    你的任務：
+    1. 論述邏輯 — 各章節之間的銜接是否流暢
+    2. 段落結構 — 每段是否有明確的 topic sentence 和 supporting evidence
+    3. 學術語氣 — 是否適當使用 hedging language，避免過度武斷
+    4. APA 格式 — 引用格式、標題層級、圖表標註是否符合規範
+    5. 文法與用詞 — 英文文法錯誤、用詞精確度、一致性
+    6. Abstract 品質 — 是否完整涵蓋 background、method、results、conclusion
+
+    你可以使用 Skill tool 呼叫 perspective-writer 來分析特定段落的寫作風格。
+
+    {focus_instruction}
+
+    用中文逐點列出問題和建議。每個問題標注嚴重性（HIGH/MEDIUM/LOW）。
+    引用具體段落或句子作為例證。
+    最後給整體評價（一段話）。
+```
+
+**Agent 3: reference-verifier**
+```
+Agent:
+  name: "reference-verifier"
+  subagent_type: "general-purpose"
+  team_name: "academic-review-{timestamp}-round{N}"
+  prompt: |
+    你是 Reference Verifier，專門驗證學術文獻的真實性。
+    審閱論文：{FILE}
+    {context}
+
+    你的核心任務：**偵測幻覺文獻**（hallucinated references）。
+
+    {hybrid_mode_ref_verifier_instruction}
+
+    步驟：
+    1. 從論文中提取所有引用文獻（作者、年份、標題、期刊）
+    2. 對每一筆文獻，使用 che-zotero-mcp 工具驗證：
+       - 用 `academic_search` 搜尋標題或作者+年份
+       - 如果有 DOI，用 `academic_lookup_doi` 驗證
+       - 用 `zotero_search` 檢查是否已在 Zotero 資料庫中
+    3. 分類每筆文獻：
+       - ✅ 已驗證（找到匹配的真實文獻）
+       - ⚠️ 存疑（部分匹配，可能是資訊不完整）
+       - ❌ 疑似幻覺（完全找不到，或作者/標題/年份不匹配）
+    4. 檢查 in-text citation 與 reference list 是否一致（有沒有引了但沒列、或列了但沒引）
+
+    輸出格式：
+    ```
+    ## 文獻驗證結果
+
+    ### 已驗證 ✅
+    1. Author (Year). Title. — DOI: xxx ✅
+
+    ### 存疑 ⚠️
+    1. Author (Year). Title. — 原因：找到類似文獻但年份不同
+
+    ### 疑似幻覺 ❌
+    1. Author (Year). Title. — 原因：完全查無此文獻
+
+    ### 引用一致性
+    - 引了但沒列在 references：...
+    - 列在 references 但文中未引用：...
+    ```
+
+    每筆文獻都要查。不可跳過。
+    用中文輸出結果。
+```
+
+**Agent 4: number-verifier**（如未 `--no-numeric`）
+```
+Agent:
+  name: "number-verifier"
+  subagent_type: "general-purpose"
+  team_name: "academic-review-{timestamp}-round{N}"
+  prompt: |
+    你是 Number Verifier，專門驗證學術／實證文件中每一個數字 vs ground truth artifact。
+    審閱論文：{FILE}
+    {context}
+
+    你的核心任務：**偵測幻覺數字**（hallucinated numbers）— tex/docx/md 中與原始計算不符的數值。
+
+    {hybrid_mode_number_verifier_instruction}
+
+    步驟：
+    1. 識別 ground-truth 來源：
+       - R 專案：`analysis/*.rds`、`*.RData`、`*.R` 腳本
+       - Python 專案：`*.npz`、`*.csv`、`*.ipynb`、`*.py`
+       - Excel/csv 原始資料：`*.xlsx`、`*.csv`
+    2. 從 doc 中提取每個數值（test stat、coef、p-value、AIC/BIC、forecast、平均、sd、t-stat、F、χ²、CI 等）
+    3. 對每個數字，找對應 ground-truth：
+       - 直接讀 .rds：`Rscript -e 'x <- readRDS("..."); print(x$path$to$value)'`
+       - 直接讀 .npz：`python -c 'import numpy as np; print(np.load("...")["k"])'`
+       - 重跑腳本：`Rscript analysis/q1.R` 或 `python scripts/main.py`
+       - 從原始資料重算：必要時自己跑 ADF / ARIMA / VAR / OLS
+    4. 分類每個數字：
+       - ✅ 已驗證（與 ground truth 完全相符）
+       - ⚠️ rounding（最後一位 ±1 可接受）
+       - ❌ 幻覺數字（差量超過 rounding 容差）
+    5. 跨檔一致性：若有多版本（EN tex、ZH tex、DOCX），每個數字三檔一致嗎？
+    6. 內部一致性：tex 表格中的 forecast 是否真的等於 last_obs + cumulative diff？
+
+    輸出格式：
+    ```
+    ## 數字驗證結果
+
+    ### ✅ 已驗證
+    - ARIMA(1,1,0) coef 0.5564 — matches q1c.rds$fit$coef ✅
+
+    ### ⚠️ rounding 偏差（last digit ±1）
+    - log s_q[1] = -0.04723 vs rds -0.04724 (rounding) ⚠️
+
+    ### ❌ 幻覺數字（必修）
+    - tex line 52 寫 y_T=890569 — 實際 RGDPCAN.xlsx 末值 836072 ❌
+    - tex line 200 寫 1-step σ̂=0.0207 — 實際 fc_se=0.0181（標籤錯）❌
+
+    ### 三檔一致性（EN tex / ZH tex / DOCX）
+    - 13 個 spot-check 全綠 ✅
+    - 或：EN/ZH 一致但 DOCX 不同步 ❌
+    ```
+
+    每個出現在 tex 中的數字都要查。不可只抽樣。
+    HIGH count = 幻覺數字總數。MEDIUM = rounding-only。
+    用中文輸出結果，最後給一段 verdict。
+```
+
+**Agent 5: devils-advocate**
+```
+Agent:
+  name: "devils-advocate"
+  subagent_type: "general-purpose"
+  team_name: "academic-review-{timestamp}-round{N}"
+  prompt: |
+    你是 Devil's Advocate，學術審閱的對抗性驗證者。
+    審閱論文：{FILE}
+    {context}
+
+    你的任務：等其他 3 個 reviewer（methodology、writing、reference-verifier）完成後，
+    用 SendMessage 詢問他們的結論，然後**試著反駁每一個「通過」或「LOW」的判斷**。
+
+    {hybrid_mode_devils_advocate_instruction}
+
+    步驟：
+    1. 先用 Read 工具讀取論文，形成自己的理解
+    2. 用 SendMessage 分別問 methodology、writing、reference-verifier 他們的 findings
+    3. 對每個「通過」的判斷，找理由說它其實有問題
+    4. 對每個「LOW」的判斷，論證為什麼應該是 MEDIUM 或 HIGH
+    5. 特別挑戰：
+       - methodology 說統計方法 OK → 找 alternative interpretation
+       - writing 說邏輯清晰 → 找隱含的邏輯跳躍
+       - reference-verifier 說文獻 OK → 質疑文獻的相關性和時效性
+    6. 如果你找不到反駁的理由，才承認確實通過
+
+    這是對抗性驗證 — 你的存在是為了防止群體盲點。
+    用中文輸出你的反駁結果。
+```
+
+#### Mode-specific prompt injections
+
+以下變數在 independent 輪為空字串，在 hybrid 輪注入內容：
+
+**`{hybrid_mode_ref_verifier_instruction}`** — 給 reference-verifier：
+```
+（hybrid 輪時注入）
+前幾輪審閱標記了以下可疑文獻，請特別留意：
+{prior_ref_issues}
+但你的核心任務仍然是逐一查核所有文獻，不要只看這份清單。
+前輪的判斷可能有誤，你需要獨立驗證。
+```
+
+**`{hybrid_mode_number_verifier_instruction}`** — 給 number-verifier：
+```
+（hybrid 輪時注入）
+注意：本作業已跑過至少一輪驗證；前輪 number-verifier 標記過的可疑數字：
+{prior_number_issues}
+但你的核心任務仍是逐一從 ground truth 重跑驗證所有數字，**不要只看這份清單**。
+前輪可能漏掉新出現或剛修進去的數字（修正常引入新錯）。
+```
+
+**`{hybrid_mode_devils_advocate_instruction}`** — 給 devil's advocate：
+```
+（hybrid 輪時注入）
+## 所有前輪審閱結果
+
+以下是前面所有輪次的 ensemble 審閱結果：
+{prior_full_report}
+
+你的額外任務（除了反駁本輪 reviewer 的判斷之外）：
+1. **挑戰前輪「通過」的判斷** — 前輪認為 OK 或只給 LOW 的項目，是否有被低估的問題？
+2. **找出所有前輪的盲點** — 有什麼問題是前面所有輪次都沒想到的？
+3. **驗證前輪的結論** — 前輪的 HIGH 判斷是否真的那麼嚴重？有沒有過度反應的？
+4. **不要重複已知問題** — 前輪已經充分討論的問題不需要重新論述，除非你有新的反駁角度
+
+在輸出中，明確區分：
+- 「前輪已知 + 本輪確認」的問題
+- 「前輪已知但需要升級/降級」的問題
+- 「前輪完全未發現」的新問題 🆕
+```
+
+#### 2b. Codex（背景執行 — 直接 HTTP，繞過 codex CLI subprocess）
+
+```bash
+codex-call \
+  --output "{output_file}" \
+  --model gpt-5.5 \
+  --effort xhigh \
+  --service-tier fast \
+  --max-time 900 \
+  --instructions "你是嚴謹的學術論文審閱者，從 methodology、writing、reference 三個角度審閱。用中文輸出。" << 'EOF'
+{codex_prompt}
+EOF
+```
+
+> **為什麼不用 `codex exec`**：subprocess 偶爾會 hang（stdin/stdout pipe 互鎖、tty 問題），等 10 分鐘 timeout 才能繼續。`codex-call` 是 plugin 自帶 wrapper（`bin/codex-call`，Swift script，安裝時自動加入 PATH），直接 HTTP POST 到 `chatgpt.com/backend-api/codex/responses`，仍走你的 ChatGPT 訂閱 OAuth — 但 `--max-time` 是硬性保證，不會 hang。
+>
+> **論文審閱用 max-time 900s**（15 分鐘），因為輸入長、reasoning 比 code review 重。Fast mode：傳 `--service-tier fast`，wrapper 內部翻譯成 `priority`（backend 拒絕字面 "fast"，但接受 codex CLI 內部翻譯後的 `priority`）。
+>
+> **OAuth token**：wrapper 自動讀 `~/.codex/auth.json`（codex CLI 的同一份），到期前 5 分鐘自動 refresh，用 file lock 避免 ensemble 平行 race。
+
+Codex prompt 應包含：
+- 論文全文（或摘要 + 關鍵段落，視長度而定）
+- 要求從 methodology、writing、reference 三個角度審閱
+- 用中文回答
+- **不提及 Claude team 的存在**（確保獨立性）
+
+### Phase 3: 收集結果
+
+1. 等待 4 個 Claude teammates 完成（透過自動訊息通知）
+2. 等待 Codex 完成（輪詢 status）
+3. 如果 Codex 失敗或超時（>10 分鐘），跳過，標注「Codex 不可用」
+
+### Phase 4: 合併去重 + 寫入本輪結果
+
+由主 session 的 Claude 讀取所有結果，產出本輪比較表：
+
+1. **去重**：相同問題 → 合併，標註來源
+2. **severity 以最高為準**
+3. **Devil's Advocate 的反駁如果成立** → 升級 severity
+4. **幻覺文獻特別標示** — reference-verifier 的 ❌ 結果優先級最高
+
+#### hybrid 輪額外步驟
+
+5. **與前輪交叉比對**：將本輪發現分為三類：
+   - **前輪已知 + 本輪確認**：增加可信度
+   - **前輪已知但本輪修正**：前輪判斷不夠精確
+   - **本輪新發現 🆕**：前輪所有審閱者都未發現的問題
+
+#### 寫入本輪結果
+
+將本輪結果寫入 `review-round-{N}.md`（與論文同目錄），然後：
+- independent / hybrid 單輪模式：這就是最終輸出
+- mix 模式：TaskUpdate 標記本輪完成，繼續下一輪
+
+### Phase 5: Mix 模式的輪次循環
+
+```
+for round in 1..N:
+    if round is odd:
+        run Phase 1-4 as independent
+    else:
+        run Phase 1-4 as hybrid (prior = all previous rounds)
+    
+    TaskUpdate: "Round {round}/{N}" → completed
+    Write review-round-{round}.md
+
+TaskUpdate: "Final: merge all rounds" → in_progress
+```
+
+### Phase 5b: `--auto-iterate` 模式的自治收斂迴圈(v2.3.0+, #34)
+
+`--auto-iterate` 是 `mix N` 的擴展,加上「每輪結束讀 Codex verdict + 自動 apply HIGH-severity fix + 自動 commit per round」的 round → fix → round 收斂迴圈。
+
+#### 啟動條件
+
+- User 傳 `--auto-iterate` flag
+- 不可與 `--mode independent` 或 `--mode hybrid` 同時使用 (auto-iterate 自含 mode 邏輯,內部沿用 mix 的 alternating independent/hybrid pattern)
+
+#### 主迴圈
+
+```
+N=1
+verdict=NEEDS_ITER_1
+focus_history=[]
+
+while N <= max_rounds:
+    # 1. Run round (alternating: odd=independent, even=hybrid)
+    mode = 'independent' if N is odd else 'hybrid'
+    run Phase 1-4 with mode  → review-round-{N}.md
+
+    # 2. Parse Codex verdict
+    verdict = extract_verdict(codex_output)
+    # Look for <verdict>PERMANENT_CONVERGENCE</verdict>, <verdict>CONVERGED</verdict>, etc.
+
+    # 3. Halt check
+    if verdict == converge_on:
+        break
+
+    # 4. Apply HIGH-severity fixes
+    high_findings = parse_findings(review-round-{N}.md, severity='HIGH')
+    apply_fixes(high_findings)  → working tree modified
+
+    # 5. Auto-commit checkpoint
+    git add -A
+    git commit -m "iter-{N}: apply HIGH fixes from ensemble round {N}"
+
+    # 6. Rotate focus heuristic (after K=3 same-focus CONVERGED)
+    focus_history.append((current_focus, verdict))
+    if last_3_verdicts_all_CONVERGED_with_same_focus(focus_history):
+        current_focus = next_focus_in_pool()
+        # focus pool: method-section, proofs, typography, cross-references, boundary-cases
+
+    N += 1
+
+if N > max_rounds:
+    log("Halted at max_rounds without reaching {converge_on}")
+```
+
+#### Verdict 解析 protocol
+
+Codex prompt 結尾必須含明確 instruction:
+
+```
+At the very end of your review, output exactly one structured verdict tag:
+
+  <verdict>NEEDS_ITER_{N}</verdict>     — issues remain, iterate again
+  <verdict>CONVERGED</verdict>          — review converged within current focus
+  <verdict>PERMANENT_CONVERGENCE</verdict> — converged across all foci, paper-level done
+
+Choose conservatively. If unsure, NEEDS_ITER_{N}.
+```
+
+Skill 用 regex `<verdict>([A-Z_0-9]+)</verdict>` 從 Codex output 抓 tag。Robust 對 phrasing 變異;regex 容易 miss 「basically converged」近義詞,因此採結構化 tag。
+
+#### Apply-fixes protocol
+
+從 `review-round-{N}.md` 解出 HIGH-severity findings(MEDIUM/LOW 累積到最後一輪一次處理):
+
+```
+For each finding with severity=HIGH:
+    parse 「file:line — issue description — suggested fix」
+    Apply via Edit tool;若 fix 模糊或 suggestion 帶推測,skip + log to {SESSION}/skipped_fixes.log
+```
+
+跳過 ambiguous fix 而非硬套,避免 reviewer suggestion 自身錯誤被放大。
+
+#### Backup / rollback
+
+每輪結束 auto-commit `iter-{N}: apply HIGH fixes from ensemble round {N}`。User 可隨時:
+
+```bash
+git log --oneline | grep 'iter-'    # 列所有迭代 checkpoint
+git revert iter-{N}                  # 回退某輪
+git reset --hard iter-{N-1}          # hard reset 到前一輪
+```
+
+#### Rotate-focus heuristic
+
+如連續 K=3 輪同一 focus 都 CONVERGED 但未 PERMANENT_CONVERGENCE → 自動 switch focus 避免 local optimum。Focus pool:
+
+| Focus | 描述 |
+|-------|------|
+| `method-section` | 統計方法、研究設計 |
+| `proofs` | 數學證明、推導 |
+| `typography` | 排版、引用、bibliography |
+| `cross-references` | 交叉引用、ToC、bookmarks |
+| `boundary-cases` | edge case、退化情境 |
+
+Default 起始 focus = (none) — 不設,讓 reviewer 自主探;同一 focus 重複 CONVERGED 才強制 rotate。
+
+#### 與 ralph-loop 的差別
+
+`--auto-iterate` 是 **self-contained Bash while + state machine**,不依賴 ralph-loop 的 Stop-hook re-feed。Mode boundary 明確,可隨時中止 (`Ctrl+C` 在 round 之間生效);ralph-loop 把整個 session 鎖進迴圈,容易意外干擾其他 skill。
+
+若 user 同時跑 `ralph-loop` + `--auto-iterate`,skill 偵測 ralph-loop active 會印警告。
+
+#### Default 上限與 cost 警示
+
+- `--max-rounds` default 12,max 30
+- 每輪約 5 reviewer + Codex ≈ 6 LLM call;30 rounds × 6 ≈ 180 call
+- Skill prompt 會提示預估 token cost 並要求 confirm 才開跑
+
+### Phase 6: 最終合併（mix 模式）
+
+讀取所有 `review-round-*.md`，產出最終的 `review-summary.md`：
+
+```markdown
+## Ensemble Academic Review: {FILE}
+## Mode: mix {N} rounds
+
+### 審閱歷程
+| 輪次 | 模式 | 新發現數 | 累計問題數 |
+|------|------|---------|-----------|
+| Round 1 | independent | 15 | 15 |
+| Round 2 | hybrid | 8 🆕 | 23 |
+| Round 3 | independent | 4 | 27 |
+| Round 4 | hybrid | 1 🆕 | 28 |
+
+### 收斂判斷
+新發現數逐輪遞減（15 → 8 → 4 → 1），審閱已趨近飽和。
+
+### 跨輪共識（多輪都獨立指出）
+| # | 問題 | 出現輪次 | 嚴重性 |
+|---|------|---------|--------|
+| 1 | ... | R1, R2, R3 | HIGH |
+
+### 僅單輪發現
+| # | 問題 | 首次出現 | 嚴重性 | 後續輪次確認？ |
+|---|------|---------|--------|--------------|
+| 1 | ... | R2 🆕 | HIGH | R3 確認 |
+| 2 | ... | R4 🆕 | MEDIUM | 未再驗證 |
+
+### 文獻驗證（取最完整的一輪）
+...
+
+### 建議修改優先順序
+...
+```
+
+### Phase 7: 詢問下一步
+
+```
+審閱完成（{mode}, {N} 輪）。
+新發現趨勢：{round1_new} → {round2_new} → ... → {roundN_new}
+{收斂判斷}
+
+要怎麼做？
+1. 修正幻覺文獻和 HIGH 問題
+2. 只看不改（純審閱）
+3. 針對特定問題深入討論
+4. 用 /perspective-writer 改寫特定段落
+5. 再跑一輪（如果新發現數未收斂）
+```
+
+## 鐵律
+
+### 所有模式共用
+
+- **所有 tool calls 在同一個 message 送出**（N Agent + 1 Bash codex；N ∈ {3,4,5} 視啟用設定）。不可分步驟。
+- **Codex 看不到 Claude Team 的討論**。完全獨立的盲驗。
+- **Codex 的審稿結果原封不動呈現**，不要修改或摘要。
+- **reference-verifier 必須逐一查每筆文獻**。不可跳過或抽樣。
+- **number-verifier 必須對每個出現在 doc 中的數字查 ground truth**。不可只抽樣。
+- **幻覺文獻、幻覺數字皆最高優先級**。任何 ❌ 結果都是 HIGH severity。
+- **共識問題 > 單方問題**：多個來源都指出的問題最需要修。
+- **衝突不自動裁決**：呈現給使用者判斷。
+- **Devil's Advocate 是必要的**。防止群體盲點。
+
+### hybrid 輪專屬
+
+- **methodology、writing、Codex 絕對不看前輪結果**。防止 anchoring bias。
+- **只有 devil's advocate 拿到所有前輪完整結果**。
+- **reference-verifier 與 number-verifier 只拿到 watch list**，不是完整判斷。仍須獨立全面查核（從 ground truth 重跑）。
+- **合併時必須標記 🆕 新發現**。
+
+### mix 模式專屬
+
+- **每一輪都是完整的 Phase 1-4**。不可偷工減料、跳過 Codex、或減少 reviewer。
+- **用 TaskCreate/TaskUpdate 追蹤每輪進度**。讓使用者看到即時狀態。
+- **每輪結果獨立寫入 `review-round-{N}.md`**。不可覆蓋前輪。
+- **最終合併必須包含「收斂判斷」**:新發現數是否遞減。如果最後一輪仍有大量新發現,建議使用者再跑一輪。
+- **前輪結論可以被後輪推翻**。independent 輪的獨立審閱者如果得出不同結論,標記衝突供使用者判斷。
+
+### `--auto-iterate` 模式專屬(v2.3.0+)
+
+- **不可在 `--mode independent|hybrid` 上同時開**;mode 自含 alternating logic
+- **每輪 auto-commit `iter-{N}` checkpoint**,user 可隨時 git revert 回退
+- **HIGH-only fix application**;MEDIUM/LOW 累積到最後一輪一次處理(降低 round-to-round 雜訊)
+- **Ambiguous fix 一律 skip + log to `skipped_fixes.log`**,寧少做不錯做
+- **`<verdict>...</verdict>` tag 必填**;Codex prompt 結尾強制要求,parsing 用結構化 regex 不靠語意
+- **rotate-focus 在 K=3 同 focus CONVERGED 才觸發**;新 focus 從 pool 順序輪換
+- **`max_rounds` 上限 30**;達上限 halt 並報告未達 verdict 條件
+- **同時跑 ralph-loop + `--auto-iterate` 時 skill 警告**(雙 Stop-hook 衝突風險)
+
+## 8 個 cumulative methodological lessons (v2.3.0+, from real 23-round campaign)
+
+來源:`PsychQuantHsu/psychophysic_representations_manuscript/docs/rounds/INDEX.md`。可作 `--auto-iterate` 模式 review 中的「常踩坑」清單,Codex prompt 可選擇性 inject 部分 lessons 加強 detection。
+
+1. **Light-weight spot-check 容易 false-positive CONVERGED** — 至少跑滿 3 reviewer + Codex 才能 trust verdict
+2. **Theorem counter shared across `\newtheorem{lemma}[theorem]` = printing off-by-one** — 必查 LaTeX counter 結構
+3. **Hypothesis silently inherited across theorems** — 在某 theorem 加的 condition 可能影響後續 theorem,需明示「not inherited by Theorem N」
+4. **Stress-test on rare-audited sections (§Notation, §Discussion) 抓得到 11+ NEW HIGH** — 建議 rotate-focus 時主動進這些區
+5. **Codex `gpt-5.5 xhigh` 比 4-Claude consensus 嚴格** — 4-Claude 全 PASS 不等於 Codex 也 PASS
+6. **PDF Token warnings (hyperref) 是真 bug 不是 cosmetic** — silent 不 fix 會在 ToC/bookmarks 失敗
+7. **degenerate counter-example 必查** — 「u≡0」「g(z)=z²-1」這類 counter 應在 case-taxonomy 之內排除
+8. **CONVERGED ≠ PERMANENT_CONVERGENCE** — 前者是 scope-limited 的「目前 focus 沒抓到新東西」,後者是 cross-focus 全綠;只接受後者作 halt verdict 是 default 設計
diff --git a/plugins/parallel-ai-agents/skills/ensemble-code-review/SKILL.md b/plugins/parallel-ai-agents/skills/ensemble-code-review/SKILL.md
new file mode 100644
index 00000000..6708241c
--- /dev/null
+++ b/plugins/parallel-ai-agents/skills/ensemble-code-review/SKILL.md
@@ -0,0 +1,322 @@
+---
+name: ensemble-code-review
+description: |
+  Claude + Codex 雙 AI 獨立審閱程式碼，交叉比對找共識和盲點。
+  4 Claude teammates（architecture, correctness, security, devils-advocate）+ Codex GPT-5.5 獨立審一遍，最後合成比較表。
+  Use when: 程式碼、技術文件、設計文件發布前需要嚴格審閱。
+argument-hint: "FILE_OR_DIR [--focus 'review focus'] e.g. 'src/auth/', 'packages/ocr-swift/ --focus API正確性'"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - TeamCreate
+  - SendMessage
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - TaskGet
+  - AskUserQuestion
+---
+
+# /ensemble-review — Orchestrated Team + Codex 交叉審閱
+
+4 個 Claude teammates（orchestrated team）+ 1 個 Codex（gpt-5.5）各自獨立審閱，合成比較表找出共識和盲點。
+
+> **原理同 Ensemble OCR**：不同模型、不同角色的錯誤模式不重疊。4 個 Claude 以不同專業角度審閱且互相挑戰，Codex 提供跨模型盲驗。
+
+## 審閱架構
+
+```
+/ensemble-review FILE_OR_DIR
+│
+├── Claude Team（4 teammates，互相挑戰）
+│   ├── architecture — 設計模式、API 用法、依賴關係、全局合理性
+│   ├── correctness — 邏輯正確性、bug、edge case、型別安全
+│   ├── security — injection、secrets、權限、輸入驗證（攻擊者視角）
+│   └── devils-advocate — 讀前 3 人結論，反駁「通過」判斷
+│
+└── Codex（gpt-5.5，完全獨立 process，跨模型盲驗）
+
+→ 5 份 findings 合併去重 → 比較表
+```
+
+**為什麼 5 個？**
+- 4 個 Claude teammates 在同一個 team 裡**互相挑戰**（不是各自獨立報告）
+- Devil's Advocate 的工作是**試著證明其他 3 個的通過判斷是錯的**
+- Codex 是完全不同的模型家族（gpt-5.5），提供**跨模型盲驗**
+
+## 執行流程
+
+### Phase 0: 解析輸入
+
+```
+Arguments:
+  FILE_OR_DIR — 要審閱的檔案或目錄路徑
+  --focus — 審閱重點（可選，如「API正確性」「技術準確性」「安全性」）
+
+如果沒有 FILE_OR_DIR，問使用者。
+如果 FILE_OR_DIR 是目錄，讀取所有原始碼檔案作為審閱範圍。
+```
+
+### Phase 1: 讀取文件 + 準備 context
+
+1. 讀取目標文件（如果是目錄，列出所有檔案路徑和內容摘要）
+2. 自動判斷審閱類型：
+
+| 檔案類型 | 審閱重點 |
+|---------|---------|
+| `.md` blog/文章 | 技術準確性、邏輯一致性、聲明可驗證性 |
+| `.md` 設計文件 | 架構合理性、邊界情況、可行性、遺漏 |
+| `.swift` / `.py` / `.ts` 程式碼 | bug、安全漏洞、效能、API 用法、edge case |
+| 目錄（整個 package） | 架構、死碼、API 一致性、依賴管理 |
+
+3. 準備 context 字串，包含：檔案路徑、內容、focus 指示
+
+### Phase 2: 平行啟動 Claude Team + Codex
+
+**CRITICAL: 所有 tool calls（TeamCreate + Codex Bash）必須在同一個 message 送出。不可分步驟。**
+
+**CRITICAL: Teammates 必須用 `subagent_type: "general-purpose"`。不可用 `Explore`（Explore 不會主動 SendMessage 回報結果，會直接 idle）。**
+
+#### 2a. Claude Team（4 reviewers）
+
+用 TeamCreate 建立 team，然後用 Agent 啟動 4 個 teammates：
+
+```
+TeamCreate:
+  name: "ensemble-review-{timestamp}"
+  description: "Ensemble review for {FILE_OR_DIR}"
+```
+
+然後在**同一個 message** 啟動 4 個 Agent + 1 個 Codex Bash（共 5 個 tool calls）：
+
+**Agent 1: architecture**
+```
+Agent:
+  name: "architecture"
+  subagent_type: "general-purpose"
+  team_name: "ensemble-review-{timestamp}"
+  subagent_type: "general-purpose"
+  prompt: |
+    你是 Architecture Reviewer。
+    審閱範圍：{FILE_OR_DIR}
+    {context}
+
+    你的任務：
+    1. 設計模式是否正確（protocol 使用、抽象層級）
+    2. API 用法是否符合上游框架的推薦方式
+    3. 依賴關係是否合理（有沒有多餘或缺少的）
+    4. 檔案組織是否清晰
+    5. 有沒有死碼或重複實作
+
+    {focus_instruction}
+
+    用 Read/Grep/Glob 工具實際去看相關檔案確認。
+    用中文逐點列出問題和建議。每個問題標注嚴重性（HIGH/MEDIUM/LOW）。
+    最後給整體評價（一段話）。
+```
+
+**Agent 2: correctness**
+```
+Agent:
+  name: "correctness"
+  subagent_type: "general-purpose"
+  team_name: "ensemble-review-{timestamp}"
+  subagent_type: "general-purpose"
+  prompt: |
+    你是 Correctness Reviewer。
+    審閱範圍：{FILE_OR_DIR}
+    {context}
+
+    你的任務：
+    1. 邏輯正確性 — 有沒有 bug
+    2. Edge cases — null、empty、boundary values
+    3. 型別安全 — 隱式轉換、optional handling
+    4. 控制流程 — if/else 覆蓋、switch fall-through
+    5. 錯誤處理 — 有沒有漏接的 error
+
+    {focus_instruction}
+
+    用 Read 工具查看完整函數上下文。
+    用中文逐點列出問題和建議。每個問題標注嚴重性（HIGH/MEDIUM/LOW）。
+    最後給整體評價（一段話）。
+```
+
+**Agent 3: security**
+```
+Agent:
+  name: "security"
+  subagent_type: "general-purpose"
+  team_name: "ensemble-review-{timestamp}"
+  subagent_type: "general-purpose"
+  prompt: |
+    你是 Security Reviewer，以攻擊者視角審閱。
+    審閱範圍：{FILE_OR_DIR}
+    {context}
+
+    你的任務：
+    1. Injection 風險（SQL、command、path traversal）
+    2. Hardcoded secrets（API keys、passwords、tokens）
+    3. 權限檢查（有沒有繞過的可能）
+    4. 輸入驗證（external data 是否被信任）
+    5. 敏感資訊洩漏（error message、log）
+
+    {focus_instruction}
+
+    用 Grep 搜尋可疑模式（hardcoded strings、eval、exec 等）。
+    用中文逐點列出問題和建議。每個問題標注嚴重性（HIGH/MEDIUM/LOW）。
+    最後給整體評價（一段話）。
+```
+
+**Agent 4: devils-advocate**
+```
+Agent:
+  name: "devils-advocate"
+  subagent_type: "general-purpose"
+  team_name: "ensemble-review-{timestamp}"
+  subagent_type: "general-purpose"
+  prompt: |
+    你是 Devil's Advocate。
+    審閱範圍：{FILE_OR_DIR}
+    {context}
+
+    你的任務：等其他 3 個 reviewer（architecture、correctness、security）完成後，
+    用 SendMessage 詢問他們的結論，然後**試著反駁每一個「通過」或「LOW」的判斷**。
+
+    步驟：
+    1. 用 SendMessage 分別問 architecture、correctness、security 他們的 findings
+    2. 對每個「通過」的判斷，找理由說它其實有問題
+    3. 對每個「LOW」的判斷，論證為什麼應該是 MEDIUM 或 HIGH
+    4. 如果你找不到反駁的理由，才承認確實通過
+
+    這是對抗性驗證 — 你的存在是為了防止群體盲點。
+    用中文輸出你的反駁結果。
+```
+
+#### 2b. Codex（背景執行 — 直接 HTTP，繞過 codex CLI subprocess）
+
+```bash
+codex-call \
+  --output "{output_file}" \
+  --model gpt-5.5 \
+  --effort xhigh \
+  --service-tier fast \
+  --max-time 600 \
+  --instructions "你是嚴謹的程式碼審閱者，用中文輸出。" << 'EOF'
+{codex_prompt}
+EOF
+```
+
+> **為什麼不用 `codex exec`**：subprocess 偶爾會 hang（stdin/stdout pipe 互鎖、tty 問題），等 10 分鐘 timeout 才能繼續。`codex-call` 是 plugin 自帶 wrapper（`bin/codex-call`，Swift script，安裝時自動加入 PATH），直接 HTTP POST 到 `chatgpt.com/backend-api/codex/responses`，仍走你的 ChatGPT 訂閱 OAuth — 但 `--max-time` 是硬性保證，不會 hang。
+>
+> **Fast mode**：傳 `--service-tier fast`，wrapper 內部會翻譯成 backend 接受的 `priority`（codex CLI 內部也是這樣翻譯）。Fast = 1.5× 速度、2.5× credit（gpt-5.5）；ensemble 場景值得，因為 user 在等。
+>
+> **OAuth token**：wrapper 自動讀 `~/.codex/auth.json`（codex CLI 的同一份），到期前 5 分鐘自動 refresh，用 file lock 避免 ensemble 平行 race。
+
+Codex prompt 應包含：
+- 審閱範圍和 focus
+- 要求逐點分析，標注嚴重性
+- 用中文回答
+- **不提及 Claude team 的存在**（確保獨立性）
+
+### Phase 3: 收集結果
+
+1. 等待 4 個 Claude teammates 完成（透過自動訊息通知）
+2. 等待 Codex 完成（輪詢 status）
+3. 如果 Codex 失敗或超時（>10 分鐘），跳過，標注「Codex 不可用」
+
+`codex-call` 完成後輸出會寫入 `--output` 指定的檔案，直接用 Read 讀取即可。
+
+### Phase 4: 合併去重 + 交叉比對
+
+由主 session 的 Claude 讀取所有結果，產出比較表：
+
+1. **去重**：相同檔案 + 相似描述 → 合併，標註來源 `[team:architecture+codex]`
+2. **severity 以最高為準**：如果 correctness 說 MEDIUM 但 codex 說 HIGH → HIGH
+3. **Devil's Advocate 的反駁如果成立** → 升級 severity
+
+輸出格式：
+
+```markdown
+## Ensemble Review: {FILE_OR_DIR}
+
+### 審閱者
+- **Claude Team**: architecture, correctness, security, devils-advocate（orchestrated）
+- **Codex GPT-5.5**: 獨立盲驗
+
+### 共識（≥2 個來源都指出）
+| # | 問題 | 嚴重性 | 來源 | 說明 |
+|---|------|--------|------|------|
+| 1 | ... | HIGH | team:arch+correct+codex | ... |
+
+### 僅 Claude Team 指出
+| # | 問題 | 嚴重性 | 來源 | 說明 |
+|---|------|--------|------|------|
+| 1 | ... | ... | team:security | ... |
+
+### 僅 Codex 指出
+| # | 問題 | 嚴重性 | 說明 |
+|---|------|--------|------|
+| 1 | ... | ... | ... |
+
+### Devil's Advocate 反駁結果
+| # | 原始判斷 | 反駁 | 成立？ |
+|---|---------|------|--------|
+| 1 | correctness: LOW | 「其實是 MEDIUM 因為...」 | ✅ 升級 |
+| 2 | security: 通過 | 「未能反駁」 | ❌ 維持 |
+
+### 衝突（來源間意見矛盾）
+| # | 議題 | Claude Team | Codex | 建議 |
+|---|------|------------|-------|------|
+| 1 | ... | ... | ... | 交由使用者判斷 |
+
+### Summary
+- 共識問題: N 個（最需要修）
+- 僅 Claude Team: M 個
+- 僅 Codex: K 個
+- Devil's Advocate 升級: L 個
+- 衝突: J 個
+
+### 建議修改優先順序
+1. {highest priority fix}
+2. ...
+```
+
+### Phase 5: 詢問下一步
+
+```
+審閱完成。要怎麼做？
+1. 根據共識問題修改文件
+2. 只看不改（純審閱）
+3. 針對特定問題深入討論
+```
+
+## Codex CLI 參考
+
+```bash
+# companion script 路徑（優先 marketplace，fallback cache）
+CODEX_SCRIPT="$HOME/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs"
+
+# 啟動 task
+node "$CODEX_SCRIPT" task --effort high "prompt"
+
+# 查狀態
+node "$CODEX_SCRIPT" status --all
+
+# 取結果
+node "$CODEX_SCRIPT" result $JOB_ID
+```
+
+## 鐵律
+
+- **5 個 tool calls 在同一個 message 送出**（4 Agent + 1 Bash codex）。不可分步驟。
+- **Codex 看不到 Claude Team 的討論**。它是完全獨立的盲驗。
+- **Codex 的審稿結果原封不動呈現**，不要修改或摘要。
+- **交叉比對由主 session 的 Claude 做**，因為主 session 有完整 context。
+- **共識問題 > 單方問題**：多個來源都指出的問題最需要修。
+- **衝突不自動裁決**：呈現給使用者判斷。
+- **Devil's Advocate 是必要的**。防止 3 個 reviewer 的群體盲點。
diff --git a/plugins/parallel-ai-agents/skills/ensemble-lecture-review/SKILL.md b/plugins/parallel-ai-agents/skills/ensemble-lecture-review/SKILL.md
new file mode 100644
index 00000000..31dbafb1
--- /dev/null
+++ b/plugins/parallel-ai-agents/skills/ensemble-lecture-review/SKILL.md
@@ -0,0 +1,209 @@
+---
+name: ensemble-lecture-review
+description: |
+  教學講義 Ensemble 審閱：4 個 Claude teammates（教學審閱角色）各自獨立審閱講義品質。
+  當用戶提到「review 講義」「審閱講義」「講義品質」「lecture review」時使用。
+argument-hint: "[講義 HTML 路徑] [--srt 對應逐字稿路徑]"
+---
+
+# /ensemble-lecture-review — 教學講義 Ensemble 審閱
+
+4 個 Claude teammates 各自獨立審閱講義，合成比較表找共識和盲點。
+
+> **與 ensemble-academic-review 的差異**：角色從「學術論文審閱」改為「教學材料審閱」。不查文獻真偽，改查逐字稿覆蓋率。
+
+## 審閱架構
+
+```
+/ensemble-lecture-review lecture.html [--srt transcript.srt]
+│
+├── Claude Team（4 teammates）
+│   ├── content-accuracy — 內容正確性（統計、理論、公式）
+│   ├── student-readability — 學生可讀性（白話程度、邏輯銜接）
+│   ├── completeness — 完整性（對照逐字稿找遺漏）
+│   └── devils-advocate — 反駁前三個的判斷
+│
+└── 比較表 + 修改建議
+```
+
+## 執行流程
+
+### Phase 0: 解析輸入
+
+```
+Arguments:
+  FILE — 講義 HTML 檔案路徑
+  --srt — 對應的 SRT 逐字稿（可選，completeness reviewer 會用）
+
+如果沒有 FILE，掃描 handout 目錄列出所有講義讓用戶選。
+如果沒有 --srt，嘗試從 lectures/ 目錄自動匹配。
+```
+
+### Phase 1: 讀取文件 + 準備 context
+
+1. 讀取講義 HTML 全文
+2. 如果有 SRT，讀取逐字稿全文
+3. 讀取 teaching.json（了解學生背景）
+4. 準備 context 字串
+
+### Phase 2: 平行啟動 4 個 Claude Teammates
+
+**CRITICAL: 所有 4 個 Agent tool calls 必須在同一個 message 送出。**
+
+**CRITICAL: Teammates 必須用 `subagent_type: "general-purpose"`。**
+
+用 TeamCreate 建立 team，然後在同一個 message 啟動 4 個 Agent：
+
+#### Agent 1: content-accuracy
+
+```
+你是 Content Accuracy Reviewer，專門檢查教學講義的知識正確性。
+審閱講義：{FILE}
+{context}
+
+學生背景：{student_info}
+
+你的任務：
+1. **統計概念**：定義是否正確（p-value、power、effect size、confidence interval）
+2. **公式**：數學符號有沒有寫錯（KaTeX 語法是否正確）
+3. **理論解釋**：心理學理論的描述是否準確（Higgins, Regulatory Focus/Fit）
+4. **因果推論**：有沒有把相關說成因果、或過度推論
+5. **術語一致性**：同一個概念在不同地方是否用同一個名稱
+6. **範例正確性**：舉的例子是否恰當地支持概念
+
+用 Read 工具讀取講義確認。
+逐點列出問題，每個標注嚴重性（HIGH/MEDIUM/LOW）。
+引用具體的段落或句子。
+```
+
+#### Agent 2: student-readability
+
+```
+你是 Student Readability Reviewer，從學生的角度審閱講義的易懂程度。
+審閱講義：{FILE}
+{context}
+
+學生背景：{student_info}（注意：學生零程式基礎，概念理解可能表面化）
+
+你的任務：
+1. **白話程度**：有沒有用了專業術語但沒解釋的地方
+2. **邏輯銜接**：段落之間的跳躍是否太大（學生能不能跟上）
+3. **具體例子**：抽象概念有沒有搭配具體例子
+4. **視覺輔助**：表格、圖表是否幫助理解（還是增加混淆）
+5. **篇幅平衡**：重要概念是否得到足夠篇幅（vs 次要內容佔太多）
+6. **結構導航**：學生能不能快速找到想看的段落（標題是否清楚）
+7. **前後呼應**：「重點整理」是否真的涵蓋了最重要的內容
+
+用 Read 工具讀取講義。
+站在學生的角度思考：「如果我是零基礎的學生，讀到這裡我會卡住嗎？」
+逐點列出問題，每個標注嚴重性（HIGH/MEDIUM/LOW）。
+```
+
+#### Agent 3: completeness
+
+```
+你是 Completeness Reviewer，檢查講義是否完整覆蓋了上課教的內容。
+審閱講義：{FILE}
+{context}
+
+{srt_instruction}
+
+你的任務：
+1. **逐字稿覆蓋率**：逐字稿裡有教但講義沒寫到的重點（最重要）
+2. **結構完整性**：
+   - 有沒有「重點整理」section
+   - 有沒有「課後作業」section
+   - h2/h3 層級是否正確（沒有孤立的 h3）
+   - h2 之間有沒有 --- 分隔
+3. **KaTeX/Mermaid**：有數學符號的地方有沒有加 KaTeX CDN？有路徑圖的地方有沒有用 Mermaid 或 ASCII art？
+4. **連結有效性**：href 指向的檔案是否存在
+5. **缺少的教學元素**：
+   - 有沒有該有 blockquote 提醒但沒有的地方
+   - 有沒有該用表格對比但只用文字描述的地方
+
+如果有 SRT，分段讀（每次 200 行），逐段對照講義找遺漏。
+沒有 SRT 就只做結構完整性檢查。
+逐點列出問題，每個標注嚴重性（HIGH/MEDIUM/LOW）。
+```
+
+SRT instruction（有 SRT 時注入）：
+```
+逐字稿路徑：{SRT_PATH}
+請用 Read 工具分段讀取逐字稿（每次 200 行），逐段對照講義。
+如果逐字稿裡有教學重點但講義沒寫到，標記為 HIGH。
+```
+
+#### Agent 4: devils-advocate
+
+```
+你是 Devil's Advocate，教學講義審閱的對抗性驗證者。
+審閱講義：{FILE}
+{context}
+
+你的任務：等其他 3 個 reviewer 完成後，用 SendMessage 詢問他們的結論，
+然後試著反駁每一個「通過」或「LOW」的判斷。
+
+步驟：
+1. 先用 Read 工具讀取講義，形成自己的理解
+2. 用 SendMessage 分別問 content-accuracy、student-readability、completeness 他們的 findings
+3. 對每個「通過」的判斷，找理由說它其實有問題：
+   - content-accuracy 說概念正確 → 找邊界情況或過度簡化
+   - student-readability 說易懂 → 找可能讓特定背景學生困惑的地方
+   - completeness 說完整 → 找隱含的教學目標是否達成
+4. 特別挑戰：
+   - 「重點整理」是否真的是重點，還是只是把小標題抄了一遍
+   - 表格是否真的幫助理解，還是增加認知負擔
+   - 課後作業是否可執行，學生知不知道具體要做什麼
+5. 如果找不到反駁的理由，才承認確實通過
+
+用中文輸出反駁結果。
+```
+
+### Phase 3: 收集結果
+
+等待 4 個 teammates 完成（透過自動訊息通知）。
+
+### Phase 4: 合併去重
+
+由主 session 的 Claude 讀取所有結果，產出比較表：
+
+```markdown
+## Ensemble Lecture Review: {FILE}
+
+### 比較表
+| # | 問題 | 嚴重性 | 來源 | 位置 |
+|---|------|--------|------|------|
+| 1 | Power 的定義缺少直覺解釋 | HIGH | content-accuracy, student-readability | 統計概念 section |
+| 2 | h3 「OpenClaw」沒有 h2 父層 | HIGH | completeness | AI 工具比較 section |
+| 3 | ... | ... | ... | ... |
+
+### 共識問題（多個 reviewer 都指出）
+...
+
+### Devil's Advocate 升級的問題
+...
+
+### 統計
+- content-accuracy: N 個問題（H: x, M: y, L: z）
+- student-readability: N 個問題
+- completeness: N 個問題
+- devils-advocate 升級: N 個
+```
+
+### Phase 5: 詢問下一步
+
+```
+審閱完成。要怎麼做？
+1. 修正 HIGH 問題
+2. 只看不改
+3. 針對特定問題深入討論
+4. 用 /teaching-toolkit:lecture-enrich 充實講義
+```
+
+## 鐵律
+
+- **4 個 tool calls 在同一個 message 送出**。不可分步驟。
+- **completeness reviewer 必須讀逐字稿**（如果有提供）。不可跳過。
+- **共識問題 > 單方問題**：多個 reviewer 都指出的問題最需要修。
+- **Devil's Advocate 是必要的**。防止群體盲點。
+- **考慮學生背景**：所有 reviewer 都要知道學生的程度和目標。
diff --git a/plugins/perspective-writer/.claude-plugin/plugin.json b/plugins/perspective-writer/.claude-plugin/plugin.json
index e8fe1493..f8a44945 100644
--- a/plugins/perspective-writer/.claude-plugin/plugin.json
+++ b/plugins/perspective-writer/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "perspective-writer",
   "description": "Write letters, emails, autobiographies, and formal documents by simulating the writer's authentic voice. Uses Tarski's T-Schema to ensure every sentence has a concrete referent, and a 6-phase process (understand writer, understand recipient, simulate, write, anti-pattern check, iterate) to produce writing that sounds like a real person, not AI.",
-  "version": "2.2.0",
+  "version": "2.8.0",
   "author": {
     "name": "Che Cheng"
   }
diff --git a/plugins/perspective-writer/CHANGELOG.md b/plugins/perspective-writer/CHANGELOG.md
new file mode 100644
index 00000000..8469b661
--- /dev/null
+++ b/plugins/perspective-writer/CHANGELOG.md
@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [2.8.0] - 2026-05-20
+
+### Added
+- **Mode: Compose vs. Revise section** (#86): the skill now explicitly distinguishes drafting a new letter from iteratively revising an existing draft. Revise mode does not skip Phase 1-2 (the understanding phases where prior correspondence gets read). Real-world trigger: a host-inquiry letter was iteratively revised across many rounds while Phase 1-3 was silently skipped every round — the recipient's verbatim "If you contact me in a year" was softened into "at a later point" with no archive re-read, and downstream judgments built on the erased timeline drifted unrecoverably.
+- **Phase 5 anti-pattern row — English sincerity-intensifier adverbs**: `sincerely`, `deeply`, `truly`, `genuinely`, `wholeheartedly`, `really`, `very much` modifying verbs of gratitude / hope / appreciation. Native English correspondence carries sincerity in the verb structure, not in adverbs; stacking intensifiers ("I deeply appreciate", "I sincerely hope") reads as ESL or AI. Fix is almost always deletion. `Sincerely yours` at sign-off is the one fixed-slot exception.
+- **Mode-independent rule**: whenever prior correspondence with the recipient exists, reading it (Phase 1-2) is mandatory — covers the in-between case (reply to an incoming message when no draft yet exists).
+
+### Changed
+- **Phase 0 TaskList** (#86): `phase1_understand_writer` and `phase2_understand_recipient` task descriptions now explicitly require reading the recipient's archived correspondence, not merely asking whether it exists.
+- **Phase 1 "Sources to check"** (#86): the recipient's prior-correspondence archive is no longer an "ask which are available" item; it is a mandatory-read-if-it-exists item. Other sources (blog / CV / etc.) remain ask-which.
+- **Phase 2 paraphrasing rule** (#86): paraphrasing the recipient is now an explicit T-schema referent. Distinguishes "softening the tentativeness of a polite refusal" (allowed — keep `may be able to consider` tentative) from "erasing factual guidance" (not allowed — a concrete time / condition / instruction the recipient gave is a referent, not bookkeeping to be loosened away). Erasing one and every downstream judgment drifts silently — invisibly, because the reworded sentence still reads fine.
+- **Phase 6b** (#86): cross-references the new Mode section. Each user edit begins another Revise pass; re-anchor to prior correspondence before reworking the draft again.
+- **Span label correction** (#86 verify): the reading claim now says "Phase 1-2" (where prior correspondence actually gets read) rather than "Phase 1-3" (Phase 3 is Simulate and reads nothing). The "understanding phases" label is kept for the Phase 1-3 block as a whole.
+
+## [2.7.0] - 2026-05-15
+
+### Added
+- **Phase 1 temporal anchors**: explicit questions for today's date, writer's lifecycle stage (onboarding week N / post-acceptance / mid-sabbatical etc.), and last contact/event with the recipient. Required before writing any time-relative phrasing ("recently", "前幾天", "上週", "last month"). Real-world trigger: AI defaulted to "陳老師前幾天提到..." when the actual conversation was 1 week earlier at a specific named meeting (storyline 會議, 2026-05-08). Recipient's memory of the event would not match "前幾天" → instant AI-generation tell.
+
+### Changed
+- **Golden Rule (T-schema)**: time phrasing now explicitly listed as a referent. Words like "recently / 前幾天 / 上週" must be anchored to a specific date verified with the writer, not guessed by the AI. Anchored phrasing ("5/8 在 storyline 會議時") carries the same warmth without the AI smell.
+- **Phase 5 anti-pattern checklist**: added row for "vague temporal phrasing without verified anchor". Fix is to ask the writer for the specific date and replace with anchored form.
+
+## [2.6.0] - 2026-05-07
+
+### Added
+- New `save-feedback` skill (#28): captures **conversational feedback** that user gives mid-draft into reusable rules. Complements `draft-learner` (which only triggers on file-modification system-reminders). Real-world gap: when user gives verbal tone/style/relationship/structure feedback in conversation and agent rewrites the file each round, no file diff is produced → draft-learner never fires → feedback evaporates at session end. `save-feedback` fills that gap with explicit invocation (`/perspective-writer:save-feedback`) or proactive trigger phrases ("存 feedback" / "把這些建議記下來"). 6-step workflow (scan conversation → classify → extract concrete rules with **Why** field → locate `.claude/rules/` file → write → confirm). Distinct from draft-learner per a side-by-side comparison table in the SKILL.md.
+
+## [2.5.0] - (date unknown — please fill in)
+
+### Changed
+- Write letters, emails, autobiographies, and formal documents by simulating the writer's authentic voice.
+- Uses Tarski's T-Schema to ensure every sentence has a concrete referent, and a 6-phase process (understand writer, understand recipient, simulate, write, anti-pattern check, iterate) to produce writing that sounds like a real person, not AI
diff --git a/plugins/perspective-writer/skills/draft-learner/SKILL.md b/plugins/perspective-writer/skills/draft-learner/SKILL.md
index 1affbefd..2801bbdb 100644
--- a/plugins/perspective-writer/skills/draft-learner/SKILL.md
+++ b/plugins/perspective-writer/skills/draft-learner/SKILL.md
@@ -5,13 +5,31 @@ description: >
   diff the changes, extract concrete rules, and update .claude/rules/ files. Trigger when you
   detect a file modification system-reminder on a file you recently wrote or edited.
 argument-hint: (auto-triggered from file modification)
-allowed-tools: Read, Edit, Write, Grep, Glob
+allowed-tools: Read, Edit, Write, Grep, Glob, TaskCreate, TaskUpdate, TaskList
 ---
 
 # Draft Learner
 
 You have been triggered because a file you recently wrote or edited in this conversation was modified by the user. Your job is to learn from their edits and persist those preferences as reusable rules.
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**在動任何事之前**先用 `TaskCreate` 為這個 stage 建 todo list：
+
+```
+TaskCreate(name="step1_detect_and_diff",     description="Step 1: 讀修改後的檔案，對照原版，把每個改動分類")
+TaskCreate(name="step2_extract_rules",       description="Step 2: 把每個改動轉成具體、可重用的 rule（一改動一 rule）")
+TaskCreate(name="step3_locate_rules_file",   description="Step 3: Glob 找 .claude/rules/ 現有檔案；沒有就詢問是否建立")
+TaskCreate(name="step4_update_rules",        description="Step 4: Edit 現有檔案（不覆寫、不重複、矛盾就取代）或 Write 新檔")
+TaskCreate(name="step5_confirm_with_user",   description="Step 5: 給 user 簡短摘要說學到什麼、存到哪")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：draft-learner 最大風險是 step 2 偷懶寫出「be more formal」這種沒用的模糊 rule 就交差。TaskList 讓 step 2 的「extract_rules」必須被看到完成，不能靜默跳過。
+
+---
+
 ## Step 1: Detect and Diff
 
 1. Read the modified file using the `Read` tool (the path comes from the system-reminder or conversation context).
diff --git a/plugins/perspective-writer/skills/perspective-writer/SKILL.md b/plugins/perspective-writer/skills/perspective-writer/SKILL.md
index a981d301..460836cb 100644
--- a/plugins/perspective-writer/skills/perspective-writer/SKILL.md
+++ b/plugins/perspective-writer/skills/perspective-writer/SKILL.md
@@ -32,6 +32,12 @@ for a claim, either ask the user or don't make the claim.
 This principle overrides tone-matching. A sentence with perfect voice but no referent is worse than
 an awkward sentence that points to something real.
 
+**Time phrasing is a referent.** Words like "recently", "last week", "前幾天", "上週", "earlier this month"
+all assert a specific time. Their referent must come from the writer's *verified* memory, not the AI's
+guess. If the writer says 陳老師 mentioned X "前幾天" but the actual conversation happened 6 weeks ago,
+the recipient reads "前幾天" and instantly distrusts the letter. Anchor every time-phrase to a specific
+date (YYYY-MM-DD) before writing it. See Phase 1 "Temporal anchors" for the questions to ask.
+
 **But T-schema alone is not enough.** Every sentence must simultaneously satisfy two constraints:
 1. **T-schema**: it points to something concrete and verifiable.
 2. **Writing goal**: it serves the document's purpose at the right level of detail.
@@ -88,12 +94,47 @@ looks impressive on paper.
 Before you write a single word of the actual letter, you must complete two phases of understanding.
 Skipping these phases is not allowed. If you don't have enough information, ask.
 
+## Mode: Compose vs. Revise
+
+This skill runs in one of two modes. Identify which one before Phase 0:
+
+- **Compose** — writing a new letter or document from scratch. Run every phase in order.
+- **Revise** — iteratively editing an existing draft. The draft may be a file the user points at, text pasted inline, or a draft produced earlier in the conversation; the request is to change a sentence, fix a paragraph, adjust tone, or smooth the logic. Once a first draft exists, this is the most common mode.
+
+**Independent of mode**: whenever prior correspondence with the recipient exists, reading it (Phase 1-2) is mandatory. This also covers the in-between case — replying to an incoming message when no draft yet exists — because a reply is anchored to what the other side actually said, so the prior message is read first.
+
+**The Revise trap.** Once a draft exists it is tempting to skip the understanding phases (Phase 1-3) — "the draft is already here, I already understand the writer and the recipient" — and jump straight to editing. Do not. Phase 1-2 is where the prior correspondence actually gets read (Phase 3 then re-derives the writer's perspective from it). A revision that changes *how the recipient's words are paraphrased*, or *what the writer claims*, is only safe when it is re-anchored to the real interaction history. Wording that merely reads smoothly can still have drifted from what was actually said.
+
+**Revise mode does not skip the understanding phases.** It still reads the prior correspondence — the recipient's actual archived messages, the earlier drafts — before touching the draft. The phases are lighter in Revise mode (you are confirming, not building from nothing), but never skipped.
+
+## Phase 0: Bootstrap Stage Task List（強制）
+
+**在動任何事之前**先用 `TaskCreate` 為這個 stage 建 todo list，確保 7 個 phase 都有被追蹤：
+
+```
+TaskCreate(name="phase1_understand_writer",        description="Phase 1: 讀 user 材料（含與收件人的往來歸檔原文）建立 voice model + 問情緒狀態")
+TaskCreate(name="phase2_understand_recipient",     description="Phase 2: 讀與收件人的真實往來原文 + 研究背景、power dynamic、cultural context")
+TaskCreate(name="phase3_simulate",                 description="Phase 3: 寫出 simulation 段落再開始 draft")
+TaskCreate(name="phase4_write_draft",              description="Phase 4: 初稿（Lead with WHY、Voice matching、Pressure calibration）")
+TaskCreate(name="phase5_antipatterns_check",       description="Phase 5+5b: 過 anti-pattern checklist、用 horizontal rule 包裹輸出")
+TaskCreate(name="phase6_present_and_iterate",      description="Phase 6: 呈現草稿並解釋選擇，等 user 回饋；若編輯檔案 → delegate draft-learner (6b)")
+TaskCreate(name="phase7_persist_rules",            description="Phase 7: 徵詢後把通信習慣寫到 .claude/rules/correspondence-[recipient].md")
+```
+
+完成每一個 phase 立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：Phase 1-3 是「理解」階段，很容易被跳過直接 Phase 4 寫 draft。強制 TaskList 讓 skip 變得明顯。另外 Phase 7（persist rules）常被忘記，TaskList 收尾時就會提醒還沒做。
+
+**注意**：Phase 5b 是 output format 的格式規範（用 `---` 不用 `>`），併進 `phase5_antipatterns_check`；Phase 6b 是偵測到檔案被改動時 delegate 到 `draft-learner` skill，不算獨立 phase，處理完回到 `phase6_present_and_iterate`。
+
+---
+
 ## Phase 1: Understand the Writer
 
 Read the user's existing materials to build a mental model of who they are and how they write.
 
-**Sources to check (ask the user which are available):**
-- Previous sent emails or correspondence
+**Sources to check:**
+- Previous sent emails or correspondence — **if a prior-correspondence archive exists, read the actual messages; do not merely ask whether it exists.** This is the ground truth for the writer's voice and for what each side actually said. Reading it is mandatory whenever it exists, not only in Revise mode (see "Mode: Compose vs. Revise").
 - Blog posts or personal writing
 - The current conversation history (how the user talks to you is how they talk)
 - Application materials, CV, academic papers
@@ -108,11 +149,18 @@ Read the user's existing materials to build a mental model of who they are and h
   (See Golden Rule above.) Match their specificity level, not just their voice.
 
 **What you must ask the user directly:**
+
+*Internal state:*
 - "What's your actual feeling about this?" (nervous? excited? uncertain?)
 - "What do you most want the recipient to take away?"
 - "Is there anything you're worried about with this letter?"
 
-Do not guess these. A person's internal state determines their writing tone, and you cannot infer it from their CV.
+*Temporal anchors (critical — see "Time phrasing as referent" under Golden Rule):*
+- **Today's date** — explicitly state YYYY-MM-DD as the reference point for every "recently / 前幾天 / 上週 / last month" phrasing. Use system context (currentDate) when available, otherwise ask.
+- **Writer's lifecycle stage** — what stage is the writer in right now? (e.g., onboarding week 2 of new postdoc, first semester teaching, mid-sabbatical, post-acceptance pre-start, application phase). This affects self-positioning ("I am..." vs "I will be..."), tense, and how much credentials need explaining.
+- **Last contact / event with the recipient** — when, where, what context? Required before writing any "recently / last week / 前幾天 / 上次" phrasing. Convert into a specific date and verify against the writer's memory.
+
+Do not guess any of these. A person's internal state determines their writing tone, and you cannot infer it from their CV. Time phrasings ("recently", "前幾天", "上週") that don't match the recipient's own memory of when an event happened are an immediate AI-generation tell — the recipient reads "前幾天" and thinks "wait, when?"
 
 ## Phase 2: Understand the Recipient
 
@@ -122,7 +170,12 @@ Research who the recipient is and what the relationship looks like from the writ
 - The recipient's position, research area, recent work
 - The power dynamic (professor you've never met? someone who knows your advisor? a peer?)
 - Cultural context (Taiwanese academic norms? Japanese? Western?)
-- Any prior interaction between the writer and recipient
+- Any prior interaction between the writer and recipient — **read the actual archived messages, both sides, verbatim**
+
+**Paraphrasing the recipient is a referent (T-schema).** When the letter restates something the recipient said, check that restatement against the recipient's actual words. Two distinct moves — do not conflate them:
+
+- *Softening the tentativeness of a polite refusal* is allowed: "we may be able to consider" need not harden into "you will consider."
+- *Erasing factual guidance the recipient gave* is not allowed: a concrete time ("in a year"), a condition, an instruction — these are referents, not bookkeeping to be loosened away. Drop one and every downstream judgment that rested on it (how early is "early", whether an apology is warranted, whether a deadline was missed) drifts silently — invisibly, because the reworded sentence still reads fine.
 
 **Then ask yourself (and write down the answers before drafting):**
 - What does this person probably care about when reading this letter?
@@ -233,6 +286,12 @@ Before presenting the draft, check for these AI writing tells and remove every i
 | Starting paragraphs with "在...方面" | Formulaic topic sentence structure | Vary your openings |
 | "不僅...更..." "不僅...也..." | AI loves this construction. Humans use it sparingly. | Use it at most once per document |
 | Ending with "期盼" "期許" "展望" | Overly formal, sounds like a press release | End like a person: "謝謝老師" or "希望有機會跟老師聊聊" |
+| English sincerity-intensifier adverbs ("sincerely", "deeply", "truly", "genuinely", "wholeheartedly", "really", "very much") modifying verbs of gratitude / hope / appreciation | Native English correspondence carries sincerity in the verb and the structure, not in adverbs. Stacked intensifiers ("I deeply appreciate", "I sincerely hope", "I would very much like to", "I am truly grateful") read as ESL or AI — the writer is *telling* you they are sincere instead of *being* sincere. The fix is almost always deletion, not substitution. | Drop the adverb entirely: "I appreciate" / "I hope" / "I would like to" / "I am grateful". `Sincerely yours` at sign-off is the one fixed slot; elsewhere, sincerity intensifiers are noise. Exception: "I sincerely apologize" in formal rituals (and even then, often "I apologize" is enough). |
+| Vague temporal phrasing without verified anchor ("recently", "前幾天", "上次", "earlier") | If the writer hasn't told you the specific date, AI defaults to "前幾天" / "recently" — but the recipient knows when things actually happened and will notice the mismatch. Pure AI tell. | Ask the writer for the specific date. Replace "前幾天" with "上週四" or "5/8 在 storyline 會議時" — anchored phrasings carry the same warmth without the AI smell. |
+| Extra `---` / `***` hrules inside letter body | AI uses horizontal rules to segment emails into card-like sections. Humans don't—they use paragraph breaks. | Delete every hrule except the Phase 5b wrapper pair. One paragraph = one idea; adjacent paragraphs separated by blank lines, not hrules |
+| **Adjacent structural dividers** | Two lines with only whitespace between (e.g., section-closing rule + next-section-opening rule, or heading-trailing rule right before `---`). This is the *actual* AI tell—not the total count of lines but the back-to-back pair. | Remove one side of the pair. Default to keeping the semantically stronger line (e.g., keep the wrapper; remove the heading-trailing decorative `::after` rule) |
+| `2px double` borders (in HTML/PDF drafts) | Double-line borders are AI design reflex for emphasis (e.g., total row, CTA divider) | Use `1px solid`. Emphasis comes from *weight difference* against neighboring soft rules, not from doubling the line itself |
+| Decorative `::before` / `::after` rules on every heading | AI adds trailing horizontal lines after `I SCOPE · 關於本工作坊`-style labels to "make it look editorial" | Remove. Small-caps labels with proper letter-spacing carry enough visual weight alone |
 
 ## Phase 5b: Output Format
 
@@ -260,6 +319,57 @@ Signature
 ---
 ```
 
+### Only TWO `---` allowed per draft (before + after). Zero internal hrules.
+
+Common AI mistakes (all are AI signatures — real people don't do any of these):
+
+- ❌ Adding `---` between body paragraphs as section dividers
+- ❌ Adding `---` before the signature line
+- ❌ Using `---` or `***` to separate "main content" from "postscript"
+- ❌ Using `---` to replace a period or comma transition
+
+If the draft needs to signal structural shift, let paragraphs do it: blank line between
+two paragraphs is enough. If two topics feel like they need a hard divider between them,
+they probably belong in **two separate messages**, not one email with hrules.
+
+**When you present the draft, count your `---`. There should be exactly 2.** More than 2
+means you've accidentally built a template aesthetic into what should feel like a personal
+letter. Delete the extras before showing the user.
+
+### The Adjacency Principle (generalizes beyond `---`)
+
+The real AI tell isn't "too many dividers"—it's **two dividers appearing back-to-back**
+with nothing meaningful between them. This generalizes beyond markdown hrules to any
+formatted output:
+
+| Medium | Adjacent-pair anti-pattern |
+|--------|---------------------------|
+| Markdown letter/email | `---` then blank line then another `---` (both wrapping something trivial) |
+| Markdown with sections | `---` section divider immediately after a `## heading` line |
+| HTML / PDF drafts | `border-bottom` on one section + `border-top` on the next section with only margin between |
+| HTML / PDF tables | Last `.row { border-bottom }` soft + `.total { border-top }` strong = double line above total |
+| HTML / PDF typography | `::after { background }` decorative rule after heading + next section's `border-top` |
+
+**Fix pattern**: remove one side of the pair. Default: keep the semantically stronger/structural
+line, drop the decorative one. For table footers specifically: `.row:has(+ .row.total) { border-bottom: none }`.
+
+### Default bias: human-messier > AI-tidy
+
+When in doubt, **cut the divider**. Real human writing is structurally messier than AI
+output—paragraphs end, new paragraphs start, and the reader infers structure from the
+writing itself. AI compulsively adds visual scaffolding (hrules, borders, ::before rules,
+card wrappers) because it feels "organized." Humans don't care, and the pattern betrays
+the generator.
+
+Heuristic: if you can remove a divider (hrule, border, `::after`, wrapper) and the adjacent
+content is still comprehensible, **remove it**. Your default should skew toward "too few
+dividers" rather than "just enough." Err on the side of typography doing the work, not
+visual bars.
+
+This heuristic applies not just to `---` in markdown but to **every CSS border declaration**
+when generating HTML/PDF drafts (DMs, proposals, reports). Count rendered horizontal lines
+per page; pairs with nothing meaningful between them are the AI tell to fix.
+
 ## Phase 6: Present and Iterate
 
 Show the draft to the user. Don't just dump it. Explain:
@@ -278,6 +388,10 @@ invoke the **`draft-learner`** skill: `/perspective-writer:draft-learner`
 This skill handles diffing, rule extraction, and updating `.claude/rules/` automatically.
 Do NOT duplicate its logic here.
 
+Each user edit begins another Revise pass. Per "Mode: Compose vs. Revise", a revision is not mere
+wording polish — before reworking the draft again, re-anchor to the prior correspondence
+(Phase 1-2). Do not skip it just because a draft already exists.
+
 ## Phase 7: Persist for Next Time
 
 After the user confirms the draft (or after tone corrections), ask:
diff --git a/plugins/perspective-writer/skills/role-calibrator/SKILL.md b/plugins/perspective-writer/skills/role-calibrator/SKILL.md
index caf063b3..64dd46bb 100644
--- a/plugins/perspective-writer/skills/role-calibrator/SKILL.md
+++ b/plugins/perspective-writer/skills/role-calibrator/SKILL.md
@@ -6,7 +6,7 @@ description: >
   "不應該用請教", "tone doesn't match my expertise", or when a draft uses deference language
   for topics where the user is the expert. Also trigger from /perspective-writer:role-calibrator directly.
 argument-hint: <role description or correction>
-allowed-tools: Read, Edit, Write, Grep, Glob
+allowed-tools: Read, Edit, Write, Grep, Glob, TaskCreate, TaskUpdate, TaskList
 ---
 
 # Role Calibrator
@@ -19,6 +19,24 @@ A single correspondence relationship has multiple **domains**. The writer might
 (business strategy) but senior in another (statistical methodology). Generic rules like "always use 請教"
 break down when the writer IS the expert on the topic being discussed.
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**在動任何事之前**先用 `TaskCreate` 為這個 stage 建 todo list：
+
+```
+TaskCreate(name="step1_identify_calibration",     description="Step 1: 從 user 輸入抽出 who / domain / current problem / desired positioning")
+TaskCreate(name="step2_read_existing_rules",      description="Step 2: Glob .claude/rules/correspondence-*.md 並 Read 出現有 rules")
+TaskCreate(name="step3_add_role_section",         description="Step 3: 加或更新「## 角色定位」section（含語氣切換表、替換詞彙）")
+TaskCreate(name="step4_update_related_sections",  description="Step 4: 檢查信件結構 / 用詞偏好 / 注意事項是否要跟著調")
+TaskCreate(name="step5_confirm_with_user",        description="Step 5: 給 user 摘要：角色對哪些 domain 是專家、哪些 domain 仍請教")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：最容易漏的是 step 4（update related sections）—— 只加「角色定位」section 卻忘了更新「信件結構」裡的「提出想請教的點」，會留下前後矛盾的 rule。TaskList 強迫 step 4 被看見。
+
+---
+
 ## Step 1: Identify the Calibration
 
 From the user's input, extract:
diff --git a/plugins/perspective-writer/skills/save-feedback/SKILL.md b/plugins/perspective-writer/skills/save-feedback/SKILL.md
new file mode 100644
index 00000000..fdce608d
--- /dev/null
+++ b/plugins/perspective-writer/skills/save-feedback/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: save-feedback
+description: >
+  Capture conversational feedback during a perspective-writer drafting session into
+  reusable rules. Trigger when user explicitly requests it (e.g. /perspective-writer:save-feedback)
+  or when they say "存 feedback" / "save what you learned" / "把這些建議記下來" mid-draft.
+  Distinct from draft-learner (which only triggers on file modification).
+argument-hint: (auto-triggered or invoked manually mid-draft)
+allowed-tools: Read, Edit, Write, Grep, Glob, TaskCreate, TaskUpdate, TaskList
+---
+
+# Save Feedback
+
+You have been triggered to capture **conversational feedback** that the user gave during a drafting session — feedback that did **not** result in a file modification (so draft-learner never ran). Your job is to scan recent conversation, extract concrete style/tone/relationship/structure rules, and persist them to `.claude/rules/`.
+
+## Why this skill exists (separate from draft-learner)
+
+`draft-learner` only triggers on a file-modification system-reminder. But in real drafting sessions, **most style feedback happens in conversation**:
+
+> 「短一點然後不要有AI感」
+> 「她是我的長輩,減少指示性論點」
+> 「段落順序按 APA 排」
+> 「太直接了,改委婉一點」
+
+When the user gives verbal feedback and the agent rewrites the file each round, **no file diff is produced**. draft-learner never fires. The feedback evaporates at session end.
+
+`save-feedback` fills that gap. User invokes it explicitly when they want a snapshot of conversational feedback baked into rules.
+
+## Step 0: Bootstrap Stage Task List(強制)
+
+```
+TaskCreate(name="step1_scan_conversation",  description="Step 1: 掃 recent 對話,找出 user 給的 style/tone/relationship/structure feedback")
+TaskCreate(name="step2_classify_feedback",  description="Step 2: 把每條 feedback 分類 (tone / relationship / structure / cultural / rejection-reason)")
+TaskCreate(name="step3_extract_rules",      description="Step 3: 把每條 feedback 轉成具體可重用的 rule (一條 feedback 一個 rule)")
+TaskCreate(name="step4_locate_rules_file",  description="Step 4: Glob 找 .claude/rules/ 現有檔;沒有就建議 path")
+TaskCreate(name="step5_write_rules",        description="Step 5: Edit 既有檔(避免重複)或 Write 新檔")
+TaskCreate(name="step6_confirm_with_user",  description="Step 6: 給 user 簡短摘要 (學到 N 條,存到哪)")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+---
+
+## Step 1: Scan Conversation for Feedback
+
+Read recent messages (last ~20 turns or since the perspective-writer session started). Look for:
+
+| Pattern | Examples |
+|---------|----------|
+| **Tone correction** | 「太直接」「太 AI」「太正式」「太硬」「短一點」 |
+| **Relationship context** | 「她是長輩」「他是合作者」「我們很熟」「日本文化要委婉」 |
+| **Structure preference** | 「按 APA 排」「先講結論」「用 bullet 不要長句」「加數字」 |
+| **Cultural calibration** | 「日文書信不能直接 say no」「中文不要用破折號」 |
+| **Rejection of a draft** | 「這版不行,太...」「重寫,這次要更...」 |
+| **Negation patterns** | 「不要 X」「避免 Y」「除非...否則...」 |
+
+Skip pure factual corrections (「這個日期錯了」/「拼字錯」)— 那些是 content fix,不是 style rule。
+
+## Step 2: Classify Each Feedback
+
+每條 feedback 標 1-2 個 tag:
+
+- `tone` — 語氣強度、AI 感、商業化程度
+- `relationship` — 跟收件人的關係(長輩 / 同輩 / 學生 / 客戶)
+- `structure` — 段落順序、列表 vs 散文、長度上限
+- `cultural` — 跨文化的書信慣例
+- `negation` — 「絕對不要 X」這類禁忌
+- `format` — 格式偏好(無破折號、無 emoji 等)
+
+## Step 3: Extract Concrete Rules
+
+每條 feedback **必須**轉成可重用的 rule。不要寫「be more formal」這種沒用的模糊 rule。
+
+### BAD (太模糊):
+- 「Be appropriate for the audience」
+- 「Use natural tone」
+- 「Match cultural conventions」
+
+### GOOD (具體):
+- 「對日本長輩:避免直接的「請你做 X」,改用「もしご都合がよろしければ、Xをお願いできますでしょうか」這類緩衝句」
+- 「APA 段落順序:Background → Method → Results → Discussion;reorder if user wrote out of order」
+- 「中文書信不用破折號(——),改用句號分句」
+
+### Inferring WHY (重要)
+
+如果 user 給 feedback 但沒解釋原因,**推測背後的 invariant**:
+- 「她是長輩」 → 推測 invariant 「對方權力位階高,需要 buffer / hedging」
+- 「太 AI 感」 → 推測 invariant 「避免 elaborate parallel structures、過度使用 bullet、過度修飾」
+
+把 invariant 寫進 rule 的 **Why** 欄位,這樣未來 reader 知道何時 apply / 何時例外。
+
+## Step 4: Locate Rules File
+
+```bash
+ls .claude/rules/*.md 2>/dev/null
+```
+
+### 命名慣例
+
+- 對特定 recipient 的 rules → `recipient-{name}.md` (e.g. `recipient-tatsuma.md`、`recipient-japanese-elders.md`)
+- 對 document type 的 rules → `style-{type}.md` (e.g. `style-academic-jp.md`、`style-recommendation-letter.md`)
+- 通用 anti-patterns → `anti-patterns.md`
+
+### 已有檔 vs 新建
+
+- 既有檔的 topic 與本次 feedback overlap → Edit 加新 rules,**不重複既有 rules**
+- 完全新主題 → Write 新檔
+- 不確定 → 詢問 user 哪個 path
+
+## Step 5: Write Rules File
+
+格式:
+
+```markdown
+# Recipient: tatsuma (日本琉球大學合作者)
+
+## Tone
+- 對長輩 / senior 合作者:用 です/ます 體 + 緩衝句(「もしご都合がよろしければ」)。**Why**:日本書信對 senior 必須加 hedging,直接 imperative 視為失禮
+- 不用「請你 X」直接句:改 「Xをお願いできますでしょうか」
+
+## Structure
+- 段落順序:greeting → context → main request → closure。**Why**:APA-like 順序在跨文化書信也通用,user 偏好
+
+## Anti-patterns
+- ❌ 破折號 「——」 — user 明示「太 AI 感」
+- ❌ 長段落含多個 bullet — 改散文敘述
+- ❌ 「我們建議...」這類 directive 語氣
+```
+
+每條 rule 帶 `**Why**` 句子,讓未來 reader 判斷 edge case。
+
+## Step 6: Confirm With User
+
+簡短回報:
+
+```
+✓ 從對話擷取 N 條 feedback,存到 .claude/rules/recipient-tatsuma.md:
+  - tone: 3 條 (緩衝句 / です ます / 避免 directive)
+  - structure: 1 條 (APA-like 段落順序)
+  - anti-patterns: 2 條 (破折號 / bullet)
+
+下次起草給 tatsuma 的信時,perspective-writer 自動套用這些 rules。
+要我順便把這些 rules 跟 draft-learner 已存的 rules merge 嗎?
+```
+
+---
+
+## Important Guardrails
+
+- **DO NOT scan beyond perspective-writer session**:只擷取本次 drafting session 的 feedback,不掃整個對話歷史
+- **DO NOT invent rules from agent's own decisions**:只擷取 user 明確說的 feedback,不把 agent 自己「猜對方喜歡這樣」的決策寫成 rule
+- **DO NOT overwrite existing rules silently**:既有 rule 與本次 feedback 衝突 → 詢問 user 哪個對
+- **DO ask for tag if ambiguous**:無法歸類的 feedback (e.g. 「這版比較好」沒說為什麼) → 詢問 user 是 tone / structure / 其他
+
+## When to invoke
+
+- `/perspective-writer:save-feedback` — explicit invocation
+- User says 「存 feedback」「save what you learned」「把這些建議記下來」mid-draft
+- End of perspective-writer session if user gave 3+ rounds of conversational feedback (proactive suggestion: 「我注意到你給了不少 feedback,要 save 起來嗎?」)
+
+## Distinct from draft-learner
+
+| | draft-learner | save-feedback |
+|---|---|---|
+| Trigger | file-modification system-reminder | explicit invocation |
+| Source | file diff | conversation history |
+| Scope | per-file change | per-session feedback |
+| Output | rules in `.claude/rules/` | rules in `.claude/rules/` |
+| Run order | automatic | manual / proactive suggestion |
+
+兩個 skill **互補**,可同時跑。draft-learner 抓 file edit 的明顯改動,save-feedback 抓對話裡 user 沒動手只口頭說的偏好。
diff --git a/plugins/plugin-tools/.claude-plugin/plugin.json b/plugins/plugin-tools/.claude-plugin/plugin.json
index 1fd5e520..5c0222df 100644
--- a/plugins/plugin-tools/.claude-plugin/plugin.json
+++ b/plugins/plugin-tools/.claude-plugin/plugin.json
@@ -1,8 +1,16 @@
-{
-  "name": "plugin-tools",
-  "version": "1.7.0",
-  "description": "Claude Code Plugin 完整生命週期工具：plugin-create、plugin-deploy、plugin-update、plugin-health、plugin-debug",
-  "author": { "name": "Che Cheng" },
-  "license": "MIT",
-  "keywords": ["plugin", "marketplace", "update", "sync", "management"]
-}
+{
+  "name": "plugin-tools",
+  "version": "1.17.0",
+  "description": "Claude Code Plugin 完整生命週期工具：plugin-create、plugin-upgrade、plugin-deploy、plugin-update、plugin-health、plugin-debug. v1.17.0 (#66): plugin-update 新增 (a) Phase 0.3 Sync Intent Gate — pre-flight 偵測 binary-backed plugin、比對 marketplace.json drift + 30 天內 shell 改動 + binary repo `main` 是否超前 last release;nothing-to-sync 案例 abort early (no-op short-circuit),救 v1.16.0 之前「跑了 plugin-update 卻什麼都沒同步」的盲點;(b) Phase 1.5 Step 2 新增 Signal 2 (binary repo main vs last release drift) — git -C <binary-repo> log v$BINARY_VERSION..main 偵測 [Unreleased] backlog,提示先 cd binary repo 跑 release.sh + bump binary_version。v1.16.0 (#60): plugin-update Phase 0.5 git-state preview + 5-case AskUserQuestion confirmation gate(clean+0/clean+N/dirty+0/dirty+N/diverged),idd-all unattended mode auto-abort,cross-plugin commits warn-only(Tier A;Tier C scope guard 留給 #65)。",
+  "author": {
+    "name": "Che Cheng"
+  },
+  "license": "MIT",
+  "keywords": [
+    "plugin",
+    "marketplace",
+    "update",
+    "sync",
+    "management"
+  ]
+}
diff --git a/plugins/plugin-tools/CHANGELOG.md b/plugins/plugin-tools/CHANGELOG.md
new file mode 100644
index 00000000..5b4da591
--- /dev/null
+++ b/plugins/plugin-tools/CHANGELOG.md
@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.16.0] - 2026-05-10
+
+### Added
+- **`plugin-update` Phase 0.5 git-state confirmation gate (#60)**:在 Phase 0(detect marketplace)與 Phase 1(detect changes)之間插入新 phase。讀 only preview block 顯示 `git status --short` + `git log origin..HEAD` + divergence count,接 5-case AskUserQuestion dispatch:
+  - **Case A** clean + 0 unpushed → abort with "nothing to push"(trivially correct)
+  - **Case B** clean + N unpushed → default `push N as-is`(unambiguous happy path)
+  - **Case C** dirty + 0 unpushed → default `abort`(skill 不擅自決定要 commit 什麼);options: stage-all / manual-stage-subset / abort
+  - **Case D** dirty + N unpushed → default `abort`(4 種 sensible 動作對應不同意圖,user 必須明確選);options: push-N-leave-dirty / amend-into-HEAD / commit-as-new-commit / abort
+  - **Case E** origin diverged → default `abort`(conflict resolution 是 user 的工作);options: fetch+rebase+push / fetch+merge+push / abort
+- **idd-all unattended mode handler**:env var detect → auto-abort with structured error,return non-zero exit。idd-all 在 final report 標 "plugin-update skipped under unattended mode"。同 idd-diagnose Step 3.4 F unattended pattern。
+- **Cross-plugin commits warn-only**(Tier A scope):若 unpushed commits touch 多個 plugin,heads-up print only(不 refuse)。Active scope guard 留給 follow-up issue #65。
+- **Edge case abort handling**:detached HEAD / no upstream tracking / incomplete rebase-merge state → 各自 abort with structured error,don't try to handle。
+
+### Changed
+- **`plugin-update` Phase 1 Step 2 deprecated → reference**:既有 lines 93-106 的 narrative advisory「請先 commit + push」(沒實際 gate)替換為 one-liner 指向 Phase 0.5。Pre-v1.16.0 此 step 印 `git status` 後接 reminder text,AI executor 可以 print 後繼續;v1.16.0 升格為 explicit AskUserQuestion 5-case dispatch。
+- **Step 0 stage TaskList** 新增 `git_state_gate` 條目,排在 `detect_marketplace` 之後、`detect_changes` 之前。
+
+### Notes
+- Plugin minor bump 1.15.0 → 1.16.0(new feature surface,additive,backward compat — explicit-pin user 行為不變)。Plan 走 IDD `/idd-plan #60` approval gate,EnterPlanMode 已 user-approved 後才 chain to implement。
+- **Tier A only** scope:Tier B(commit message auto-draft + dialog)+ Tier C(active cross-plugin scope guard with `marketplace.json` allowlist)deferred until Tier A UX validated。
+- **Relationship to IDD `pr_policy`**:orthogonal axes — `pr_policy` 控制 development-time PR-vs-direct-commit 決定(during `idd-implement`);Phase 0.5 控制 release-time push-or-abort 決定(during `plugin-update`)。Phase 0.5 不 consult / 不 override `pr_policy`,documented 在 phase intro。
+- Out-of-scope follow-ups already filed:**#63** (apply pattern to plugin-deploy / plugin-create — same plugin-tools family);**#65** (apply pattern to mcp-tools:mcp-deploy / cli-tools:cli-deploy — cross-marketplace);**#64** (CHANGELOG `[1.15.0]` placeholder date drift,pre-existing,unrelated);**#58** (post-marketplace-sync stale-MCP-PID warning,complementary lifecycle-end angle)。
+
+## [1.15.0] - 2026-04-26
+
+### Added
+- **README Freshness Gate v2** — 從 3 信號擴展到 6,新增 3 偵測 + 2 suppressions,從跨 28 plugin 大規模 audit 萃取的盲點(commit `60f8cab`):
+  - **s4 Component inventory drift**:每個 `skills/` / `agents/` / `commands/` 下的 component 必須在 README 被 reference(backtick / slash / namespaced slash / agent at-form / bold list 任一)。Catches issue-driven-dev 5 listed vs 10 actual + mcp-tools 漏列 mcp-issue/mcp-publish/mcp-to-plugin。
+  - **s5 Tool count drift**:parse `(N tools)` / `(N MCP tools)` / `Available Tools (N)` / `N 個工具` from README header,對比 plugin.json description 的 tool count 宣稱。Catches che-ical-mcp(README 說 20、description 說 28)。
+  - **s6 Version history multi-version gap**:scan git log 找最近 90 天 same-major versions,對比 README Version History table。容忍 1 個 missing(可能 patch / internal),2+ 同 major missing 觸發 gate。Catches che-duckdb-mcp(v2.0 → v2.2.1 中 v2.1.0/v2.1.1/v2.2.0 漏列)。
+- **2 suppressions**:
+  - `no-version-section` — plugin 刻意不維護 Version History section 時 suppress version-related signals
+  - `wrapper-only / marketplace-sync / version-bump commits` — commits 只動 `bin/*-wrapper.sh`、`marketplace.json` sync、或 `plugin.json` version field 視為 distribution maintenance(非 substantive 改動),不觸發 README staleness gate。Filters commit message patterns 含 `(fix|chore|docs)(.*)(version-aware auto-download|sync marketplace.json|update repo URLs|wrapper)` 與 path patterns `wrapper.sh` / `marketplace.json` / `plugin.json` version。Catches `1a4c1fe` wrapper-update commit 同時 touch 9 個 plugin 但對 user 不可見的情境。
+
+### Notes
+- Backfilled per **#64** (sister concern from #60) — original v1.15.0 release on 2026-04-26 used `changelog-tools:changelog-init` placeholder `(date unknown — please fill in)` 而沒填入。Date verified via `git show -s 60f8cab`;description detail backfilled from commit body + original `marketplace.json` description。
diff --git a/plugins/plugin-tools/CLAUDE.md b/plugins/plugin-tools/CLAUDE.md
index fe29198a..cfe4ef31 100644
--- a/plugins/plugin-tools/CLAUDE.md
+++ b/plugins/plugin-tools/CLAUDE.md
@@ -44,3 +44,9 @@ plugin-create → 開發/測試 → plugin-update → plugin-deploy → plugin-h
     ↑                                              |
     └── 有問題？ ←─────────────────────────────────┘
 ```
+
+## Rules
+
+| Rule | 何時適用 |
+|------|---------|
+| [mcp-binary-distribution.md](rules/mcp-binary-distribution.md) | MCP Server 是編譯型 binary（Swift / Rust / Go…）— 必須走 GitHub Release + wrapper 自動下載，否則修 bug 使用者收不到 |
diff --git a/plugins/plugin-tools/README.md b/plugins/plugin-tools/README.md
index 55d4c22f..f9d11939 100644
--- a/plugins/plugin-tools/README.md
+++ b/plugins/plugin-tools/README.md
@@ -20,11 +20,48 @@ Claude Code Plugin 完整生命週期工具。
 | Skill | 用途 |
 |-------|------|
 | `plugin-create` | 建立新 plugin 或從現有 skill 轉換（含 marketplace 同步、CLAUDE.md、GitHub Issue） |
+| `plugin-upgrade` | 改善現有 plugin 的能力（匯入 rules/skills、補 hooks 格式、重生 CLAUDE.md）|
 | `plugin-deploy` | 發布到 Anthropic 官方 marketplace（pre-flight check + 開啟提交頁） |
 | `plugin-update` | 修改 plugin 後同步到 marketplace + 更新安裝 |
 | `plugin-health` | 檢查所有已安裝 plugin 的健康狀態 |
 | `plugin-debug` | 深度除錯單一 plugin 的問題 |
 
+### README Freshness Gate（v1.13.0）
+
+`plugin-update` 和 `plugin-deploy` 都會檢查 `README.md` 是否跟上 `plugin.json` 版本 / 新工具 / CHANGELOG：
+
+| Skill | Stale 時行為 | 理由 |
+|-------|-----------|------|
+| `plugin-update` Phase 2.5 | **ASK**（三選項：更新 / 已 OK / 稍後）| 日常同步常有 README 暫時落後 |
+| `plugin-deploy` Step 2.6 | minor/major bump → **BLOCK**；patch → warn | 正式發布 = 文件必須對齊版本號 |
+
+偵測信號：README 沒提到新版本字串、README mtime 早於 code 改動、CHANGELOG 最新 entry 版本沒進 README。
+
+### Tool README Sync Rule（v1.14.x）
+
+跨 `mcp-tools` / `cli-tools` / `plugin-tools` 共用的 rule：每次新增 / 重命名 / 刪除工具時，必須同步：
+
+1. Plugin 內的 `skills/<name>/SKILL.md`
+2. 該 plugin 的 `README.md` 工具表格（含工具數）
+3. GitHub repo 的 About metadata（v1.14.1 擴充涵蓋）
+
+`plugin-deploy` 與 `plugin-update` 的 readme-freshness check 會掃這三個來源。
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.15.0 | 2026-04-26 | README Freshness Gate v2 — 從 3 信號擴展到 **6 信號 + 2 suppressions**。新增：(4) component inventory drift（skills/agents/commands 沒進 README）、(5) tool count drift（README 寫 "20 tools" 但 plugin.json description 說 28）、(6) Version History multi-version gap（漏中間版本，不只 latest）。新增 suppressions：A) README 沒版本標記時不誤判 mtime drift；B) Wrapper-only / marketplace.json sync commits 不算 substantive 改動。從跨 28 plugin 大規模 audit 萃取的盲點。 |
+| v1.14.1 | 2026-04-22 | tool-readme-sync rule 擴充到 GitHub repo About metadata |
+| v1.14.0 | 2026-04-22 | tool-readme-sync rule（codify tool list ↔ README sync 跨 mcp-tools/cli-tools/plugin-tools）|
+| v1.13.0 | 2026-04-22 | README Freshness Gate（plugin-update Phase 2.5 ASK / plugin-deploy Step 2.6 BLOCK）|
+| v1.12.0 | 2026-04-17 | Step 0 TaskCreate bootstrap across all skills |
+| v1.11.1 | 2026-04-17 | plugin-update Phase 1.5 WARN → ASK + AUTO-SYNC |
+| v1.11.0 | 2026-04-17 | plugin-update Phase 1.5 external binary dependency check |
+| v1.10.0 | 2026-04-16 | plugin-deploy ↔ mcp-deploy integration |
+| v1.9.0 | 2026-04-16 | mcp-binary-distribution rule |
+| v1.8.0 | 2026-04-02 | plugin-upgrade skill |
+
 ## Plugin Lifecycle
 
 ```
diff --git a/plugins/plugin-tools/rules/mcp-binary-distribution.md b/plugins/plugin-tools/rules/mcp-binary-distribution.md
new file mode 100644
index 00000000..b1d8cc01
--- /dev/null
+++ b/plugins/plugin-tools/rules/mcp-binary-distribution.md
@@ -0,0 +1,244 @@
+# MCP Binary Distribution via GitHub Releases
+
+當 MCP Server 是編譯型 binary（Swift、Rust、Go…），**必須**走 GitHub Release + wrapper 自動下載，讓 plugin 版本升級 = binary 自動更新。
+
+## 為什麼
+
+| 現象 | 後果 |
+|------|------|
+| Binary 手動編譯 + 手動 copy | 修了 bug，使用者不會收到 |
+| Plugin 版本 bump 只更新 wrapper，binary 保持舊版 | 新功能宣稱了但跑不出來 |
+| Wrapper 只找本地 binary，不會 fallback 下載 | 使用者 clone repo + `swift build` 才能用 |
+
+IDD 的 `#3 → #4 → close` 跑完後，bug 已修、版本已 bump、文件已更新——但使用者端的 binary 還是舊版。這層斷裂是**自動化鏈的最後一哩**。
+
+## 三個必備元件
+
+### 1. GitHub Actions — 發 release 時自動編譯 binary
+
+```yaml
+# .github/workflows/release.yml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: macos-14  # 或對應平台
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build release binary
+        run: swift build -c release --product MyMCPBinary
+      - name: Upload to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: .build/release/MyMCPBinary
+```
+
+**觸發條件**：push `v*` tag（例如 `git tag v0.5.0 && git push --tags`）。
+
+### 2. GitHub Release — binary 當 asset
+
+Binary 必須是 release asset 而非 git-committed（太大、會撐爆 repo）。命名用 **純檔名**（`CheTelegramAllMCP`），不要加版本字尾——wrapper 下載後就是這個名字。
+
+```bash
+# 手動發 release（CI 尚未設好時）
+gh release create v0.4.1 \
+  --repo owner/repo \
+  --title "v0.4.1 — get_chat_history fixes" \
+  --notes "See CHANGELOG.md" \
+  .build/release/MyMCPBinary
+```
+
+### 3. Wrapper 自動下載邏輯
+
+參考 `che-telegram-bot-mcp-wrapper.sh`（實戰範本）：
+
+```bash
+#!/bin/bash
+BINARY_NAME="MyMCPBinary"
+GITHUB_REPO="owner/repo"
+INSTALL_DIR="$HOME/bin"
+
+# Step 1: 找 binary（多個可能路徑）
+BINARY=""
+for loc in "$INSTALL_DIR/$BINARY_NAME" "/usr/local/bin/$BINARY_NAME" \
+           "$HOME/Developer/repo/.build/release/$BINARY_NAME"; do
+    [[ -x "$loc" ]] && BINARY="$loc" && break
+done
+
+# Step 2: 找不到 → 從 GitHub Release 下載
+if [[ -z "$BINARY" ]]; then
+    echo "$BINARY_NAME not found. Downloading from GitHub..." >&2
+    mkdir -p "$INSTALL_DIR"
+    URL=$(curl -sL "https://api.github.com/repos/$GITHUB_REPO/releases/latest" \
+        | grep '"browser_download_url"' | grep "$BINARY_NAME" | head -1 \
+        | sed 's/.*"\(https[^"]*\)".*/\1/')
+    if [[ -n "$URL" ]]; then
+        curl -sL "$URL" -o "$INSTALL_DIR/$BINARY_NAME" \
+            && chmod +x "$INSTALL_DIR/$BINARY_NAME" \
+            || { echo "ERROR: Download failed." >&2; exit 1; }
+        BINARY="$INSTALL_DIR/$BINARY_NAME"
+    else
+        # Fallback：教使用者從 source 編譯
+        echo "No release found. Build from source:" >&2
+        echo "  git clone https://github.com/$GITHUB_REPO.git" >&2
+        echo "  cd repo && swift build -c release" >&2
+        exit 1
+    fi
+fi
+
+exec "$BINARY" "$@"
+```
+
+## 陷阱與對策
+
+### 1. 同名新舊 binary 混淆
+
+Wrapper 的「找本地 binary」邏輯若命中 `$HOME/Developer/.../release/` 的舊 build，會跑到舊版。
+
+**對策**：
+
+| 做法 | 適用情境 |
+|------|---------|
+| `$HOME/bin/$BINARY_NAME` 放最優先 | 一般使用者（下載的 release）|
+| Binary 支援 `--version` | 可以讓 wrapper 比對版本決定是否重新下載 |
+| 明確告知使用者 clear cache | `rm ~/bin/$BINARY_NAME` 強制重下載 |
+
+### 2. 大型 binary（含 framework）
+
+像 TDLib（~100 MB）這種 binary，release asset 可行（GitHub 限制 2 GB），但下載慢。
+
+**對策**：
+- 考慮分 framework 和 binary（framework 另外壓 `.tar.gz`）
+- CI build + `strip` 減小 binary 大小
+- 加 checksum 驗證（release notes 附 `shasum -a 256`）
+
+### 3. 平台差異
+
+MCP binary 常是 macOS only（Swift + AppleScript）或 cross-platform。
+
+**對策**：
+
+| 情境 | 做法 |
+|------|------|
+| macOS only | Asset 名稱不加平台，wrapper 檢查 `uname -s` |
+| Multi-platform | 上傳多個 asset（`-macos-arm64`、`-linux-x64`），wrapper 依 `uname` 選 |
+| 單一平台但多架構 | `lipo -create` 做 universal binary，一個 asset 就夠 |
+
+### 4. Code signing / notarization
+
+macOS binary 未簽章會被 Gatekeeper 擋。
+
+**對策**：
+- 簡單方案：wrapper 下載後自動 `xattr -dr com.apple.quarantine`
+- 正規方案：CI 用 Apple Developer certificate 簽章 + notarize（需付費帳號）
+
+## 何時不適用
+
+| 情境 | 為何跳過這個 rule |
+|------|------------------|
+| Python / Node MCP（純 script） | 沒有 binary，plugin 直接帶 source |
+| Binary < 5 MB 且 platform-specific | 直接 commit 到 plugin repo 也 OK |
+| 內部使用、單一使用者 | 手動 rebuild 可接受 |
+
+## 檢查清單
+
+發布 binary-based MCP 前，確認：
+
+- [ ] GitHub Actions 在 tag push 時 build binary
+- [ ] Release workflow 上傳 binary 當 asset
+- [ ] Wrapper 有「找不到本地 → 下載 release」fallback
+- [ ] Wrapper 把 `~/bin/` 放最高優先搜尋路徑
+- [ ] README 有說明 `--version` 和手動更新方式
+- [ ] Binary release 附 checksum（`.sha256` 或 release notes 裡）
+
+## plugin-deploy ↔ mcp-deploy 依賴關係
+
+Binary-based MCP 的 deploy 有兩個 repo 要同步：
+
+```
+MCP source repo (e.g. che-msg)              Plugin marketplace repo
+        │                                       │
+        ├─ Source code                          ├─ bin/wrapper.sh (引用 binary)
+        └─ mcp-deploy                           └─ plugin-deploy
+              │                                       │
+              ├─ Build binary                        ├─ Bump plugin.json version
+              ├─ Create GitHub Release              ├─ Update marketplace.json
+              └─ Phase 4: bump plugin (opt-in) ──► └─ 使用者裝了就拿到新 binary
+                      ↑
+                      └── 如果跳過 Phase 4，plugin-deploy 必須 block
+```
+
+### 正確順序
+
+| 場景 | 順序 |
+|------|------|
+| **只改 MCP code（修 bug、加 tool）** | `mcp-deploy` → Phase 4 opt-in → plugin 自動 bump |
+| **只改 plugin shell（wrapper、skill、agent）** | `plugin-deploy` 即可，binary 不需動 |
+| **同時改兩邊** | 先 `mcp-deploy` 發 release，再 `plugin-deploy` |
+
+### Deploy skill 的 cross-check
+
+`plugin-tools:plugin-deploy` 的 **Step 2.5 MCP Binary Check** 會：
+
+1. 偵測 plugin 是否含 `.mcp.json`
+2. 掃 `bin/*-wrapper.sh` 抓 `BINARY_NAME` + `GITHUB_REPO`
+3. 查該 repo 的 latest release 有沒有對應 asset
+4. **沒有 → 直接 block，要求先跑 `/mcp-tools:mcp-deploy`**
+5. **有 → AskUserQuestion 確認是最新 source code 的版本**
+
+為什麼是 block 而非 warn：
+
+| 狀況 | 後果 |
+|------|------|
+| Release 沒 binary | 使用者裝新 plugin → wrapper auto-download 失敗 → plugin 完全壞掉 |
+| Release 有但過時 | 使用者跑舊 binary → 新功能用不到（silent failure）|
+
+第一種是使用者立刻發現的 hard failure，必須 block；第二種只能靠 trust + AskUserQuestion。
+
+## 擴展: 非 MCP 的 CLI-dependent plugin
+
+同樣的 dependency graph 也適用於不是 MCP 但依賴 CLI binary 的 plugin（例：[gifthub](../../gifthub) → `~/bin/gfh`）。
+
+### 訊號判斷
+
+| 訊號 | 意義 |
+|------|------|
+| `.mcp.json` 存在 | MCP plugin（走 mcp-tools 流程）|
+| `hooks/session-start.sh` curl `api.github.com/releases` | CLI-dependent plugin（走 cli-tools 流程）|
+| Skill 引用 `~/bin/$BINARY` 但無 `.mcp.json` | CLI-dependent plugin |
+
+### 三邊 ↔ 整合
+
+```
+MCP source repo               Plugin marketplace            CLI binary repo
+   (che-msg)                  (psychquant-plugins)           (GiftHub)
+      │                              │                           │
+      ├─ mcp-deploy                  ├─ plugin-deploy            ├─ cli-deploy
+      │  (build+release              │  (Step 2.5 checks MCP)    │  (release binary)
+      │   + Phase 4 bump plugin)     │                           │
+      │                              ├─ plugin-update            └─ cli-install / cli-upgrade
+      └────── binary ready ─────────►│  (Phase 1.5 checks both   ◄─── binary ready
+                                     │   MCP and CLI, warn only)
+```
+
+### plugin-update Phase 1.5 的行為
+
+| 依賴類型 | 檢查 | 發現不同步 |
+|---------|------|-----------|
+| MCP | wrapper 引用的 binary 在 GitHub Release 裡 | **AskUserQuestion** → 選「順便更新」時自動呼叫 `/mcp-tools:mcp-deploy` |
+| CLI | `~/bin/$BINARY version` vs latest release tag | **AskUserQuestion** → 選「順便更新」時自動呼叫 `/cli-tools:cli-upgrade $BINARY` |
+| 無（純 skill/rule） | 跳過 | — |
+
+### 為什麼 plugin-update 是 ask-then-auto-sync、plugin-deploy 是 block
+
+| Skill | 觸發頻率 | 行為 | 理由 |
+|-------|---------|------|------|
+| `plugin-deploy` | 偶爾（發版時）| **BLOCK** | Release 沒 binary = 新使用者裝 plugin 就壞，必須擋 |
+| `plugin-update` | 頻繁（日常同步）| **ASK + AUTO-SYNC** | 日常同步時多數情境是想一次更新完整鏈，但要尊重「只改 shell 不動 binary」的選擇 |
+
+Plugin-update 被定位為 **dependency-aware orchestrator**——偵測到底層 binary 也該更新時，主動觸發整條 chain，而不只是提醒。但保留使用者控制權：AskUserQuestion 三個選項（順便更新 / 只更新 shell / 中止）。
diff --git a/plugins/plugin-tools/rules/tool-readme-sync.md b/plugins/plugin-tools/rules/tool-readme-sync.md
new file mode 100644
index 00000000..aacd606c
--- /dev/null
+++ b/plugins/plugin-tools/rules/tool-readme-sync.md
@@ -0,0 +1,141 @@
+# Plugin Component Surface ↔ README 同步紀律
+
+Plugin 自身的「工具面」是它匯出的 skills / agents / commands / hooks。這個集合變動時，**必須**在同一個 commit 或同一個 release 週期內更新 README。
+
+## 為什麼
+
+Plugin README 是 marketplace 卡片的延伸。讀者（人 + LLM）靠 README 判斷：
+
+| 問題 | README 要能回答 |
+|------|--------------|
+| 這 plugin 做什麼？ | Features / Overview |
+| 裝了之後我能用哪些東西？ | Skills 清單 + Agents 清單 + Commands 清單 |
+| 對應工作流怎麼跑？ | Usage / Examples |
+| 和相關 plugin 怎麼區分？ | Comparison / When to use which |
+
+Plugin 的 component 一改但 README 沒動：
+
+- 新加的 skill 使用者不知道它存在 → 沒人叫 → 做白工
+- 移除的 skill README 還寫著 → 使用者叫了但找不到 → 回報 bug
+- Skills 之間職責分工改動（例如把功能從 A skill 搬到 B skill）→ 舊 README 的決策樹誤導
+
+## 觸發條件
+
+滿足任一即啟動：
+
+1. **新增 skill / agent / command / hook**
+2. **移除 / rename 上述任一**
+3. **Skill 的 description 重大改寫**（因為 description 決定 LLM 何時叫它）
+4. **Skill 之間職責重分配**（功能從 A 搬到 B，兩邊 README 都要動）
+5. **Plugin keyword / description 在 plugin.json 改變**
+6. **依賴的 binary 或外部 plugin 改變**（例如原本依賴 mcp-X，改成內建）
+
+純 SKILL.md 內部步驟優化（2-step 改 3-step，不影響使用者感知）→ 不需動 README。
+
+## 必要的 README 改動範圍
+
+| 改動 | README 連動 |
+|------|------------|
+| 加 skill | Skills 表格 / Quick Reference / Usage Examples |
+| 加 agent | Agents 表格 + When to use this agent |
+| 加 command | Commands 表格 + 觸發語法 |
+| Skill 之間職責重劃 | 「Skill 比較表」或 Decision tree |
+| 依賴其他 plugin | Prerequisites / Related plugins |
+| 重大重構（v1 → v2） | Migration section |
+
+## Plugin 家族的「橫向同步」責任
+
+`plugin-tools` / `mcp-tools` / `cli-tools` 這種**家族 plugin**有額外義務：
+當其中一個 plugin 的 `*-deploy` skill 規則改了（例如 `mcp-deploy` 加了 Step 2.6 README check），
+它的 sibling（`cli-deploy`、`plugin-deploy`）如果適用同樣的 pattern，**應該同步加**。
+
+否則會出現「MCP 的 deploy 會檢查 README，CLI 的 deploy 不會」這種隱性不對稱，踩坑的是未來的自己。
+
+## Deploy 前的自我檢查
+
+`plugin-deploy` skill 跑完**前**做這個檢查：
+
+```bash
+# 實際有的 components
+ACTUAL_SKILLS=$(ls plugins/$PLUGIN/skills/ 2>/dev/null | sort)
+ACTUAL_AGENTS=$(ls plugins/$PLUGIN/agents/*.md 2>/dev/null | xargs -n1 basename | sort)
+ACTUAL_COMMANDS=$(ls plugins/$PLUGIN/commands/*.md 2>/dev/null | xargs -n1 basename -s .md | sort)
+
+# README 裡提到的 components
+DOCUMENTED=$(grep -oE '`[a-z_-]+`' plugins/$PLUGIN/README.md | sort -u)
+
+# 找出 README 沒提到的 actual component
+for s in $ACTUAL_SKILLS; do
+  grep -q "\`$s\`" plugins/$PLUGIN/README.md || echo "⚠️ Skill '$s' 不在 README"
+done
+```
+
+## 當 README 落差已累積時的補救
+
+1. **用 `ls skills/ agents/ commands/` 做 ground truth**，逐一檢查 README 是否列齊
+2. **Skills 表格重建** — 每個 skill 的 description frontmatter 抓出來對照 README
+3. **Agent 描述重建** — agent 描述是判斷「這個 agent 是否應該被叫」的關鍵，對照 README 確保對齊
+4. **Version History 表格補齊** — 把中間遺漏的 minor 版本補上，寫明當時加了什麼
+
+## GitHub Repo About Metadata（和 README 同等級的使用者第一印象）
+
+**重要提醒**：多數 plugin 沒有自己的 repo（都住在 `psychquant-claude-plugins` 這個 monorepo 底下）。這個章節主要適用於：
+
+1. **Marketplace repo 本身**（`psychquant-claude-plugins`）— 整個 marketplace 的 About
+2. **含 binary 的 plugin 家族** — 例如 `che-word-mcp` plugin 對應的 `PsychQuant/che-word-mcp` repo
+3. **從 monorepo 拆出去的獨立 plugin repo** — 極少數情況
+
+對於住在 monorepo 裡的 plugin，plugin 自身沒有 repo metadata 可改；但 plugin 的存在**可能要反映到 marketplace repo 的 description**（例如 marketplace 裡裝的 plugin 從 15 個變 25 個，description 可能要更新）。
+
+### Plugin 對應的 binary repo（最常見的情況）
+
+當 plugin 包 MCP binary（`che-word-mcp-wrapper.sh` → `~/bin/CheWordMCP`）時，**binary repo 的 About metadata** 才是使用者主要會看到的。規則見 `mcp-tools/rules/tool-readme-sync.md` 的 GitHub Repo About Metadata 章節。
+
+### Marketplace repo 的 About（如果你是 maintainer）
+
+| 欄位 | 位置 | 應該同步的時機 |
+|------|------|-------------|
+| **Description** | `gh repo view PsychQuant/psychquant-claude-plugins --json description` | 加了新 plugin 類別（如第一個 OCR plugin、第一個 bioinformatics plugin）|
+| **Topics** | 同上 | 隨 plugin 家族成長；例如首次加入 `rust-plugin` 類型就該加 `rust` topic |
+| **Homepage URL** | 同上 | 通常指 marketplace 首頁或 docs 網站 |
+
+範例 marketplace description 模板：
+
+```
+Curated Claude Code plugins marketplace with N plugins — MCP servers (Word / PPTX / Calendar / ...), dev tools (IDD / Spectra / TDD), CLI toolkits. Swift / TypeScript / Python. Optimized for {domain focus}.
+```
+
+### 為什麼這條對 plugin-tools 特別重要
+
+`plugin-deploy` / `plugin-update` skill 跑完後通常會 push 到 marketplace repo。當 plugin 數量從 20 → 30 時，marketplace description 不會自己更新——必須有人記得。本 rule 就是那個「記得」的點。
+
+### Deploy 前的 marketplace 審計
+
+```bash
+# 抓實際 plugin 數量
+PLUGIN_COUNT=$(ls -d /Users/che/Developer/psychquant-claude-plugins/plugins/*/ | wc -l | tr -d ' ')
+
+# marketplace repo description 是否反映
+CURRENT_DESC=$(gh repo view PsychQuant/psychquant-claude-plugins --json description -q .description)
+echo "$CURRENT_DESC" | grep -qE "[0-9]+ plugins" || echo "⚠️ Marketplace description 沒提到 plugin 總數"
+
+# topics 數量
+TOPIC_COUNT=$(gh repo view PsychQuant/psychquant-claude-plugins --json repositoryTopics -q '.repositoryTopics | length')
+[ "$TOPIC_COUNT" -ge 5 ] || echo "⚠️ Marketplace topics 只有 $TOPIC_COUNT 個（建議 15-20）"
+```
+
+## 例外
+
+- 純 rule 修改或 bug fix（SKILL.md 內部小改，沒加減 component）→ README / Description / Topics 皆不用動
+- 未發佈到 marketplace 的 WIP plugin → README 可延後；但 push 前要補
+- 住在 monorepo 裡的 plugin（沒獨立 repo）→ 不需要自己改 About metadata，但要注意 marketplace repo 是否被此 plugin 的加入改變了定位
+
+## 和其他 skill 的關係
+
+- `plugin-deploy` Step 2.6 做 component inventory 對照，不一致時 **BLOCK** 發布
+- `plugin-upgrade` 建議加新 skill 時，會提醒「README Skills 表格要補 1 行」
+- `plugin-create` scaffold 直接產出含 Skills / Agents / Commands 三區塊的 README 骨架
+
+## TL;DR
+
+**改了 `skills/` `agents/` `commands/` 任一個目錄，就改 README；README 沒改就不要 bump 版本、不要 push。**
diff --git a/plugins/plugin-tools/skills/plugin-create/SKILL.md b/plugins/plugin-tools/skills/plugin-create/SKILL.md
index 45216234..a3fd69c4 100644
--- a/plugins/plugin-tools/skills/plugin-create/SKILL.md
+++ b/plugins/plugin-tools/skills/plugin-create/SKILL.md
@@ -33,7 +33,27 @@ allowed-tools:
 
 ## Execution Steps
 
-### Step 0: Parse Arguments
+### Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="parse_arguments", description="解析 $ARGUMENTS 決定 New/Convert mode")
+TaskCreate(name="gather_info", description="AskUserQuestion 蒐集 plugin name / description / category / skills")
+TaskCreate(name="locate_marketplace", description="找到 plugin marketplace repo（psychquant 或 local）")
+TaskCreate(name="create_directory_structure", description="mkdir plugins/{name}/{.claude-plugin,skills,...}")
+TaskCreate(name="create_plugin_json", description="寫 .claude-plugin/plugin.json")
+TaskCreate(name="create_or_convert_skills", description="New: 建空 skills / Convert: 從 .claude/skills 轉換")
+TaskCreate(name="generate_claude_md", description="寫 plugin CLAUDE.md 列出所有組件")
+TaskCreate(name="sync_marketplace_json", description="加入 marketplace.json 的 plugins 陣列")
+TaskCreate(name="commit_push", description="git add + commit + push marketplace repo")
+TaskCreate(name="install_plugin", description="claude plugin install {name}@marketplace")
+TaskCreate(name="create_github_issue", description="（可選）建追蹤 issue 紀錄這個 plugin 的 roadmap")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+### Step 0.5: Parse Arguments
 
 ```
 $ARGUMENTS 格式：
diff --git a/plugins/plugin-tools/skills/plugin-debug/SKILL.md b/plugins/plugin-tools/skills/plugin-debug/SKILL.md
index 118fc15a..7cdd3790 100644
--- a/plugins/plugin-tools/skills/plugin-debug/SKILL.md
+++ b/plugins/plugin-tools/skills/plugin-debug/SKILL.md
@@ -23,6 +23,25 @@ allowed-tools:
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 stage-level todo list：
+
+```
+TaskCreate(name="identify_plugin", description="Phase 1: 確定要 debug 的 plugin + 找所有相關路徑（source / installed / cache）")
+TaskCreate(name="check_version_consistency", description="Phase 2: 比對 source vs cache / diff 源碼差異 / 找舊版殘留")
+TaskCreate(name="analyze_hooks", description="Phase 3: 列出所有 hook events + 分析副作用（特別是 chflags/xattr）")
+TaskCreate(name="trace_runtime_behavior", description="Phase 4: 重現問題 + trace script 執行 + 檢查 exit code")
+TaskCreate(name="identify_root_cause", description="Phase 5: 歸納根因（版本錯亂 / hook 誤觸 / 權限 / 格式）")
+TaskCreate(name="propose_fix", description="Phase 6: 列出修復步驟，建議用 plugin-update 或手動處理")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：debug 是探索性流程，很容易跳步驟「直接看 hook」忽略版本問題。Task list 強迫走完每個 phase，避免誤判根因。
+
+---
+
 ## Phase 1: 鎖定目標
 
 ### Step 1: 確定 Plugin
diff --git a/plugins/plugin-tools/skills/plugin-deploy/SKILL.md b/plugins/plugin-tools/skills/plugin-deploy/SKILL.md
index ccec96e0..15d1550d 100644
--- a/plugins/plugin-tools/skills/plugin-deploy/SKILL.md
+++ b/plugins/plugin-tools/skills/plugin-deploy/SKILL.md
@@ -25,6 +25,28 @@ allowed-tools:
 
 ## Execution Steps
 
+### Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 stage-level todo list：
+
+```
+TaskCreate(name="identify_plugin", description="Step 1: 從 $ARGUMENTS 找 plugin 目錄")
+TaskCreate(name="preflight_checks", description="Step 2: 跑必要 + 建議項目檢查")
+TaskCreate(name="mcp_binary_check", description="Step 2.5: 若是 MCP plugin，驗證 binary 在 GitHub Release 裡（不在則 BLOCK）")
+TaskCreate(name="readme_freshness_gate", description="Step 2.6: README 是否跟上 plugin.json 版本 / 新工具；minor/major bump stale → BLOCK")
+TaskCreate(name="present_checklist", description="Step 3: 顯示結果，讓使用者決定繼續或修問題")
+TaskCreate(name="fix_issues", description="Step 4: 若使用者選修問題，處理 README/LICENSE/hooks 等")
+TaskCreate(name="version_bump", description="Step 5: patch/minor/major bump plugin.json + marketplace.json")
+TaskCreate(name="update_marketplace_json", description="Step 6: 同步 marketplace.json 確認 version / description")
+TaskCreate(name="commit_and_push", description="Step 7: git add + commit + push")
+TaskCreate(name="sync_and_reload", description="Step 8: claude plugin marketplace update + plugin update")
+TaskCreate(name="verify", description="Step 9: claude plugin list 驗證版本")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：plugin-deploy 有 10 個步驟，其中兩個是容易被跳過的關卡——Step 2.5（MCP binary 沒發布會讓新使用者下載失敗）和 Step 2.6（README 沒同步會讓使用者看到舊文件 + 新版本號的矛盾訊息）。沒 task list 容易靜默略過。
+
 ### Step 1: Identify Plugin
 
 從 `$ARGUMENTS` 取得 plugin name，找到 plugin 目錄：
@@ -49,9 +71,189 @@ PLUGIN_DIR="$MARKETPLACE_ROOT/plugins/$PLUGIN_NAME"
 | 至少一個 skill 或 command | 掃描 `skills/` 和 `commands/` | 必要 |
 | 每個 SKILL.md 有 description | 讀取 frontmatter | 必要 |
 | README.md 存在 | 檔案存在 | 建議 |
+| **README.md 與新版本同步** | 見 Step 2.6 | **minor / major bump 必要**；patch 建議 |
 | CLAUDE.md 存在 | 檔案存在 | 建議 |
 | 無硬編碼絕對路徑 | grep `/Users/` 等 | 建議 |
 | hooks 用 ${CLAUDE_PLUGIN_ROOT} | grep hooks 中的路徑 | 如有 hooks |
+| **MCP binary 已發布到 release** | 見 Step 2.5 | **MCP plugin 必要** |
+
+### Step 2.5: MCP Binary Check（MCP plugin 必跑）
+
+如果 plugin 包含 MCP server wrapper（透過 `.mcp.json` + `bin/*-wrapper.sh`），**必須**驗證 wrapper 所引用的 binary 已發布到 GitHub Release，否則使用者裝新版 plugin 也拿不到對應的 binary。
+
+**歷史脈絡**：plugin version bump 只更新 wrapper + marketplace.json，不會自動 trigger MCP binary 的 rebuild + release。若此步沒做好，使用者端會出現「plugin 顯示 vX.Y.Z，但跑的是舊 binary」的詭異狀態。
+
+```bash
+# 1. 偵測是否為 MCP plugin
+MCP_JSON="$PLUGIN_DIR/.mcp.json"
+if [ ! -f "$MCP_JSON" ]; then
+    echo "Not an MCP plugin — skip Step 2.5"
+    IS_MCP_PLUGIN=false
+else
+    IS_MCP_PLUGIN=true
+fi
+
+# 2. 若是 MCP plugin，掃 bin/ 下的 wrapper 抓 BINARY_NAME + GITHUB_REPO
+if [ "$IS_MCP_PLUGIN" = "true" ]; then
+    MCP_STALE=false
+    for wrapper in "$PLUGIN_DIR/bin/"*wrapper.sh; do
+        [ -f "$wrapper" ] || continue
+        BINARY_NAME=$(grep '^BINARY_NAME=' "$wrapper" | head -1 | cut -d'"' -f2)
+        GITHUB_REPO=$(grep '^GITHUB_REPO=' "$wrapper" | head -1 | cut -d'"' -f2)
+        [ -z "$BINARY_NAME" ] && continue
+        [ -z "$GITHUB_REPO" ] && continue
+
+        # 3. 查詢該 repo 的 latest release 是否含對應 binary asset
+        HAS_BINARY=$(curl -sL "https://api.github.com/repos/$GITHUB_REPO/releases/latest" \
+            | grep '"browser_download_url"' | grep -c "/$BINARY_NAME\"" || true)
+
+        if [ "$HAS_BINARY" = "0" ]; then
+            echo "❌ BLOCKER: $BINARY_NAME not found in latest release of $GITHUB_REPO"
+            echo "   Wrapper will fail to auto-download. Run mcp-deploy first:"
+            echo "   cd <MCP-source-repo> && /mcp-tools:mcp-deploy"
+            MCP_STALE=true
+        else
+            echo "✅ $BINARY_NAME present in $GITHUB_REPO latest release"
+        fi
+    done
+
+    # 4. 如果有任何 binary 不在 release → BLOCK deploy
+    if [ "$MCP_STALE" = "true" ]; then
+        echo ""
+        echo "Plugin deploy blocked — MCP binary release is out of sync."
+        echo "Fix: run /mcp-tools:mcp-deploy from the MCP source repo first."
+        exit 1
+    fi
+fi
+```
+
+**用 AskUserQuestion 再確認 binary 是否為當前 source code 版本**：
+
+```
+question: "Release 有 $BINARY_NAME，但可能是舊版。source code 從那次 release 後有改動嗎？"
+options:
+  - "沒改動，release 是最新"
+  - "有改動但先 deploy plugin，之後再發 binary"
+  - "有改動，我先去跑 /mcp-tools:mcp-deploy 更新 binary"
+```
+
+**為什麼是 BLOCKER 而非 warning**：
+| 狀況 | 後果 |
+|------|------|
+| Release 沒 binary | 使用者裝新版 plugin → wrapper auto-download 失敗 → 整個 plugin 無法使用 |
+| Release 有 binary 但過時 | 使用者裝新版 plugin → 跑舊 binary → 新功能宣告了但跑不出來 |
+
+第一種是 hard failure（使用者完全 blocked），必須 block；第二種是 silent failure（使用者困惑但能跑），可以 warn。
+
+### Step 2.6: README Freshness Gate（正式發布 = README 必須同步）
+
+`plugin-update` 的 Phase 2.5 是 ASK；這裡是 **minor / major bump 的必過關卡**。原因：plugin-deploy 代表正式發布，使用者進 marketplace 裝 plugin 第一眼就是 README，stale README 代表「功能宣稱 v$NEW 但文件還停在舊版」，是公開場合的差評起點。
+
+#### 2.6.1: 分類版本 bump 類型
+
+從 `Step 5: Version Bump` 預期的新版本反推 bump 類型（patch / minor / major）。若尚未決定，可先跳到 Step 5 決定後回來。
+
+| Bump 類型 | README 要求 |
+|-----------|-----------|
+| **major** (x+1.0.0) | **MUST** — README 必須更新到新版本（通常含 breaking changes 描述） |
+| **minor** (x.y+1.0) | **MUST** — 新 skill / 新工具 / 新 command 幾乎必然需要改 README |
+| **patch** (x.y.z+1) | **SHOULD** — bug fix 若會改變行為則需更新；純內部修補可略 |
+
+#### 2.6.2: Staleness 偵測（同 plugin-update Phase 2.5 Step 1）
+
+掃六個信號（v1.15.0 起；第 4 條詳見 `rules/tool-readme-sync.md`）：
+1. README 沒出現新版本字串（套用 Suppression A：README 完全沒版本標記時跳過）
+2. README mtime 早於 skills/hooks/plugin.json 最近修改（套用 Suppression A + B：wrapper-only / marketplace 同步 commits 不算）
+3. CHANGELOG.md 最新 entry 版本在 README 中找不到
+4. **Component inventory mismatch** — 實際 `skills/` `agents/` `commands/` 目錄內容與 README 列表不符
+5. **Tool count drift** — README 標題寫的工具數（"Available Tools (N)"）跟 plugin.json description 宣稱的工具數對不上
+6. **Version history gap** — git log 顯示 shipped 過的版本中，有 2+ 個沒出現在 README 的 Version History 表格
+
+每個信號的 bash 偵測碼跟 `plugin-update/SKILL.md` Phase 2.5 Step 1 完全一致，避免兩處邏輯漂移。
+
+#### 2.6.2b: Component inventory 檢查
+
+```bash
+PLUGIN_DIR="plugins/$PLUGIN_NAME"
+
+# 實際有的
+ACTUAL_SKILLS=$(ls "$PLUGIN_DIR/skills/" 2>/dev/null | sort)
+ACTUAL_AGENTS=$(ls "$PLUGIN_DIR/agents/"*.md 2>/dev/null | xargs -n1 basename -s .md 2>/dev/null | sort)
+ACTUAL_COMMANDS=$(ls "$PLUGIN_DIR/commands/"*.md 2>/dev/null | xargs -n1 basename -s .md 2>/dev/null | sort)
+
+# README 有沒有提到
+for s in $ACTUAL_SKILLS; do
+    grep -q "\`$s\`\|/$s\b" "$PLUGIN_DIR/README.md" 2>/dev/null || echo "⚠️ skill '$s' 不在 README"
+done
+for a in $ACTUAL_AGENTS; do
+    grep -q "\`$a\`\|$a\b" "$PLUGIN_DIR/README.md" 2>/dev/null || echo "⚠️ agent '$a' 不在 README"
+done
+for c in $ACTUAL_COMMANDS; do
+    grep -q "/$c\b\|\`$c\`" "$PLUGIN_DIR/README.md" 2>/dev/null || echo "⚠️ command '$c' 不在 README"
+done
+```
+
+有任何 ⚠️ 都視為 stale 訊號 4。
+
+#### 2.6.2c: Marketplace repo About metadata 審計（WARN，不 BLOCK）
+
+多數 plugin 住在 `psychquant-claude-plugins` monorepo 底下，plugin 自己沒有獨立 repo metadata。
+但 plugin 的加入或大改可能影響 **marketplace repo** 的 About 是否還準確。
+
+```bash
+gh auth status >/dev/null 2>&1 || { echo "⚠️ gh 未登入，跳過 marketplace metadata audit"; exit 0; }
+
+cd "$MARKETPLACE_ROOT"
+MARKETPLACE_SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null)
+[ -z "$MARKETPLACE_SLUG" ] && { echo "⚠️ 非 GitHub repo 或無權限"; exit 0; }
+
+PLUGIN_COUNT=$(ls -d plugins/*/ 2>/dev/null | wc -l | tr -d ' ')
+DESC=$(gh repo view --json description -q .description)
+DESC_LEN=${#DESC}
+
+echo "Marketplace: $MARKETPLACE_SLUG"
+echo "Plugin count: $PLUGIN_COUNT"
+echo "Description ($DESC_LEN chars): $DESC"
+
+# 是否提到 plugin 總數（允許範圍模糊，不要一個個 pin 住）
+echo "$DESC" | grep -qE "[0-9]+ plugins" || echo "💡 Marketplace description 沒提到 plugin 總數，加入 '$PLUGIN_COUNT plugins' 讓新訪客秒懂規模"
+
+# Topics
+TOPIC_COUNT=$(gh repo view --json repositoryTopics -q '.repositoryTopics | length')
+[ "$TOPIC_COUNT" -lt 5 ] && echo "⚠️ Marketplace topics 太少（$TOPIC_COUNT < 5）"
+[ "$TOPIC_COUNT" -lt 15 ] && echo "💡 建議 15-20 個 topics"
+```
+
+如果這次 deploy 新增了一個**新類型**的 plugin（例如首個 Rust-based plugin、首個 Zotero 整合），
+強烈建議用 `gh repo edit --add-topic` 把對應 topic 加到 marketplace。
+
+#### 2.6.2d: Plugin 對應的 binary repo metadata（若有）
+
+當 plugin 是 MCP wrapper（`bin/*-wrapper.sh` 下載 binary）時，
+binary 對應的獨立 repo（如 `PsychQuant/che-word-mcp`）才是使用者主要看到的 About。
+這類 repo 的 metadata 屬於 `mcp-tools/rules/tool-readme-sync.md` 範疇——在 `mcp-deploy` Step 4.7 會處理。
+這裡只需確認 plugin wrapper 版本和 binary repo 對齊。
+
+#### 2.6.3: 行為決策
+
+```
+若 bump = major / minor 且 stale：
+    AskUserQuestion: "正式 deploy v$NEW 前 README 必須同步。選擇處理方式："
+    options:
+      - "現在更新 README" — 我幫忙起草 → Edit → commit 後繼續 Step 3 Present Checklist
+      - "改為 patch bump，README 暫不動" — 確認此變更不含對外 surface 變動
+      - "中止 deploy" — 手動處理後再跑 plugin-deploy
+
+若 bump = patch 且 stale：
+    顯示 warning 但不 block，繼續 Step 3 Checklist
+```
+
+#### 2.6.4: 為什麼 plugin-deploy 比 plugin-update 嚴格
+
+| Skill | README stale 時 |
+|-------|---------------|
+| `plugin-update`（日常）| 三選項，略過 OK（開發過程中 README 落後一版很常見）|
+| `plugin-deploy`（發版）| minor/major bump BLOCK；patch warn（發版 = 對外承諾，文件必須 match）|
 
 ### Step 3: Present Checklist
 
@@ -80,6 +282,7 @@ PLUGIN_DIR="$MARKETPLACE_ROOT/plugins/$PLUGIN_NAME"
 
 如果有問題，幫使用者修正：
 - 缺 README.md → 從 CLAUDE.md 和 skills 自動產生
+- **README 已過時**（Step 2.6 標記 stale）→ 讀 CHANGELOG.md + `git log --oneline -n 10 -- plugins/{name}/` 當素材，提出 README diff → 使用者審閱 → Edit → commit
 - 缺 LICENSE → 建立 MIT LICENSE
 - 硬編碼路徑 → 提示修正
 
@@ -152,3 +355,13 @@ claude plugin list | grep {plugin-name}
 - 這個 skill 發布到**自己的 marketplace**（如 PsychQuant），push 即生效，不需要審核
 - 如果未來要提交到 Anthropic 官方 marketplace，目前只接受企業級合作夥伴
 - 發布前建議先用 `claude --plugin-dir` 本地測試
+
+## MCP plugin 的依賴
+
+若此 plugin 含 `.mcp.json` + `bin/*-wrapper.sh`，屬於 **binary-based MCP plugin**：
+
+- Wrapper 執行時會自動從 GitHub Release 下載 binary
+- Plugin version bump **不等於** binary 會自動更新
+- 必須先在 MCP source repo 跑 `/mcp-tools:mcp-deploy` 發 binary release，才能跑 `plugin-deploy`
+
+詳見 [rules/mcp-binary-distribution.md](../../rules/mcp-binary-distribution.md) 的「plugin-deploy ↔ mcp-deploy 依賴關係」。Step 2.5 會自動偵測並 block 不同步的情況。
diff --git a/plugins/plugin-tools/skills/plugin-health/SKILL.md b/plugins/plugin-tools/skills/plugin-health/SKILL.md
index bfce5e8e..c0f35453 100644
--- a/plugins/plugin-tools/skills/plugin-health/SKILL.md
+++ b/plugins/plugin-tools/skills/plugin-health/SKILL.md
@@ -20,6 +20,27 @@ allowed-tools:
 
 ---
 
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 stage-level todo list：
+
+```
+TaskCreate(name="list_plugins_and_status", description="Phase 1: claude plugin list + claude plugin marketplace list")
+TaskCreate(name="check_hook_format", description="Phase 2 Check 1: 掃 hooks.json 格式錯誤")
+TaskCreate(name="check_script_permissions", description="Phase 2 Check 2: .sh 檔是否 executable")
+TaskCreate(name="check_plugin_json", description="Phase 2 Check 3: plugin.json 必要欄位")
+TaskCreate(name="check_mcp_binaries", description="Phase 2 Check 4: MCP wrapper 引用的 binary 是否存在 + universal")
+TaskCreate(name="check_directory_structure", description="Phase 2 Check 5: .claude-plugin 等目錄結構")
+TaskCreate(name="check_version_sync", description="Phase 3: marketplace.json vs installed 版本同步")
+TaskCreate(name="report_summary", description="Phase 4: 彙整所有 issue，排優先級，列修復步驟")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+**為什麼強制**：plugin-health 跑很多獨立檢查，沒 task list 容易少做（特別是 MCP binary check 和 version sync），這些 silent failure 最傷。
+
+---
+
 ## Phase 1: 取得全局狀態
 
 ### Step 1: 列出所有 plugin 和狀態
diff --git a/plugins/plugin-tools/skills/plugin-update/SKILL.md b/plugins/plugin-tools/skills/plugin-update/SKILL.md
index 1da31eef..513a442d 100644
--- a/plugins/plugin-tools/skills/plugin-update/SKILL.md
+++ b/plugins/plugin-tools/skills/plugin-update/SKILL.md
@@ -1,242 +1,973 @@
----
-name: plugin-update
-description: 更新 Plugin 到最新版本（marketplace.json 同步 + marketplace update + plugin update + 安裝檢查）。當修改了任何 plugin 原始碼後需要同步、或用戶提到「更新 plugin」、「同步 plugin」、「plugin 沒生效」、「reload plugins」時使用。
-argument-hint: [plugin-name]
-allowed-tools:
-  - Bash(git:*)
-  - Bash(claude:*)
-  - Bash(ls:*)
-  - Bash(cat:*)
-  - Bash(python3:*)
-  - Read
-  - Edit
-  - Grep
-  - Glob
-  - AskUserQuestion
----
-
-# Plugin Update — 同步與更新流程
-
-修改 plugin 原始碼後，確保變更生效的完整流程。
-
-## 為什麼需要這個？
-
-Plugin 修改後有 5 個環節容易漏掉：
-1. 忘了更新 `marketplace.json` 中的版本號（新 plugin 忘了加 entry）
-2. 忘了 commit/push 到 git remote
-3. 忘了同步 marketplace cache（`claude plugin marketplace update`）
-4. 忘了 update 已安裝的 plugin（`claude plugin update`）
-5. 忘了重啟 Claude Code 使快取生效
-
-此 skill 自動檢查並執行所有步驟。
-
----
-
-## Phase 0: 偵測 Marketplace
-
-先確定 plugin 所在的 marketplace repo。
-
-### 已知的 marketplace
-
-| Marketplace | 路徑 | 類型 |
-|-------------|------|------|
-| `psychquant-claude-plugins` | `/Users/che/Developer/psychquant-claude-plugins` | Git (GitHub) |
-| `che-local-plugins` | `/Users/che/Library/CloudStorage/Dropbox/che_workspace/projects/che-claude-config/che-local-plugins` | 本地目錄 |
-
-根據用戶指定的 plugin 名稱，從上面的 marketplace 中找到對應的 repo 路徑。
-
-```bash
-# 列出所有 marketplace
-claude plugin marketplace list 2>&1
-```
-
----
-
-## Phase 1: 偵測變更
-
-### Step 1: 確定 Plugin
-
-如果用戶指定了 plugin 名稱，直接使用。否則從 git 推斷：
-
-```bash
-cd {marketplace_repo_path}
-git diff --name-only HEAD~3 | grep '^plugins/' | cut -d/ -f2 | sort -u
-```
-
-列出最近變更的 plugin，請用戶確認要更新哪些。
-
-### Step 2: 檢查 Git 狀態
-
-```bash
-cd {marketplace_repo_path}
-git status --short -- plugins/{plugin_name}/
-```
-
-- 如果有未提交變更 → 提醒用戶先 commit + push
-- 如果已 commit 但未 push → 提醒 `git push`
-- 如果已 push → 繼續下一步
-
-```bash
-git log origin/main..HEAD --oneline
-```
-
----
-
-## Phase 2: 更新 marketplace.json（關鍵！）
-
-`marketplace.json` 位於 `{marketplace_repo_path}/.claude-plugin/marketplace.json`，是 marketplace 的 plugin index。
-**如果這個檔案沒更新，`claude plugin marketplace update` 不會看到新版本。**
-
-### Step 1: 列出 marketplace 中所有 plugin 版本
-
-```bash
-cd {marketplace_repo_path}
-cat .claude-plugin/marketplace.json | python3 -c "
-import json, sys
-data = json.load(sys.stdin)
-for p in data['plugins']:
-    print(f\"  {p['name']}: {p['version']}\")
-"
-```
-
-### Step 2: 對比 plugin.json 的實際版本
-
-```bash
-cat plugins/{plugin_name}/.claude-plugin/plugin.json | python3 -c "
-import json, sys
-d = json.load(sys.stdin)
-print(f\"plugin.json: {d['version']}\")
-"
-```
-
-如果 marketplace.json 的版本落後 plugin.json，用 Edit 工具更新 marketplace.json。
-
-### Step 3: 新 Plugin 需加入 entry
-
-如果是全新的 plugin（不在 marketplace.json 中），需要在 `plugins` 陣列加入新 entry：
-
-```json
-{
-  "name": "{plugin_name}",
-  "version": "1.0.0",
-  "description": "{description}",
-  "author": { "name": "Che Cheng" },
-  "source": "./plugins/{plugin_name}",
-  "category": "{category}"
-}
-```
-
-category 常用值：`development`、`productivity`、`creative`
-
-### Step 4: Commit + Push marketplace.json
-
-marketplace.json 的變更也需要 commit + push，才能被 `marketplace update` 抓到。
-
-```bash
-cd {marketplace_repo_path}
-git add .claude-plugin/marketplace.json
-git commit -m "chore: update marketplace.json for {plugin_name} v{version}"
-git push
-```
-
----
-
-## Phase 3: 同步 Marketplace Cache
-
-### Step 1: 更新 marketplace cache
-
-```bash
-claude plugin marketplace update {marketplace_name}
-```
-
-這會從 source（git remote 或本地目錄）重新拉取 plugin index。
-
-### Step 2: 驗證
-
-```bash
-claude plugin list 2>&1 | grep -A3 "{plugin_name}"
-```
-
----
-
-## Phase 4: 更新已安裝的 Plugin
-
-### 注意：必須加 `@marketplace_name` 後綴
-
-```bash
-# 已安裝 → 更新
-claude plugin update {plugin_name}@{marketplace_name}
-
-# 未安裝 → 安裝
-claude plugin install {plugin_name}@{marketplace_name}
-```
-
-先檢查是否已安裝：
-```bash
-claude plugin list 2>&1 | grep "{plugin_name}"
-```
-
----
-
-## Phase 5: 驗證與提醒
-
-### Step 1: 確認最終狀態
-
-```bash
-claude plugin list 2>&1 | grep -A5 "{plugin_name}"
-```
-
-檢查：
-- Version 是否已更新到目標版本
-- Status 是否 `✔ enabled`
-- 是否有 `failed to load` 錯誤
-
-### Step 2: 提醒重啟
-
-> 更新完成。請重啟 Claude Code（退出再重新開啟）讓變更完全生效。
-> 或者在下次啟動新對話時，新版 plugin 就會自動載入。
-
----
-
-## 批次更新
-
-多個 plugin 需要更新時：
-
-```bash
-# 1. 同步 marketplace（只需一次）
-claude plugin marketplace update {marketplace_name}
-
-# 2. 逐一更新（需加 @marketplace 後綴）
-claude plugin update plugin-a@{marketplace_name}
-claude plugin update plugin-b@{marketplace_name}
-```
-
----
-
-## 常見問題
-
-### Plugin 更新後 skill 沒變？
-Claude Code 有快取機制。需要重啟才能載入新版 skill 內容。
-
-### `failed to load` 錯誤？
-通常是 hooks.json 格式問題：
-```bash
-claude plugin validate {marketplace_repo_path}/plugins/{plugin_name}
-```
-
-### `marketplace update` 沒看到新版本？
-1. 確認 `marketplace.json` 的版本號已更新
-2. 確認已 push 到 remote：
-```bash
-cd {marketplace_repo_path}
-git log origin/main..HEAD --oneline
-```
-
-### `plugin update` 找不到 plugin？
-需要加 `@marketplace_name` 後綴：
-```bash
-# 錯誤
-claude plugin update my-plugin
-# 正確
-claude plugin update my-plugin@psychquant-claude-plugins
-```
+---
+name: plugin-update
+description: 更新 Plugin 到最新版本（marketplace.json 同步 + marketplace update + plugin update + 安裝檢查）。當修改了任何 plugin 原始碼後需要同步、或用戶提到「更新 plugin」、「同步 plugin」、「plugin 沒生效」、「reload plugins」時使用。
+argument-hint: [plugin-name]
+allowed-tools:
+  - Bash(git:*)
+  - Bash(claude:*)
+  - Bash(ls:*)
+  - Bash(cat:*)
+  - Bash(python3:*)
+  - Read
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Plugin Update — 同步與更新流程
+
+修改 plugin 原始碼後，確保變更生效的完整流程。
+
+## 為什麼需要這個？
+
+Plugin 修改後有 6 個環節容易漏掉：
+1. 忘了更新 `marketplace.json` 中的版本號（新 plugin 忘了加 entry）
+2. 忘了 commit/push 到 git remote
+3. 忘了同步 marketplace cache（`claude plugin marketplace update`）
+4. 忘了 update 已安裝的 plugin（`claude plugin update`）
+5. 忘了重啟 Claude Code 使快取生效
+6. **忘了同步 `README.md`**（版本 bump 但 README 仍在舊版、沒提新工具 / 新 skill，使用者看文件以為功能沒做完）
+
+此 skill 自動檢查並執行所有步驟。
+
+---
+
+## Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 stage-level todo list，每完成一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+```
+TaskCreate(name="detect_marketplace", description="Phase 0: 找到 plugin 所屬的 marketplace repo")
+TaskCreate(name="sync_intent_gate", description="Phase 0.3 (v1.17.0+): pre-flight intent check — detect binary-backed plugin; if no shell changes AND binary not bumped AND binary already at last release, abort early (no-op short-circuit)")
+TaskCreate(name="git_state_gate", description="Phase 0.5 (v1.16.0+ #60): preview git status / unpushed commits / divergence + 5-case AskUserQuestion (abort default for non-clean states); idd-all unattended → auto-abort")
+TaskCreate(name="detect_changes", description="Phase 1: 確認 plugin + 最近 commits（git status 已由 Phase 0.5 gate）")
+TaskCreate(name="check_external_deps", description="Phase 1.5: 偵測 MCP/CLI 依賴，不同步時 AskUserQuestion")
+TaskCreate(name="sync_marketplace_json", description="Phase 2: 比對 plugin.json 和 marketplace.json 版本，commit+push")
+TaskCreate(name="check_readme_freshness", description="Phase 2.5: 檢查 README 是否跟上版本 / 新工具，過時時 AskUserQuestion")
+TaskCreate(name="marketplace_update", description="Phase 3: claude plugin marketplace update")
+TaskCreate(name="plugin_install_or_update", description="Phase 4: claude plugin install/update @marketplace")
+TaskCreate(name="verify_and_report", description="Phase 5: claude plugin list 驗證 + 提醒重啟")
+```
+
+**若 Phase 1.5 使用者選「順便更新」**，補加一筆：
+```
+TaskCreate(name="invoke_dependency_skill", description="Phase 1.5 auto-sync: 呼叫 /mcp-tools:mcp-deploy 或 /cli-tools:cli-upgrade")
+```
+
+**為什麼強制**：plugin-update 有 5 個常被漏掉的環節（marketplace.json 沒更新、沒 push、cache 沒 sync、plugin 沒 update、沒重啟），task list 讓每一步都有可見證據。
+
+---
+
+## Phase 0: 偵測 Marketplace
+
+先確定 plugin 所在的 marketplace repo。
+
+### 已知的 marketplace
+
+| Marketplace | 路徑 | 類型 |
+|-------------|------|------|
+| `psychquant-claude-plugins` | `/Users/che/Developer/psychquant-claude-plugins` | Git (GitHub) |
+| `che-local-plugins` | `/Users/che/Library/CloudStorage/Dropbox/che_workspace/projects/che-claude-config/che-local-plugins` | 本地目錄 |
+
+根據用戶指定的 plugin 名稱，從上面的 marketplace 中找到對應的 repo 路徑。
+
+```bash
+# 列出所有 marketplace
+claude plugin marketplace list 2>&1
+```
+
+---
+
+## Phase 0.3: Sync Intent Gate（v1.17.0+, no-op short-circuit）
+
+> **為什麼這 phase 在 Phase 0.5 之前**：Phase 0.5 鎖的是 git state 的「敢不敢 push」決定。**0.3 鎖的是更上游的問題：你跑 plugin-update 到底是想 sync 什麼？** 如果這個問題的答案是「沒有」，跑下去純粹是 no-op + 浪費 user 時間 + 風險誤 push 別人的 unrelated commits（在 marketplace monorepo 場景特別容易發生）。
+>
+> **歷史脈絡**：早期 plugin-update 預設「跑了就是有東西要 sync」，binary-backed plugin 沒改 shell + binary 沒新 release 時走完整個 flow 卻什麼都沒同步是常見坑。今天 (v1.17.0 #66) 的 root cause 是 user 從 binary repo 跑 plugin-update 但 binary 沒 release、shell 沒改 — 純運氣靠 Phase 0.5 抓到 unrelated unpushed commits 才 abort。0.3 把這個運氣升格成顯式 gate。
+>
+> **Relationship to Phase 0.5**：0.3 處理「該不該動」，0.5 處理「怎麼安全 push」。0.3 abort → 不進 0.5；0.3 pass → 0.5 接手。
+
+### Step 1: 偵測 binary-backed plugin
+
+```bash
+PLUGIN_DIR="{marketplace_repo_path}/plugins/{plugin_name}"
+
+# Signal: .mcp.json 或 bin/*-wrapper.sh with GITHUB_REPO → MCP binary plugin
+IS_BINARY_BACKED=false
+if [ -f "$PLUGIN_DIR/.mcp.json" ]; then
+    IS_BINARY_BACKED=true
+elif ls "$PLUGIN_DIR/bin/"*-wrapper.sh 2>/dev/null | xargs grep -l GITHUB_REPO 2>/dev/null | head -1 > /dev/null; then
+    IS_BINARY_BACKED=true
+fi
+
+# Signal: hooks/session-start.sh curls GitHub API → CLI-binary plugin
+if grep -q 'api.github.com.*releases' "$PLUGIN_DIR/hooks/session-start.sh" 2>/dev/null; then
+    IS_BINARY_BACKED=true
+fi
+```
+
+**非 binary-backed plugin（純 skill / rule / agent）**：跳過 Phase 0.3，直接走 Phase 0.5。Pure-shell plugin 沒有「binary version drift」這層問題，sync intent 比較單純（要嘛 shell 改了要 push，要嘛沒改 → Phase 0.5 自然 abort）。
+
+### Step 2: 收集 sync 候選變更（binary-backed only）
+
+```bash
+# (a) 從 plugin.json 取 binary_version + shell version
+SHELL_VERSION=$(python3 -c "import json; print(json.load(open('$PLUGIN_DIR/.claude-plugin/plugin.json'))['version'])")
+BINARY_VERSION=$(python3 -c "import json; print(json.load(open('$PLUGIN_DIR/.claude-plugin/plugin.json')).get('binary_version', ''))")
+
+# (b) 比對 marketplace.json — 落後嗎？
+MP_VERSION=$(python3 -c "
+import json
+d = json.load(open('{marketplace_repo_path}/.claude-plugin/marketplace.json'))
+for p in d['plugins']:
+    if p['name'] == '{plugin_name}':
+        print(p.get('version', ''))
+        break
+")
+MP_DRIFT=$([ "$MP_VERSION" != "$SHELL_VERSION" ] && echo yes || echo no)
+
+# (c) Shell 檔案最近 N 個 commits 是否觸到此 plugin？
+cd {marketplace_repo_path}
+SHELL_RECENT_TOUCHES=$(git log --since="30 days ago" --name-only --pretty=format: \
+    -- "plugins/{plugin_name}/" 2>/dev/null \
+    | grep -v '^$' | sort -u | head -10)
+
+# (d) BINARY repo: main 是否有 unreleased commits（信號移植自 #66 Phase 1.5 強化）
+# 這裡只做 detection；warn 文案在 Step 4 統一輸出
+if [ -n "$BINARY_VERSION" ]; then
+    BINARY_REPO_PATH=$(detect_binary_repo "$PLUGIN_DIR")  # 由 Phase 1.5 detection 邏輯共用
+    if [ -d "$BINARY_REPO_PATH" ]; then
+        BINARY_UNRELEASED=$(git -C "$BINARY_REPO_PATH" log "v$BINARY_VERSION..main" --oneline 2>/dev/null | wc -l | tr -d ' ')
+    fi
+fi
+```
+
+> **`detect_binary_repo` heuristic**：從 wrapper script 抓 `GITHUB_REPO`（e.g. `PsychQuant/che-apple-mail-mcp`），然後在常見路徑下找 local clone：`$HOME/Developer/<repo>` / `$HOME/Developer/che-mcps/<repo>` / `$HOME/code/<repo>`。找不到就跳過 binary-repo-drift 信號（不 fail-stop — 信號是 best-effort）。
+
+### Step 3: Sync intent 判斷
+
+把 Step 2 收集到的信號濃縮成「真的有東西要 sync 嗎？」的 boolean：
+
+| 信號命中 | sync intent | 解讀 |
+|---------|------------|------|
+| marketplace.json 版本落後 plugin.json (`MP_DRIFT=yes`) | YES | shell 已 bump 但 marketplace 沒同步 — 經典 plugin-update use case |
+| 30 天內有 plugin 檔案 commits（`SHELL_RECENT_TOUCHES` 非空）| YES | shell 真的有改動 |
+| Binary repo `main` 超前 last release ≥ 1 commits | MAYBE | 提示「binary 有 unreleased commits — 是不是該先 mcp-deploy / release？」|
+| 全部都沒命中 | **NO** | nothing to sync — short-circuit abort |
+
+### Step 4: AskUserQuestion 4-case dispatch
+
+#### Case A: Nothing to sync → abort
+
+當 (a) `MP_DRIFT=no` AND (b) `SHELL_RECENT_TOUCHES` 為空 AND (c) `BINARY_UNRELEASED=0`：
+
+```bash
+echo "✗ Phase 0.3: Nothing to sync."
+echo "  - marketplace.json @ $MP_VERSION matches plugin.json @ $SHELL_VERSION"
+echo "  - no plugin file changes in last 30 days"
+echo "  - binary v$BINARY_VERSION matches latest release"
+echo ""
+echo "  If you intended to force a marketplace cache refresh anyway,"
+echo "  bypass plugin-update and run: claude plugin marketplace update {marketplace_name}"
+exit 0
+```
+
+#### Case B: Binary unreleased commits 是唯一信號 → AskUserQuestion
+
+當 (a) `MP_DRIFT=no` AND (b) `SHELL_RECENT_TOUCHES` 為空 AND (c) `BINARY_UNRELEASED >= 1`：
+
+```
+question: "Binary repo `main` 累積 $BINARY_UNRELEASED 個未 release 的 commits (last release: v$BINARY_VERSION)。Shell 沒改、marketplace.json 已同步。怎麼處理？"
+options:
+  - "abort, release binary first (default, recommended)"
+    description: "exit; cd <binary-repo>; ./scripts/release.sh v<next>; 完成後 bump plugin.json binary_version + 重跑 plugin-update"
+  - "proceed anyway (force shell sync only)"
+    description: "略過 binary release 提醒，繼續走 Phase 0.5+ 同步 shell（binary 仍是舊版）— 只適合純 documentation / shell-side bug fix 的情境"
+  - "abort"
+    description: "exit; 不動 anything"
+```
+
+選 `abort, release binary first` / `abort` → exit 0。
+選 `proceed anyway` → 繼續 Phase 0.5。
+
+#### Case C: Sync intent confirmed → 通過 0.3，直接進 0.5
+
+當 `MP_DRIFT=yes` OR `SHELL_RECENT_TOUCHES` 非空：正常 sync use case，print 簡短摘要後進入 Phase 0.5。
+
+```bash
+echo "→ Phase 0.3: sync intent confirmed"
+[ "$MP_DRIFT" = "yes" ] && echo "  - marketplace.json drift: $MP_VERSION → $SHELL_VERSION"
+[ -n "$SHELL_RECENT_TOUCHES" ] && echo "  - recent shell changes: $(echo "$SHELL_RECENT_TOUCHES" | wc -l) files"
+[ "$BINARY_UNRELEASED" -gt 0 ] 2>/dev/null && echo "  - binary main has $BINARY_UNRELEASED unreleased commits (see Phase 1.5 for warn detail)"
+```
+
+#### Case D: idd-all unattended → auto-decide
+
+當 plugin-update 在 `idd-all` orchestrator 下 invoke：
+- Nothing to sync (Case A) → 同樣 abort（idd-all 在最終 report 標 "plugin-update skipped: no sync intent"）
+- Binary unreleased only (Case B) → auto-abort（unattended 不該 force shell sync）+ structured error
+- Sync intent confirmed (Case C) → 繼續 Phase 0.5（0.5 自己有 unattended handler）
+
+設計同 Phase 0.5 Step 4：user-attendance-required gates 在 unattended mode 統一走 abort + audit trail。
+
+---
+
+## Phase 0.5: Git State Preview & Confirmation Gate（v1.16.0+ #60）
+
+> **為什麼這 phase 在 Phase 1 之前**:Phase 1+ 會 `git add` / `git commit` / `git push` / `claude plugin marketplace update`,**任何 state-mutating 操作開始前**,user 必須明確表態現在的 git state 是不是該 push 的。
+>
+> 既有 (pre-v1.16.0) 行為:Phase 1 Step 2 印出 `git status` 後接 narrative reminder text 「請先 commit + push」,但**沒實際 gate**,AI executor 可以印 reminder 後繼續。新 phase 把這個決定升格成 **AskUserQuestion** explicit dispatch,跟 skill 內既有 [Phase 1.5: External Binary Dependency Check](#phase-15-external-binary-dependency-check若有) + [Phase 2.5: README Freshness Check](#phase-25-readme-freshness-check) 同 pattern(用 section refs 而非 line numbers,避免後續 insert 後 stale)。
+>
+> **Relationship to IDD `pr_policy`**:`pr_policy` 控制 development-time PR-vs-direct-commit 決定(during `idd-implement`)。Phase 0.5 控制 release-time push-or-abort 決定(during `plugin-update`)。**Different lifecycle moments;Phase 0.5 不 consult / 不 override `pr_policy`**。
+
+### Step 1: Read-only Preview Block
+
+```bash
+cd {marketplace_repo_path}
+
+# Resolve upstream once + abort on missing/unusual configs (v1.16.0 fix #60-verify P1)
+# - No upstream tracking → abort with structured error (don't silently proxy to origin/main)
+# - Detached HEAD → abort
+# - Incomplete rebase/merge → abort
+if [ ! -e "$(git rev-parse --git-dir)/HEAD" ] || ! git symbolic-ref -q HEAD >/dev/null; then
+    echo "✗ Detached HEAD or invalid HEAD; checkout a branch first." >&2
+    exit 1
+fi
+GITDIR=$(git rev-parse --git-dir)
+if [ -d "$GITDIR/rebase-merge" ] || [ -d "$GITDIR/rebase-apply" ] || [ -e "$GITDIR/MERGE_HEAD" ] || [ -e "$GITDIR/CHERRY_PICK_HEAD" ]; then
+    echo "✗ Repo in incomplete rebase/merge/cherry-pick state; resolve before plugin-update." >&2
+    exit 1
+fi
+UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null) || {
+    echo "✗ No upstream tracking branch. Set with 'git branch --set-upstream-to=origin/<branch>' first." >&2
+    exit 1
+}
+# UPSTREAM is now the canonical source for all comparisons (e.g. origin/main, upstream/feat-xyz)
+
+echo "=== Git State Preview ==="
+echo ""
+echo "--- branch ---"
+git branch --show-current
+echo "(upstream: $UPSTREAM)"
+echo ""
+echo "--- working tree ---"
+git status --short
+echo "(empty = clean)"
+echo ""
+echo "--- unpushed commits (\"$UPSTREAM\"..HEAD) ---"
+git log --oneline "$UPSTREAM"..HEAD
+echo "(empty = none)"
+echo ""
+echo "--- divergence count (upstream <-> HEAD) ---"
+git rev-list --left-right --count "$UPSTREAM"...HEAD
+echo "(left = origin behind us; right = we ahead of origin; '0 0' = synced; '0 N' = ahead; 'M 0' = pure-behind; 'M N' = diverged)"
+```
+
+**Read-only by contract**:本 step **只 print + read**,不 mutate。Phase 1+ 才允許 `git add` / `git commit` / `git push`。
+
+> **Why resolve `UPSTREAM` upfront**(v1.16.0 fix #60-verify P1):earlier draft used `origin/$(... | sed 's|^origin/||' || echo main)` chain which silently fell back to `origin/main` on no-upstream / fork remote workflow,defeating the L128 spec contract. New version aborts cleanly + uses single `$UPSTREAM` variable consistently.
+
+### Step 2: State Detection (priority-ordered, v1.16.0 fix #60-verify P1)
+
+從 preview output 判斷以下 case。**Detection 是 priority-ordered,先測 divergence,再測 dirty/clean × unpushed**:
+
+| Priority | State | Detection signal |
+|----------|-------|------------------|
+| 1 (highest) | **Origin diverged** (Case E) | divergence `M N` with **M ≥ 1 AND N ≥ 1** — branches diverged, not just one-sided |
+| 2 | **Pure behind** (Case E') | divergence `M 0` with **M ≥ 1 AND N = 0** — fast-forward case, short-circuit to fetch + ff merge (no need to AskUserQuestion;just `git pull --ff-only` then re-evaluate) |
+| 3 | **Dirty + N unpushed** (Case D) | divergence `0 N` AND `git status --short` non-empty |
+| 4 | **Dirty + 0 unpushed** (Case C) | divergence `0 0` AND `git status --short` non-empty |
+| 5 | **Clean + N unpushed** (Case B) | divergence `0 N` AND `git status --short` empty |
+| 6 (lowest) | **Clean + 0 unpushed** (Case A) | divergence `0 0` AND `git status --short` empty |
+
+> **Why divergence wins** (priority 1-2 first):dirty + diverged 同時成立時,先處理 divergence(無法 push 在落後的 branch);user 可以 fetch + rebase 後再決定 dirty 怎麼處理。原 draft 把 dirty 跟 diverged 並列導致雙重匹配,新版用 priority order 消除歧義。
+>
+> **Pure-behind (Case E') 是新增 case** — origin 比 local 多 commits 但 local 無 unpushed,這是 `git pull --ff-only` 的乾淨情境;原 draft 漏列。
+
+**Edge cases all → abort with structured error**(由 Step 1 preview block 的開頭 guard 處理):
+- Detached HEAD → already aborted in Step 1
+- No upstream tracking → already aborted in Step 1
+- Incomplete rebase / merge / cherry-pick → already aborted in Step 1
+
+### Step 3: AskUserQuestion 5-case Dispatch
+
+依 detected state 跑對應的 AskUserQuestion。**Default option = `abort` for any state with multiple sensible actions**;`push as-is` 只在 unambiguous clean+unpushed case 是 default。
+
+#### Case A: Clean + 0 unpushed
+
+不需要 dispatch,直接 abort:
+
+```bash
+echo "✗ Nothing to push — working tree is clean and 0 unpushed commits."
+echo "  If you intended to update the marketplace anyway (e.g. just trigger 'claude plugin marketplace update' on origin),"
+echo "  bypass plugin-update and run that command directly."
+exit 0
+```
+
+#### Case B: Clean + N unpushed → AskUserQuestion
+
+```
+question: "$N unpushed commits on $BRANCH. Push them to origin and proceed with marketplace sync?"
+options:
+  - label: "push N as-is (default)"
+    description: "git push origin $BRANCH → continue to Phase 1+"
+  - label: "interactive rebase first"
+    description: "abort plugin-update; run 'git rebase -i origin/$BRANCH' manually then re-run plugin-update"
+  - label: "abort"
+    description: "exit; nothing changed"
+```
+
+選 `push N as-is` → Phase 1+ continue。
+選其他 → exit 0。
+
+#### Case C: Dirty + 0 unpushed → AskUserQuestion
+
+```
+question: "Working tree has uncommitted changes, 0 unpushed commits. What to do?"
+options:
+  - label: "abort (default)"
+    description: "exit; manually 'git add ...' + 'git commit -m ...' the changes you want to push, then re-run plugin-update"
+  - label: "stage all + commit + push"
+    description: "git add -A then prompt for commit message → commit → push → continue"
+  - label: "manually stage subset + commit + push"
+    description: "abort; run 'git add' interactively, then re-run plugin-update"
+```
+
+預設 `abort` — skill 不擅自決定要 commit 什麼。
+
+#### Case D: Dirty + N unpushed → AskUserQuestion
+
+```
+question: "$N unpushed commits AND working tree has uncommitted changes. What to do?"
+options:
+  - label: "abort (default)"
+    description: "ambiguous state; exit and let user choose: amend dirty into HEAD? new commit? push without dirty? Re-run after deciding."
+  - label: "push N existing commits, leave dirty for later"
+    description: "git push origin $BRANCH → continue (dirty stays uncommitted)"
+  - label: "amend dirty into HEAD then push"
+    description: "git add -A then git commit --amend --no-edit (dirty staged + merged into HEAD) → push → continue"
+  - label: "commit dirty as new commit then push N+1"
+    description: "stage all + prompt for commit message → push → continue"
+```
+
+預設 `abort` — 4 種 sensible 動作對應不同意圖,user 必須明確選。
+
+#### Case E: Origin diverged → AskUserQuestion
+
+```
+question: "Origin is ahead by M commits AND HEAD has N unpushed (diverged). Resolve manually."
+options:
+  - label: "abort (default)"
+    description: "exit; run 'git fetch + git rebase origin/$BRANCH' or 'git merge origin/$BRANCH' then re-run plugin-update"
+  - label: "fetch + rebase + push"
+    description: "git fetch + git rebase origin/$BRANCH (linear history) → push → continue (may have conflicts)"
+  - label: "fetch + merge + push"
+    description: "git fetch + git merge origin/$BRANCH (preserve both branches' history) → push → continue (may have conflicts)"
+```
+
+預設 `abort` — conflict resolution 是 user 的工作,不是 skill 的。
+
+### Step 4: idd-all Unattended Mode Handler
+
+當 plugin-update 在 `idd-all` orchestrator 下被 invoke(env var or args detect,e.g. `IDD_ALL_UNATTENDED=1`):
+
+1. 仍跑 Step 1 preview block(printed for audit)
+2. **Auto-abort** with structured error:
+   ```
+   ✗ plugin-update Phase 0.5 cannot prompt under unattended mode.
+     Detected state: $STATE.
+     User must run /plugin-update <name> manually after IDD chain completes.
+   ```
+3. Return exit code non-zero(e.g. 75 = "abort by gate")so `idd-all` 在 final report 標 "plugin-update skipped under unattended mode"
+
+設計同 `idd-diagnose` Step 3.4 F unattended-mode pattern:auto-default to safe path + audit trail entry。**Plan tier 的 EnterPlanMode + plugin-update 的 Phase 0.5 都是 user-attendance-required gates**,unattended mode 統一走 abort + audit。
+
+### Step 5: Cross-plugin Commits Warning（v1.16.0 Tier A:warn-only)
+
+當 Step 3 選擇 `push N as-is` / `push N+1`,檢查 unpushed commits 有沒有 touch 預期外的 plugin / 完全沒 touch target plugin。**前置條件**:`$TARGET_PLUGIN` 必須先由 Phase 1 Step 1 plugin-name resolution 設定;若 Phase 0.5 在 Phase 1 之前就需要這個 check,要等 Phase 1 inference 完成再回來跑(skill 內由 Step 0 stage TaskList 控制 ordering)。
+
+```bash
+# Pre-condition: TARGET_PLUGIN 已由 Phase 1 Step 1 解析(命令列 arg 或從 git inferred)
+# 若 TARGET_PLUGIN 為空,跳過此 check(讓 Phase 1 處理 inference 後再看)
+if [ -z "${TARGET_PLUGIN:-}" ]; then
+    echo "ℹ Cross-plugin scope check deferred — TARGET_PLUGIN not yet resolved (Phase 1 Step 1 will set)."
+    return 0
+fi
+
+# 收集 unpushed commits touch 到的 plugin 名(去重)
+TOUCHED=$(git log --name-only --pretty=format: "$UPSTREAM"..HEAD \
+  | grep '^plugins/' | cut -d/ -f2 | sort -u)
+TOUCHED_COUNT=$(echo -n "$TOUCHED" | grep -c . || true)
+
+# Three cases:
+#   (a) TOUCHED_COUNT = 0 — 無 plugin 被 touch (commits 只改 root files / 完全沒碰 plugins/) — 危險!
+#   (b) TOUCHED_COUNT = 1 AND 該 plugin = $TARGET_PLUGIN — happy path,silent
+#   (c) TOUCHED_COUNT ≥ 1 但 (a) (b) 都不成立 — 跨 plugin 或不對 target,warn
+
+if [ "$TOUCHED_COUNT" = "0" ]; then
+    # Empty-set case (v1.16.0 fix #60-verify P2 #5): commits 沒碰任何 plugin
+    echo "⚠ Heads-up: unpushed commits touch NO plugin under plugins/."
+    echo "   Commits in question:"
+    git log --oneline "$UPSTREAM"..HEAD | sed 's/^/     /'
+    echo "   Pushing will publish marketplace.json / docs / root-only changes."
+    echo "   If you intended to update '$TARGET_PLUGIN' specifically, abort and re-check commits."
+elif [ "$TOUCHED_COUNT" = "1" ] && [ "$TOUCHED" = "$TARGET_PLUGIN" ]; then
+    : # Happy path — single-plugin commit matching target. No warning.
+else
+    # Cross-plugin or wrong target
+    echo "⚠ Heads-up: unpushed commits touch plugin(s) other than (or in addition to) target '$TARGET_PLUGIN':"
+    echo "$TOUCHED" | sed 's/^/   - plugins\//'
+    echo "   Pushing will publish all of them via marketplace update."
+    echo "   (warn-only; active scope guard 留給 follow-up issue #65 處理)"
+fi
+```
+
+**Tier A scope = warn-only(3 cases:empty / happy / cross-plugin)**;**Tier C scope guard(active 拒絕 push,refuse + suggest interactive rebase)留給 follow-up issue #65 處理**。
+
+### Step 6: Pass to Phase 1
+
+通過 Phase 0.5 gate(user 選 push,或 idd-all unattended fail-fast 已 abort)後,進 Phase 1 with 已驗證的 git state。
+
+---
+
+## Phase 1: 偵測變更
+
+### Step 1: 確定 Plugin
+
+如果用戶指定了 plugin 名稱，直接使用。否則從 git 推斷：
+
+```bash
+cd {marketplace_repo_path}
+git diff --name-only HEAD~3 | grep '^plugins/' | cut -d/ -f2 | sort -u
+```
+
+列出最近變更的 plugin，請用戶確認要更新哪些。
+
+### Step 2: 檢查 Git 狀態
+
+> **Skipped(v1.16.0+ #60)**:Git state preview + commit/push decision 已在 [**Phase 0.5: Git State Preview & Confirmation Gate**](#phase-05-git-state-preview--confirmation-gate-v1160-60) 處理。
+>
+> 走到 Phase 1 等於 Phase 0.5 已 gate 過 + user 明確選擇了 push(或 abort 的話根本不會走到這裡)。
+>
+> Pre-v1.16.0 此 step 印 `git status` 後接 narrative reminder 「請先 commit + push」,**沒實際 gate**;新版升格成 Phase 0.5 explicit AskUserQuestion 5-case dispatch。歷史脈絡見 #60。
+
+---
+
+## Phase 1.5: External Binary Dependency Check（若有）
+
+Plugin 如果依賴外部 binary（MCP server、CLI 工具），plugin-update 只會同步 shell
+（wrapper / skill / command），**不會** 自動更新 binary。這個 phase 偵測並提示。
+
+### Step 1: 偵測依賴類型
+
+| 訊號 | 類型 | 判斷方式 |
+|------|------|---------|
+| `.mcp.json` 存在 | **MCP binary** | `ls plugins/{name}/.mcp.json` |
+| `bin/*-wrapper.sh` 有 `GITHUB_REPO` | **MCP binary** | `grep -l GITHUB_REPO plugins/{name}/bin/*.sh` |
+| `hooks/session-start.sh` curl GitHub API | **CLI tool** | `grep 'api.github.com.*releases' plugins/{name}/hooks/` |
+| Skill / hook 引用 `~/bin/$BINARY` | **CLI tool** | `grep -rn '\$HOME/bin/\|~/bin/' plugins/{name}/{skills,hooks}/` |
+
+### Step 2: MCP 情境 — 兩個信號（asset present + repo drift）
+
+兩個獨立信號：
+
+1. **Latest release 有沒有對應 asset** — 救「release 漏上傳 binary」這類 #13-style 失誤
+2. **Binary repo main 是否超前 last release**（v1.17.0+ 新增信號）— 救「main 累積大量 [Unreleased] 改動但沒 cut release」這類盲點
+
+兩個信號獨立、各自 warn。
+
+```bash
+for wrapper in plugins/{name}/bin/*-wrapper.sh; do
+    [ -f "$wrapper" ] || continue
+    BINARY_NAME=$(grep '^BINARY_NAME=' "$wrapper" | head -1 | cut -d'"' -f2)
+    GITHUB_REPO=$(grep '^GITHUB_REPO=' "$wrapper" | head -1 | cut -d'"' -f2)
+    [ -z "$BINARY_NAME" ] && continue
+
+    # === Signal 1: asset present in latest release? ===
+    HAS_BINARY=$(curl -sL "https://api.github.com/repos/$GITHUB_REPO/releases/latest" \
+        | grep '"browser_download_url"' | grep -c "/$BINARY_NAME\"" || true)
+
+    if [ "$HAS_BINARY" = "0" ]; then
+        echo "⚠️  $BINARY_NAME not in $GITHUB_REPO latest release"
+        echo "   Plugin will install but wrapper auto-download will fail."
+        echo "   → cd <MCP-source-repo> && /mcp-tools:mcp-deploy"
+    fi
+
+    # === Signal 2: binary repo main has unreleased commits? (v1.17.0+) ===
+    # plugin.json declares binary_version (#77 schema, post-staleness-detection);
+    # compare with binary repo's main HEAD to surface accumulated [Unreleased] backlog.
+    BINARY_VERSION=$(python3 -c "
+import json
+d = json.load(open('plugins/{name}/.claude-plugin/plugin.json'))
+print(d.get('binary_version') or d.get('version'))
+" 2>/dev/null)
+
+    # detect_binary_repo: try common local-clone paths derived from GITHUB_REPO
+    REPO_BASENAME=$(basename "$GITHUB_REPO")
+    BINARY_REPO_PATH=""
+    for candidate in \
+        "$HOME/Developer/$REPO_BASENAME" \
+        "$HOME/Developer/che-mcps/$REPO_BASENAME" \
+        "$HOME/code/$REPO_BASENAME"; do
+        if [ -d "$candidate/.git" ]; then
+            BINARY_REPO_PATH="$candidate"
+            break
+        fi
+    done
+
+    if [ -n "$BINARY_REPO_PATH" ] && [ -n "$BINARY_VERSION" ]; then
+        # Verify the tag exists locally (might need `git fetch --tags` first if stale)
+        if git -C "$BINARY_REPO_PATH" rev-parse "refs/tags/v$BINARY_VERSION" >/dev/null 2>&1; then
+            UNRELEASED=$(git -C "$BINARY_REPO_PATH" log "v$BINARY_VERSION..main" --oneline 2>/dev/null | wc -l | tr -d ' ')
+            if [ "$UNRELEASED" -gt 0 ] 2>/dev/null; then
+                echo "⚠️  $REPO_BASENAME main has $UNRELEASED unreleased commits since v$BINARY_VERSION"
+                echo "   plugin.json pins binary_version=$BINARY_VERSION; wrapper auto-download will fetch that."
+                echo "   Recent unreleased commits:"
+                git -C "$BINARY_REPO_PATH" log "v$BINARY_VERSION..main" --oneline 2>/dev/null | head -5 | sed 's/^/      /'
+                echo "   → cd $BINARY_REPO_PATH && ./scripts/release.sh v<next>"
+                echo "     then bump plugins/{name}/.claude-plugin/plugin.json binary_version + re-run plugin-update"
+            fi
+        else
+            # Local tag missing — could mean: never fetched, or release made on remote-only.
+            # Best-effort: skip rather than misreport.
+            echo "ℹ️  $REPO_BASENAME local repo found but tag v$BINARY_VERSION missing — run 'git fetch --tags' to enable Signal 2"
+        fi
+    fi
+done
+```
+
+**何時 Signal 2 沉默**：
+- Plugin.json 無 `binary_version` 欄位且 `version` 不是 v-semver
+- 本機沒有 binary repo 的 clone（試過 `~/Developer/` / `~/Developer/che-mcps/` / `~/code/` 三個 fallback）
+- Local clone 沒有對應的 `v$BINARY_VERSION` tag（建議使用者跑 `git fetch --tags`）
+
+設計理由：Signal 2 是 best-effort warn — 對能取得的資訊提示，缺資料時 silent skip。**不 abort plugin-update**（這是 Phase 0.3 的工作）；Phase 1.5 維持「prompt then sync」的協助型行為。
+
+### Step 3: CLI 情境 — 比對本機 binary 和 latest release 版本
+
+```bash
+# 從 session-start.sh 抓 GitHub repo
+GFH_REPO=$(grep -oE '[A-Za-z0-9_-]+/[A-Za-z0-9_-]+' plugins/{name}/hooks/session-start.sh | head -1)
+BINARY_NAME=$(basename $(grep -oE '\$HOME/bin/[A-Za-z0-9_-]+' plugins/{name}/hooks/session-start.sh | head -1))
+
+LOCAL_VERSION=$("$HOME/bin/$BINARY_NAME" version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+LATEST_VERSION=$(curl -sL "https://api.github.com/repos/$GFH_REPO/releases/latest" \
+    | grep '"tag_name"' | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+
+if [ "$LOCAL_VERSION" != "$LATEST_VERSION" ]; then
+    echo "⚠️  $BINARY_NAME local v$LOCAL_VERSION, latest v$LATEST_VERSION"
+    echo "   → /cli-tools:cli-upgrade $BINARY_NAME"
+fi
+```
+
+### Step 4: 行為決策 — AskUserQuestion 主動同步
+
+偵測到依賴且不同步時，**主動問使用者要不要一起更新**，不只是 warn。
+plugin-update 是日常同步操作——連帶更新底層 binary 通常是想要的行為。
+
+**AskUserQuestion 格式**：
+
+```
+question: "此 plugin 依賴 $BINARY（$BINARY_TYPE），目前本機/release 不同步。要順便更新 binary 嗎？"
+options:
+  - "順便更新" — 自動觸發底層 skill（MCP → mcp-deploy / CLI → cli-upgrade）
+  - "只更新 plugin shell" — 略過 binary，只跑 marketplace.json sync + reload
+  - "中止" — 停止 plugin-update，讓我手動處理
+```
+
+**若使用者選「順便更新」**：
+
+| 依賴類型 | 自動觸發 | 時機 |
+|---------|---------|------|
+| MCP binary | `/mcp-tools:mcp-deploy` | 在此 phase 內執行，完成後才繼續 Phase 2 |
+| CLI tool | `/cli-tools:cli-upgrade $BINARY` | 同上 |
+
+**狀況表**：
+
+| 狀況 | 動作 |
+|------|------|
+| 無依賴（純 skill / rule plugin） | 跳過此 phase |
+| 有依賴且已同步 | 顯示 ✅，繼續 Phase 2 |
+| 有依賴但不同步 | **AskUserQuestion**：要順便更新 binary 嗎？ |
+
+**為什麼 plugin-update 是 prompt-then-sync 而 plugin-deploy 是 block**：
+
+| Skill | 觸發頻率 | 行為 | 理由 |
+|-------|---------|------|------|
+| `plugin-deploy` Step 2.5 | 偶爾（發版時）| **BLOCK** | Release 沒 binary = 新使用者裝 plugin 就壞，不能放過 |
+| `plugin-update` Phase 1.5 | 頻繁（日常同步）| **ASK + AUTO-SYNC** | 開發者通常想要一次更新完，但要尊重「只改 shell 不動 binary」的情境 |
+
+### Step 5: 執行 auto-sync（若使用者選擇）
+
+**MCP 情境**：
+
+```bash
+# 找到 MCP source repo（通常在 ~/Developer/ 下）
+MCP_SOURCE=$(find ~/Developer -maxdepth 3 -name "Package.swift" -exec grep -l "$BINARY_NAME" {} \; | head -1 | xargs dirname 2>/dev/null)
+
+if [ -n "$MCP_SOURCE" ]; then
+    cd "$MCP_SOURCE"
+    # 呼叫 mcp-deploy skill（建議用 Skill tool，不是 shell）
+    echo "Invoking /mcp-tools:mcp-deploy in $MCP_SOURCE..."
+    # Skill invocation: Skill(skill="mcp-tools:mcp-deploy")
+else
+    echo "MCP source repo not found. Please run /mcp-tools:mcp-deploy manually from the MCP repo."
+fi
+```
+
+**CLI 情境**：
+
+```bash
+# cli-upgrade 已知如何找 repo（從 ~/bin/$BINARY 偵測）
+# Skill invocation: Skill(skill="cli-tools:cli-upgrade", args="$BINARY_NAME")
+```
+
+完成後回到 Phase 2 繼續 marketplace.json sync。
+
+---
+
+## Phase 2: 更新 marketplace.json（關鍵！）
+
+`marketplace.json` 位於 `{marketplace_repo_path}/.claude-plugin/marketplace.json`，是 marketplace 的 plugin index。
+**如果這個檔案沒更新，`claude plugin marketplace update` 不會看到新版本。**
+
+### Step 1: 列出 marketplace 中所有 plugin 版本
+
+```bash
+cd {marketplace_repo_path}
+cat .claude-plugin/marketplace.json | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+for p in data['plugins']:
+    print(f\"  {p['name']}: {p['version']}\")
+"
+```
+
+### Step 2: 對比 plugin.json 的實際版本
+
+```bash
+cat plugins/{plugin_name}/.claude-plugin/plugin.json | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+print(f\"plugin.json: {d['version']}\")
+"
+```
+
+如果 marketplace.json 的版本落後 plugin.json，用 Edit 工具更新 marketplace.json。
+
+### Step 3: 新 Plugin 需加入 entry
+
+如果是全新的 plugin（不在 marketplace.json 中），需要在 `plugins` 陣列加入新 entry：
+
+```json
+{
+  "name": "{plugin_name}",
+  "version": "1.0.0",
+  "description": "{description}",
+  "author": { "name": "Che Cheng" },
+  "source": "./plugins/{plugin_name}",
+  "category": "{category}"
+}
+```
+
+category 常用值：`development`、`productivity`、`creative`
+
+### Step 4: Commit + Push marketplace.json
+
+marketplace.json 的變更也需要 commit + push，才能被 `marketplace update` 抓到。
+
+```bash
+cd {marketplace_repo_path}
+git add .claude-plugin/marketplace.json
+git commit -m "chore: update marketplace.json for {plugin_name} v{version}"
+git push
+```
+
+---
+
+## Phase 2.5: README Freshness Check
+
+版本 bump 後，`README.md` 常常被遺忘。這個 phase 在 marketplace sync 之前做最後一道檢查：**使用者看到的文件有沒有跟上程式碼**。
+
+### 為什麼要做這步
+
+`plugin.json` / `marketplace.json` 的版本升了，但 README 還寫著舊工具數量、舊 feature 列表——使用者從 marketplace 裝 plugin 看到的是 stale README，會以為新功能沒做完。這不是 hard failure（plugin 還是能跑），但是 silent UX failure（使用者困惑）。
+
+### Step 1: Staleness 偵測
+
+掃 `plugins/{plugin_name}/README.md`，**六個訊號任一命中 = 可疑 stale**。
+新增的信號 4-6 是 v1.15.0 從跨 28 plugin 大規模 audit 中萃取的盲點 —
+舊三信號漏掉「tool count drift / component inventory drift / multi-version
+catch-up gap」這三類常見 staleness。
+
+```bash
+PLUGIN_DIR="{marketplace_repo_path}/plugins/{plugin_name}"
+README="$PLUGIN_DIR/README.md"
+NEW_VERSION=$(python3 -c "import json; print(json.load(open('$PLUGIN_DIR/.claude-plugin/plugin.json'))['version'])")
+
+# README 是否有任何版本追蹤標記（給 Suppression A 用）
+HAS_VERSION_SECTION=false
+if grep -qE '## (Version|Changelog)|# Changelog|v[0-9]+\.[0-9]+' "$README" 2>/dev/null; then
+    HAS_VERSION_SECTION=true
+fi
+
+# 信號 1: README 沒出現新版本字串
+if [ "$HAS_VERSION_SECTION" = "true" ] && ! grep -q "v$NEW_VERSION\|$NEW_VERSION" "$README" 2>/dev/null; then
+    echo "⚠️  signal-1: README has version markers but doesn't mention v$NEW_VERSION"
+    STALE_README=true
+fi
+
+# 信號 2: README 最後一次修改早於 plugin.json / skills / hooks 最近修改
+# 套用兩個 suppression 避免誤判：
+#   A. README 完全沒有版本追蹤內容 → mtime drift 沒意義（純 skill plugin / glue plugin）
+#   B. 所有「比 README 新的 commits」都是 wrapper-only / marketplace.json sync 等
+#      不影響使用者可見 surface 的 plumbing 改動 → 不算 stale
+README_MTIME=$(git log -1 --format=%ct -- "$PLUGIN_DIR/README.md" 2>/dev/null)
+CODE_MTIME=$(git log -1 --format=%ct -- "$PLUGIN_DIR/.claude-plugin/plugin.json" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks" "$PLUGIN_DIR/agents" "$PLUGIN_DIR/rules" "$PLUGIN_DIR/commands" 2>/dev/null)
+if [ -n "$README_MTIME" ] && [ -n "$CODE_MTIME" ] && [ "$README_MTIME" -lt "$CODE_MTIME" ]; then
+    if [ "$HAS_VERSION_SECTION" = "false" ]; then
+        # Suppression A — 沒版本追蹤標記，mtime drift 沒意義
+        :
+    else
+        # Suppression B — 過濾掉純 wrapper / marketplace 同步 commits
+        # 找出 README mtime 之後、touch 此 plugin 的所有 commits
+        SUBSTANTIVE_COMMITS=$(git log --since="@$README_MTIME" --format='%s' \
+            -- "$PLUGIN_DIR/" 2>/dev/null | \
+            grep -vE '^(fix|chore|docs)\(.*\): (add version-aware auto-download|sync marketplace\.json|update repo URLs|bump.*version|wrapper)' | \
+            grep -vE 'wrapper.sh\b|marketplace\.json sync|plugin\.json version' | \
+            head -5)
+        if [ -n "$SUBSTANTIVE_COMMITS" ]; then
+            echo "⚠️  signal-2: README older than substantive code changes:"
+            echo "$SUBSTANTIVE_COMMITS" | sed 's/^/      /'
+            STALE_README=true
+        fi
+    fi
+fi
+
+# 信號 3: 若有 CHANGELOG.md，檢查最新 entry 是否已出現在 README
+CHANGELOG="$PLUGIN_DIR/CHANGELOG.md"
+if [ -f "$CHANGELOG" ]; then
+    LATEST_CL_VERSION=$(grep -oE '^## \[?[0-9]+\.[0-9]+\.[0-9]+\]?' "$CHANGELOG" | head -1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
+    if [ -n "$LATEST_CL_VERSION" ] && ! grep -q "$LATEST_CL_VERSION" "$README"; then
+        echo "⚠️  signal-3: CHANGELOG latest v$LATEST_CL_VERSION not in README"
+        STALE_README=true
+    fi
+fi
+
+# 信號 4: Component inventory drift（v1.15.0 新增；移植自 plugin-deploy）
+# 實際 skills / agents / commands 是否都在 README 提到。
+# 漏掉 = 使用者看 README 不知道有這個 skill。
+#
+# 篩選規則（v1.15.0）：只計算「真實組件」 —
+#   skills/<name>/   必須含 SKILL.md（空目錄是實驗殘留，不算 skill）
+#   agents/*.md      檔案必須存在
+#   commands/*.md    檔案必須存在
+ACTUAL_SKILLS=$(find "$PLUGIN_DIR/skills/" -maxdepth 2 -name 'SKILL.md' 2>/dev/null | xargs -n1 dirname 2>/dev/null | xargs -n1 basename 2>/dev/null | sort)
+ACTUAL_AGENTS=$(find "$PLUGIN_DIR/agents/" -maxdepth 1 -name '*.md' 2>/dev/null | xargs -n1 basename -s .md 2>/dev/null | sort)
+ACTUAL_COMMANDS=$(find "$PLUGIN_DIR/commands/" -maxdepth 1 -name '*.md' 2>/dev/null | xargs -n1 basename -s .md 2>/dev/null | sort)
+MISSING_COMPONENTS=()
+# 認可的引用格式（任一命中即視為「README 提到這個 component」）：
+#   `name`              — backtick-quoted reference
+#   /name               — bare slash command form
+#   /plugin-name:name   — plugin-namespace form (typical in installed clients)
+#   @name               — agent reference
+#   - **name**          — markdown bold list entry
+for s in $ACTUAL_SKILLS; do
+    grep -qE "\`$s\`|/${s}\b|/[a-z0-9_-]+:${s}\b|^- \*\*$s\*\*" "$README" 2>/dev/null || MISSING_COMPONENTS+=("skill:$s")
+done
+for a in $ACTUAL_AGENTS; do
+    grep -qE "\`$a\`|@$a\b|/[a-z0-9_-]+:${a}\b|^- \*\*$a\*\*" "$README" 2>/dev/null || MISSING_COMPONENTS+=("agent:$a")
+done
+for c in $ACTUAL_COMMANDS; do
+    grep -qE "/${c}\b|\`/${c}\`|/[a-z0-9_-]+:${c}\b" "$README" 2>/dev/null || MISSING_COMPONENTS+=("command:$c")
+done
+if [ ${#MISSING_COMPONENTS[@]} -gt 0 ]; then
+    echo "⚠️  signal-4: README missing ${#MISSING_COMPONENTS[@]} components: ${MISSING_COMPONENTS[*]}"
+    STALE_README=true
+fi
+
+# 信號 5: Tool count drift（v1.15.0 新增）
+# README 多半會在標題寫「(N tools)」「N MCP Tools」「Tool 數量: N」。
+# 把這個 N 抓出來跟 plugin.json description 中宣稱的 tool 數比對。
+# README 落後最容易在這露餡（che-ical-mcp v0.8.2 → v1.7.2 README 寫 20 tools 實際 28）。
+DESC=$(python3 -c "import json; print(json.load(open('$PLUGIN_DIR/.claude-plugin/plugin.json')).get('description', ''))")
+DESC_TOOLS=$(echo "$DESC" | grep -oE '[0-9]+ ?(?:個 )?(?:MCP )?(?:tools|工具)' | head -1 | grep -oE '^[0-9]+')
+README_TOOLS=$(grep -oE 'Available Tools \([0-9]+\)|\([0-9]+ (?:MCP )?tools\)|\*\*[0-9]+ MCP Tools\*\*|[0-9]+ 個工具' "$README" 2>/dev/null | grep -oE '[0-9]+' | head -1)
+if [ -n "$DESC_TOOLS" ] && [ -n "$README_TOOLS" ] && [ "$DESC_TOOLS" != "$README_TOOLS" ]; then
+    echo "⚠️  signal-5: README tool count ($README_TOOLS) != plugin.json description ($DESC_TOOLS)"
+    STALE_README=true
+fi
+
+# 信號 6: Version history multi-version gap（v1.15.0 新增）
+# 如果 README 有 Version History 表格，掃「最近 90 天」的 git log 找出 bump commits，
+# 確保表格涵蓋這段時間出貨的版本 — 不只是「latest 有沒有」（信號 1）而是「中間是否漏版本」。
+# 範圍只看 90 天避免 major rewrite（plugin v1.x → v2.x README 改寫）誤觸發。
+if grep -q '## Version History\|### Changelog' "$README" 2>/dev/null; then
+    SHIPPED_VERSIONS=$(git log --since="90 days ago" --format='%s' -- "$PLUGIN_DIR/" 2>/dev/null | \
+        grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | sort -uV | tail -8)
+    MISSING_VERSIONS=()
+    for v in $SHIPPED_VERSIONS; do
+        v_clean=${v#v}
+        grep -q "$v_clean\|v$v_clean" "$README" 2>/dev/null || MISSING_VERSIONS+=("$v_clean")
+    done
+    # 進一步限制：只計算「同 major 版本」的 missing（避免 major rewrite 誤判）
+    CURRENT_MAJOR=$(echo "$NEW_VERSION" | cut -d. -f1)
+    SAME_MAJOR_MISSING=()
+    for v in "${MISSING_VERSIONS[@]}"; do
+        v_major=$(echo "$v" | cut -d. -f1)
+        [ "$v_major" = "$CURRENT_MAJOR" ] && SAME_MAJOR_MISSING+=("$v")
+    done
+    if [ ${#SAME_MAJOR_MISSING[@]} -gt 1 ]; then
+        # 容忍漏 1 個（可能是 patch/internal），漏 2+ 個就明顯 stale
+        echo "⚠️  signal-6: README Version History missing ${#SAME_MAJOR_MISSING[@]} same-major versions: ${SAME_MAJOR_MISSING[*]}"
+        STALE_README=true
+    fi
+fi
+```
+
+**設計理由速覽**：
+
+| 信號 | 解決的 false negative | 觀察來源 |
+|------|---------------------|---------|
+| 1 (legacy) | README 整個版本記錄沒同步 | 原始版本 |
+| 2 (legacy + suppressions) | mtime drift；現避免誤判 wrapper-only 改動 | 大規模 audit 發現 4/11 是 false positive |
+| 3 (legacy) | CHANGELOG bump 但 README 沒同步 | 原始版本 |
+| 4 (new) | 新增的 skill / agent / command 沒寫進 README | issue-driven-dev：5 個 skill 列表，實際 10 個 |
+| 5 (new) | README 寫的工具數比實際少 | che-ical-mcp：寫 20 工具，實際 28 |
+| 6 (new) | Version History 表格漏中間 N 個版本 | che-duckdb-mcp：v2.0 → v2.2.1 中間漏 4 版 |
+
+### Step 2: 行為決策 — AskUserQuestion
+
+偵測到 stale 時，**不要直接繼續**。用 AskUserQuestion 讓使用者決定：
+
+```
+question: "README.md 看起來沒跟上 v$NEW_VERSION（沒提到新版本 / 新工具 / 比程式碼舊）。要怎麼處理？"
+options:
+  - "更新 README" — 我會讀 CHANGELOG + recent commits 幫忙起草，你審閱後 commit
+  - "已經沒問題" — README 其實是對的（純內部重構、不對外新增 surface），繼續 deploy
+  - "先略過，稍後手動處理" — 繼續 deploy 但留一條 warning 在最終 report
+```
+
+| 選項 | 行為 |
+|------|------|
+| 更新 README | Read CHANGELOG.md + `git log --oneline -n 10 -- plugins/{name}/` → 提出 README diff → 使用者確認後 Edit + commit + push |
+| 已經沒問題 | 繼續 Phase 3，不記 warning |
+| 先略過 | 繼續 Phase 3，**Phase 5 最終 report 要顯眼標註** README 待補 |
+
+### 狀況表
+
+| 狀況 | 動作 |
+|------|------|
+| README 不存在 | 跳過（plugin-deploy 才會強制補） |
+| README 存在且 fresh（六個信號都通過）| 顯示 ✅，繼續 Phase 3 |
+| README 存在但 stale | **AskUserQuestion**（三選項） |
+| 只有 signal-2 命中且 Suppression A/B 啟動 | 視為 fresh（避免誤判 wrapper-only / no-version-section plugins） |
+
+### 為什麼是 ASK 而不是 BLOCK
+
+| Skill | 觸發頻率 | README 行為 | 理由 |
+|-------|---------|-----------|------|
+| `plugin-update` Phase 2.5 | 頻繁（日常同步）| **ASK** | 有時純修 typo / hook / internal refactor，不需要動 README |
+| `plugin-deploy` Step 2 | 偶爾（發版時）| **列入 checklist 並 offer 修復** | 正式發布時使用者第一眼看 README，stale 就是差的第一印象 |
+
+---
+
+## Phase 3: 同步 Marketplace Cache
+
+### Step 1: 更新 marketplace cache
+
+```bash
+claude plugin marketplace update {marketplace_name}
+```
+
+這會從 source（git remote 或本地目錄）重新拉取 plugin index。
+
+### Step 2: 驗證
+
+```bash
+claude plugin list 2>&1 | grep -A3 "{plugin_name}"
+```
+
+---
+
+## Phase 4: 更新已安裝的 Plugin
+
+### 注意：必須加 `@marketplace_name` 後綴
+
+```bash
+# 已安裝 → 更新
+claude plugin update {plugin_name}@{marketplace_name}
+
+# 未安裝 → 安裝
+claude plugin install {plugin_name}@{marketplace_name}
+```
+
+先檢查是否已安裝：
+```bash
+claude plugin list 2>&1 | grep "{plugin_name}"
+```
+
+---
+
+## Phase 5: 驗證與提醒
+
+### Step 1: 確認最終狀態
+
+```bash
+claude plugin list 2>&1 | grep -A5 "{plugin_name}"
+```
+
+檢查：
+- Version 是否已更新到目標版本
+- Status 是否 `✔ enabled`
+- 是否有 `failed to load` 錯誤
+
+### Step 2: 提醒重啟
+
+> 更新完成。請重啟 Claude Code（退出再重新開啟）讓變更完全生效。
+> 或者在下次啟動新對話時，新版 plugin 就會自動載入。
+
+---
+
+## 批次更新
+
+多個 plugin 需要更新時：
+
+```bash
+# 1. 同步 marketplace（只需一次）
+claude plugin marketplace update {marketplace_name}
+
+# 2. 逐一更新（需加 @marketplace 後綴）
+claude plugin update plugin-a@{marketplace_name}
+claude plugin update plugin-b@{marketplace_name}
+```
+
+---
+
+## 常見問題
+
+### Plugin 更新後 skill 沒變？
+Claude Code 有快取機制。需要重啟才能載入新版 skill 內容。
+
+### `failed to load` 錯誤？
+通常是 hooks.json 格式問題：
+```bash
+claude plugin validate {marketplace_repo_path}/plugins/{plugin_name}
+```
+
+### `marketplace update` 沒看到新版本？
+1. 確認 `marketplace.json` 的版本號已更新
+2. 確認已 push 到 remote：
+```bash
+cd {marketplace_repo_path}
+git log origin/main..HEAD --oneline
+```
+
+### `plugin update` 找不到 plugin？
+需要加 `@marketplace_name` 後綴：
+```bash
+# 錯誤
+claude plugin update my-plugin
+# 正確
+claude plugin update my-plugin@psychquant-claude-plugins
+```
diff --git a/plugins/plugin-tools/skills/plugin-upgrade/SKILL.md b/plugins/plugin-tools/skills/plugin-upgrade/SKILL.md
new file mode 100644
index 00000000..c5fb3e7f
--- /dev/null
+++ b/plugins/plugin-tools/skills/plugin-upgrade/SKILL.md
@@ -0,0 +1,313 @@
+---
+name: plugin-upgrade
+description: |
+  分析現有 plugin 的結構和能力，找出缺少的組件、過時的格式、
+  可以從相關專案匯入的 rules/skills/agents，然後自動補上。
+  當用戶想要「改善 plugin」、「升級 plugin」、「plugin 缺什麼」、
+  「把 X 的設定加進 plugin」、「plugin upgrade」時使用。
+argument-hint: "<plugin-name> [--source /path/to/related/project]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+# Plugin Upgrade — 分析與增強現有 Plugin
+
+掃描現有 plugin 的結構，對比最佳實踐和相關專案，找出缺少的組件並自動補上。
+
+## 與其他 skill 的區別
+
+| Skill | 做什麼 | 什麼時候用 |
+|-------|--------|-----------|
+| `plugin-create` | 從零建立新 plugin | 全新的 plugin |
+| `plugin-upgrade` | **改善現有 plugin 的能力** | plugin 功能不足、想加東西 |
+| `plugin-update` | 同步版本號 + push + reload | 改完 code 後的機械步驟 |
+| `plugin-health` | 檢查載入錯誤 | plugin 壞了 |
+| `plugin-deploy` | 品質檢查 + 版本升級 + 發布 | 要正式發布 |
+
+## Execution Steps
+
+### Step 0: Bootstrap Stage Task List（強制）
+
+**動任何事之前**先用 `TaskCreate` 建 todo list：
+
+```
+TaskCreate(name="parse_arguments", description="Step 0: 解析 plugin-name 和 --source（若有）")
+TaskCreate(name="locate_plugin", description="Step 1: 找到 marketplace 下的 plugin 目錄")
+TaskCreate(name="scan_structure", description="Step 2: 掃描 skills/agents/rules/hooks/commands/CLAUDE.md")
+TaskCreate(name="check_hook_format", description="Step 3: 驗證 hooks 格式（plugin.json 不該含 hooks）")
+TaskCreate(name="scan_related_projects", description="Step 4: 掃 --source 的 .claude/ 目錄找可匯入資源")
+TaskCreate(name="present_report", description="Step 5: 顯示 upgrade report，列出問題和可匯入清單")
+TaskCreate(name="execute_fixes", description="Step 6: 使用者選擇修復範圍（全部/🔴/逐一/只看報告）")
+TaskCreate(name="fix_hook_format", description="Step 7: 轉換 plugin.json hooks → hooks/hooks.json（若需要）")
+TaskCreate(name="import_rules", description="Step 8: 從 source 匯入 rules")
+TaskCreate(name="import_skills", description="Step 9: 從 source 匯入相關 skills（使用者選）")
+TaskCreate(name="update_claude_md", description="Step 10: 重新生成 CLAUDE.md 反映所有組件")
+TaskCreate(name="version_bump", description="Step 11: 根據變更幅度 bump 版本")
+TaskCreate(name="deploy", description="Step 12: 呼叫 plugin-update（git commit/push + marketplace update）")
+```
+
+完成每一步立即 `TaskUpdate → completed`。**靜默完成 = 違規**。
+
+### Step 0.5: Parse Arguments
+
+從 `<args>` 取得：
+- `plugin-name`：要升級的 plugin
+- `--source /path`（可選）：相關專案路徑，從中匯入 rules/skills
+
+如果沒指定 `--source`，嘗試從 plugin 的 CLAUDE.md 或 agent 描述推斷相關專案。
+
+### Step 1: Locate Plugin
+
+```bash
+MARKETPLACE_ROOT="/Users/che/Developer/psychquant-claude-plugins"
+PLUGIN_DIR="$MARKETPLACE_ROOT/plugins/{plugin-name}"
+
+# 確認存在
+ls "$PLUGIN_DIR/.claude-plugin/plugin.json"
+```
+
+### Step 2: Scan Current Structure
+
+掃描 plugin 現有的組件：
+
+```bash
+echo "=== Skills ==="
+ls "$PLUGIN_DIR/skills/" 2>/dev/null || echo "(none)"
+
+echo "=== Agents ==="
+ls "$PLUGIN_DIR/agents/" 2>/dev/null || echo "(none)"
+
+echo "=== Rules ==="
+ls "$PLUGIN_DIR/rules/" 2>/dev/null || echo "(none)"
+
+echo "=== Hooks ==="
+ls "$PLUGIN_DIR/hooks/" 2>/dev/null || echo "(none)"
+
+echo "=== Commands ==="
+ls "$PLUGIN_DIR/commands/" 2>/dev/null || echo "(none)"
+
+echo "=== CLAUDE.md ==="
+[ -f "$PLUGIN_DIR/CLAUDE.md" ] && echo "exists" || echo "(missing)"
+
+echo "=== README.md ==="
+[ -f "$PLUGIN_DIR/README.md" ] && echo "exists" || echo "(missing)"
+```
+
+### Step 3: Check Hook Format
+
+Plugin hooks 的正確格式是 `hooks/hooks.json`，不是 `plugin.json` 裡的 `hooks` 欄位。
+
+```bash
+# 檢查 plugin.json 是否誤含 hooks
+python3 -c "
+import json
+with open('$PLUGIN_DIR/.claude-plugin/plugin.json') as f:
+    d = json.load(f)
+if 'hooks' in d:
+    print('ERROR: hooks should be in hooks/hooks.json, not plugin.json')
+else:
+    print('OK: plugin.json clean')
+"
+
+# 檢查 hooks.json 格式
+if [ -f "$PLUGIN_DIR/hooks/hooks.json" ]; then
+    python3 -c "
+import json
+with open('$PLUGIN_DIR/hooks/hooks.json') as f:
+    d = json.load(f)
+# 正確格式：hooks.{EventType}[].matcher + hooks[].type + hooks[].command
+for event_type, matchers in d.get('hooks', {}).items():
+    for m in matchers:
+        if 'matcher' not in m:
+            print(f'WARNING: {event_type} entry missing matcher')
+        if 'hooks' not in m:
+            print(f'WARNING: {event_type} entry missing hooks array')
+        else:
+            for h in m['hooks']:
+                if 'type' not in h or 'command' not in h:
+                    print(f'WARNING: hook entry missing type or command')
+print('Hook format check done')
+"
+fi
+```
+
+### Step 4: Scan Related Projects
+
+如果有 `--source` 或能推斷出相關專案，掃描它的 `.claude/` 目錄：
+
+```bash
+SOURCE_DIR="$SOURCE_PATH/.claude"
+
+echo "=== Source Rules ==="
+ls "$SOURCE_DIR/rules/" 2>/dev/null
+
+echo "=== Source Skills ==="
+ls "$SOURCE_DIR/skills/" 2>/dev/null
+
+echo "=== Source Settings ==="
+cat "$SOURCE_DIR/settings.json" 2>/dev/null
+```
+
+比對 plugin 缺少什麼。
+
+### Step 5: Present Upgrade Report
+
+```markdown
+## Plugin Upgrade Report: {plugin-name}
+
+### 現有組件
+| 類型 | 數量 | 項目 |
+|------|------|------|
+| Skills | 2 | grind, status |
+| Agents | 1 | lean-prover |
+| Rules | 0 | (none) |
+| Hooks | 1 | PostToolUse |
+
+### 發現的問題
+| # | 問題 | 嚴重度 | 自動修復？ |
+|---|------|--------|-----------|
+| 1 | hooks 在 plugin.json 而非 hooks.json | 🔴 會導致安裝失敗 | ✅ |
+| 2 | 缺少 rules/（相關專案有 2 個） | 🟡 影響證明品質 | ✅ |
+| 3 | 缺少 codex-prove-assist skill | 🟡 缺少 Codex 整合 | ✅ |
+| 4 | CLAUDE.md 未列出所有組件 | 🟢 文件不完整 | ✅ |
+
+### 可從相關專案匯入
+| 來源 | 檔案 | 用途 |
+|------|------|------|
+| {source}/.claude/rules/mathlib-api.md | → rules/ | Mathlib API 速查 |
+| {source}/.claude/rules/lean-imports.md | → rules/ | 引用紀律 |
+| {source}/.claude/skills/codex-prove-assist/ | → skills/ | Codex 整合 |
+
+要自動修復所有問題嗎？
+```
+
+### Step 6: Execute Fixes (AskUserQuestion)
+
+問用戶：
+1. 修復所有問題（推薦）
+2. 只修 🔴 嚴重問題
+3. 逐一確認
+4. 只看報告，不修
+
+### Step 7: Fix Hook Format
+
+如果 `plugin.json` 含 `hooks`：
+
+1. 讀取 `plugin.json` 的 hooks 欄位
+2. 轉換成 `hooks/hooks.json` 格式
+3. 從 `plugin.json` 移除 hooks 欄位
+4. 寫入 `hooks/hooks.json`
+
+正確的 `hooks/hooks.json` 格式：
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command-here"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Step 8: Import Rules from Source
+
+```bash
+mkdir -p "$PLUGIN_DIR/rules"
+
+for rule_file in "$SOURCE_DIR/rules/"*.md; do
+    rule_name=$(basename "$rule_file")
+    if [ ! -f "$PLUGIN_DIR/rules/$rule_name" ]; then
+        cp "$rule_file" "$PLUGIN_DIR/rules/"
+        echo "Imported: $rule_name"
+    else
+        echo "Already exists: $rule_name"
+    fi
+done
+```
+
+### Step 9: Import Skills from Source
+
+只匯入與 plugin 功能相關的 skills（不是全部）。
+用 AskUserQuestion 讓用戶選擇要匯入哪些。
+
+```bash
+mkdir -p "$PLUGIN_DIR/skills"
+
+for skill_dir in "$SOURCE_DIR/skills/"*/; do
+    skill_name=$(basename "$skill_dir")
+    # 跳過 spectra 系列（那是 Spectra 框架的，不是 plugin 的）
+    if [[ "$skill_name" == spectra-* ]]; then
+        continue
+    fi
+    if [ ! -d "$PLUGIN_DIR/skills/$skill_name" ]; then
+        echo "Available: $skill_name"
+    fi
+done
+```
+
+### Step 10: Update CLAUDE.md
+
+重新生成 CLAUDE.md，列出所有組件：
+
+- 所有 skills（含新匯入的）
+- 所有 agents
+- 所有 rules（含新匯入的）
+- 所有 hooks
+- 使用範例（含 ralph-loop 整合）
+
+### Step 11: Version Bump
+
+根據變更幅度建議版本號：
+- 只修 hooks 格式 → patch（x.y.z+1）
+- 加了 rules/skills → minor（x.y+1.0）
+- 改了 agent 或 CLAUDE.md 架構 → minor
+
+更新 `plugin.json` 和 `marketplace.json` 的版本號。
+
+### Step 12: Deploy（呼叫 plugin-update）
+
+自動執行 plugin-update 的流程：
+1. `git add` + `git commit`
+2. `git push`
+3. `claude plugin marketplace update`
+4. `claude plugin install`（或 `update`）
+
+提醒用戶重啟 Claude Code。
+
+## 升級策略
+
+### Rules 匯入規則
+
+| 來源 | 匯入條件 |
+|------|---------|
+| 相關專案的 `.claude/rules/` | 與 plugin 功能直接相關 |
+| 其他 plugin 的 `rules/` | 有共用價值（如通用的 coding style） |
+| 全局 rules（`~/.claude/rules/`） | 不匯入（那是全局的，不需要在 plugin 裡重複） |
+
+### Skills 匯入規則
+
+| 來源 skill | 匯入條件 |
+|-----------|---------|
+| 與 plugin 核心功能相關 | ✅ 匯入 |
+| Spectra 系列（spectra-*） | ❌ 跳過（框架 skill，不是功能 skill） |
+| 已存在的同名 skill | ❌ 跳過（避免覆蓋） |
+
+### Agent 匯入規則
+
+通常不從外部匯入 agent——agent 應該是 plugin 自己設計的。
+但如果相關專案有一個 agent 明確標註「可共用」，可以建議匯入。
diff --git a/plugins/postgresql-guide/CHANGELOG.md b/plugins/postgresql-guide/CHANGELOG.md
new file mode 100644
index 00000000..ce6ec8df
--- /dev/null
+++ b/plugins/postgresql-guide/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.0] - (date unknown — please fill in)
+
+### Changed
+- Auto-triggered Skill for querying PostgreSQL official documentation.
+- Forces WebFetch instead of relying on memory
diff --git a/plugins/r-docs-guide/CHANGELOG.md b/plugins/r-docs-guide/CHANGELOG.md
new file mode 100644
index 00000000..083418e3
--- /dev/null
+++ b/plugins/r-docs-guide/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.0] - (date unknown — please fill in)
+
+### Changed
+- Auto-triggered Skills for querying R package documentation via WebFetch.
+- Covers CRAN, tidyverse, Shiny, and general R packages. /r-docs-guide for cross-ecosystem lookup
diff --git a/plugins/r-shiny-debugger/.claude-plugin/plugin.json b/plugins/r-shiny-debugger/.claude-plugin/plugin.json
index a6219bd5..e8bea810 100644
--- a/plugins/r-shiny-debugger/.claude-plugin/plugin.json
+++ b/plugins/r-shiny-debugger/.claude-plugin/plugin.json
@@ -1,10 +1,10 @@
 {
   "name": "r-shiny-debugger",
-  "version": "1.0.0",
-  "description": "功能測試導向的 R Shiny App Debug 工具，整合 agent-browser（前端）與 R console（後端）",
+  "version": "1.2.0",
+  "description": "功能測試導向的 R Shiny App Debug 工具，整合 agent-browser（前端）與 R console（後端）+ shiny-adaptive-walk 自我收斂測試 loop",
   "author": {
     "name": "Che Cheng"
   },
   "license": "MIT",
-  "keywords": ["r", "shiny", "debug", "testing", "agent-browser"]
+  "keywords": ["r", "shiny", "debug", "testing", "agent-browser", "safari-browser", "adaptive-testing", "mp165"]
 }
diff --git a/plugins/r-shiny-debugger/CHANGELOG.md b/plugins/r-shiny-debugger/CHANGELOG.md
new file mode 100644
index 00000000..35891293
--- /dev/null
+++ b/plugins/r-shiny-debugger/CHANGELOG.md
@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.2.0] - 2026-05-13
+
+### Changed
+- **BREAKING**: Default discovery browser for `/shiny-adaptive-walk` is now `agent-browser` (headless Chromium) instead of `safari-browser`. Existing invocations without `--browser` flag now run headless. Pass `--browser safari` (or set `SHINY_ADAPTIVE_BROWSER=safari`) to preserve the previous visible-Safari behavior. Rationale: both engines render real DOM; safari's only unique value is live visibility, which costs nothing to opt into when needed and saves multi-hour unattended runs from per-iter Safari startup, user-profile drift, and tab-focus contention. Refs PsychQuant/psychquant-claude-plugins#77 + spectra change `adaptive-walk-agent-browser-default`.
+- Anti-pattern table entry `Use agent-browser for discovery walk → wrong` removed. Using `agent-browser` for discovery is now the recommended default; using `safari-browser` is the opt-in path.
+- Troubleshooting section restructured: separate `safari-browser missing` (only matters when `--browser safari` is opted into) and `agent-browser missing` (default-path failure mode) subsections.
+- `08-shiny-testing.md` narrow exception clause cross-reference updated to note safari is opt-in via `--browser safari`; clause text itself remains accurate.
+
+### Added
+- `--browser=safari|agent` flag and `SHINY_ADAPTIVE_BROWSER` env var. Precedence: flag > env var > static default (`agent`). Invalid values abort Step 0 pre-flight with a message naming the accepted set.
+- `browser_cmd()` shell helper dispatching the five discovery primitives (open / snapshot / click / fill / screenshot) to the selected CLI. Single source of truth — Step 3a contains no direct `safari-browser` / `agent-browser` invocations.
+- Per-iteration commit body now records `BROWSER=<safari|agent>` audit-trail line for traceability.
+- New documentation section `### When to opt into --browser safari` covering live-demo / teaching / in-the-moment debugging scenarios.
+
+### Verified (per spectra change ACs)
+- Phase 1 contract primitive tests (`test_contract_primitives.R`) pass.
+- Phase 2 walker tests (`test_smoke_lite_walker.R`) pass.
+- `grep "Use agent-browser for discovery walk"` against the skill markdown returns 0 hits (AC5).
+- `grep "When to opt into"` returns multiple hits (AC6).
+
+## [1.1.0] - 2026-05-13
+
+### Added
+- New skill `/shiny-adaptive-walk <COMPANY>` — self-converging adaptive testing loop. Each iter:
+  - Discovery via safari-browser (real macOS Safari renderer, visible to user)
+  - LLM judge classifies defects: `real_bug` → `/idd-issue` / `test_infra_gap` → skill mutates yaml/contracts.R
+  - Per-iter safety gate (`testthat::test_dir` + mechanical gate) + auto-rollback on regression
+  - Convergence: CONVERGED / PLATEAUED / DIMINISHING (mirrors `/glue-bridge` MP102 v1.3 pattern)
+  - Branch isolation (`idd/<N>-adaptive-test-loop`), no auto-push during loop
+  - LLM budget cap via `MP165_ADAPTIVE_BUDGET=100` env var
+- Mutation boundary spec — skill CAN edit `98_test/e2e/**`, `23_deployment/dashboard_presence_gate.R`, `04_utils/fn_debug_mode.R`; skill MUST NOT touch production UI components, derivations, analysis functions, or ETL/DRV scripts (files `/idd-issue` instead)
+- Issue dedup via composite signature `<company>:<module>:<sub_tab>:<defect_class>:<key_phrase>` + `gh issue list --search` before filing
+
+### Changed
+- README.md restructured to clearly distinguish `/shiny-debug` (single-pass interactive) vs `/shiny-adaptive-walk` (self-converging loop)
+- Plugin description expanded to mention adaptive testing
+- Keywords added: `safari-browser`, `adaptive-testing`, `mp165`
+
+### Refs
+- Spectra change: `adaptive-dashboard-test-loop` in `kiki830621/ai_martech_global_scripts` repo
+- Parent issue: kiki830621/ai_martech_global_scripts#653
+- MP165 v1.2 amendment (Track A + Track B dual architecture)
+
+## [1.0.0] - 2026-01-13
+
+### Added
+- 功能測試導向的 R Shiny App Debug 工具，整合 agent-browser（前端）與 R console（後端）
+- `/shiny-debug` command with Log-First discipline
+- E2E 腳本生成功能（shinytest2 format）
diff --git a/plugins/r-shiny-debugger/README.md b/plugins/r-shiny-debugger/README.md
index 519e02d4..1abcf1bf 100644
--- a/plugins/r-shiny-debugger/README.md
+++ b/plugins/r-shiny-debugger/README.md
@@ -1,21 +1,35 @@
 # R Shiny Debugger
 
-功能測試導向的 R Shiny App Debug 工具。
+R Shiny App debug + adaptive testing tools。
+
+## 命令
+
+| 命令 | 用途 |
+|------|------|
+| `/shiny-debug` | 單次互動式功能測試 + debug,Log-First 原則 |
+| `/shiny-adaptive-walk` | 自我收斂 adaptive testing loop — discover + classify + mutate test infra,real bug 開 `/idd-issue`(MP165 v1.2 Track B) |
 
 ## 特色
 
-- **功能測試導向** — 測試「做 A 應該發生 B」，不只是看 app 能不能跑
+- **功能測試導向** — 測試「做 A 應該發生 B」,不只是看 app 能不能跑
 - **前後端整合** — 同時觀察 UI 變化和 R console 輸出
 - **自然語言測試** — 用口語描述測試目標
-- **E2E 腳本生成** — Debug 完成後可自動產生 shinytest2 E2E 測試腳本
+- **Adaptive convergence** — 新 `shiny-adaptive-walk` 採 self-converging loop pattern(沿用 `/glue-bridge` MP102 v1.3),iter 直到 CONVERGED / PLATEAUED / DIMINISHING
+- **Real bug vs test gap 分流** — adaptive-walk 自動判別 user-visible defect(file `/idd-issue`)vs test infra coverage gap(skill 自動修)
+- **Mutation boundary** — adaptive-walk 限定只動 `98_test/e2e/**` + `dashboard_presence_gate.R`,production code 一律走 issue
+- **E2E 腳本生成** — `/shiny-debug` 完成後可自動產生 shinytest2 E2E 測試腳本
 
 ## 前置需求
 
 ```bash
-# agent-browser
+# agent-browser (default for both /shiny-debug and /shiny-adaptive-walk discovery)
 npm install -g agent-browser
 agent-browser install
 
+# safari-browser (opt-in for /shiny-adaptive-walk --browser safari, macOS only)
+# 安裝路徑見 https://github.com/...
+# 平常不需要;只在想看 adaptive-walk loop 即時跑(教學 / live demo / 視覺 debug)時才裝。
+
 # R + Shiny
 # 確保已安裝 R 和 shiny 套件
 ```
@@ -23,15 +37,40 @@ agent-browser install
 ## 使用
 
 ```bash
-# 互動模式
+# 互動 debug 模式
 /shiny-debug
 
-# 指定測試
+# 指定測試目標
 /shiny-debug 上傳 CSV 後圖表會更新
+
+# Adaptive testing loop(需要 spectra change adaptive-dashboard-test-loop merged)
+/shiny-adaptive-walk QEF_DESIGN                  # default: agent-browser (headless)
+/shiny-adaptive-walk QEF_DESIGN --browser safari # opt-in: visible Safari for live watch
+/shiny-adaptive-walk D_RACING --budget 50 --max-iter 3
+
+# Browser mode rationale: default is headless agent-browser (faster, reproducible,
+# no macOS Safari tab-focus contention). --browser safari is opt-in for live demo /
+# teaching / in-the-moment visual debugging. See shiny-adaptive-walk.md
+# "When to opt into --browser safari" for details.
 ```
 
-## 命令
+## Tool 對比
 
-| 命令 | 說明 |
+| 情境 | 工具 |
 |------|------|
-| `/shiny-debug` | 啟動功能測試工作流程 |
+| Local dev 單次 debug,知道要測什麼 | `/shiny-debug` |
+| Live remote URL verification(Posit Connect)| `safari-browser` CLI 直接調用 |
+| 不知道有什麼 bug,讓 skill 主動探索 + 補 test | `/shiny-adaptive-walk` |
+| CI 自動化迴歸 | `shinytest2` test files in `98_test/e2e/` |
+
+## 相關 spectra changes
+
+- `adaptive-dashboard-test-loop`(issue #653)— `/shiny-adaptive-walk` 的 design / spec / tasks source
+- `dashboard-presence-verification`(issue #599)— MP165 framework Track A declarative baseline
+
+## 相關 principles
+
+- **MP165** Dashboard Presence as Pipeline Acceptance(v1.2 後含 Track A + Track B 雙軌制)
+- **MP102 v1.3** Self-Converging Review pattern(`/glue-bridge` 同源)
+- **IC_R011** Commercial Low-Bar Issue Filing(`/shiny-adaptive-walk` 對 real bug 的處理依據)
+- `00_principles/.claude/rules/08-shiny-testing.md` 含 default browser rule(local = agent-browser; remote = safari-browser narrow scope;adaptive-walk discovery 是 narrow exception)
diff --git a/plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md b/plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md
new file mode 100644
index 00000000..9a0e8e2e
--- /dev/null
+++ b/plugins/r-shiny-debugger/commands/shiny-adaptive-walk.md
@@ -0,0 +1,712 @@
+---
+description: Self-converging adaptive walker for MP165 dashboard testing — discovers defects via agent-browser (or opt-in safari-browser) + LLM judge, auto-mutates test infra, files real bugs as /idd-issue. Spectra: adaptive-dashboard-test-loop (#653) + adaptive-walk-agent-browser-default
+argument-hint: <COMPANY> [--budget N] [--max-iter N] [--no-pr] [--browser=safari|agent]
+---
+
+# Shiny Adaptive Walk
+
+Self-converging test-builder loop for MP165 dashboard rendering acceptance. Each iteration:
+
+1. Walks the company dashboard via **agent-browser** by default (headless Chromium — fast, stable, reproducible). Opt into visible **safari-browser** via `--browser safari` for live-watch scenarios.
+2. LLM judges each rendered screenshot for defects
+3. Bifurcates per defect:
+   - **test_infra_gap** → skill auto-mutates `qef_design.yaml` / `contracts.R` / `run_smoke_lite.R`
+   - **real_bug** → skill files `/idd-issue` (does NOT touch production code)
+4. Runs existing test suite + mechanical gate to confirm no regression
+5. Repeats until CONVERGED / PLATEAUED / DIMINISHING
+
+Refs: spectra change `adaptive-dashboard-test-loop` (issue #653) / sister of `/shiny-debug` (interactive debug, single-pass) / MP165 v1.2 Track B (adaptive overlay vs Track A declarative baseline).
+
+## 使用方式
+
+```
+/shiny-adaptive-walk QEF_DESIGN                    # default config (browser=agent)
+/shiny-adaptive-walk QEF_DESIGN --browser safari   # opt into visible Safari (live watch)
+/shiny-adaptive-walk QEF_DESIGN --budget 50        # cap LLM calls at 50
+/shiny-adaptive-walk QEF_DESIGN --max-iter 3       # cap iterations at 3 (default 5)
+/shiny-adaptive-walk QEF_DESIGN --no-pr            # don't open PR after converge
+```
+
+Required argument: `<COMPANY>` matching `app_config.yaml` company code (QEF_DESIGN / D_RACING / MAMBA / WISER / kitchenMAMA).
+
+## 核心原則
+
+| Rule | Detail |
+|------|--------|
+| **Discovery walk** | Default `agent-browser` (headless Chromium) — fast, reproducible, no tab-focus contention. Opt into `safari-browser` via `--browser safari` for live observation; see "When to opt into `--browser safari`" below. Both engines render real DOM; `08-shiny-testing.md` narrow exception clause covers the opt-in safari path. |
+| **Mechanical regression** | `agent-browser` (headless Chromium) — confirms mutations don't break existing tests + new contracts catch defects. Independent of the discovery `--browser` setting. |
+| **Mutation boundary** | Skill CAN edit test infra (`98_test/e2e/**`, `23_deployment/dashboard_presence_gate.R`, `04_utils/fn_debug_mode.R`). Skill MUST NOT touch production code (`10_rshinyapp_components/`, `16_derivations/`, `04_utils/fn_analysis_*.R`, `update_scripts/ETL/`, `update_scripts/DRV/`) → files `/idd-issue` instead. |
+| **Atomic per-iter commit** | Each iteration ships as ONE commit `iter-N: <summary> (refs <#issue>)`. If post-mutation tests fail, `git reset --hard HEAD~1` reverts the iter. |
+| **LLM budget cap** | `MP165_ADAPTIVE_BUDGET=100` env var (default 100 calls per session). Short-circuit DIMINISHING when exhausted. |
+| **Branch isolation** | Skill operates on `idd/<N>-adaptive-test-loop` feature branch from main. NEVER pushes to remote during loop (Phase 6 final action: open PR for human review). |
+| **Issue dedup** | Real bugs filed with composite signature `<company>:<module>:<sub_tab>:<defect_class>:<key_phrase>`. Skill `gh issue list --search` before filing — match → comment on existing instead of new issue. |
+
+---
+
+## 執行步驟
+
+### Step 0: Pre-flight checks
+
+```bash
+# Browser selection — flag overrides env var overrides static `agent` default.
+# BROWSER_FLAG is set by the flag-parsing pass below (empty if --browser not given).
+BROWSER="${BROWSER_FLAG:-${SHINY_ADAPTIVE_BROWSER:-agent}}"
+case "$BROWSER" in
+  safari|agent) ;;
+  *) abort "--browser must be one of: safari, agent (got: $BROWSER)" ;;
+esac
+
+# Required tools — only the selected browser's CLI is required.
+if [ "$BROWSER" = "safari" ]; then
+  which safari-browser || abort "safari-browser CLI required for --browser safari (macOS only). Pass --browser agent to switch, or install safari-browser. See $L4_ENT/.../08-shiny-testing.md Live URL section"
+else
+  which agent-browser  || abort "agent-browser CLI required for default browser mode. npm install -g agent-browser && agent-browser install (or pass --browser safari if safari-browser is available)"
+fi
+which gh             || abort "gh CLI required"
+command -v Rscript   || abort "R + Rscript required"
+
+# Required env
+COMPANY="${1:?company required (QEF_DESIGN / D_RACING / MAMBA / WISER / kitchenMAMA)}"
+BUDGET="${MP165_ADAPTIVE_BUDGET:-100}"
+MAX_ITER="${MP165_MAX_ITER:-5}"
+OPEN_PR="${OPEN_PR:-true}"
+```
+
+Parse flags:
+- `--budget N` → override `MP165_ADAPTIVE_BUDGET` to N
+- `--max-iter N` → override `MP165_MAX_ITER` (default 5)
+- `--no-pr` → skip auto-PR at end
+- `--browser safari|agent` → override `SHINY_ADAPTIVE_BROWSER` env var (precedence: flag > env > `agent`)
+
+No tab-focus / window-count probing is performed — browser mode is determined explicitly by the precedence chain above. There is no runtime auto-fallback.
+
+### Step 1: Working tree + branch setup
+
+```bash
+# Must start clean
+test -z "$(git status --porcelain)" || abort "uncommitted changes; commit or stash first"
+
+# Determine parent issue for branch name (default #653, can override)
+PARENT_ISSUE="${PARENT_ISSUE:-653}"
+
+# Branch: idd/<N>-adaptive-test-loop[-2|-3...]
+BASE_BRANCH="idd/${PARENT_ISSUE}-adaptive-test-loop"
+BRANCH="$BASE_BRANCH"
+suffix=2
+while git rev-parse --verify "$BRANCH" >/dev/null 2>&1; do
+  BRANCH="${BASE_BRANCH}-${suffix}"
+  suffix=$((suffix + 1))
+done
+
+git checkout main
+git pull origin main
+git checkout -b "$BRANCH"
+echo "→ Working on branch: $BRANCH"
+```
+
+### Step 2: Pre-loop reconnaissance — read existing yaml
+
+```bash
+YAML_PATH="shared/global_scripts/98_test/e2e/contracts/$(echo "$COMPANY" | tr '[:upper:]' '[:lower:]').yaml"
+test -f "$YAML_PATH" || YAML_NEW=1
+
+# Snapshot pre-state for dedup
+PRE_CONTRACTS_HASH=$(test -f "$YAML_PATH" && sha256sum "$YAML_PATH" | cut -d' ' -f1 || echo "missing")
+```
+
+If `$YAML_PATH` doesn't exist (e.g., wiser / kitchenmama), skill will CREATE it during first iter with the standard schema header + reserved `# === auto-suggested ===` block.
+
+### Step 3: Iteration loop (max `$MAX_ITER`)
+
+```
+ITER=1
+LLM_CALLS_USED=0
+PREV_DEFECTS_HASH=""
+
+while [ $ITER -le $MAX_ITER ]; do
+  echo "═══ Iteration $ITER / $MAX_ITER ═══"
+  echo "Budget remaining: $((BUDGET - LLM_CALLS_USED)) / $BUDGET LLM calls"
+
+  if [ $LLM_CALLS_USED -ge $BUDGET ]; then
+    VERDICT="DIMINISHING"
+    REASON="budget exhausted at iter $ITER"
+    break
+  fi
+
+  iter_result=$(run_iteration $ITER)
+
+  case "$iter_result" in
+    "converged")      VERDICT="CONVERGED"; break ;;
+    "plateaued")      VERDICT="PLATEAUED"; break ;;
+    "diminishing")    VERDICT="DIMINISHING"; break ;;
+    "rollback")       echo "  iter $ITER rolled back due to regression"; ITER=$((ITER + 1)) ;;
+    "progress")       ITER=$((ITER + 1)) ;;
+  esac
+done
+
+if [ -z "$VERDICT" ]; then
+  VERDICT="MAX_ITER_REACHED"
+fi
+```
+
+#### Step 3a: Discovery walk
+
+The discovery walk uses the browser selected in Step 0 (`$BROWSER`). All five discovery primitives (`open` / `snapshot` / `click` / `fill` / `screenshot`) flow through a single dispatcher helper:
+
+```bash
+# Single source of truth for browser dispatch.
+# safari mode appends --url "$URL_SUBSTR" for tab targeting;
+# agent mode runs headless with a single ephemeral context (no --url needed).
+# Supported subcommands: open / snapshot / click / fill / screenshot.
+browser_cmd() {
+  local subcmd="$1"; shift
+  if [ "$BROWSER" = "safari" ]; then
+    safari-browser "$subcmd" "$@" --url "$URL_SUBSTR"
+  else
+    agent-browser "$subcmd" "$@"
+  fi
+}
+
+discover_defects() {
+  # 1. Start Shiny app via nohup
+  cd "$COMPANY_DIR"
+  pkill -TERM -f "Rscript app.R" 2>/dev/null
+  sleep 1
+  mkdir -p .shiny-debug
+  rm -f .shiny-debug/shiny.log
+  SHINY_DEBUG_MODE=TRUE nohup Rscript app.R > .shiny-debug/shiny.log 2>&1 &
+  APP_PID=$!
+
+  # 2. Wait for "Listening on" marker
+  for i in $(seq 1 60); do
+    if grep -q "Listening on" .shiny-debug/shiny.log 2>/dev/null; then break; fi
+    sleep 1
+  done
+  URL=$(grep "Listening on" .shiny-debug/shiny.log | tail -1 | grep -oE "http://[^[:space:]]+")
+  URL_SUBSTR=$(echo "$URL" | sed -E 's#https?://##; s#/$##')
+
+  # 3. Open the app (safari uses --url tab targeting; agent uses headless single-context)
+  browser_cmd open "$URL"
+  sleep 2
+
+  # 4. Login
+  browser_cmd snapshot -i > /tmp/snap_login.txt
+  PWD_REF=$(extract_ref_from_snap /tmp/snap_login.txt "textbox.*密碼|textbox.*password")
+  SUBMIT_REF=$(extract_ref_from_snap /tmp/snap_login.txt "button.*進入|button.*Login")
+  browser_cmd fill "${PWD_REF:-@e1}" VIBE
+  browser_cmd click "${SUBMIT_REF:-@e2}"
+  sleep 3
+
+  # 5. Walk top-level + sub-tabs, screenshot each
+  SCREENSHOTS=()
+  for tab in "總覽儀表板" "TagPilot" "Marketing Vital-Signs" "BrandEdge" "InsightForge 360" "報告中心"; do
+    browser_cmd snapshot -i > "/tmp/snap_${tab}.txt"
+    TAB_REF=$(extract_ref_from_snap "/tmp/snap_${tab}.txt" "link.*${tab}")
+    [ -n "$TAB_REF" ] || continue
+
+    browser_cmd click "$TAB_REF"
+    sleep 2.5  # bs4Dash accordion settle
+
+    # Take screenshot for top-level
+    browser_cmd screenshot "/tmp/walk_iter${ITER}_${tab}.png"
+    SCREENSHOTS+=("/tmp/walk_iter${ITER}_${tab}.png")
+
+    # Re-snap to find sub-tabs (reuse run_smoke_lite.R::.smoke_extract_sub_tab_refs)
+    SUB_REFS=$(R -e "source('shared/global_scripts/98_test/e2e/run_smoke_lite.R'); cat(.smoke_extract_sub_tab_refs(snap_text, '$tab', remaining_tabs))")
+    for sub_ref in $SUB_REFS; do
+      browser_cmd click "$sub_ref"
+      sleep 1
+      browser_cmd screenshot "/tmp/walk_iter${ITER}_${tab}_${sub_ref}.png"
+      SCREENSHOTS+=("/tmp/walk_iter${ITER}_${tab}_${sub_ref}.png")
+    done
+  done
+
+  kill -TERM "$APP_PID" 2>/dev/null
+}
+```
+
+No literal `safari-browser` or `agent-browser` CLI invocation should appear in Step 3a outside the `browser_cmd` helper.
+
+#### Step 3b: LLM judge classification (per screenshot)
+
+For each screenshot in `${SCREENSHOTS[@]}`, classify defects using hybrid rule + LLM:
+
+**Hard rules (deterministic, no LLM call needed)**:
+- Text content contains `Error:` / `[object Object]` / `<NA>` / `NaN` → `real_bug` (production-visible error)
+- KPI card value is `--` / `-` / `N/A` → `real_bug` (data path broken)
+- Title contains TitleCase English (4+ chars, not in DT controls whitelist) → `real_bug` (i18n regression)
+- Sub-tab visible in safari but absent from `$YAML_PATH` contracts → `test_infra_gap`
+
+**LLM judgment (for ambiguous cases)**:
+
+```
+Prompt template (for each screenshot):
+
+  You are evaluating a Shiny dashboard screenshot for defects.
+
+  Context:
+  - Company: $COMPANY
+  - Tab: $TAB_NAME / $SUB_TAB
+  - Product line: $PRODUCT_LINE
+  - Reference healthy state: $HEALTHY_REF_SCREENSHOT (when available)
+
+  Classify each visible defect:
+  - real_bug: user-visible error, missing data, broken render
+  - test_infra_gap: render is OK but test contracts don't cover this element
+  - acceptable: empty state with explanatory message (e.g., "請先選擇產品線")
+
+  Return JSON: { "defects": [{"signature": "...", "class": "real_bug|test_infra_gap|acceptable", "evidence": "..." }] }
+```
+
+Increment `LLM_CALLS_USED += 1` per LLM invocation. Use Claude Haiku 4.5 (per CLAUDE.md performance rule: lightweight + high-frequency).
+
+#### Step 3c: Mutation bifurcation
+
+```bash
+for defect in $defects_json; do
+  signature=$(echo "$defect" | jq -r .signature)
+  class=$(echo "$defect" | jq -r .class)
+  evidence=$(echo "$defect" | jq -r .evidence)
+
+  case "$class" in
+    "real_bug")
+      handle_real_bug "$signature" "$evidence"
+      ;;
+    "test_infra_gap")
+      handle_test_infra_gap "$signature" "$evidence"
+      ;;
+    "acceptable")
+      # No action; just log
+      echo "  $signature: acceptable empty state, no defect"
+      ;;
+  esac
+done
+```
+
+##### `handle_real_bug` — file `/idd-issue` with dedup
+
+```bash
+handle_real_bug() {
+  local sig="$1"  # e.g., "QEF_DESIGN:insightforge:market_track:error_object:coefficient"
+  local evidence="$2"
+
+  # Dedup: search existing issues
+  existing=$(gh issue list --repo kiki830621/ai_martech_global_scripts \
+    --state open --search "in:body \"$sig\"" --json number -q '.[0].number')
+
+  if [ -n "$existing" ]; then
+    # Re-observed during this run; comment instead of new issue
+    gh issue comment "$existing" --repo kiki830621/ai_martech_global_scripts \
+      --body "Re-observed during \`/shiny-adaptive-walk\` iter $ITER ($(date -u +%Y-%m-%d)). Signature: \`$sig\`"
+    FILED_ISSUES+=("$existing (re-observed)")
+  else
+    # New issue
+    new_url=$(gh issue create --repo kiki830621/ai_martech_global_scripts \
+      --title "[bug][$COMPANY] $(echo "$evidence" | head -1)" \
+      --label "bug,confidence:confirmed,priority:P2,company:$COMPANY" \
+      --body "$(cat <<EOF
+## Problem
+
+Discovered during \`/shiny-adaptive-walk $COMPANY\` iteration $ITER.
+
+**Defect signature**: \`$sig\`
+
+**Evidence**: $evidence
+
+## Source
+
+Surfaced during \`/shiny-adaptive-walk\` adaptive testing loop (refs spectra change \`adaptive-dashboard-test-loop\`, parent issue #$PARENT_ISSUE). Per IC_R011 commercial low-bar filing — skill files this rather than fixing because production code is OUTSIDE mutation boundary.
+
+## Files NOT touched by skill
+
+- \`shared/global_scripts/10_rshinyapp_components/**\`
+- \`shared/global_scripts/16_derivations/**\`
+- \`shared/global_scripts/04_utils/fn_analysis_*.R\`
+- \`shared/update_scripts/ETL/**\`
+- \`shared/update_scripts/DRV/**\`
+
+Bug fix is human responsibility.
+EOF
+)")
+    FILED_ISSUES+=("$new_url")
+  fi
+}
+```
+
+##### `handle_test_infra_gap` — mutate test framework
+
+```bash
+handle_test_infra_gap() {
+  local sig="$1"
+  local evidence="$2"
+
+  # Parse signature to identify which file + what mutation
+  module=$(echo "$sig" | cut -d: -f2)
+  sub_tab=$(echo "$sig" | cut -d: -f3)
+  gap_type=$(echo "$sig" | cut -d: -f4)
+
+  case "$gap_type" in
+    "missing_contract")
+      # Append to # === auto-suggested === block in yaml
+      append_yaml_contract "$YAML_PATH" "$module" "$sub_tab" "$evidence"
+      ;;
+    "weak_primitive")
+      # New primitive or strengthen existing in contracts.R
+      add_contracts_primitive "$evidence"
+      ;;
+    "walker_miss")
+      # Strengthen run_smoke_lite.R walker logic
+      strengthen_walker "$evidence"
+      ;;
+    *)
+      log_warn "  Unknown gap_type '$gap_type', skipping mutation"
+      ;;
+  esac
+}
+```
+
+Auto-suggested yaml append pattern:
+
+```yaml
+# === auto-suggested by adaptive walker (2026-MM-DD iter N) ===
+modules:
+  insightforge:
+    enabled: true
+    sub_tabs:
+      market_track:
+        active_product_lines: [hsg, sfg, ...]  # detected from app config
+        contracts:
+          - selector: "insightforge_market-kpi_track_champion"
+            assertion: "no_error_placeholder"
+            severity: critical
+          - selector: "insightforge_market-table_track_analysis"
+            assertion: "no_error_text"
+            severity: critical
+```
+
+Skill **must** preserve hand-maintained sections of yaml above the `# === auto-suggested ===` marker. Diff-aware: walker only modifies content AFTER the marker.
+
+#### Step 3d: Per-iter safety gate
+
+```bash
+run_safety_gate() {
+  # 1. Existing test suite
+  echo "  Running existing test suite..."
+  if ! NOT_CRAN=true Rscript -e "testthat::test_dir('shared/global_scripts/98_test/e2e', reporter='summary')" > /tmp/test_dir.log 2>&1; then
+    echo "  ✗ Existing tests broke — iter $ITER will rollback"
+    return 1
+  fi
+
+  # 2. Mechanical gate against current company
+  echo "  Running mechanical gate..."
+  if ! Rscript shared/global_scripts/23_deployment/dashboard_presence_gate.R \
+    --company "$COMPANY" \
+    --app-dir "$COMPANY_DIR" \
+    --allow-warnings \
+    --password VIBE \
+    --timeout 90 > /tmp/gate.log 2>&1; then
+    echo "  ✗ Mechanical gate failed — iter $ITER will rollback"
+    return 1
+  fi
+
+  return 0
+}
+
+# Commit + safety check + rollback if needed.
+# Per-iter commit body carries an audit-trail line BROWSER=<safari|agent>
+# so commit history records which browser produced this iter's evidence.
+if [ -n "$(git status --porcelain)" ]; then
+  git add -A
+  COMMIT_BODY="BROWSER=$BROWSER"
+  if [ -n "$ITER_BODY_EXTRA" ]; then
+    COMMIT_BODY="$COMMIT_BODY
+
+$ITER_BODY_EXTRA"
+  fi
+  git commit -m "iter-$ITER: $ITER_SUMMARY (refs #$PARENT_ISSUE)" -m "$COMMIT_BODY" 2>&1
+
+  if ! run_safety_gate; then
+    git reset --hard HEAD~1
+    echo "  ROLLBACK: iter $ITER mutations reverted"
+    iter_result="rollback"
+  else
+    iter_result="progress"
+  fi
+fi
+```
+
+#### Step 3e: Convergence detection
+
+```bash
+# Defect signatures this iter
+CURRENT_DEFECTS_HASH=$(echo "${DEFECT_SIGNATURES[@]}" | sort | sha256sum | cut -d' ' -f1)
+
+# Real-bug ratio
+REAL_BUG_RATIO=$(echo "scale=2; ${#FILED_ISSUES[@]} / (${#DEFECT_SIGNATURES[@]} + 0.001)" | bc)
+
+if [ ${#DEFECT_SIGNATURES[@]} -eq 0 ]; then
+  iter_result="converged"
+  REASON="0 defects this iter, mutations from iter $((ITER-1)) all PASS regression"
+elif [ "$CURRENT_DEFECTS_HASH" = "$PREV_DEFECTS_HASH" ]; then
+  iter_result="plateaued"
+  REASON="same defect set 2 consecutive iters; user intervention needed"
+elif (( $(echo "$REAL_BUG_RATIO > 0.8" | bc -l) )); then
+  iter_result="diminishing"
+  REASON="${#FILED_ISSUES[@]} real bugs filed vs only ${#MUTATIONS_THIS_ITER[@]} test gaps — test infra converged, await bug fixes"
+fi
+
+PREV_DEFECTS_HASH="$CURRENT_DEFECTS_HASH"
+```
+
+### Step 4: PLATEAUED handling — AskUserQuestion
+
+When `VERDICT="PLATEAUED"`, surface to user before exit:
+
+```
+AskUserQuestion:
+  question: "Loop plateaued at iter $ITER on $defect_count same defects 2 iters. How to handle?"
+  options:
+    - "force-converge: accept current state, exit"
+    - "bulk-file: file remaining defects as omnibus issue"
+    - "abort: leave branch as-is, user investigates manually"
+```
+
+### Step 5: Final report
+
+```
+══════════════════════════════════════════
+/shiny-adaptive-walk $COMPANY — $VERDICT
+══════════════════════════════════════════
+
+Iterations:    $ITER / $MAX_ITER
+LLM calls:     $LLM_CALLS_USED / $BUDGET
+Branch:        $BRANCH
+Walk time:     ${ELAPSED}s total
+
+Test framework mutations:
+$(printf '  - %s\n' "${MUTATIONS[@]}")
+
+Real bugs filed (per IC_R011 commercial low-bar):
+$(printf '  - %s\n' "${FILED_ISSUES[@]}")
+
+Rollbacks:     $ROLLBACK_COUNT
+Reason:        $REASON
+
+Next: review git diff main..$BRANCH + open PR for human review
+```
+
+### Step 6: Open PR (if `--no-pr` not specified)
+
+```bash
+if [ "$OPEN_PR" = "true" ]; then
+  git push -u origin "$BRANCH"
+  gh pr create --repo kiki830621/ai_martech_global_scripts \
+    --base main --head "$BRANCH" \
+    --title "[adaptive-test] $COMPANY iter $ITER $VERDICT (refs #$PARENT_ISSUE)" \
+    --body "$(cat <<EOF
+Refs #$PARENT_ISSUE — \`/shiny-adaptive-walk $COMPANY\` run
+
+## Convergence
+- Verdict: **$VERDICT**
+- Iterations: $ITER / $MAX_ITER
+- LLM budget: $LLM_CALLS_USED / $BUDGET
+
+## Mutations
+$(printf '- %s\n' "${MUTATIONS[@]}")
+
+## Real bugs filed
+$(printf '- %s\n' "${FILED_ISSUES[@]}")
+
+## Cross-co (IC_P002)
+Single-co run for $COMPANY. Verified: trailer requires running on 5 cos (per parent spectra change adaptive-dashboard-test-loop Phase 5).
+
+🤖 Generated by /shiny-adaptive-walk
+EOF
+)"
+fi
+```
+
+---
+
+## Mutation boundary spec (CRITICAL)
+
+### Mutable zone (skill CAN edit)
+
+| Path glob | Why |
+|-----------|-----|
+| `shared/global_scripts/98_test/e2e/contracts/*.yaml` | Auto-emit contracts to `# === auto-suggested ===` block |
+| `shared/global_scripts/98_test/e2e/contracts/contracts.R` | Add new primitives when existing 5 + 3 (Phase 1) insufficient |
+| `shared/global_scripts/98_test/e2e/run_smoke_lite.R` | Strengthen walker when navigation gaps surface |
+| `shared/global_scripts/98_test/e2e/test-*.R` | Add new regression test files for discovered defects |
+| `shared/global_scripts/23_deployment/dashboard_presence_gate.R` | Add new gate logic / flags |
+| `shared/global_scripts/04_utils/fn_debug_mode.R` | Strengthen NULL detection or add new debug-mode signals |
+
+### Immutable zone (skill MUST file `/idd-issue` instead)
+
+| Path glob | Reason for immutability |
+|-----------|-------------------------|
+| `shared/global_scripts/10_rshinyapp_components/**` | UI component source code — code-under-test |
+| `shared/global_scripts/16_derivations/**` | Business logic derivations |
+| `shared/global_scripts/04_utils/fn_analysis_*.R` | Analysis functions |
+| `shared/update_scripts/ETL/**` | ETL pipeline scripts |
+| `shared/update_scripts/DRV/**` | Derivation execution scripts |
+| `shared/global_scripts/01_db/**` | Database connection / DDL |
+| Any `.qmd` principle file | Principle changes require explicit human decision |
+
+**Pre-mutation check**: before any file edit, verify path is in mutable zone via hard glob match. Refuse mutation if file is in immutable zone — file issue instead.
+
+---
+
+## Convergence model (mirrors `/glue-bridge` MP102 v1.3)
+
+| Verdict | Trigger | Action |
+|---------|---------|--------|
+| **CONVERGED** | 0 new defects this iter AND previous iter's mutations all PASS regression | Exit success. Test infra has full coverage of currently-observable defects. |
+| **PLATEAUED** | Same defect signature set 2 consecutive iters | AskUserQuestion 3-option (force-converge / bulk-file / abort) |
+| **DIMINISHING** | >80% real_bug classifications this iter (test gaps mostly resolved, remaining defects are code bugs awaiting human fix) | Exit success with list of filed bugs. Test infra is converged for what's testable. |
+| **MAX_ITER_REACHED** | Hit `$MAX_ITER` without other terminal state | Exit partial. User can re-invoke to continue. |
+| **BUDGET_EXHAUSTED** | `LLM_CALLS_USED >= BUDGET` mid-iter | Short-circuit DIMINISHING. User can re-invoke with `--budget` override. |
+
+---
+
+## Examples
+
+### Today's #653 F1-F5 retroactive walkthrough
+
+If `/shiny-adaptive-walk QEF_DESIGN` were run against current main (assuming Phase 1+2 already merged), expected behavior:
+
+**Iter 1**:
+- Discovery walks 6 top + 8 sub-tabs (Phase 2 walker)
+- LLM judge classifies:
+  - F1 InsightForge 市場賽道 `Error: [object Object]` → **real_bug** (hard rule)
+  - F2 InsightForge 精準行銷 `--` KPI → **real_bug** (hard rule)
+  - F3 InsightForge 時間分析 `0/0/--/0` → **real_bug** (LLM judges as broken data path)
+  - F4 BrandEdge KFE `Key Factor Evaluation` hardcoded English → **real_bug** (hard rule)
+  - F5 BrandEdge 理想點分析 hardcoded English subtitle → **real_bug** (hard rule)
+  - meta: InsightForge sub-tabs absent from `qef_design.yaml` → **test_infra_gap**
+
+Skill actions:
+- File `/idd-issue` for F1+F2+F3 (combined or separate, dedup against #655 if exists)
+- File `/idd-issue` for F4+F5 (dedup against #656)
+- Mutate `qef_design.yaml` — append InsightForge module to `# === auto-suggested ===` block with contracts using `assert_no_error_text` + `assert_kpi_no_error_placeholder`
+- Commit `iter-1: file 5 bugs + add InsightForge contracts (refs #653)`
+- Run safety gate — confirm new contracts catch F1-F5 + existing tests pass
+
+**Iter 2**:
+- Discovery walks again
+- Same F1-F5 defects appear (no code fix yet)
+- LLM judge classifies all as **real_bug** — but dedup finds existing issues, skip filing
+- No new test_infra_gap (yaml already has contracts)
+- DIMINISHING verdict (100% real_bug, no new mutations)
+
+**Final report**: CONVERGED on test infra, 5 bugs filed awaiting human fix.
+
+### Empty company (already-covered)
+
+If `/shiny-adaptive-walk D_RACING` runs and walker finds no new defects:
+
+**Iter 1**:
+- Walks 6 tabs + sub-tabs
+- LLM judge: 0 defects across all screenshots
+- No mutations needed, no bugs filed
+- CONVERGED at iter 1
+
+Final yaml `# === auto-suggested ===` block contains `# (none — already covered)`.
+
+---
+
+## Anti-patterns
+
+| Don't | Do |
+|-------|----|
+| Edit production code (UI components, business logic) | File `/idd-issue` — skill respects bug ownership boundary |
+| Skip per-iter regression gate | ALWAYS run test_dir + mechanical gate; auto-rollback on failure |
+| File duplicate bug issues | Compute composite signature + `gh issue list --search` before filing |
+| Run on dirty working tree | Refuse start with uncommitted changes (per Step 1) |
+| Auto-merge PR | NEVER push directly to main; only feature branch + PR for human review |
+| Ignore budget | Short-circuit DIMINISHING when `LLM_CALLS_USED >= BUDGET` |
+
+---
+
+## Configuration reference
+
+| Env var | Default | Effect |
+|---------|---------|--------|
+| `MP165_ADAPTIVE_BUDGET` | 100 | Max LLM judge calls per skill session |
+| `MP165_MAX_ITER` | 5 | Max iterations before MAX_ITER_REACHED |
+| `PARENT_ISSUE` | 653 | Issue # used in branch name + commit refs |
+| `OPEN_PR` | true | If "false", skill doesn't auto-create PR at end |
+| `SHINY_ADAPTIVE_BROWSER` | `agent` | Discovery browser. Values: `safari` or `agent`. Overridden by `--browser` flag when both are set. See "When to opt into `--browser safari`" below. |
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| `--budget N` | Override `MP165_ADAPTIVE_BUDGET` to N |
+| `--max-iter N` | Override `MP165_MAX_ITER` to N |
+| `--no-pr` | Skip auto-PR (sets `OPEN_PR=false`) |
+| `--browser safari\|agent` | Discovery browser. Default `agent`. Overrides `SHINY_ADAPTIVE_BROWSER` env var. See "When to opt into `--browser safari`" below. |
+
+### When to opt into `--browser safari`
+
+The default `agent-browser` (headless Chromium) is the right choice for almost every invocation: unattended runs, CI, multi-hour cross-company rollouts, and any case where nobody is watching the loop iterate. Headless is faster (no Safari startup or window animation per iteration), more reproducible (ephemeral context, no user-profile cookies or extensions), and immune to macOS Safari's tab-focus contention.
+
+Opt into `--browser safari` only when realtime visibility is the value:
+
+| Scenario | Why safari |
+|----------|------------|
+| Live demo / teaching | The audience needs to see the loop walk the dashboard |
+| In-the-moment debugging | You want to watch each click land in a real Safari window |
+| Visual regression spot-check | You're suspicious of an engine-specific WebKit rendering issue |
+
+If none of those apply, leave the default. Both engines render real DOM; for Shiny apps built on bs4Dash + plotly + DT there is no meaningful rendering difference. The "real renderer ground truth" framing that earlier versions of this skill carried was Safari-bias, not fact.
+
+---
+
+## Cross-references
+
+- **Sister skill**: `/shiny-debug` — single-pass interactive functional debug (this skill = self-converging adaptive loop)
+- **Parent spectra change**: `adaptive-dashboard-test-loop` in `kiki830621/ai_martech_global_scripts` repo (`openspec/changes/adaptive-dashboard-test-loop/`)
+- **Parent issue**: kiki830621/ai_martech_global_scripts#653
+- **MP165 v1.2 amendment**: codifies dual-track architecture (Track A declarative `qef_design.yaml` baseline + Track B adaptive walker overlay)
+- **Prior art**: `/glue-bridge` MP102 v1.3 self-converging review pattern (CONVERGED / PLATEAUED / DIMINISHING verdicts)
+- **Principle exception**: `00_principles/.claude/rules/08-shiny-testing.md` narrow exception clause permits safari-browser on local for adaptive-walker discovery. The clause stays accurate as written; default browser is `agent-browser` since the `adaptive-walk-agent-browser-default` change (issue PsychQuant/psychquant-claude-plugins#77), and safari is opt-in via `--browser safari`.
+- **Default browser change**: PsychQuant/psychquant-claude-plugins#77 — inverted default from safari to agent.
+- **Bug filing discipline**: IC_R011 commercial low-bar filing
+
+---
+
+## Troubleshooting
+
+### safari-browser missing (only matters when `--browser safari` is selected)
+
+```bash
+safari-browser --version
+```
+
+If `safari-browser` is missing and you passed `--browser safari` (or set `SHINY_ADAPTIVE_BROWSER=safari`), Step 0 pre-flight aborts with a message naming the missing CLI. Two ways forward:
+
+- Drop the safari opt-in: invoke without `--browser` (and unset `SHINY_ADAPTIVE_BROWSER`) — skill runs the default headless `agent-browser` path.
+- Install safari-browser: macOS-only. See `$L4_ENT/.../08-shiny-testing.md` Live URL section.
+
+If you did NOT opt into safari, this section does not apply — the default `agent-browser` path bypasses safari-browser entirely.
+
+### agent-browser missing (default path)
+
+```bash
+agent-browser --version
+```
+
+If `agent-browser` is missing and you are on the default browser mode (no `--browser` flag and no `SHINY_ADAPTIVE_BROWSER=safari`), Step 0 pre-flight aborts. Install with `npm install -g agent-browser && agent-browser install`. Most macOS dev environments already have it (used by `/shiny-debug` sister skill). Common in bare Linux CI containers.
+
+### Branch collision
+
+If `idd/<N>-adaptive-test-loop` already exists, skill auto-suffixes to `-2`, `-3`, etc. (per Step 1).
+
+### LLM judge returns inconsistent classification
+
+Skill caches LLM responses per screenshot (content hash). Re-running iter N with same screenshots reuses cache. To invalidate: `rm -rf /tmp/adaptive_walk_cache_*`.
+
+### git status not clean after iter
+
+If `git status` shows untracked files (e.g., new test fixture in `98_test/e2e/test-foo-fixture-iter1.png`), those are skill artifacts. Commit them as part of the iter's mutations OR add to `.gitignore`. Skill should NEVER leave dirty state mid-loop — debug if encountered.
diff --git a/plugins/safari-browser/CLAUDE.md b/plugins/safari-browser/CLAUDE.md
new file mode 100644
index 00000000..a8662f29
--- /dev/null
+++ b/plugins/safari-browser/CLAUDE.md
@@ -0,0 +1,11 @@
+## Design Principle: Non-Interference
+
+All safari-browser commands default to non-interference — users can do other things simultaneously.
+
+- No mouse/keyboard control unless `--allow-hid` / `--native`
+- No system dialogs
+- No sounds (`screencapture -x`)
+- No window focus stealing
+
+New commands must be classified by interference level before implementation.
+Full spec: project repo `openspec/specs/non-interference/spec.md`
diff --git a/plugins/safari-browser/hooks/check-cli.sh b/plugins/safari-browser/hooks/check-cli.sh
new file mode 100755
index 00000000..60f4b277
--- /dev/null
+++ b/plugins/safari-browser/hooks/check-cli.sh
@@ -0,0 +1,19 @@
+#!/bin/bash
+# Check if safari-browser CLI is installed
+
+BINARY_NAME="safari-browser"
+INSTALL_PATH="$HOME/bin/$BINARY_NAME"
+SOURCE_DIR="$HOME/Developer/safari-browser"
+
+if [[ -x "$INSTALL_PATH" ]]; then
+    echo "✓ $BINARY_NAME installed: $INSTALL_PATH"
+else
+    echo "⚠️  $BINARY_NAME not found at $INSTALL_PATH"
+    if [[ -d "$SOURCE_DIR" ]]; then
+        echo "   Build and install: cd $SOURCE_DIR && make install"
+    else
+        echo "   Clone and install:"
+        echo "     git clone git@github.com:PsychQuant/safari-browser.git $SOURCE_DIR"
+        echo "     cd $SOURCE_DIR && make install"
+    fi
+fi
diff --git a/plugins/safari-browser/hooks/hooks.json b/plugins/safari-browser/hooks/hooks.json
new file mode 100644
index 00000000..24fd6dac
--- /dev/null
+++ b/plugins/safari-browser/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-cli.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/safari-browser/plugin.json b/plugins/safari-browser/plugin.json
new file mode 100644
index 00000000..9d54a1cc
--- /dev/null
+++ b/plugins/safari-browser/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "safari-browser",
+  "description": "macOS native browser automation via Safari + AppleScript — permanent login, upload --native, site-specific playbook skills, persistent daemon (Phase 1 commands ~50ms vs ~370ms stateless), exec script v2 (single-invocation multi-step JSON), --mark-tab opt-in tab ownership marker, daemon security hardening (socket/pid 0600, log redaction, stale-pid liveness, dirty-build handshake, lifecycle bypass).",
+  "version": "2.6.0",
+  "author": {
+    "name": "Che Cheng"
+  }
+}
diff --git a/plugins/safari-browser/skills/CONTRIBUTING-PLAYBOOKS.md b/plugins/safari-browser/skills/CONTRIBUTING-PLAYBOOKS.md
new file mode 100644
index 00000000..c32ccbf0
--- /dev/null
+++ b/plugins/safari-browser/skills/CONTRIBUTING-PLAYBOOKS.md
@@ -0,0 +1,90 @@
+# Contributing a Playbook Skill
+
+Playbook skills live next to the main `safari-browser` skill and document how to accomplish a specific operation on a specific website using `safari-browser` commands. Claude Code auto-surfaces them when a user's intent matches a skill's `description`.
+
+This doc is the quick reference for contributors. The authoritative spec is `openspec/specs/playbook-skills/spec.md` in the safari-browser repo.
+
+## Directory naming
+
+```
+skills/
+  safari-browser/SKILL.md       ← main skill (pre-existing)
+  safari-<site>-<action>/SKILL.md   ← playbook skills
+```
+
+- Use the pattern `safari-<site>-<action>`.
+- `<site>` is a lowercase kebab-case fragment of the domain (`plaud.ai` → `plaud`, `github.com` → `github`, `icloud.com` → `icloud`).
+- `<action>` is a lowercase verb describing the operation (`upload`, `star`, `login`).
+- Keep the layout flat. `skills/plaud/upload/SKILL.md` (nested) will NOT be discovered by Claude Code's skill loader and is rejected by the convention.
+- The `safari-` prefix is required: it prevents collisions with other plugins that might ship skills for the same site (for example, a Chrome-based plaud tool).
+
+## Frontmatter contract
+
+Each `SKILL.md` begins with exactly these three YAML keys:
+
+```yaml
+---
+name: safari-plaud-upload
+description: Upload audio files to Plaud via Safari. Use when the user asks to upload recordings to Plaud, add tracks to a Plaud folder, or transcribe audio with Plaud in Safari.
+allowed-tools:
+  - Bash(safari-browser:*)
+  - Bash(safari-browser *)
+---
+```
+
+Rules:
+
+- `name` MUST equal the enclosing directory name.
+- `description` MUST NOT exceed 200 characters, MUST mention "Safari", and MAY include an action clause followed by trigger phrases (e.g., "Upload audio files to Plaud via Safari. Use when ..."). Without the "Safari" keyword, Claude may auto-surface the playbook when the user is actually using a Chrome-based tool.
+- `allowed-tools` MUST include at minimum `Bash(safari-browser:*)` and `Bash(safari-browser *)`. Additional entries (for example, `Bash(curl:*)` or `Bash(jq:*)`) are permitted when the playbook needs them.
+
+## SKILL.md body — six ordered sections
+
+The body MUST contain exactly these six level-2 headings, in this order:
+
+```markdown
+## When to use
+## Preconditions
+## Steps
+## Error handling
+## Verification
+## Gotchas
+```
+
+What goes in each:
+
+| Section | Purpose |
+|---|---|
+| `When to use` | Concrete trigger phrases and situations; narrow enough to avoid false activation. |
+| `Preconditions` | Required login state, tab state, input files, permissions. Written so the user can satisfy them without reading the author's mind. |
+| `Steps` | Numbered `safari-browser` invocations; each step includes the expected result so failures are diagnosable. |
+| `Error handling` | Common failure modes and how to branch. |
+| `Verification` | How the agent confirms success (URL change, visible element, response text). |
+| `Gotchas` | Site-specific framework quirks, selector traps, anti-bot surprises, reactive-title resets, etc. |
+
+## Generalized seeds, not personal workflows
+
+A playbook MUST work for any user who installs the plugin and satisfies the `Preconditions`. Do NOT hardcode a specific account, plan tier, regional URL, or folder name — surface those in `Preconditions` so users can adapt them.
+
+If your workflow cannot be generalized, keep it as a user-local playbook at `~/.claude/skills/safari-<site>-<action>/SKILL.md` instead of shipping it in the plugin.
+
+## User-local override
+
+Users can override or extend plugin-hosted playbooks by placing their own `SKILL.md` at `~/.claude/skills/safari-<site>-<action>/SKILL.md` using the same naming, frontmatter, and body structure. Claude Code's native skill loading handles discovery — the plugin adds no custom precedence logic.
+
+## Review checklist
+
+Before opening a PR that adds a playbook, verify each item:
+
+- [ ] Directory name matches `safari-<site>-<action>` exactly.
+- [ ] `name` in frontmatter matches directory name.
+- [ ] `description` is ≤200 characters and mentions "Safari" (single or multiple clauses both fine).
+- [ ] `allowed-tools` includes both `Bash(safari-browser:*)` and `Bash(safari-browser *)`.
+- [ ] Body contains the six headings in the specified order.
+- [ ] Every section is non-empty.
+- [ ] `Preconditions` lists every assumed state, not just "user is logged in".
+- [ ] `Steps` include expected results, not just commands.
+- [ ] `Verification` is concrete (a URL pattern, an element, a response) — not "check that it worked".
+- [ ] No hardcoded personal identifiers or account-specific URLs.
+
+A reviewer should walk through each scenario in `openspec/specs/playbook-skills/spec.md` against your SKILL.md before merging.
diff --git a/plugins/safari-browser/skills/safari-browser/SKILL.md b/plugins/safari-browser/skills/safari-browser/SKILL.md
new file mode 100644
index 00000000..d2ce07bb
--- /dev/null
+++ b/plugins/safari-browser/skills/safari-browser/SKILL.md
@@ -0,0 +1,317 @@
+---
+name: safari-browser
+description: >-
+  macOS native browser automation via Safari + AppleScript. Use when the user needs to automate
+  websites that require login (Plaud, Elementor, banking, social media) — Safari preserves
+  localStorage and cookies permanently. Also use when agent-browser fails due to session/auth
+  issues, or when the user explicitly asks to use Safari. Triggers on: "login to site",
+  "automate with Safari", "use Safari", "session expired with agent-browser", "Plaud upload",
+  or any website automation where persistent auth is needed.
+allowed-tools:
+  - Bash(safari-browser:*)
+  - Bash(safari-browser *)
+---
+
+# Safari Browser Automation
+
+macOS native browser automation CLI using Safari + AppleScript. **Core advantage: permanent login** — uses the user's existing Safari session directly.
+
+## When to Use safari-browser vs agent-browser
+
+| Condition | Use |
+|-----------|-----|
+| Website requires login (Plaud, Elementor, banking, etc.) | **safari-browser** |
+| Need localStorage/cookies from existing session | **safari-browser** |
+| agent-browser `state save/load` fails | **safari-browser** |
+| Vue/React sites where `fill` doesn't trigger reactivity | **safari-browser** (JS events dispatched) |
+| Headless / CI / public sites | agent-browser |
+| Cross-platform needed | agent-browser |
+| Sites that block headless browsers (banks, social media) | **safari-browser** (real browser, no bot detection) |
+| AI + human collaboration (user watches and takes over) | **safari-browser** (shared Safari window) |
+| Need CDP accessibility tree | agent-browser (safari-browser has JS-based snapshot) |
+
+## Core Workflow
+
+```bash
+# Navigate
+safari-browser open "https://example.com"
+
+# Discover elements (like agent-browser snapshot)
+safari-browser snapshot              # @e1 input[type="email"], @e2 button "Submit"
+safari-browser snapshot -c           # compact (hide invisible elements)
+safari-browser snapshot --json       # structured JSON output
+
+# Interact using @refs or CSS selectors
+safari-browser click @e2
+safari-browser fill @e1 "user@example.com"
+safari-browser press Enter
+
+# Get information
+safari-browser get url
+safari-browser get text "h1"
+
+# Wait for page changes
+safari-browser wait --url "dashboard"
+safari-browser wait --js "document.querySelector('.loaded')"
+```
+
+## Command Reference
+
+### Navigation
+```bash
+safari-browser open <url> [--new-tab] [--new-window]
+safari-browser back
+safari-browser forward
+safari-browser reload
+safari-browser close
+```
+
+### Element Interaction
+```bash
+safari-browser click <selector>
+safari-browser dblclick <selector>
+safari-browser fill <selector> <text>       # clear + fill + input/change events
+safari-browser type <selector> <text>       # append text + input event
+safari-browser select <selector> <value>    # dropdown
+safari-browser hover <selector>
+safari-browser focus <selector>
+safari-browser check <selector>             # checkbox
+safari-browser uncheck <selector>
+safari-browser scroll <dir> [pixels]        # up/down/left/right, default 500px
+safari-browser scrollintoview <selector>
+safari-browser highlight <selector>         # red outline for debug
+safari-browser drag <src> <dst>            # drag and drop (JS events)
+```
+
+### Keyboard
+```bash
+safari-browser press Enter
+safari-browser press Tab
+safari-browser press Escape
+safari-browser press Control+a              # modifier combos
+safari-browser press Shift+Tab
+```
+
+### Find Elements (by text/role/label/placeholder)
+```bash
+safari-browser find text "Submit" click
+safari-browser find role "button" click
+safari-browser find label "Email" fill "user@example.com"
+safari-browser find placeholder "Search" fill "query"
+```
+
+### JavaScript
+```bash
+safari-browser js "document.title"
+safari-browser js --file script.js
+safari-browser js "JSON.stringify(localStorage)"
+safari-browser js --large "document.body.innerText"    # chunked read for large output
+safari-browser js --output /tmp/page.txt "document.body.innerText"  # write to file
+```
+
+**Large output handling**: Safari's `do JavaScript` silently drops results >~1MB. Use `--large` to force chunked read, or `--output` to write to file. The CLI auto-retries with chunked read when it detects empty output.
+
+### Page & Element Info
+```bash
+safari-browser get url
+safari-browser get title
+safari-browser get text [selector]          # full page or element
+safari-browser get source
+safari-browser get html <selector>
+safari-browser get value <selector>         # input value
+safari-browser get attr <selector> <name>
+safari-browser get count <selector>
+safari-browser get box <selector>           # bounding box JSON
+```
+
+### State Checks
+```bash
+safari-browser is visible <selector>        # true/false
+safari-browser is exists <selector>
+safari-browser is enabled <selector>
+safari-browser is checked <selector>
+```
+
+### Snapshot (Element Discovery + Page State)
+```bash
+safari-browser snapshot                     # scan interactive elements → @e1, @e2...
+safari-browser snapshot -c                  # compact (exclude hidden elements)
+safari-browser snapshot -d 3                # limit DOM depth
+safari-browser snapshot --page              # full page state: accessibility tree + metadata + alerts + dialogs
+safari-browser snapshot --page --json       # full page state as JSON
+safari-browser snapshot --page -s "main"    # scoped to <main> element
+safari-browser snapshot -s "form.login"     # scope to CSS selector
+safari-browser snapshot --json              # JSON array output
+```
+
+All selector-accepting commands support `@eN` refs from the last snapshot.
+
+### Screenshot, PDF & Upload
+```bash
+safari-browser screenshot [path]            # default: screenshot.png [non-interfering]
+safari-browser screenshot --full path       # full page [non-interfering]
+safari-browser pdf --allow-hid [path]       # export as PDF [actively interfering — requires --allow-hid]
+safari-browser upload <selector> <file>     # smart default: native dialog if Accessibility permitted, else JS fallback
+safari-browser upload --js <sel> <file>    # force JS DataTransfer injection [non-interfering]
+safari-browser upload --native <sel> <file> # force native file dialog [requires Accessibility permission]
+```
+
+**Upload behavior**: With Accessibility permission granted, `upload` uses the native file dialog by default (clipboard paste for path input — fast, supports all characters including CJK and spaces). Without permission, it automatically falls back to JS DataTransfer injection and prints a hint to stderr. Use `--js` to force JS mode, or `--native`/`--allow-hid` to force native mode (backward compatible).
+
+**PDF export**: Uses clipboard paste for path input (instead of keystroke), precise waits (`repeat until exists`) instead of blind delays, and AXDefault button click (locale-independent) for the Save button. Still requires `--allow-hid`.
+
+### Tab Management
+```bash
+safari-browser tabs                         # list all tabs
+safari-browser tabs --json                  # JSON array output
+safari-browser tab <n>                      # switch to tab n
+safari-browser tab new                      # new tab
+```
+
+### Wait
+```bash
+safari-browser wait <ms>                    # wait milliseconds
+safari-browser wait --url <pattern>         # wait for URL to contain pattern
+safari-browser wait --js <expr>             # wait for JS truthy
+safari-browser wait --timeout <ms>          # custom timeout (default 30s)
+```
+
+### Storage
+```bash
+safari-browser cookies get [name]           # get all or by name
+safari-browser cookies get --json           # JSON object output
+safari-browser cookies set <name> <value>
+safari-browser cookies clear
+safari-browser storage local get <key>
+safari-browser storage local set <key> <value>
+safari-browser storage local remove <key>
+safari-browser storage local clear
+safari-browser storage session get/set/remove/clear
+
+# Multi-window: per-origin storage requires --url targeting (#23)
+safari-browser storage local get token --url plaud   # Plaud's token
+safari-browser storage local get token --url oauth   # different OAuth provider's token
+```
+
+### Multi-Window Targeting (#17 #18 #21 #23)
+
+When Safari has more than one window open, every command that reads from
+or drives a document accepts global targeting flags:
+
+```bash
+safari-browser documents                                # discover available windows
+safari-browser get url --url plaud                      # target by URL substring
+safari-browser get title --window 2                     # target by window index (1-based)
+safari-browser snapshot --url plaud                     # snapshot specific document
+safari-browser wait --for-url "/dashboard" --url plaud  # wait on specific document
+
+# Window-scoped commands (close/screenshot/pdf/upload --native) only accept --window
+safari-browser screenshot --window 2 out.png
+safari-browser pdf --window 2 --allow-hid out.pdf
+safari-browser upload --native "input[type=file]" file.mp3 --window 2
+```
+
+**Reusing a lock flag across commands — use a bash array, not a string.**
+To lock several commands to the same document, store the flag in an **array** so
+it word-splits in both shells. A plain string + unquoted `$LOCK` breaks under zsh
+(Claude Code's Bash runs zsh), which does NOT word-split unquoted variables —
+`--url plaud` is then passed as one token and the CLI errors `Unknown option
+'--url plaud'`:
+
+```bash
+LOCK=(--url plaud)                       # ✅ array — splits in bash AND zsh
+safari-browser snapshot "${LOCK[@]}"
+safari-browser get url  "${LOCK[@]}"
+
+# ❌ LOCK="--url plaud"; safari-browser snapshot $LOCK   # breaks under zsh
+```
+
+**Default `screenshot` behavior** (#23 R7): when AX permission is granted, default `screenshot` (no flag) uses AX SPI for reliable identity (no title/bounds heuristic). Without AX permission, falls back to legacy CG name match.
+
+**`screenshot --window N`** (#23 R6 C1): requires Accessibility permission. Uses `_AXUIElementGetWindow` private SPI for reliable AS↔CG mapping. Eliminates the wrong-window failure modes that bedevil bounds-/title-based matching. Strict fail-closed: throws `windowIdentityAmbiguous` when multiple visible windows can't be uniquely identified, instead of silently picking one.
+
+**Wait command rename** (#23 BREAKING): `wait --url <pattern>` → `wait --for-url <pattern>`. The old `--url` flag is now a global targeting flag.
+
+### Settings
+```bash
+safari-browser set media dark               # force dark mode
+safari-browser set media light              # force light mode
+```
+
+### Debug
+```bash
+safari-browser console --start              # capture all levels (log/warn/error/info/debug)
+safari-browser console                      # read captured messages ([warn], [error] prefixed)
+safari-browser console --clear
+safari-browser errors --start               # capture JS errors
+safari-browser errors
+safari-browser mouse move <x> <y>
+safari-browser mouse down / up / wheel <dy>
+```
+
+## Common Patterns
+
+### Login-Required Site (e.g., Plaud)
+```bash
+# Safari already has the session — just navigate
+safari-browser open "https://web.plaud.ai"
+safari-browser wait --js "!document.querySelector('.login-form')"
+
+# Get JWT from localStorage
+TOKEN=$(safari-browser js "localStorage.getItem('tokenstr')")
+
+# Use token with curl for API calls
+curl -H "Authorization: $TOKEN" https://api.example.com/data
+```
+
+### Form Submission
+```bash
+safari-browser open "https://example.com/form"
+safari-browser fill "input#name" "John"
+safari-browser fill "input#email" "john@example.com"
+safari-browser select "select#country" "TW"
+safari-browser check "input#agree"
+safari-browser click "button[type='submit']"
+safari-browser wait --url "success"
+```
+
+### File Upload
+```bash
+safari-browser open "https://example.com/upload"
+safari-browser upload "input[type='file']" "/path/to/document.pdf"         # smart default (native if permitted, else JS)
+safari-browser upload --js "input[type='file']" "/path/to/document.pdf"   # force JS injection (no permissions needed)
+safari-browser upload --native "input[type='file']" "/path/to/document.pdf" # force native dialog
+safari-browser wait 5000   # wait for upload to complete
+```
+
+### Human-like Delays (Anti-Bot)
+
+When automating sites that detect bots (banks, hospital EMR, social media), use Cauchy-distributed random delays instead of fixed `sleep`:
+
+```bash
+# Cauchy delay: median ~3s, occasionally 5-10s (simulates human rhythm)
+sleep $(python3 -c "import random, math; print(max(2, round(3 + math.tan(math.pi * (random.random() - 0.5)) * 0.8, 1)))")
+```
+
+Use between every `safari-browser` command when operating sensitive sites. Never use fixed intervals — that's how bots get detected.
+
+## Troubleshooting
+
+- **Binary killed (exit 137 / SIGKILL)** — macOS Sequoia kills unsigned binaries that call osascript. Fix: `codesign --force --sign - ~/bin/safari-browser`. This is done automatically by `make install`.
+- **Large JS output returns empty** — Safari `do JavaScript` silently drops results >~1MB. Use `safari-browser js --large "..."` or `--output /tmp/result.txt` for chunked read.
+
+## Limitations
+
+- **macOS only** — requires Safari + AppleScript
+- **Not headless** — Safari always has a visible window
+- **JS returns strings only** — use `JSON.stringify()` for objects
+- **JS output ~1MB limit** — use `--large` flag for bigger results (auto-retries with chunked read)
+- **No network interception** — Safari has no API for this
+- **JS-based snapshot** — `snapshot` uses DOM scanning (not CDP accessibility tree), 90% as effective
+- **Automation permission required** — first run prompts for Terminal → Safari access (System Settings → Privacy & Security → Automation)
+- **upload smart default** — uses native file dialog when Accessibility permission is granted; auto-falls back to JS DataTransfer otherwise. Force with `--js` or `--native`
+- **pdf requires Accessibility permission** — System Settings → Privacy & Security → Accessibility (uses clipboard paste + AXDefault button click)
+
+## Playbooks
+
+Site-specific operation guides live as sibling skills named `safari-<site>-<action>/SKILL.md` — Claude Code auto-surfaces them by description when the user's intent matches. Seeds currently shipping: `safari-plaud-upload`, `safari-github-star`. To add a personal playbook (private site, custom flow), drop a `SKILL.md` at `~/.claude/skills/safari-<site>-<action>/SKILL.md` using the same convention; Claude loads user-local skills natively and no custom precedence is added by this plugin. Contribution guide: `plugins/safari-browser/skills/CONTRIBUTING-PLAYBOOKS.md`. Authoritative spec: `openspec/specs/playbook-skills/spec.md` in the safari-browser repo.
diff --git a/plugins/safari-browser/skills/safari-github-star/SKILL.md b/plugins/safari-browser/skills/safari-github-star/SKILL.md
new file mode 100644
index 00000000..8b13a0b1
--- /dev/null
+++ b/plugins/safari-browser/skills/safari-github-star/SKILL.md
@@ -0,0 +1,104 @@
+---
+name: safari-github-star
+description: Star a GitHub repository in Safari. Use when the user asks to star, favorite, or bookmark a GitHub repo via Safari and wants the action performed inside their own logged-in Safari session.
+allowed-tools:
+  - Bash(safari-browser:*)
+  - Bash(safari-browser *)
+---
+
+# safari-github-star
+
+Star a GitHub repository in the user's Safari session. Handles the logged-in / not-logged-in branch explicitly.
+
+## When to use
+
+Trigger phrases:
+- "star this repo on GitHub"
+- "star browser-use/browser-harness for me"
+- "bookmark this GitHub project via Safari"
+
+Do NOT trigger for:
+- Un-starring a repo (different action — would need a separate `safari-github-unstar` playbook).
+- Starring via API (`gh api ...`) — unrelated to Safari UI.
+- Any Chrome-based GitHub automation — use a Chrome-targeted tool.
+
+## Preconditions
+
+The user MUST satisfy these:
+
+1. **Safari is running** with at least one window.
+2. **Repository URL known**: Either a full URL (`https://github.com/<owner>/<name>`) or an `<owner>/<name>` slug you can expand.
+3. **Login state will be detected at runtime**: The user does NOT have to be logged in before invocation. If they are not, the playbook STOPS and reports the state — it does NOT attempt to type credentials.
+4. **No interstitial pages**: Cookies / privacy banners on github.com must already be dismissed for the active profile, or the first real interaction will dismiss them.
+
+## Steps
+
+1. **Open or focus the repo URL**
+   ```bash
+   safari-browser open https://github.com/<owner>/<name>
+   ```
+   Expected: a Safari tab shows the repo page. safari-browser's default behaviour focuses an existing matching tab rather than opening a second one.
+
+2. **Wait for the page to settle**
+   ```bash
+   safari-browser wait --for-url "github.com/<owner>/<name>" --url <owner>/<name>
+   ```
+   Expected: the URL resolver finds the GitHub tab and readyState reaches `complete`.
+
+3. **Detect login state**
+   ```bash
+   safari-browser js "!!document.querySelector('a[href=\"/login\"], a[href^=\"/login?\"]')" --url <owner>/<name>
+   ```
+   Expected: `true` if a sign-in link is visible (user is NOT logged in), `false` otherwise.
+
+   - If `true`: STOP. Report "not logged in — ask the user whether they want to sign in manually or skip." Do NOT type credentials.
+   - If `false`: continue to step 4.
+
+4. **Snapshot to locate the Star button**
+   ```bash
+   safari-browser snapshot -i --url <owner>/<name>
+   ```
+   Expected: a list of `@eN` refs. Look for an element labelled `Star` or `Unstar` with an `aria-label` containing "star this repository" or the repo name. Note its ref.
+
+5. **Check current star state before clicking**
+
+   Examine the snapshot output or run:
+   ```bash
+   safari-browser js "document.querySelector('form[action$=\"/star\"]')?.getAttribute('action') || document.querySelector('form[action$=\"/unstar\"]')?.getAttribute('action')" --url <owner>/<name>
+   ```
+   Expected: ends with `/star` if currently unstarred, `/unstar` if already starred.
+
+   - If already starred: STOP and report "already starred — no action needed."
+   - If unstarred: continue to step 6.
+
+6. **Click the Star button**
+   ```bash
+   safari-browser click @eN --url <owner>/<name>
+   ```
+   Expected: button label flips to `Starred` within ~1 second.
+
+## Error handling
+
+- **User is not logged in** (step 3 returned `true`): Report and STOP. Typing credentials from an agent is a safety violation.
+- **Repo not found** (404 or "This repository doesn't exist"): Report exactly what GitHub showed; STOP.
+- **Rate limited by GitHub** (visible banner): STOP and surface the cooldown period shown on the page.
+- **Star button not in snapshot**: GitHub occasionally ships A/B UI variants. Fall back to `safari-browser click button[aria-label*="star this repository" i] --url <owner>/<name>`; if that also fails, ask the user.
+- **Private repo without access**: GitHub 404s these as if they do not exist; same handling as "not found".
+
+## Verification
+
+Success criteria — ALL must hold:
+
+1. Re-run step 5's JS query and confirm the form action now ends with `/unstar`.
+2. Re-run `safari-browser snapshot -i --url <owner>/<name>` and confirm a ref labelled `Starred` or `Unstar` is present near where the Star ref used to be.
+3. Optionally, the star count near the button has incremented by 1 (not required — UI caches sometimes lag a second).
+
+If criterion 1 fails, the star click did NOT register — do NOT claim success.
+
+## Gotchas
+
+- **GitHub reactive title**: GitHub updates `document.title` on client-side navigation, so a `🟢` marker set by safari-browser may be reset. Harmless but surprising.
+- **Keyboard shortcuts inside the page**: GitHub's "s" keyboard shortcut focuses search. Don't use `press_key` to send "s" as a shortcut for star — use an explicit click.
+- **Star vs Watch vs Sponsor**: All three buttons are clustered. A loose selector like `button[aria-label*="star" i]` can match "Unstar" or even "star" inside sponsor copy. Prefer `form[action$="/star"]` when disambiguating.
+- **Enterprise GitHub**: `github.<company>.com` has the same DOM but different URL. Adjust the `--url` substring in every command accordingly — this playbook targets `github.com` by default.
+- **Authenticated session vs device-flow**: Safari-based session auth is what this playbook relies on. Device-flow (`gh auth`) does not affect the web session; the two are independent.
diff --git a/plugins/safari-browser/skills/safari-plaud-upload/SKILL.md b/plugins/safari-browser/skills/safari-plaud-upload/SKILL.md
new file mode 100644
index 00000000..100cfec0
--- /dev/null
+++ b/plugins/safari-browser/skills/safari-plaud-upload/SKILL.md
@@ -0,0 +1,99 @@
+---
+name: safari-plaud-upload
+description: Upload audio files to Plaud via Safari. Use when the user asks to upload a recording to Plaud, add tracks to a Plaud folder, or trigger Plaud transcription from a file that is already on disk.
+allowed-tools:
+  - Bash(safari-browser:*)
+  - Bash(safari-browser *)
+---
+
+# safari-plaud-upload
+
+Upload an audio file to Plaud via the user's already-logged-in Safari session.
+
+## When to use
+
+Trigger phrases:
+- "upload this recording to Plaud"
+- "add this audio to Plaud folder X"
+- "send this file to Plaud for transcription"
+
+Do NOT trigger for:
+- Querying Plaud transcription status → use `plaud-transcriber:plaud-status` instead.
+- Downloading transcripts → use `plaud-transcriber:plaud-download` instead.
+- Chrome / non-Safari browser automation → use a Chrome-based tool.
+
+## Preconditions
+
+The user MUST satisfy all of these before the playbook runs:
+
+1. **Logged in**: A Safari tab is open on `app.plaud.ai` (or the current Plaud web app origin) and the user is signed into their own Plaud account. If you see a login/SSO page, STOP and ask the user to sign in manually; do not type credentials.
+2. **Target folder known**: The user has either (a) already navigated to the destination folder in that tab, or (b) told you the exact folder name to use.
+3. **File on disk**: The audio file exists at a known absolute path. Supported formats follow Plaud's current restrictions (commonly `.mp3`, `.m4a`, `.wav`; confirm via Plaud's UI if unsure).
+4. **No modal sheet blocking the tab**: Close any Plaud first-run tour, banner, or subscription prompt before uploading.
+
+## Steps
+
+Run each step and check the expected result before moving on. Target the Plaud tab explicitly with `--url plaud` so nothing depends on which Safari window is frontmost.
+
+1. **Verify the Plaud tab is reachable**
+   ```bash
+   safari-browser get url --url plaud
+   ```
+   Expected: a URL on the Plaud origin. If multiple Plaud tabs exist, safari-browser fails with `ambiguousWindowMatch`; ask the user which window to use or pass `--window N` explicitly.
+
+2. **Snapshot the page to find the upload control**
+   ```bash
+   safari-browser snapshot -i --url plaud
+   ```
+   Expected: a list of `@eN` refs including a clearly labelled upload button (text such as "Upload", "+", or a plus-icon affordance near the folder content area). Note the ref of the upload trigger.
+
+3. **Click the upload trigger**
+   ```bash
+   safari-browser click @eN --url plaud
+   ```
+   Expected: a file picker opens OR an in-page drop zone becomes visible.
+
+4. **Attach the file**
+
+   Prefer the native file dialog (requires AX / Accessibility permission for safari-browser):
+   ```bash
+   safari-browser upload --native "input[type=file]" <absolute-path> --url plaud
+   ```
+
+   If AX is not granted OR the dialog is stubborn, fall back to JS:
+   ```bash
+   safari-browser upload --js "input[type=file]" <absolute-path> --url plaud
+   ```
+   Expected: the filename appears in Plaud's upload progress list or in the current folder's item list.
+
+5. **Wait for upload to complete**
+   ```bash
+   safari-browser wait --for-text "Uploaded" --url plaud
+   ```
+   Expected: a progress indicator reaches 100% or a "Uploaded"/"Processed" status appears. Timeout defaults to 30s; adjust with `--timeout 120` for large files.
+
+## Error handling
+
+- **`ambiguousWindowMatch`**: The user has multiple Plaud tabs. Ask which one, or pass `--window N`.
+- **File picker opens but upload is silent**: The element targeted by `input[type=file]` was wrong. Re-run `safari-browser snapshot -i --url plaud`, find the `<input>` with `data-testid` or `accept="audio/*"`, and retry.
+- **Upload progress stalls at <100%**: Plaud's backend is slow or the file exceeds the current plan's limit. Surface the exact error message from `snapshot` — do NOT retry silently.
+- **Quota exceeded banner**: STOP and tell the user; retrying will not fix it.
+- **Login redirect mid-upload**: The session expired. STOP and ask the user to re-authenticate in Safari; do NOT attempt to type credentials.
+
+## Verification
+
+Success criteria — ALL must hold:
+
+1. The filename appears in the target folder's item list (visible via a fresh `safari-browser snapshot -i --url plaud`).
+2. The item's status is either "Processing", "Transcribing", or a terminal state such as "Ready" — not "Failed".
+3. No error banner is visible anywhere on the page.
+
+If any criterion fails, report it with the snapshot output rather than claiming success.
+
+## Gotchas
+
+- **Plan-specific limits**: Free-tier Plaud has lower file-size and duration limits than Pro. A failure on Free may "just work" on Pro without any UI change — check plan tier in Preconditions if uploads keep failing.
+- **Folder vs library root**: Plaud treats the library root differently from folders (some uploads to root re-appear only after a manual refresh). Prefer uploading into a named folder.
+- **Reactive title resets**: Plaud may reset `document.title` on navigation; a `🟢` ownership marker you set earlier will disappear. This is harmless; do not interpret it as the tab being "lost".
+- **Large file memory**: The JS upload path (`--js`) loads the file into a JavaScript `DataTransfer` object and is constrained by the plugin's internal ~10MB cap. Use `--native` for anything larger; if AX is not granted, split the file or grant AX.
+- **Two-tab race**: If the user has a second Plaud tab open in another window, a snapshot on the "wrong" one looks valid but clicks go nowhere because the target folder is on the other tab. Always pass `--url plaud` together with `--window N` when in doubt.
diff --git a/plugins/tool-finder/CHANGELOG.md b/plugins/tool-finder/CHANGELOG.md
new file mode 100644
index 00000000..c795ced7
--- /dev/null
+++ b/plugins/tool-finder/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> ⚠ This file was bootstrapped by `changelog-tools:changelog-init` from the
+> `plugin.json` description field. Section categorization is best-effort —
+> review and refine `Added` / `Changed` / `Fixed` etc. as needed.
+
+## [Unreleased]
+
+## [1.0.0] - (date unknown — please fill in)
+
+### Changed
+- 找出任務可用的工具（MCP、Skills、CLI）或搜尋更好的替代方案
diff --git a/scripts/audit_step0_bootstrap.sh b/scripts/audit_step0_bootstrap.sh
new file mode 100755
index 00000000..81dd260c
--- /dev/null
+++ b/scripts/audit_step0_bootstrap.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+#
+# Audit: every IDD skill MUST declare a Step 0 (or Step 0.5) Bootstrap
+# Stage Task List section so TaskCreate tracks its execution.
+#
+# Exit code: number of skills missing the Bootstrap section.
+# Exit 0 = all skills clean.
+#
+# Usage:
+#   ./scripts/audit_step0_bootstrap.sh
+#
+# Reference: issue #27 (psychquant-claude-plugins).
+
+set -uo pipefail
+
+PLUGIN_SKILLS_DIR="plugins/issue-driven-dev/skills"
+if [ ! -d "$PLUGIN_SKILLS_DIR" ]; then
+    echo "ERROR: must run from repo root (expected $PLUGIN_SKILLS_DIR)" >&2
+    exit 99
+fi
+
+miss=0
+total=0
+for skill_dir in "$PLUGIN_SKILLS_DIR"/*/; do
+    skill_name=$(basename "$skill_dir")
+    skill_md="${skill_dir}SKILL.md"
+    [ -f "$skill_md" ] || continue
+    total=$((total + 1))
+
+    # Match the literal Bootstrap heading. Accepts both "### Step 0:" (plain) and
+    # "### Step 0.5:" (used when Step 0 is a non-bootstrap gate, e.g. idd-close's
+    # Checklist Gate Check). The "Bootstrap Stage Task List" literal prevents
+    # false positives where Step 0 exists but is something other than a bootstrap
+    # (this is the bug Codex caught in #27 verify).
+    if grep -qE '^### Step 0(\.5)?: Bootstrap Stage Task List' "$skill_md"; then
+        # Defence in depth: also verify a TaskCreate( appears in the file.
+        # An empty bootstrap section (just heading, no tasks) is also a bug.
+        if grep -q 'TaskCreate(' "$skill_md"; then
+            echo "OK    $skill_name"
+        else
+            echo "MISS  $skill_name (Bootstrap heading present but no TaskCreate( found)"
+            miss=$((miss + 1))
+        fi
+    else
+        echo "MISS  $skill_name (no '### Step 0[.5]: Bootstrap Stage Task List' heading)"
+        miss=$((miss + 1))
+    fi
+done
+
+echo
+echo "Summary: $((total - miss))/$total skills have Step 0 Bootstrap"
+exit $miss