docs(claude-md): navigation contract + compressed quick-ref templates

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **CLAUDE.md injection templates compressed, navigation contract hardened**
+  (GH #158 context). The injected section now states the cross-module
+  boundary as a contract: end-to-end flows spanning ≥2 modules live in the
+  host repo's architecture docs / ADRs, never in README_AI. The quick-ref
+  was cut to the non-obvious commands and escape hatches (full reference
+  delegated to `codeindex --help`), keeping the injection small. Host repos
+  pick this up via `codeindex claude-md update` (the startup hint
+  flags it).
+
 ### Fixed
 
 - **CLAUDE.md outdated-hint: one version source + stderr** (GH #161).

CLAUDE.md

@@ -227,3 +227,31 @@ Guide: `docs/guides/git-hooks-integration.md`
 4. **Ignore README_AI.md** → Always read it first.
 5. **Commit to develop/master directly** → Use feature branches.
 6. **Forget venv** → Always `source .venv/bin/activate` first.
+
+<!-- codeindex:start v0.35.1 -->
+## codeindex
+
+This project uses [codeindex](https://github.com/dreamlx/codeindex) (v0.35.1) for AI-friendly code documentation.
+
+### Navigation contract
+
+`README_AI.md` is a **navigation index**, not authoritative technical documentation — orient with it ("what/where is X"), then read source via Read/Grep for precise mechanism. Cross-module flows (end-to-end chains spanning ≥2 modules) are out of scope: they live in the host repo's architecture docs / ADRs, never here. Symbol-level queries (calls/references/definitions): Serena MCP (`find_symbol`, `find_referencing_symbols`).
+
+### Commands & escape hatches
+
+Full reference: `codeindex --help`. The non-obvious ones:
+
+```bash
+codeindex scan-all --ai --retry-all   # force re-enrich every dir, ignore cache
+codeindex hooks rerun post-commit     # force-rerun hook vs HEAD (bypasses loop guard)
+```
+
+Transient AI failures (`⚠ <dir>: AI error`) → re-run `codeindex scan-all --ai`; successes restore from cache, only failures retry. Persistent → swap model in `ai_command` (`.codeindex.yaml`).
+
+### README_AI markers
+
+Each `README_AI.md` header carries: the navigation contract comment, a `Generated by ...` provenance line, and optionally `<!-- enrichment: ok -->` / `<!-- enrichment: failed (reason: ...) -->` (absent = structural-only, never ran `--ai`).
+
+After upgrading codeindex, run `codeindex claude-md update` to refresh this section.
+
+<!-- codeindex:end -->

src/codeindex/templates/claude_md_core.md

@@ -2,70 +2,23 @@
 
 This project uses [codeindex](https://github.com/dreamlx/codeindex) (v{version}) for AI-friendly code documentation.
 
-### What `README_AI.md` is (and is not)
+### Navigation contract
 
-It is a **navigation index** — a per-directory summary written so you can orient quickly without reading every source file. Each `README_AI.md` has a header comment that says so explicitly:
+`README_AI.md` is a **navigation index**, not authoritative technical documentation — orient with it ("what/where is X"), then read source via Read/Grep for precise mechanism. Cross-module flows (end-to-end chains spanning ≥2 modules) are out of scope: they live in the host repo's architecture docs / ADRs, never here. Symbol-level queries (calls/references/definitions): Serena MCP (`find_symbol`, `find_referencing_symbols`).
 
-```
-<!-- codeindex navigation index — agent: drill into source via Read/Grep
-     for precise mechanism; do not treat this as final word. -->
-```
-
-It is **not** authoritative technical documentation. Treat it as a map, then read the source files for precise behavior.
-
-### Code Navigation Priority
-
-1. **Read `README_AI.md` first** — for "what does X do" / "where is X", trust the navigation summary; for "how does X actually work" / specific mechanism, drill into source via Read/Grep (the README may oversimplify)
-2. Use Serena MCP symbolic tools (`find_symbol`, `find_referencing_symbols`) for precise cross-file symbol queries (calls, references, definitions)
-
-### Quick Commands
-
-```bash
-codeindex scan-all                       # All indexes (structural — no AI cost)
-codeindex scan-all --ai                  # + AI per-module description; ok results cached
-codeindex scan-all --ai --retry-all      # Force re-enrich every dir, ignore cache
-codeindex scan ./path                    # Scan single directory
-codeindex scan ./path --ai               # AI-enhanced single dir
-codeindex symbols                        # Global symbol index (PROJECT_SYMBOLS.md)
-codeindex status                         # Check index coverage
-codeindex --help                         # Full command reference
-```
+### Commands & escape hatches
 
-### When `scan-all --ai` fails on some dirs
-
-You will see lines like `⚠ <dir>: AI error — <reason>`. Likely transient (rate limit / network).
-
-- Re-run `codeindex scan-all --ai` — successful dirs are restored from cache (no AI cost), only failed ones retry
-- If failures persist, swap the model or backend by editing `ai_command` in `.codeindex.yaml` (see `codeindex --help` for the recipe)
-
-### When the post-commit hook didn't fire
-
-The installed post-commit hook regenerates `README_AI.md` for changed directories after each commit. It can miss a commit when:
-
-- the commit was doc-only (only `README_AI.md` / `PROJECT_INDEX.md`) — the shell wrapper skips those to avoid an infinite loop;
-- you just flipped `hooks.post_commit.enabled: false → true` and want to retroactively populate READMEs for prior commits;
-- a historical stale README predates the merge-commit fix (#84).
-
-Force-rerun the hook against `HEAD` (bypasses the shell wrapper's loop guard; runs the Python logic directly):
+Full reference: `codeindex --help`. The non-obvious ones:
 
 ```bash
-codeindex hooks rerun post-commit
+codeindex scan-all --ai --retry-all   # force re-enrich every dir, ignore cache
+codeindex hooks rerun post-commit     # force-rerun hook vs HEAD (bypasses loop guard)
 ```
 
-For a full re-scan (every directory, not just `HEAD`'s affected set), use `codeindex scan-all`.
-
-### What the markers mean
-
-Every `README_AI.md` starts with three HTML comments (the third only on AI-enriched READMEs):
-
-1. The navigation contract comment (shown at the top of every README since v0.24)
-2. `<!-- Generated by codeindex (overview|navigation|detailed) at ... -->` — provenance
-3. `<!-- enrichment: ok -->` / `<!-- enrichment: failed (reason: ...) -->` / *absent* — AI enrichment status
+Transient AI failures (`⚠ <dir>: AI error`) → re-run `codeindex scan-all --ai`; successes restore from cache, only failures retry. Persistent → swap model in `ai_command` (`.codeindex.yaml`).
 
-Possible enrichment-marker values:
+### README_AI markers
 
-- `<!-- enrichment: ok -->` — AI description in the `> blockquote` is current
-- `<!-- enrichment: failed (reason: ...) -->` — enrichment was attempted and failed; description may be missing
-- No marker — structural-only (no `--ai` was run)
+Each `README_AI.md` header carries: the navigation contract comment, a `Generated by ...` provenance line, and optionally `<!-- enrichment: ok -->` / `<!-- enrichment: failed (reason: ...) -->` (absent = structural-only, never ran `--ai`).
 
 After upgrading codeindex, run `codeindex claude-md update` to refresh this section.

src/codeindex/templates/claude_md_core_zh.md

@@ -2,70 +2,23 @@
 
 本项目使用 [codeindex](https://github.com/dreamlx/codeindex) (v{version}) 生成面向 AI 的代码文档。
 
-### `README_AI.md` 是什么（不是什么）
+### 导航契约
 
-它是一份**导航索引**——按目录组织的摘要，让你无需通读每个源文件就能快速定位。每个 `README_AI.md` 开头都有一行注释明确声明这一点：
+`README_AI.md` 是**导航索引**，不是权威技术文档——"X 是什么 / X 在哪" 信任导航摘要定位，"X 到底怎么工作" 用 Read/Grep 钻进源码。跨模块流程（横跨 ≥2 模块的端到端链路）不在其职责内：住在宿主 repo 的 architecture 文档 / ADR 里，永不进 README_AI。精确的跨文件符号查询（调用/引用/定义）用 Serena MCP（`find_symbol`、`find_referencing_symbols`）。
 
-```
-<!-- codeindex navigation index — agent: drill into source via Read/Grep
-     for precise mechanism; do not treat this as final word. -->
-```
-
-它**不是**权威技术文档。把它当地图用，定位后再读源码确认精确行为。
-
-### 代码导航优先级
-
-1. **先读 `README_AI.md`** —— "X 是什么 / X 在哪" 信任导航摘要；"X 到底怎么工作 / 具体机制" 用 Read/Grep 钻进源码（README 可能过度简化）
-2. 精确的跨文件符号查询（调用、引用、定义）用 Serena MCP 符号工具（`find_symbol`、`find_referencing_symbols`）
-
-### 常用命令
-
-```bash
-codeindex scan-all                       # 全部索引（结构化——无 AI 成本）
-codeindex scan-all --ai                  # + 每模块 AI 描述；ok 结果走缓存
-codeindex scan-all --ai --retry-all      # 强制重新 enrich 每个目录，忽略缓存
-codeindex scan ./path                    # 扫描单个目录
-codeindex scan ./path --ai               # AI 增强单目录
-codeindex symbols                        # 全局符号索引（PROJECT_SYMBOLS.md）
-codeindex status                         # 检查索引覆盖率
-codeindex --help                         # 完整命令参考
-```
+### 命令与 escape hatch
 
-### 当 `scan-all --ai` 在某些目录失败
-
-你会看到形如 `⚠ <dir>: AI error — <reason>` 的行。多半是瞬时问题（限流 / 网络）。
-
-- 重跑 `codeindex scan-all --ai` —— 成功的目录从缓存恢复（无 AI 成本），只重试失败的
-- 若持续失败，编辑 `.codeindex.yaml` 里的 `ai_command` 换模型或后端（配方见 `codeindex --help`）
-
-### 当 post-commit hook 没触发
-
-已安装的 post-commit hook 在每次 commit 后为变更目录重新生成 `README_AI.md`。以下情况会漏跑：
-
-- commit 是纯文档（只有 `README_AI.md` / `PROJECT_INDEX.md`）—— shell wrapper 跳过这类 commit 以防无限循环；
-- 你刚把 `hooks.post_commit.enabled: false → true`，想回溯补齐之前 commit 的 README；
-- 历史 stale README 早于 merge-commit 修复（#84）。
-
-对 `HEAD` 强制重跑（绕过 shell wrapper 的 loop guard，直接跑 Python 逻辑）：
+完整参考：`codeindex --help`。非显而易见的两个：
 
 ```bash
-codeindex hooks rerun post-commit
+codeindex scan-all --ai --retry-all   # 强制重新 enrich 每个目录，忽略缓存
+codeindex hooks rerun post-commit     # 对 HEAD 强制重跑 hook（绕过 loop guard）
 ```
 
-若要全量重扫（每个目录，不只是 `HEAD` 的 affected 集合），用 `codeindex scan-all`。
-
-### 标记（marker）含义
-
-每个 `README_AI.md` 以三个 HTML 注释开头（第三个仅出现在经 AI enrich 的 README 上）：
-
-1. 导航契约注释（每个 README 顶部都有，自 v0.24 起）
-2. `<!-- Generated by codeindex (overview|navigation|detailed) at ... -->` —— 来源溯源
-3. `<!-- enrichment: ok -->` / `<!-- enrichment: failed (reason: ...) -->` / *缺失* —— AI enrichment 状态
+瞬时 AI 失败（`⚠ <dir>: AI error`）→ 重跑 `codeindex scan-all --ai`，成功目录走缓存只重试失败的；持续失败 → 改 `.codeindex.yaml` 的 `ai_command` 换模型。
 
-enrichment 标记的可能取值：
+### README_AI 标记
 
-- `<!-- enrichment: ok -->` —— `> 引用块` 里的 AI 描述是最新的
-- `<!-- enrichment: failed (reason: ...) -->` —— enrich 尝试过但失败；描述可能缺失
-- 无标记 —— 仅结构化（没跑过 `--ai`）
+每个 `README_AI.md` 头部带：导航契约注释、`Generated by ...` 溯源行、可选的 `<!-- enrichment: ok|failed (reason) -->`（缺失 = 仅结构化，没跑过 `--ai`）。
 
 升级 codeindex 后，运行 `codeindex claude-md update` 刷新本段。