feat(cli): rebuild-index + fuzzy-resolve parity + doc clarity (v0.11.3)

CLI additions from the residual audit (source already staged pre-session):
- rebuild-index --confirm: wipes .code-graph/index.db + WAL/SHM then
  re-runs full index. Destructive-op guard refuses degenerate project_root.
- callgraph/refs/search fuzzy auto-resolve mirrors MCP resolve_fuzzy_name
  (unique promote, ambiguous list with node_id/start_line).
- ast-search --json now emits {results,count} envelope (MCP parity).
- trace --json emits single-object envelope even on no-match.
- refs --node-id envelope matches MCP find_references shape.
- health-check --json adds embedding_coverage_pct / embedding_status /
  model_available; search_mode gated on model availability.
- search/ast-search --limit clamp(1,100).

Doc correction from the 12-tool UX audit:
- claude-plugin/templates/plugin_code_graph_mcp.md "进阶 5" reworded.
  The v0.10.0 claim "hidden but callable by name" only holds for clients
  invoking tools/call with a literal name (raw JSON-RPC, MCP SDKs, CLI).
  Claude Code derives its callable set from tools/list — ToolSearch returns
  No matching deferred tools found, direct invocation errors with
  "No such tool available". Table now leads with CLI column for Claude Code
  users; raw MCP name-call retained for SDK/scripts. Auto-refreshes to
  previously-adopted projects on next SessionStart (v0.11.0 feature).
- src/mcp/tools.rs doc comment spells out the same.

New e2e tests (5):
- test_cli_rebuild_index_requires_confirm
- test_cli_rebuild_index_with_confirm_rebuilds
- test_cli_refs_node_id_envelope
- test_cli_trace_json_single_object_envelope_on_empty
- test_cli_ast_search_json_envelope

Also: src/storage/queries.rs NameCandidate derives Clone (needed by
CLI fuzzy-resolve's Ambiguous(Vec<NameCandidate>) branch).

Known limitation (unchanged, workaround available):
- incremental-index can drop call edges when the callee function is newly
  added in the same diff batch and the caller's file is processed before
  the callee's node is inserted. rebuild-index --confirm rewrites the
  graph correctly. Root-cause fix (two-phase edge resolution in
  src/parser/relations.rs) deferred to a follow-up.

Tests: cargo test --lib --no-default-features 215/215; cli_e2e 55/55.
Clippy: clean on --all-targets -- -D warnings (1.95 parity).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sdsrss

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AST knowledge graph plugin for Claude Code — semantic search, call graph, HTTP tracing, impact analysis",
-    "version": "0.11.2"
+    "version": "0.11.3"
   },
   "plugins": [
     {
       "name": "code-graph-mcp",
       "source": "./claude-plugin",
       "description": "AST knowledge graph for intelligent code navigation — auto-indexes your codebase and provides semantic search, call graph traversal, HTTP route tracing, and impact analysis via MCP tools",
-      "version": "0.11.2",
+      "version": "0.11.3",
       "author": {
         "name": "sdsrs"
       },

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v0.11.3 — Doc: "hidden but callable" clarified (Claude Code vs. raw MCP)
+
+User-facing: no behavior change; corrects a misleading claim in the adopted
+plugin memory after a 12-tool UX audit.
+
+### Context
+
+v0.10.0 trimmed `tools/list` to 7 core tools and documented the other 5
+(`impact_analysis`, `trace_http_chain`, `dependency_graph`, `find_similar_code`,
+`find_dead_code`) as "hidden but callable by name". UX audit found this holds
+only for clients that invoke `tools/call` with a literal tool name (raw JSON-RPC,
+MCP SDKs, CLI). **Claude Code's MCP integration derives its callable set from
+`tools/list`** — `ToolSearch` returns `No matching deferred tools found` for the
+hidden 5, and direct invocation errors with `No such tool available`.
+
+### Fixes
+
+1. **`claude-plugin/templates/plugin_code_graph_mcp.md` "进阶 5" table
+   reworded**: CLI is now the primary column for Claude Code users; raw MCP
+   name calls annotated as SDK/scripts-only. v0.11.0 template auto-refresh
+   pushes this to previously-adopted projects on next SessionStart.
+2. **`src/mcp/tools.rs` doc comment**: spells out which MCP clients can reach
+   hidden tools and points to CLI fallback for Claude Code.
+
+### Why this matters
+
+Misleading docs caused agents to attempt `mcp__…__impact_analysis` /
+`mcp__…__trace_http_chain` and hit a terminal "No such tool available" error
+instead of routing to `code-graph-mcp impact|trace|deps|similar|dead-code`
+via Bash.
+
 ## v0.11.2 — Post-audit follow-up: 4 residual precision fixes
 
 Follow-up audit on top of v0.11.1. All additive/tightening — no schema breakage.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "code-graph-mcp"
-version = "0.11.2"
+version = "0.11.3"
 edition = "2021"
 
 [features]

Cargo.toml

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.11.2",
+  "version": "0.11.3",
   "keywords": [
     "code-graph",
     "ast",

claude-plugin/.claude-plugin/plugin.json

@@ -18,9 +18,11 @@ type: reference
 
 ## 何时调用 MCP/CLI（替代多步 Grep/Read）
 
-> v0.10.0 起：tools/list 默认只暴露 7 个核心工具；下表中 `⚙` 标记的 5 个工具
-> 已从 tools/list 隐藏以节省 session 启动 tokens，但**仍可通过名称直接调用**
-> （向后兼容别名）或用 CLI 子命令。高频场景可优先用核心 7 个。
+> v0.10.0 起：tools/list 默认只暴露 7 个核心工具；下表"进阶 5"中的工具
+> 已从 tools/list 隐藏以节省 session 启动 tokens。**Claude Code 里请走 CLI
+> 子命令**（MCP schema 不在 list，Claude Code 的 ToolSearch 不会加载，直接
+> 调用会得到 `No such tool available`——实测验证见下方"进阶 5"）。写
+> MCP SDK / 原生 `tools/call` JSON-RPC 的脚本场景仍可按名调用。
 
 ### 核心 7（tools/list 默认暴露）
 
@@ -34,19 +36,24 @@ type: reference
 | "看 X 的源码 / 签名" | `get_ast_node` / `show X` | `include_impact=true` 含影响面（替代 impact_analysis） |
 | "项目结构总览" | `project_map` / `map` | 起手势用 `--compact` |
 
-### 进阶 5（隐藏但可调）
+### 进阶 5（Claude Code 里走 CLI；MCP 名调用仅限脚本/SDK）
 
-这 5 个工具从 `tools/list` 隐藏（省 token），但**仍可按名调用**。由于 schema 不在 list 里，**必须用下表列出的精确参数名**（猜错会返回 `"<param> is required"` 错误）。
+⚠ **实测**：从 Claude Code 里直接调 `mcp__plugin_code-graph-mcp_code-graph__<tool>`
+会得到 `No such tool available`——Claude Code 的 `ToolSearch` 只为 `tools/list`
+里的工具生成 schema，hidden 5 在 list 之外就加载不到。**Claude Code 场景一律用
+下表 CLI 列**。raw JSON-RPC (`tools/call`) 仍接受这 5 个名字（含向后兼容别名
+`find_http_route` → `trace_http_chain`, `read_snippet` → `get_ast_node`）。
 
-| 意图 | 工具 | 必填参数 | 可选参数 |
-|------|------|----------|----------|
-| "改 X 会炸啥？" | `impact_analysis` | `symbol_name` | `file_path`, `change_type` ∈ {signature,behavior,remove}, `depth` |
-| HTTP 路由 → handler 链路 | `trace_http_chain` | **`route_path`** ⚠（不是 `route`） | `depth` |
-| "X 文件依赖谁？" | `dependency_graph` | `file_path` | `direction` ∈ {outgoing,incoming,both}, `depth`, `compact` |
-| "相似/重复函数"（需 embedding） | `find_similar_code` | `symbol_name` 或 `node_id` | `top_k`, `max_distance` |
-| "未使用的代码" | `find_dead_code` | — | `path`, `node_type`, `include_tests`, `min_lines`, `compact`, **`ignore_paths`** (prefix glob 数组；默认 `["claude-plugin/"]`，传 `[]` 关闭默认豁免) |
+| 意图 | CLI（Claude Code 首选） | MCP 工具名（SDK/脚本） | 关键参数 |
+|------|--------------------------|------------------------|----------|
+| "改 X 会炸啥？" | `code-graph-mcp impact X` | `impact_analysis` | `symbol_name` (必), `file_path`, `change_type` ∈ {signature,behavior,remove}, `depth` |
+| HTTP 路由 → handler 链路 | `code-graph-mcp trace /api/x` | `trace_http_chain` | **`route_path`** ⚠ (不是 `route`), `depth` |
+| "X 文件依赖谁？" | `code-graph-mcp deps src/x.rs` | `dependency_graph` | `file_path` (必), `direction` ∈ {outgoing,incoming,both}, `depth`, `compact` |
+| "相似/重复函数"（需 embedding） | `code-graph-mcp similar X` | `find_similar_code` | `symbol_name` 或 `node_id` (必), `top_k`, `max_distance` |
+| "未使用的代码" | `code-graph-mcp dead-code [path]` | `find_dead_code` | `path`, `node_type`, `include_tests`, `min_lines`, `compact`, **`ignore_paths`** (prefix glob 数组；默认 `["claude-plugin/"]`，传 `[]` 关闭默认豁免) |
 
-CLI 等价：`impact/trace/deps/similar/dead-code`（见下方 CLI 速查）。
+**替代路径**：核心 7 里的 `get_ast_node include_impact=true` 覆盖 `impact_analysis`
+的常用场景（风险等级 + 直接/传递调用者 + 受影响文件/路由），不必跳到 CLI。
 
 ## 不要替代
 
@@ -59,8 +66,8 @@ CLI 等价：`impact/trace/deps/similar/dead-code`（见下方 CLI 速查）。
 1. 起手 `project_map --compact` 看架构
 2. `semantic_code_search` 默认带 `compact=true`，省 token
 3. 展开节点：`get_ast_node node_id=N compact=true` 看签名 / 不带 compact 看全文
-4. 改前评估影响：`get_ast_node symbol_name=X include_impact=true`（核心 7 内）
-   或直接 `impact_analysis symbol_name=X`（隐藏但可调，输出更细：风险等级 + 路由 + 文件计数）
+4. 改前评估影响：`get_ast_node symbol_name=X include_impact=true`（核心 7 内，首选）
+   或 Bash 调 `code-graph-mcp impact X`（独立进程；输出更细：风险等级 + 路由 + 文件计数）
 5. 搜不到结果 → `code-graph-mcp health-check` 检查索引与 embedding 覆盖率
 
 可用 prompts：`impact-analysis`、`understand-module`、`trace-request`

claude-plugin/templates/plugin_code_graph_mcp.md

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-arm64",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "code-graph-mcp binary for macOS ARM64",
   "license": "MIT",
   "repository": {

npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-darwin-x64",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "code-graph-mcp binary for macOS x64",
   "license": "MIT",
   "repository": {

npm/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-linux-arm64",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "code-graph-mcp binary for Linux ARM64",
   "license": "MIT",
   "repository": {

npm/linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph-linux-x64",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "code-graph-mcp binary for Linux x64",
   "license": "MIT",
   "repository": {