@mycodemap/mycodemap 0.5.2-beta.1 → 2.0.0

package/docs/README.md

@@ -1,6 +1,8 @@
 # docs/ - 文档信息架构
 
-本目录采用“入口文档短、细节文档分层”的结构。
+> **v2.0 里程碑上下文**：当前文档体系对应 CodeMap v2.0（”agent-native-foundation”）。v2.0 引入了 CLI-as-MCP 自动网关、接口契约 Schema、WASM-first 构建基础等核心能力。详见下方 [v2.0 文档索引](#v20-文档索引)。
+
+本目录采用”入口文档短、细节文档分层”的结构。
 
 ## 目录职责
 
@@ -11,6 +13,8 @@
 - `docs/product-specs/`：当前仍有效的产品规格与验收边界。
 - `docs/references/`：外部参考、设计系统、工具链资料。
 - `docs/archive/`：历史方案、迁移遗留、过期文档索引。
+- `docs/ai-guide/`：AI / Agent 集成指南（v2.0 新增）。
+- `src/cli/interface-contract/`：接口契约 Schema 定义（单一 Schema 生成 parser、MCP tool 定义、`--help-json`、shell 补全）。
 
 ## 当前状态
 
@@ -19,6 +23,20 @@
 - `docs/design-docs/` 与 `docs/product-specs/` 当前不再保留旧稿；历史内容请从 `docs/archive/README.md` 进入。
 - 新增内容优先写入分层目录，不再把新设计或新计划继续堆到根层。
 
+### v2.0 功能状态
+
+v2.0（"agent-native-foundation"）已引入以下核心能力，相关文档已就位：
+
+| 功能 | 状态 | 文档位置 |
+|------|------|----------|
+| **CLI-as-MCP 自动网关** | 已交付 | `docs/ai-guide/INTEGRATION.md` |
+| `codemap doctor` 持续健康诊断 | 已交付 | `AI_GUIDE.md` + `src/cli/doctor/` |
+| `codemap benchmark` WASM/Native 性能对比 | 已交付 | `AI_GUIDE.md` |
+| `--schema` 接口契约输出 | 已交付 | `AI_GUIDE.md` + `src/cli/interface-contract/` |
+| WASM-first 构建基础 | 已交付 | `AI_GUIDE.md` + `src/cli/loaders/` |
+| AI-First 默认输出（JSON/NDJSON） | 已交付 | `AI_GUIDE.md` |
+| Failure-to-Action 协议 | 已交付 | `docs/rules/harness.md` |
+
 ## 建议阅读顺序
 
 1. `../AGENTS.md`
@@ -28,6 +46,27 @@
 5. 与任务最相关的现行文档；如需历史背景，再看 `docs/archive/README.md`
 6. 如需过程信息，再看 `docs/exec-plans/*`
 
+## v2.0 文档索引
+
+以下文档涵盖 v2.0 核心功能，按主题分类：
+
+### AI / Agent 集成
+- `docs/ai-guide/INTEGRATION.md` — CLI-as-MCP 自动网关配置指南（动态 tool 注册、20+ 命令自动暴露）
+- `docs/ai-guide/AI_ASSISTANT_SETUP.md` — AI 助手（Kimi、Claude、Codex、Cursor、Copilot）集成配置
+- `AI_GUIDE.md` — CodeMap CLI / MCP / AI 使用总览（含 `doctor`、`benchmark`、`--schema` 用法）
+
+### 接口契约与 Schema
+- `src/cli/interface-contract/` — 单一 Schema 源文件（生成 parser、MCP tool 定义、`--help-json`、shell 补全）
+- 运行 `codemap --schema` 可输出完整契约 JSON，供 Agent 自省
+
+### Harness 与 Agent 控制
+- `docs/rules/harness.md` — Harness 设计、Agent 控制、上下文分层、权限升级策略
+- `docs/rules/harness.md` — Failure-to-Action 协议（每个错误返回 `rootCause` + `remediationPlan` + `confidence` + `nextCommand`）
+
+### 架构与构建
+- `ARCHITECTURE.md` — 架构分层、依赖方向、模块边界
+- `src/cli/loaders/` — WASM-first 构建基础（`tree-sitter` → `web-tree-sitter`；`better-sqlite3` → `node:sqlite` / `sql.js`）
+
 ## 维护规则
 
 - 入口文档只做导航，不复述大段细节。

package/docs/SETUP_GUIDE.md

@@ -84,11 +84,7 @@ npx @mycodemap/mycodemap --help
 mycodemap init
 ```
 
-会询问以下问题：
-- 分析模式（fast/smart/hybrid）
-- 包含的文件路径
-- 排除的文件路径
-- 输出目录
+默认会显示 reconciliation preview，并说明哪些资产会被创建、迁移、跳过或需要人工处理。
 
 ### 使用默认配置
 
@@ -96,7 +92,11 @@ mycodemap init
 mycodemap init -y
 ```
 
-生成的配置文件 `mycodemap.config.json`：
+执行后会收敛 canonical 配置 `.mycodemap/config.json`，并把 receipt 写入 `.mycodemap/status/init-last.json`。
+
+`init` 会同步 `.mycodemap/hooks/` 与 `.mycodemap/rules/`，但不会自动改写 `CLAUDE.md` / `AGENTS.md`；相关引用片段会通过 receipt 提示你手动加入。
+
+生成的 canonical 配置文件 `.mycodemap/config.json`：
 
 ```json
 {
@@ -116,7 +116,7 @@ mycodemap init -y
   "watch": false,
   "storage": {
     "type": "filesystem",
-    "outputPath": ".codemap/storage"
+    "outputPath": ".mycodemap/storage"
   },
   "plugins": {
     "builtInPlugins": true,
@@ -136,8 +136,8 @@ mycodemap init -y
 | `output` | string | `".mycodemap"` | 输出目录路径 |
 | `watch` | boolean | `false` | 监听模式预留配置 |
 | `storage.type` | string | `"filesystem"` | 图存储后端类型：`filesystem` / `sqlite` / `memory` / `auto` |
-| `storage.outputPath` | string | `".codemap/storage"` | 文件系统存储目录 |
-| `storage.databasePath` | string | `".codemap/governance.sqlite"` | SQLite 数据库文件路径（相对项目根目录） |
+| `storage.outputPath` | string | `".mycodemap/storage"` | 文件系统存储目录 |
+| `storage.databasePath` | string | `".mycodemap/governance.sqlite"` | SQLite 数据库文件路径（相对项目根目录，建议放在 `.mycodemap/` 下） |
 | `plugins.builtInPlugins` | boolean | `true` | 是否启用内置插件 |
 | `plugins.pluginDir` | string | - | 额外插件目录 |
 | `plugins.plugins` | string[] | `[]` | 显式加载的插件名称列表 |
@@ -146,7 +146,7 @@ mycodemap init -y
 ### 图存储后端配置
 
 - `generate` 会把 CodeGraph 写入 `storage` 指定的后端；`export json|graphml|dot` 会从同一后端读取。
-- 选择 `sqlite` 时默认落盘到 `.codemap/governance.sqlite`；也可通过 `storage.databasePath` 覆盖。
+- 选择 `sqlite` 时建议落盘到 `.mycodemap/governance.sqlite`；也可通过 `storage.databasePath` 覆盖。
 - 旧的 `neo4j` / `kuzudb` 配置已不再受支持，会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
 - 显式选择 `sqlite` 且运行时缺少 `better-sqlite3` 或 Node.js `<20` 时，会返回显式错误。
 - `storage.type = "auto"` 当前优先选择 `sqlite`；仅当 SQLite 运行时不可用时才 warning 后回退到 `filesystem`。
@@ -210,24 +210,21 @@ mycodemap impact -f src/cli/index.ts --transitive
 ### 统一分析（analyze）
 
 ```bash
-# 影响分析
-mycodemap analyze -i impact -t src/cli/index.ts
-mycodemap analyze -i impact -t src/cli/index.ts --scope transitive --include-tests
+# 搜索符号或文件
+mycodemap analyze -i find -k "UnifiedResult" --topK 10
 
-# 依赖分析
-mycodemap analyze -i dependency -t src/orchestrator
+# 读取代码范围
+mycodemap analyze -i read -t src/cli/index.ts
+mycodemap analyze -i read -t src/cli/index.ts --scope transitive --include-tests
 
-# 复杂度分析
-mycodemap analyze -i complexity -t src/domain
+# 查看模块依赖关系
+mycodemap analyze -i link -t src/orchestrator
 
-# 搜索分析
-mycodemap analyze -i search -k "UnifiedResult" --topK 10
+# 展示项目概览或复杂度
+mycodemap analyze -i show -t src/
 
-# 项目概览
-mycodemap analyze -i overview -t src/
-
-# JSON 输出
-mycodemap analyze -i impact -t src/index.ts --json
+# JSON 结构化输出
+mycodemap analyze -i find -k "UnifiedResult" --json --structured
 ```
 
 ### 工作流编排（workflow）
@@ -457,8 +454,8 @@ npx mycodemap --help
 #### 2. 配置文件未找到
 
 ```bash
-# 确认配置文件存在
-ls mycodemap.config.json
+# 确认 canonical 配置文件存在
+ls .mycodemap/config.json
 
 # 重新初始化
 mycodemap init -y

package/docs/agents/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo:
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/docs/ai-guide/COMMANDS.md

@@ -2,13 +2,29 @@
 
 > 完整的 CLI 命令详解
 >
-> CodeMap 是 AI-first 代码地图工具。以下文档记录当前公开命令，并补充已移除命令的迁移提示。  
-> 当前 CLI 过渡现实：多数命令显式使用 `--json` 输出机器可读结果；`analyze` 额外支持 `--output-mode machine|human`。
+> CodeMap 是 AI-Native 优先、人类友好的代码架构治理基础设施。以下文档记录当前公开命令，并补充已移除命令的迁移提示。  
+> 命名规范：公开命令示例统一使用 `mycodemap`；`codemap` 只作为兼容别名保留，不作为新示例首选。  
+> v2.0 AI-First Default Output：默认输出 JSON/NDJSON（非 TTY 或显式 `--json`），人类阅读使用 `--human` 或 TTY 自动检测。
 
 ---
 
 ## 核心命令
 
+### init - 收敛项目状态
+
+```bash
+mycodemap init               # 默认显示 reconciliation preview
+mycodemap init --interactive # 显式显示 preview（不写入）
+mycodemap init -y            # 使用默认选择直接写入
+```
+
+**行为说明**:
+
+- `init` 会收敛 `.mycodemap/config.json`、`.mycodemap/status/init-last.json`、`.mycodemap/hooks/` 与 `.mycodemap/rules/`
+- 默认先显示 receipt preview；只有 `-y/--yes` 才真正写入
+- 若 receipt 中仍有 `manual action`，请先处理这些动作，再继续自动化流程
+- `init` 不会自动改写 `CLAUDE.md` 或 `AGENTS.md`，只会输出可复制的 rules 引用片段
+
 ### generate - 生成代码地图
 
 ```bash
@@ -35,12 +51,12 @@ mycodemap generate --ai-context             # 生成 AI 描述
 - `generate` 完成后，`codemap.json` 会带 `graphStatus`、`failedFileCount` 与可选 `parseFailureFiles`；若 `graphStatus = "partial"`，不要把结果当成完整图。
 
 **插件运行时说明**:
-- `generate` 不提供独立 `--plugin` flags；插件通过 `mycodemap.config.json` 的 `plugins` 段声明。
+- `generate` 不提供独立 `--plugin` flags；插件通过 `.mycodemap/config.json` 的 `plugins` 段声明。
 - 只有显式存在 `plugins` 段时，`generate` 才会加载插件并运行 analyze / generate hooks。
 - `AI_MAP.md` 会增加 `Plugin Summary`，`codemap.json` 会增加 `pluginReport`，stdout 会输出插件诊断摘要。
 
 **图存储运行时说明**:
-- `generate` 会读取 `mycodemap.config.json.storage`，并把 CodeGraph 写入所选后端。
+- `generate` 会读取 `.mycodemap/config.json` 的 `storage` 段，并把 CodeGraph 写入所选后端。
 - `storage.type` 支持 `filesystem`、`sqlite`、`memory`、`auto`；默认是 `filesystem`。
 - 旧的 `neo4j` / `kuzudb` 配置会直接报迁移错误；显式选择 `sqlite` 但运行时缺少 `better-sqlite3` 或 Node.js `<20` 时也会直接报错，不会静默 fallback 到 `filesystem`。
 - `storage.type = "auto"` 当前优先走 `sqlite`；只有 SQLite 不可用时才 warning 后回退 `filesystem`。
@@ -109,7 +125,9 @@ mycodemap impact -f "src/cli/index.ts" -j   # JSON 输出
 
 ---
 
-### mcp - experimental 本地 MCP 集成
+### mcp - MCP 集成 (CLI-as-MCP Automatic Gateway)
+
+> v2.0 升级为 CLI-as-MCP Automatic Gateway。所有 20+ schema 定义的 CLI 命令自动暴露为 MCP tools；动态 tool 注册。
 
 ```bash
 mycodemap mcp install                     # 把当前仓库写入 .mcp.json
@@ -119,14 +137,14 @@ mycodemap generate --symbol-level         # 使用前必须先生成 symbol-leve
 
 | 子命令 | 说明 |
 |--------|------|
-| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap-experimental` server entry |
-| `start` | 启动 local-only / read-only / stdio-first experimental MCP server |
+| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap` server entry |
+| `start` | 启动 local-only / read-only / stdio-first MCP server |
 
-**首期规则**:
-- `mcp` 是 experimental surface，不要把它当成稳定长期 public API。
+**v2.0 行为**:
+- CLI-as-MCP Automatic Gateway：所有 schema 定义的命令（`generate`、`query`、`deps`、`impact`、`analyze`、`doctor`、`benchmark`、`design`、`check`、`ci`、`history`、`workflow` 等）自动映射为 MCP tools。
+- 动态 tool 注册：新增命令无需手动更新 MCP server，schema 变更后自动生效。
 - `mcp start` 的 `stdout` 只能承载 MCP 协议帧；欢迎信息、迁移提示与 runtime log 不会走这条流。
-- 当前只暴露两个工具：`codemap_query`、`codemap_impact`。
-- `codemap_query` / `codemap_impact` 都会返回 `graph_status`、`generated_at` 与显式 `error.code`。
+- 所有 MCP tools 返回 `graph_status`、`generated_at` 与显式 `error.code`。
 - 若图尚未生成，会返回 `GRAPH_NOT_FOUND`；若符号不存在，返回 `SYMBOL_NOT_FOUND`；若同名符号无法消歧，返回 `AMBIGUOUS_EDGE`。
 - 详细安装步骤见 `docs/ai-guide/INTEGRATION.md`；完整 output contract 见 `docs/ai-guide/OUTPUT.md`。
 
@@ -233,6 +251,7 @@ mycodemap analyze -i show -t "src/index.ts" --output-mode human
 | `--include-tests` | 包含测试文件关联 | - |
 | `--include-git-history` | 包含 Git 历史分析 | - |
 | `--json` | JSON 格式输出 | - |
+| `--human` | 强制人类可读输出（覆盖非 TTY 默认 JSON 行为） | - |
 | `--structured` | 纯结构化输出（移除自然语言字段，配合 `--json` 使用） | - |
 | `--output-mode <mode>` | 输出模式：`machine`/`human` | `human` |
 <!-- END GENERATED: analyze-commands-options -->
@@ -500,6 +519,60 @@ mycodemap workflow template recommend "任务"  # 推荐模板
 
 ---
 
+## doctor - 持续健康诊断
+
+> v2.0 新增。检测 ghost 命令、native 依赖问题、workspace drift、agent 连通性。
+
+```bash
+mycodemap doctor              # 人类可读摘要
+mycodemap doctor --json       # 机器可读完整诊断
+```
+
+| 类别 | 检查项 | 说明 |
+|------|--------|------|
+| `install` | native 依赖完整性 | 检查 `better-sqlite3` 等 native 模块是否可加载 |
+| `config` | workspace 完整性 | 检查 `.mycodemap/config.json`、图存储后端配置 |
+| `runtime` | ghost 命令检测 | 检测已注册但无实际实现的命令 |
+| `agent` | MCP 连通性 | 检查 MCP server 注册与工具发现是否正常 |
+
+- 每个类别独立返回 `ok` / `warn` / `error` 状态
+- `--json` 输出纯结构化 diagnostics，包含 `categories[]`、`summary`、`recommendations`
+- `error` 级别诊断会设置非零 exit code
+
+---
+
+## benchmark - WASM vs Native 性能对比
+
+> v2.0 新增。对比 WASM fallback 与 Native 实现的性能差异。
+
+```bash
+mycodemap benchmark           # 完整对比（WASM + Native）
+mycodemap benchmark --wasm    # 仅 WASM 性能
+mycodemap benchmark --native  # 仅 Native 性能
+mycodemap benchmark --json    # JSON 输出
+```
+
+- 输出包含各分析阶段的耗时对比（generate、query、deps、impact 等）
+- `--json` 输出结构化 benchmark 结果，便于 CI 集成与回归检测
+- 用于决定是否启用 WASM fallback 或排查性能退化
+
+---
+
+## --schema - 接口契约输出
+
+> v2.0 新增。输出完整的 Interface Contract Schema JSON，供 agent 自省与动态 tool 注册。
+
+```bash
+mycodemap --schema            # 输出完整 schema JSON
+mycodemap --schema | jq '.'   # 格式化查看
+```
+
+- 单一 schema 同时生成：parser、MCP tools、`--help-json`、shell completions
+- Agent 可通过读取 schema 动态发现所有可用命令及其参数契约
+- 输出包含所有 20+ 命令的完整接口定义（参数、类型、返回值结构）
+
+---
+
 ## 已移除的公共命令
 
 以下命令已从 public CLI 移除；直接调用时，CLI 会显式失败并给出迁移提示，而不是继续执行旧功能。
@@ -521,7 +594,7 @@ mycodemap export mermaid                     # Mermaid 语法
 mycodemap export json -o ./output.json       # 指定输出
 ```
 
-- `export json|graphml|dot` 会从 `mycodemap.config.json.storage` 指定的后端读取 CodeGraph。
+- `export json|graphml|dot` 会从 `.mycodemap/config.json` 的 `storage` 段指定后端读取 CodeGraph。
 - `export mermaid` 仍直接读取 `.mycodemap/codemap.json`，这是当前保留的文件出口，不代表 graph backend 未接入主路径。
 - 图存储后端收口不等于重新开放公共 `mycodemap server` 产品面；`Server Layer` 仍是内部层。
 
@@ -529,7 +602,7 @@ mycodemap export json -o ./output.json       # 指定输出
 
 ### ship - 一键智能发布（非代码地图首屏能力）
 
-> `ship` 负责发布整合，不是 AI-first 代码地图工具的首屏入口；首次接触项目时优先使用分析命令而非发布命令。
+> `ship` 负责发布整合，不是 CodeMap 代码分析的首屏入口；首次接触项目时优先使用分析命令而非发布命令。
 
 ```bash
 mycodemap ship                              # 完整发布流程
@@ -563,6 +636,45 @@ mycodemap ship --yes                       # 置信度 60-75 时自动确认
 
 ---
 
+### publish-status - 发布后的只读 snapshot 复核
+
+> `publish-status` 是 `ship` / `/release` 之后的 follow-up observability surface；它不触发发布、不重跑 workflow，也不猜“最新一条 run”。
+
+```bash
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456 --json
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456 --json --structured
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456 --workflow-file publish.yml
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--tag <tag>` | 发布 tag，必须精确提供 | - |
+| `--sha <sha>` | 发布 commit SHA，必须精确提供 | - |
+| `--workflow-file <file>` | GitHub Actions workflow 文件名 | `publish.yml` |
+| `--json` | 输出 machine-readable JSON | `false` |
+| `--structured` | 去掉自然语言 `content`，需配合 `--json` 使用 | `false` |
+
+**状态语义:**
+- `success`：找到唯一精确匹配 run，且 workflow 成功
+- `failure`：找到唯一精确匹配 run，且 workflow 明确失败
+- `pending`：还没观察到精确匹配 run，或 run 仍在执行中
+- `ambiguous`：出现多个同时匹配 `tag + sha` 的 runs；不会猜哪一个才是“最新”
+- `unavailable`：repo slug、GitHub API、权限或最终 truth 无法精确确认
+
+**输出契约:**
+- 默认输出终端摘要
+- `--json` 输出 machine-readable payload，并保留 `content`
+- `--json --structured` 移除自然语言字段，仅保留结构化 truth
+- payload 至少包含 `status`、`workflowUrl`、`releaseUrl`、`runId`、`failedJobs`、`reason`、`details`
+
+**边界:**
+- 只做一次 snapshot read，不内置轮询
+- 只读；不会 rerun workflow、dispatch workflow、`npm publish`、`git push`
+- 它不会替代 `ship` 或 `/release`，发布 authority 仍在 `docs/rules/release.md`
+
+---
+
 ## 全局选项
 
 所有命令支持：

package/docs/ai-guide/INTEGRATION.md

@@ -1,6 +1,6 @@
 # AI Guide - MCP / Agent 集成
 
-> 当前 canonical integration path：**真实本地 stdio MCP server**。旧 CLI wrapper 只作为 fallback。
+> v2.0 更新：CLI-as-MCP Automatic Gateway。所有 schema 定义的 CLI 命令自动暴露为 MCP tools。
 
 ---
 
@@ -11,11 +11,16 @@
 | transport | 本地 `stdio` |
 | 读写权限 | **只读** |
 | public surface | `mycodemap mcp install`、`mycodemap mcp start` |
-| MCP tools | `codemap_query`、`codemap_impact` |
+| MCP tools | **ALL 20+ schema 定义的 CLI 命令** |
 | 图前置条件 | 先执行 `mycodemap generate --symbol-level` |
-| 稳定性 | **experimental** |
+| 稳定性 | **stable (v2.0)** |
 | 非目标 | HTTP MCP、远程 transport、写操作、全局 host lifecycle |
 
+### 动态 Tool 注册
+
+- 向 `Interface Contract Schema` 添加新命令 → 重启 MCP server → 新 tool 自动出现在 host 中
+- 无需手写 tool 定义、无需修改 MCP server 代码、无需重新安装
+
 ---
 
 ## 1.1 速查表
@@ -44,7 +49,7 @@ mycodemap generate --symbol-level
 mycodemap mcp install
 ```
 
-该命令当前只做一件事：在**当前仓库根目录**的 `.mcp.json` 里写入一个 experimental server entry。
+该命令在当前仓库根目录的 `.mcp.json` 里写入一个 v2.0 server entry。
 
 ### Step 3: 让 MCP host 启动 stdio server
 
@@ -57,6 +62,8 @@ mycodemap mcp start
 - `stdout` 只承载 MCP 协议帧
 - 欢迎信息、迁移提示、runtime log 不会混入 `stdout`
 
+> **v2.0 关键变更**：所有在 `Interface Contract Schema` 中定义的命令自动作为 MCP tools 可用。无需手写 tool 定义，无需逐个注册。
+
 ---
 
 ## 3. `.mcp.json` 参考配置
@@ -66,7 +73,7 @@ mycodemap mcp start
 ```json
 {
   "mcpServers": {
-    "mycodemap-experimental": {
+    "mycodemap": {
       "command": "node",
       "args": ["dist/cli/index.js", "mcp", "start"],
       "cwd": "/absolute/path/to/repo",
@@ -80,7 +87,7 @@ mycodemap mcp start
 
 ### 当前宿主支持边界
 
-- 当前文档只保证**repo-local `.mcp.json`** 这一路径
+- 当前文档只保证 **repo-local `.mcp.json`** 这一路径
 - 不承诺全局安装、升级覆盖策略或卸载命令
 - 若你的 host 不读取 `.mcp.json`，请手动拷贝上面的 server entry 到宿主自己的 MCP 配置文件
 
@@ -88,7 +95,25 @@ mycodemap mcp start
 
 ## 4. MCP tool contract
 
-### `codemap_query`
+### Gateway 模式
+
+CLI-as-MCP Automatic Gateway 将所有 CLI 命令统一映射为 MCP tools：
+
+| CLI 命令 | MCP tool 名 | 输入参数 |
+|----------|-------------|----------|
+| `mycodemap query -s X` | `codemap_query` | `{ symbol: string, filePath?: string }` |
+| `mycodemap impact -f X` | `codemap_impact` | `{ symbol: string, filePath?: string, depth?: number, limit?: number }` |
+| `mycodemap doctor` | `codemap_doctor` | `{ category?: string, json?: boolean }` |
+| `mycodemap benchmark` | `codemap_benchmark` | `{ command?: string, json?: boolean }` |
+| `mycodemap analyze -i find -k X` | `codemap_analyze` | `{ intent: string, keyword: string, ... }` |
+| ... | ... | ... |
+
+映射规则：
+- CLI 命令名 → MCP tool 名前缀为 `codemap_`
+- CLI 短选项（`-s`）和长选项（`--symbol`）→ MCP tool 参数名使用长选项名
+- CLI 输出结构 → MCP tool 返回结构完全一致
+
+### `codemap_query`（示例之一）
 
 输入：
 
@@ -107,7 +132,7 @@ interface CodemapQueryInput {
 - `generated_at`
 - `error.code`（若失败）
 
-### `codemap_impact`
+### `codemap_impact`（示例之一）
 
 输入：
 
@@ -128,7 +153,7 @@ interface CodemapImpactInput {
 - `generated_at`
 - `error.code`（若失败）
 
-> 完整输出类型见 `docs/ai-guide/OUTPUT.md`。
+> 完整输出类型见 `docs/ai-guide/OUTPUT.md`。以上仅为 20+ tools 中的两个示例。
 
 ---
 
@@ -140,6 +165,40 @@ interface CodemapImpactInput {
 | `SYMBOL_NOT_FOUND` | 请求的 symbol 不存在 | 检查拼写，或先用 `query -S` / `analyze -i find` 搜索 |
 | `AMBIGUOUS_EDGE` | 同名 symbol 无法仅靠 `symbol` / `filePath` 消歧 | 补充更具体的 `filePath` |
 
+### Failure-to-Action Protocol
+
+v2.0 错误响应包含可执行的修复指引：
+
+```typescript
+interface McpError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  // Failure-to-Action Protocol 字段
+  rootCause?: string;           // 根因分析
+  remediationPlan?: string[];   // 修复步骤（按优先级）
+  confidence: "high" | "medium" | "low";
+  nextCommand?: string;         // 建议执行的下一步命令
+}
+```
+
+示例：
+
+```json
+{
+  "code": "GRAPH_NOT_FOUND",
+  "message": "symbol-level 图不存在",
+  "rootCause": "未执行 mycodemap generate --symbol-level",
+  "remediationPlan": [
+    "mycodemap generate --symbol-level",
+    "mycodemap mcp install",
+    "重启 MCP host"
+  ],
+  "confidence": "high",
+  "nextCommand": "mycodemap generate --symbol-level"
+}
+```
+
 ### `graph_status` 解读
 
 | 值 | 含义 |
@@ -158,6 +217,8 @@ interface CodemapImpactInput {
 mycodemap query -s "SymbolName" -j
 mycodemap impact -f "src/file.ts" -j
 mycodemap analyze -i find -k "SymbolName" --json --structured
+mycodemap doctor --json
+mycodemap benchmark --json
 ```
 
 但要注意：
@@ -178,7 +239,7 @@ mycodemap generate --symbol-level
 ### `mcp install` 后看不到 server
 
 - 确认 host 会读取当前仓库根目录的 `.mcp.json`
-- 不会读取的话，手动复制 `mycodemap-experimental` entry 到宿主配置
+- 不会读取的话，手动复制 `mycodemap` entry 到宿主配置
 
 ### `mcp start` 无法启动
 
@@ -200,6 +261,12 @@ npm ls better-sqlite3
 - 先检查 `graph_status` 是否为 `partial`
 - 再检查 symbol 是否真的唯一；必要时补 `filePath`
 
+### 新增命令后 MCP host 看不到新 tool
+
+- 确认新命令已注册到 `Interface Contract Schema`（`mycodemap --schema` 检查）
+- 重启 MCP server（host 侧或 `mycodemap mcp start`）
+- 不需要重新运行 `mcp install`，除非 server entry 本身有变更
+
 ### storage 运行时错误速查表
 
 | 错误 / 信号 | 含义 | 处理方式 |
@@ -216,4 +283,4 @@ npm ls better-sqlite3
 - 命令参考：`docs/ai-guide/COMMANDS.md`
 - 输出契约：`docs/ai-guide/OUTPUT.md`
 - 主索引：`AI_GUIDE.md`
-- 执行手册：`CLAUDE.md`
+- 入口路由：`CLAUDE.md`