@c4a/context-cli 0.5.39-beta.3 → 0.5.39-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.5.39-beta.3",
+  "version": "0.5.39-beta.4",
   "type": "module",
   "bin": {
     "context": "./cli.js"

package/plugin/README.md

@@ -1,12 +1,10 @@
-# Agentic Context System Over Compiled Knowledge
+# Context: Build Agent-Facing Knowledge
 
 > [中文版本](./README_CN.md)
 
 <p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
 
-An Agentic knowledge system built for AI Agents. It pre-compiles Feishu docs, local Markdown, code structure, and hand-curated business material into structured, traceable knowledge, so an agent can perform high-precision search over it through a dedicated CLI.
-
-This repository is the **local standalone build of C4A System**. The full C4A System will add online services with stronger multi-user collaboration support — releasing soon.
+A knowledge workflow built for small and mid-sized teams working with Agents. It compiles Feishu docs, local Markdown, code, and hand-curated business material into structured, traceable knowledge, then guides the Agent — through optimal reasoning patterns and targeted exploration of that knowledge — to deliver high-quality retrieval. Runs inside any Agent environment that supports Plugins (Skill + Command).
 
 ## Why C4A Context
 
@@ -107,17 +105,19 @@ The compiled knowledge base can be packaged for distribution:
 
 ## Recommended environment
 
-Measured behavior of Agent + model combinations across instruction following, parameter hallucination, and extraction quality (scored 0–100):
-
-| Agent | Model | Instruction following | Parameter hallucination | Extraction quality |
-|---|---|---:|---|---:|
-| Codex | GPT 5.5 xh | 95 | Almost none | 96 |
-| Claude | Opus 4.6 / 4.7 | 95 | Almost none | 95 |
-| Cursor | Opus 4.6 / 4.7 | 92 | Almost none | 88 |
-| Claude | DeepSeek V4 | 88 | Almost none | 84 |
-| Claude | DeepSeek V4 Flash | 55 | Frequent | 45 |
-
-**Recommendation**: prefer GPT or Opus for now. DeepSeek V4 still lags in instruction following and extraction quality and needs further CLI optimization; full DeepSeek V4 adaptation is planned for v0.5.40, targeting an overall score above 90.
+The numbers below come from a parallel benchmark: each model runs the full c4a flow (capture → align → compile) end-to-end over the same 10-document business corpus, with no manual intervention. Quality is scored across 7 dimensions (totaling 100) based on the resulting knowledge base; duration covers the full flow from `context init` to `compile close`.
+
+| Dimension | GPT 5.5 (Codex) | Opus 4.7 (Claude) | DeepSeek V4 Pro (Claude) |
+|---|---:|---:|---:|
+| Fact coverage (25) | 22 | 22 | 18 |
+| Fact fidelity (25) | 23 | 19 | 18 |
+| Structure (15) | 13 | 8 | 7 |
+| URL (5) | 3 | 2 | 5 |
+| Source ref (10) | 9 | 7 | 6 |
+| Section boundary (10) | 9 | 7 | 5 |
+| Schema (10) | 8 | 9 | 7 |
+| **Total** | **87** | **74** | **66** |
+| Duration | 14m55s | 19m6s | 14m44s |
 
 ## About this repository
 

package/plugin/README_CN.md

@@ -1,12 +1,10 @@
-# Agentic Context System Over Compiled Knowledge
+# Context: Build Agent-Facing Knowledge
 
 > [English](./README.md)
 
 <p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
 
-专为 AI Agent 打造的 Agentic 知识系统，将飞书文档、本地 Markdown、代码结构、人工整理的业务资料预编译为结构化、可溯源的知识，再让智能体通过专用命令行工具，在这套知识上完成高精度检索。
-
-本仓库是 **C4A System 的本地独立可运行版本**；完整的 C4A System 将支持在线服务、更适合多人协同，即将发布。
+专为 Agent 打造的中小团队知识工作流，将飞书文档、本地 Markdown、代码、人工整理的业务资料编译为结构化、可溯源的知识，再指导 Agent 通过最佳的推理模式和探查知识完成高质量检索。本工具运行在支持 Plugin （Skill + Command） 的 Agent 环境中。
 
 ## 为什么选择 C4A Context
 
@@ -105,17 +103,19 @@ bun add -g @c4a/context-cli
 
 ## 环境推荐
 
-不同 Agent 与模型组合在指令遵循、参数幻觉、提取质量三项上的实测表现（0–100 分）：
-
-| Agent | 模型 | 指令遵循度 | 参数幻觉 | 提取质量 |
-|---|---|---:|---|---:|
-| Codex | GPT 5.5 xh | 95 | 几乎无 | 96 |
-| Claude | Opus 4.6 / 4.7 | 95 | 几乎无 | 95 |
-| Cursor | Opus 4.6 / 4.7 | 92 | 几乎无 | 88 |
-| Claude | DeepSeek V4 | 88 | 几乎无 | 84 |
-| Claude | DeepSeek V4 Flash | 55 | 经常 | 45 |
-
-**建议**：目前优先使用 GPT 或 Opus；DeepSeek V4 在指令遵循与提取质量上仍有差距，需配合 CLI 进一步优化，预计 v0.5.40 完成 DeepSeek V4 适配并达到 90+ 综合得分。
+下方数据来自一次并发基准测试：每个模型在同一份 10 篇业务文档语料上端到端跑完 c4a 全流程（capture → align → compile），无人工介入。质量按 7 个维度评分（总分 100）反映产物知识库；耗时覆盖 `context init` 到 `compile close` 的全流程。
+
+| 维度 | GPT 5.5（Codex） | Opus 4.7（Claude） | DeepSeek V4 Pro（Claude） |
+|---|---:|---:|---:|
+| 事实覆盖（25） | 22 | 22 | 18 |
+| 事实忠实（25） | 23 | 19 | 18 |
+| 结构语义（15） | 13 | 8 | 7 |
+| URL（5） | 3 | 2 | 5 |
+| Source ref（10） | 9 | 7 | 6 |
+| Section 边界（10） | 9 | 7 | 5 |
+| Schema（10） | 8 | 9 | 7 |
+| **总分** | **87** | **74** | **66** |
+| 总耗时 | 14m55s | 19m6s | 14m44s |
 
 ## 关于本仓库
 

package/plugin/commands/align.md

@@ -27,7 +27,6 @@ For protocol discovery, prefer narrow commands:
 - `context schema workflow.next-action-envelope.v2 --view minimal --format json`
 - `context protocol show align-compile --format json`
 - `context schema align-structure-intent --view minimal --format json`
-- `context schema align-structure-decision --view minimal --format json` only when auditing canonical output or repairing an advanced canonical payload.
 
 ### Step 2 — Read Evidence Through The Single Evidence Path
 
@@ -36,9 +35,10 @@ If scan returns a `read-plan` command, run it and then follow the next command r
 - `read-plan` summarizes source size, active source set, navigation/placeholder sources, and the next evidence command.
 - `source-bundle` returns the selected source text with `@c4a` block annotations. Read it, then write the requested align JSON yourself, normally `align-structure-intent`; do not pipe the bundle text into `context align validate`.
 - If `source-bundle` omits text for budget, run its `next_action.command`.
+- If the next command contains `--read-cursor`, treat it as opaque continuation state. Do not decode it and do not replace it with hand-written `--source` / `--window` / `--range` / `--heading` selectors.
 - `blocks`, `windows`, `block-index`, `source-mapping`, and `pending-relation-refs` are detail views only. Use them when the read-plan/source-bundle next action or `how_to_explore[]` asks for a narrow follow-up.
 
-When a view returns `page.next_command`, follow that command to continue the same semantic view. Use `--source`, `--heading`, `--window`, or `--token-budget` only as view filters; do not inspect workflow files, cache files, host tool-results, or stdout fragments with generic tools.
+When a view returns `page.next_command`, follow that command to continue the same semantic view. Use `--source`, `--heading`, `--window`, `--range`, or `--token-budget` only as view filters; do not inspect workflow files, cache files, host tool-results, or stdout fragments with generic tools.
 
 If a detail view returns `align-blocks-read-incomplete`, `page.has_more`, or `truncated: true`, the response is a partial read. Return to the read-plan/source-bundle continuation instead of treating that partial JSON page as the complete source.
 
@@ -46,12 +46,12 @@ If a detail view returns `align-blocks-read-incomplete`, `page.has_more`, or `tr
 
 Reuse existing knowledge before inventing new Nodes: use `context mdrive glossary match <name>` and `context mdrive node list --format json` for term/entity reuse.
 
-Apply packaged `context:skill-align-workflow` Node classification gates and align intent procedure. Keep generated payloads on stdin. Do not create scratch files under the workspace or `/tmp`.
+Apply packaged `context:skill-align-workflow` Node classification gates and align intent procedure. Keep generated payloads on stdin. Prefer heredocs for small payloads; if payload staging is needed for large or parallel writes, use the workspace AGENTS.md scratch path (`.context/.tmp/agent-payloads/<run-id>/...` in embedded workspaces, `.tmp/agent-payloads/<run-id>/...` in root-layout workspaces) and redirect stdin from it. Never reuse fixed `/tmp/c4a-*` names and never place scratch payloads under output/archive/knowledge/raw truth directories.
 
 Use CLI diagnostics instead of static prompt rules:
 
 - `diagnostics.automatic_ownership_adjustments[]` explains mechanical external-reference demotions and the explicit ownership override shape.
-- `pending-relation-refs` lists explicit Parent/Children/Related markdown links. Reuse existing target Nodes when present; keep unresolved target slug hints deferred instead of writing dangling `contains_parent`.
+- `pending-relation-refs` lists explicit Parent/Children/Related markdown links. Reuse existing target Nodes when present; keep unresolved target slug hints deferred instead of writing dangling `contains_parent` / `domain_gate.child_refs` or empty placeholder Domains.
 - Validation diagnostics identify contiguity, citation eligibility, ownership, and mount-matrix problems.
 - `views[]` and `diagnostics` distinguish citable evidence from supporting context; do not infer citation eligibility from raw ownership prose.
 

package/plugin/commands/capture.md

@@ -40,7 +40,7 @@ Invocation note: code capture does not run through `npx`. The default code aspec
   - Write the body to `context capture --note --intent <intent> --anchor <node-slug>[#<section-id>] --input -` for anchored notes, or omit `--anchor` for brainstorm.
   - For `revision`, organize the stdin Markdown with headings: `旧上下文`, `修改意图`, `新内容`, `验证条件`.
   - For `decision`, organize the stdin Markdown with headings: `议题`, `选项`, `决议`, `理由`.
-  - After capture, run `context status --format json` and base the user-facing next step on `next_step.command` / `workflow.next_step`.
+  - After capture, run `context status --view summary --format json` and base the user-facing next step on `next_step.command` / `workflow.next_step`.
 
 For stdin batches, use this shape:
 
@@ -58,7 +58,7 @@ Do not pipe the heredoc through another command, and do not discover files with
 
 Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
 
-- Run `context status --format json` and use its `next_step.command` / `workflow.next_step`.
+- Run `context status --view summary --format json` and use its `next_step.command` / `workflow.next_step`.
 - If JSON status reports `incremental.pending_align.status: "pending"` with `count > 0`, suggest `/context:align` even when a previous finalized align workflow or prose `workflow.next_step` says compile. Newly captured structure work must be routed through align before compile.
 - If status says aligned knowledge is missing or alignment is required → suggest `/context:align`.
 - If status says compile work is pending for Markdown / evidence-backed knowledge → suggest `/context:compile`. Mention `/context:align` only if the user wants to revise the structure.

package/plugin/commands/compile.md

@@ -41,7 +41,7 @@ Protocol discovery:
 
 1. Run `context compile scan --format json` (or `context compile scan --delegated --format json` only for explicit delegated mode).
 2. If the scan returns `stop_noop` or no changed work, report that compile stopped before draft and no files were written.
-3. Run `context status --format json` or `context mdrive workspace stats --format json` only when needed for the final before/after report or when the CLI asks for diagnostics. Do not run doctor/status/source-list as a required preflight before following a valid compile scan or align-finalize handoff.
+3. Run `context status --view summary --format json` or `context mdrive workspace stats --format json` only when needed for the final before/after report or when the CLI asks for diagnostics. Do not run doctor/status/source-list as a required preflight before following a valid compile scan or align-finalize handoff.
 
 Run `context compile scan` only for this initial preflight unless the CLI explicitly returns it as the next command after a terminal/no-work state. During an active compile workflow, discover the next node from the current envelope (`next_action`, `views[]`, `workset_progress`) and follow returned commands; do not rerun scan between node cycles to probe for the next node.
 
@@ -51,11 +51,11 @@ Repeat until the CLI returns `stop_noop`, `close_compile` succeeds, or a blockin
 
 Carry the latest envelope forward between iterations. After a successful node cycle, continue from its returned `next_action.command` / `workset_progress` rather than restarting at `context compile scan`.
 
-### Step 1 — Read Expected Views
+### Step 1 — Read Node Evidence From The Envelope
 
-Run expected view commands from the envelope before writing. For compile evidence, prefer the CLI-returned source-ref/scaffold views. They may expose:
+Run the evidence command returned by the envelope before writing. `views[].expected` identifies the default compact evidence entry, not a separate checklist to exhaust. For compile evidence, prefer the CLI-returned source-ref/scaffold views. They may expose:
 
-- `source_refs_index_command` / `source_refs_command` — compact block-id evidence index for drafting; use `items[].block_id` in `source_block_ids[]`.
+- `source_refs_index_command` / `source_refs_command` — compact Node-scoped citation index for drafting; use `items[].block_id` in `source_block_ids[]` when the row is the evidence you will cite.
 - `source_refs_detail_command` — detailed source refs with quote previews; open only when the compact index is not enough.
 - `request_full_text_command` / `--view text` — narrow text view for one block when quote preview is not enough; this is still Node-scoped, not a workspace evidence bundle.
 - `citable_source_refs[]` — detailed-view refs eligible for draft citations; prefer `block_id` values in `source_block_ids[]`.
@@ -69,6 +69,8 @@ Follow `page.next_command` for pagination. Use `how_to_explore[]` for narrow rea
 
 For `submit_compile_cycle`, load the Node evidence via the returned command/views, invoke packaged `context:skill-compile-draft` for exactly one Node, and pass the emitted JSON on stdin to the returned `next_action.command`.
 
+Prefer heredocs for small payloads. If large or parallel draft payloads need staging, use the workspace AGENTS.md scratch path (`.context/.tmp/agent-payloads/<run-id>/...` in embedded workspaces, `.tmp/agent-payloads/<run-id>/...` in root-layout workspaces) and redirect stdin from that file. Never reuse fixed names like `/tmp/c4a-draft-<node>.json`, and never use scratch paths as workflow handoff or CLI-managed storage.
+
 For `continue_compile_cycle`, do not invoke the draft skill and do not attach `--input`; execute the returned `next_action.command` exactly. `--continue` resumes a saved draft session. If it returns `status: "noop"`, follow the returned `close_compile` next action.
 
 For `patch_compile_draft`, submit only the patch schema requested by the CLI. Use `actions_meta[].action_id` for `replace_action` / `remove_action`, or `add_action` with `before` / `after`; do not use generic `op/path/value` aliases.

package/plugin/skills/skill-align-workflow/SKILL.md

@@ -20,7 +20,7 @@ Run `context align scan --format json`, follow the top-level `next_action.comman
 - Existing knowledge is the lookup registry. Use `context mdrive glossary match <name>` and `context mdrive node list --format json`; do not read `knowledge/**` or create a separate registry file.
 - Code projection Nodes are reusable knowledge handles. When document evidence belongs on a code symbol, reuse the code slug instead of creating a parallel document Node.
 - `diagnostics.automatic_ownership_adjustments[]` and validation diagnostics are the mechanical external-reference ownership source of truth. Independent reference definitions, pure URLs, relation kind blocks, and multiline reference-only lists default to context_only; submit an explicit `block_ownership[]` owned/shared entry only when such a reference block is primary citation evidence.
-- When `pending-relation-refs` is present, inspect it before finalizing graph structure. Use existing matches for `contains_parent_ref` or `domain_gate.child_refs`; keep unresolved target slug hints deferred and do not write dangling parent or edge refs.
+- When `pending-relation-refs` is present, inspect it before finalizing graph structure. Use existing/current matches for `contains_parent_ref` or `domain_gate.child_refs`; keep unresolved target slug hints deferred and do not write dangling parent, child, or edge refs. For navigation-only / placeholder-only sources whose child refs are all deferred, the default is no Node, not an empty Domain with `child_refs: []`; only use `entity[term]` when the source title is an atomic term.
 - `views[]` and diagnostics distinguish citable evidence from supporting context. Do not promote supporting/context-only material into cited Sections unless a later ownership correction makes it citation-eligible.
 - Keep cache-friendly prompt order: fixed protocol/schema first, existing knowledge lookup second, source evidence views third, current semantic payload last. Preserve CLI JSON order and do not add timestamps, random ids, scratch paths, or host paths to generated payloads.
 - Node type, tag, fake-Entity, `domain`, and `action` gates are in `references/gates.md`.
@@ -47,7 +47,7 @@ Run the returned `next_action.command`. For structural align work this is normal
 
 If `source-bundle` omits text for budget, run its `next_action.command`.
 
-Read evidence through semantic CLI views, not shell parsing. Follow `page.next_command` for pagination. Use `--source`, `--heading`, `--window`, and `--token-budget` as view filters only. `--unwrap` removes workflow metadata; it does not expand a compact view into full detail.
+Read evidence through semantic CLI views, not shell parsing. Follow `page.next_command` for pagination. If the command contains `--read-cursor`, treat it as opaque continuation state and run it exactly; do not replace it with hand-written `--source`, `--heading`, `--window`, or `--range` selectors. Use `--source`, `--heading`, `--window`, `--range`, and `--token-budget` as view filters only. `--unwrap` removes workflow metadata; it does not expand a compact view into full detail.
 
 If a blocks view returns `align-blocks-read-incomplete`, `page.has_more`, or `truncated: true`, treat that response as a partial read. Do not finalize source-wide ownership or dense planned Sections from source-mapping/headings alone; continue the current detail view only when `page.next_command` is explicitly needed, otherwise return to the read-plan/source-bundle continuation.
 
@@ -69,9 +69,11 @@ For large or batched payloads, use `references/density-profile.md` and `referenc
 
 Use `next_action.input_schema` or the matching `context schema <name> --view minimal --format json` output to shape the payload.
 
-For the default `align-structure-intent` path, produce one intent document with semantic Nodes, `section_groups[]`, `ownership_groups[]`, optional explicit `block_ownership[]` patches, and edges. Let CLI generate `section_id` values and expand ownership groups into canonical defaults/exceptions.
+For the default `align-structure-intent` path, produce one intent document with semantic Nodes, `section_groups[]`, `ownership_groups[]`, optional explicit `block_ownership[]` patches, and edges. Let CLI generate `section_id` values and expand ownership groups into canonical defaults/exceptions. For long sources, do not hand-enumerate the largest ownership range; use one `{ source_id }` ownership group for the majority owner, then use `{ block_ids }` groups or explicit patches only for exceptions.
 
-Use only `block_ids[]` in `section_groups[]`. Do not invent heading/range/window selectors inside the intent. Treat source heading changes as section-planning signals: sibling sub-headings under a shared parent may stay in one Section when they form one coherent semantic topic; headings with no shared parent should usually split unless you intentionally want one Section to span them. The CLI reports cross-heading groups but does not rewrite your semantic grouping. If one semantic section spans non-contiguous citation-eligible blocks, align may accept the grouping, but finalized ownership will split it into compile draft-ready contiguous runs; compile source-refs templates should stay separate by default. Every block you leave as `owned` or `shared` citation evidence must appear in some section group; otherwise reclassify it as `context_only` or `ignored`. If a no-write/navigation-only/placeholder-only Node has no section group, set `planned_sections: []` explicitly so the CLI knows this was intentional.
+Use only `block_ids[]` in `section_groups[]`. Do not invent heading/range/window selectors inside the intent. Treat source heading changes as section-planning signals: sibling sub-headings under a shared parent may stay in one Section when they form one coherent semantic topic; headings with no shared parent should usually split unless you intentionally want one Section to span them. The CLI reports cross-heading groups but does not rewrite your semantic grouping. If one semantic section spans non-contiguous citation-eligible blocks, align may accept the grouping, but finalized ownership will split it into compile draft-ready contiguous runs; compile source-refs templates should stay separate by default. Every block you leave as `owned` or `shared` citation evidence must appear in some section group; otherwise reclassify it as `context_only` or `ignored`. If a no-write/navigation-only/placeholder-only Node is intentionally kept, set `planned_sections: []` explicitly so the CLI knows this was intentional. Do not keep such a Node by default when all children are unresolved relation clues; skip it until a child or content source resolves. Do not express deferred children as `domain_gate.child_refs: []`, and do not turn a container placeholder into `entity[term]` unless the title itself is a useful atomic term.
+
+Emit `depends_on` edges only when cited source blocks explicitly say one Node consumes, requires, calls, is configured by, or is downstream of another Node as a prerequisite, capability provider, upstream input, runtime dependency, or data-flow source. Direction is consumer/downstream -> provider/upstream. Do not create `depends_on` for parent/child containment, `Related`/`See also` lists, sibling co-occurrence, shared table membership, name similarity, or a plain mention without a dependency predicate. `edges[].evidence_blocks[]` must include the block that states the dependency; if the relationship matters but evidence is missing, leave the edge out or add an unresolved question instead of guessing.
 
 Prefer the strongest source-backed `section_kind` that fits the current schema priority chain; avoid planning an entire dense source as `description` when the evidence clearly contains examples, comparison tables, Q&A, decisions, specs, warnings, or principles. Treat kind precision as a drafting quality preference, not a reason to block an otherwise source-backed write. Keep only source-supported semantic decisions in the payload; leave mechanical repair and patch routing to CLI diagnostics.
 

package/plugin/skills/skill-align-workflow/references/gates.md

@@ -38,7 +38,7 @@ After choosing `node_type`, choose the title to fit that type:
 
 Scope/process words in a source title are warning signals when proposed as an Entity title, not hard classification rules. Re-check the type/title when a proposed Entity title contains words such as "方案", "架构", "体系", "演练", "流程", "策略", "能力", "机制", "framework", "architecture", "system", "strategy", "process", or "drill". Keep the wording only when evidence shows it is the formal name of a concrete object or an atomic term.
 
-Relation-only sources should not force title copying. If a relation block has resolvable children and the graph node is useful, prefer an explicit Domain placeholder with `planned_sections: []`. If the source names only an atomic concept such as SSR/CSR, prefer a term Entity title such as "SSR" or "CSR" instead of "SSR 方案" / "CSR 方案".
+Relation-only sources should not force title copying or empty graph shells. If a relation block has resolvable current/existing children and the graph node is useful, prefer an explicit Domain placeholder with `planned_sections: []`. If all children are unresolved/deferred relation clues, skip the Node by default and keep the source blocks `context_only` / `ignored`; the pending relation refs are enough until child content appears. Do not express this deferred state as `domain_gate.child_refs: []`. If the source names only an atomic concept such as SSR/CSR and that term is useful on its own, prefer a term Entity title such as "SSR" or "CSR" instead of "SSR 方案" / "CSR 方案".
 
 ## Entity Tag Rules
 
@@ -105,7 +105,7 @@ Use `node_type: domain` only for a scope that groups child Nodes. Fill:
 | `child_refs[]` | Candidate ids, local refs, or final slugs for children in the scope. |
 | `grouping_reason` | Why these children belong together under this domain. |
 
-If a domain has no resolvable child refs, no clear grouping reason, or only one same-file child without a broader scope, emit an Entity instead and choose its Entity tag yourself. The CLI rejects invalid Domain gates; it does not auto-downgrade a Domain or choose fallback tags.
+If a domain has no resolvable child refs, no clear grouping reason, or only one same-file child without a broader scope, do not emit a Domain. For navigation-only / placeholder-only sources with only deferred children, skip the Node. Emit an Entity only when evidence names an atomic term or concrete object and choose its Entity tag yourself. The CLI rejects invalid Domain gates; it does not auto-downgrade a Domain or choose fallback tags.
 
 Scope-name titles such as "X 业务域", "Y 领域", "business domain", or "technical area" are a warning sign when proposed as Entity. Keep them as Entity only when the subject is an atomic term or concrete object; otherwise use Domain with `domain_gate.child_refs`.
 

package/plugin/skills/skill-compile-draft/SKILL.md

@@ -23,13 +23,14 @@ Classify raw evidence for one Node into `add` / `skip` (and on refresh: `update`
 - Evidence boundary: treat the CLI-provided NodeContext and evidence views as complete. Cite only block ids surfaced as citation-eligible in `source-refs-index` `items[]`, `citable_source_refs[]`, or `raw_snippet_indexes.citation_eligible`; treat `supporting_context_refs[]`, `context_only`, and secondary-shared snippets as background. `request_full_text` may expose visible text for inspection through the narrow text view (`context compile context <slug> --request-full-text <block_id> --view text --format json`), and it does not change citation eligibility. If supporting/context-only evidence is needed as a citation, emit `pending_ownership_challenge` or `structure_challenge` — see [references/structural-challenges.md](references/structural-challenges.md). Never `grep` / `sed` / `jq` / `cat` / `head` raw `--format json` stdout or workflow scratch files in `/tmp` or `.context/.cache/`; use semantic views and follow returned `next_command` / `how_to_explore[]`. For write commands that take `--payload-digest`, omit the flag unless the CLI explicitly asks for a stale guard.
 - Actions are candidate write actions, not final semantic decisions; `context reconcile prepare` re-derives near-duplicate / conflict / merge relations from `candidates[]` on its own. Op naming is scoped by schema: compile-draft `actions[]` already targets Sections, so Section lifecycle ops are verb-only (`add`, `update`, `supersede`, `deprecate`, `skip`). Do not use align-style names such as `add_section`, `write_section`, or `propose_section`.
 - Source support passing is not completion. Before emitting, estimate coverage from the provided `raw_snippets[]`: if there are 3+ citation-eligible snippets, a one-action draft is valid only when the later snippets are duplicates, navigation, placeholders, or continuations of the same fact. Small dense docs still need multiple actions when later snippets state distinct capabilities, constraints, examples, risks, FAQ, or usage notes. Large manuals/design docs should compile to several orthogonal actions in the same draft. Do not switch into "speed mode" because the first action validates; coverage is part of the draft task.
-- Pick `kind` from the CLI's `context schema compile-draft` contract, especially `section_kind_priority` and the mount matrix. Treat kind precision as a drafting quality preference, not a reason to loop forever when the CLI accepts the write. A `decision` needs at least two surfaced alternatives plus a reason; bare "we use X because Y" is usually `spec`. Reach `description` only after every more specific kind fails.
+- Pick `kind` from the CLI's `context schema compile-draft` contract, especially `section_kind_priority` and the mount matrix. Treat kind precision as a drafting quality preference, not a reason to loop forever when the CLI accepts the write. A `decision` fits when the source explicitly records a choice, tradeoff, adopted path, or policy conclusion with a reason; multiple surfaced alternatives are a strong signal but not required. Bare rules or checks without a recorded choice are usually `spec`. Reach `description` only after every more specific kind fails.
 - `node.planned_sections[]` is an align-time scaffold hint, not a hard completion gate. Prefer a planned kind when the evidence fits; if a source-backed stronger kind differs, emit it and let the CLI warning guide review.
 - `kind × node.type` must satisfy the CLI Section mount matrix; mismatches get rejected at write time. When the strongest kind is blocked by mount matrix, fall to the next legal kind whose form actually fits — do not collapse to `description` just because it mounts everywhere, and do not invent thin precision (e.g. one-line `spec`) just to avoid `description` either. See [Description anti-abuse gates](#description-anti-abuse-gates) for the classification checks at the description boundary.
 - Every write action cites raw via `source_block_ids[]` from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id`; the CLI expands it to canonical `source_refs[]` before saving. Use explicit `source_refs[]` only when the CLI gives no block id for the needed citation. Never mix both fields in one action, fabricate ids, or cite navigation-only blocks as evidence for a content Section.
 - For large source-ref views, prefer the returned `source_refs_index_command` / `source_refs_command` / `--view source-refs-index` when you only need block ids; open `source_refs_detail_command` only when you need quote preview or explicit `source_refs[]`.
 - Use `content` for the Section text the reader should see. It may be long and may contain URLs, tables, commands, config, or code fences. Add `summary` for long content or when it helps readers/query output; omit it when content is short. Summary quality checks are warning hints only, not schema or evidence failures. The CLI rejects retired fields (`body`, `detail`, `raw`, singular `source_ref`, quoted-evidence) with canonical repair hints — read those hints rather than memorising the blacklist. Omit optional fields when empty.
 - Preserve user-facing Markdown structure from cited raw when it carries meaning: inline code/code fences, Markdown links and URLs, blockquotes, list nesting, tables, and emphasis around key terms. Summary remains plain text; content may keep raw Markdown when that is the clearest faithful Section text. If the CLI later reports URL, example, section-kind, or summary-style issues as advisory/debt, do not patch solely for those unless the cited source meaning is materially lost.
+- Do not synthesize a user-facing prefix by concatenating `heading_path` values (for example, `Parent - Child:`) when that prefix is not in the cited raw. Use headings only to choose grouping and framing; if a heading's wording is itself useful, keep it as sourced content only when it appears in the cited block text.
 - Preserve literals surfaced by the CLI when they are part of the user-facing knowledge. When source-refs or scaffold output lists `required_preserved_literals[]`, keep source-backed URL, code identifier, `source_ref`, or `block_id` literals visible in the relevant `content`, `summary`, skip reason, or repair challenge when doing so carries meaning. Do not rely on memorized URL rules; let CLI literal fields and citation diagnostics define what matters, and treat URL/style preservation warnings as advisory unless the next action is blocking.
 - `refers_to_nodes[]` only carries slugs present in the context's glossary, existing Sections, or the current align plan; never invent one.
 - `skip` is the honest default when raw adds nothing. Bare `skip` (no evidence) is only for deterministic no-ops such as unchanged input, pure navigation, or context-only/background snippets. When a citation-eligible snippet was reviewed and intentionally not written, emit `skip` with `source_block_ids[]` from `source-refs-index` `items[].block_id` or `citable_source_refs[].block_id` so semantic review can record `reviewed_no_write`. Never attach `context_only` / supporting block ids to skip; raise a challenge if they should become citation evidence.
@@ -96,16 +97,16 @@ Confidence is optional. Omit it for ordinary confirmed claims; set it only when
 `description` is the kind for narrative claims that do not match any other form. Before locking in `kind: description` for a snippet, run three classification checks against the cited block:
 
 1. **Atomicity**: single narrative, or multi-step / multi-row / multi-config? Multi → split into the right kinds — each step into its own `spec` / `warning`, each row into a `comparison` Section, each config block into `example` (sample) or `spec` (constraint with a check method).
-2. **Kind-precision**: does a higher-priority kind fit better? A code / config / command block belongs in `example`; a comparison table belongs in `comparison`; a Q+A pair belongs in `faq`; a real incident with timeline belongs in `incident`; a versioned change record belongs in `changelog`; a multi-option choice (≥ 2 surfaced candidates + rationale) belongs in `decision`; a verifiable rule with a check method belongs in `spec`; explicit risks belong in `warning`; a stable design rule or core mechanism without surfaced alternatives or check method belongs in `principle`.
+2. **Kind-precision**: does a higher-priority kind fit better? A code / config / command block belongs in `example`; a comparison table belongs in `comparison`; a Q+A pair belongs in `faq`; a real incident with timeline belongs in `incident`; a versioned change record belongs in `changelog`; an explicit source-backed choice / tradeoff / adopted path with rationale belongs in `decision` even when only one chosen option is surfaced; a verifiable rule with a check method belongs in `spec`; explicit risks belong in `warning`; a stable design rule or core mechanism without a recorded choice or check method belongs in `principle`.
 3. **Action threshold**: multi-step fragments that clear the Action bar → emit `op: skip` with a note "evidence warrants sub-Action; re-align needed"; do not create Nodes from this skill.
 
 A Node whose raw is genuinely narrative — definitions, summaries, plain prose without enumerations or normative wording — legitimately ends with description-dominant output. The smell fires the other way: when raw contained enumerations, normative rules, or code blocks, and the draft collapsed them to `description`. Redraft from Step 2 in that case, not from a percentage threshold. Navigation-only evidence is handled separately by the TL;DR navigation rule and Step 2 — the gates above are not the right place to second-guess that path.
 
 ## Glossary and `refers_to_nodes`
 
-When raw mentions a name that overlaps the workspace glossary, put that name's slug in `refers_to_nodes[]` for the Section that discusses it — do NOT substitute it into the prose. This preserves explicit cross-Node references for query answers and citations without rewriting the claim. Slugs come from existing Sections, the context glossary, or Nodes already declared by the current align plan; never invent one. A Section can reference multiple Nodes (common on `comparison` / `decision`).
+When a Section meaningfully discusses another known Node, or should be discoverable through that Node in query/navigation, put that known slug in `refers_to_nodes[]` — do NOT substitute it into the prose. This preserves explicit cross-Node anchors for query answers and citations without rewriting the claim. Slugs come from existing Sections, the context glossary, or Nodes already declared by the current align plan; never invent one. A Section can reference multiple Nodes (common on `comparison` / `decision`). Do not add a slug for incidental product-name mentions that add no Section-local relationship or navigation value.
 
-If the CLI returns `compile-missing-refers-to-node`, treat it as advisory: add the suggested slug only when the Section actually depends on that Node; otherwise leave the draft unchanged and rely on the cited `source_ref`.
+If the CLI returns `compile-missing-refers-to-node`, treat it as optional info: add the suggested slug only when it improves navigation/query recall or represents a meaningful Section-local relationship; otherwise leave the draft unchanged and rely on the cited `source_ref`.
 
 If the CLI returns source-ref narrowing, candidate hard-fact, summary quality, or low-coverage advisories with `agent_recommended_action: ignore`, do not patch solely to satisfy the advisory and do not inspect every folded detail row by default. Patch only when the cited source actually loses meaning, a confirmed hard fact is unsupported, the user asks for cleanup, or the returned `next_action` asks for a draft patch.