@c4a/context-cli 0.5.35-beta.1 → 0.5.35-beta.3

package/plugin/commands/status.md

@@ -4,7 +4,7 @@ argument-hint: ""
 allowed-tools: Bash(context:*)
 ---
 
-## Your task
+## Your Task
 
 Run `context status` from the active workspace root only. `status` is intentionally local-only and does not walk up from child directories. If the CLI reports `workspace-not-found`, relay that error and ask the user to rerun from the workspace root or initialize with `/context:init`; do not probe storage paths to discover a workspace.
 

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

@@ -1,5 +1,5 @@
 ---
-name: context-align-workflow
+name: skill-align-workflow
 description: "Internal procedure for /context:align. Read align workflow schemas, operate candidate ledger payloads, and produce an align-structure-decision for CLI finalize."
 ---
 
@@ -7,20 +7,21 @@ description: "Internal procedure for /context:align. Read align workflow schemas
 
 ## TL;DR
 
-Run the align workflow through the CLI-owned beta.8 payload chain: scan segments, prepare neutral candidate operations, finalize an `align-structure-decision`, and let the CLI write finalized ownership.
+Run `context align --scan --format json`, inspect the needed evidence, and follow `align_route.next_command`. Direct routes skip coarse-read/candidate-ops and finalize immediately; only `batched_review_required` routes use the coarse-read and candidate ledger path.
 
 <reference>
 
 ## Canonical Data
 
 - Schema names are exposed by `context schema <name>`.
+- `align_route` is authoritative. It defines whether this scan is direct-finalize or batched-review, and the CLI rejects route-incompatible submissions.
 - Candidate ledger and aggregate payloads are mechanical inputs only.
 - Finalized structure is represented by `align-structure-decision`.
 - Retired payloads include candidate tables, decision patches, and full-tree finalize documents.
 - Existing knowledge is the lookup registry. Use `context mdrive glossary match <name>` / `context mdrive node list --format json` for term/entity reuse; do not read `knowledge/**` and do not create a separate registry file.
 - Code projection Nodes are existing knowledge handles. When document evidence belongs on a code symbol, reuse the code slug instead of creating a parallel document Node. If the slug exists only as projected code knowledge and is not yet in finalized prose ownership, declare that same slug in the current `nodes[]`, add the prose `planned_sections`, and route `sections[].owner` plus `block_ownership[].owners` to it.
 - Keep cache-friendly prompt order: fixed protocol and schemas first, existing knowledge lookup second, source-shared payload views third, current candidate batch last. Preserve CLI JSON order and do not add timestamps, random ids, scratch paths, or host paths to generated payloads.
-- `align-segments.generation_policy` is the workspace language contract for generated Node titles, summaries, rationale prose, and planned Section wording. Source-bound Section wording should stay close to the cited source language when it differs from the workspace language. Preserve product names, code identifiers, slugs, flags, `block_id` handles, and `source_ref` tokens exactly when needed.
+- `align-segments.generation_policy` is the workspace language contract for generated Node titles, Node summaries, rationale prose, and planned Section wording. Source-bound Section wording should stay close to the cited source language when it differs from the workspace language. Section summaries may later follow either workspace language or source-bound content language. Preserve product names, code identifiers, slugs, flags, `block_id` handles, and `source_ref` tokens exactly when needed.
 - Source titles and headings are ordinary evidence, not structural authority. Do not automatically copy them into Node titles or aliases; classify the evidence referent first, then generate a title that fits the final Node type.
 - Node type, tag, fake-Entity, `domain`, and `action` gates are in `references/gates.md`.
 - Coarse-read density and neutral signal rules are in `references/density-profile.md`.
@@ -32,21 +33,49 @@ Run the align workflow through the CLI-owned beta.8 payload chain: scan segments
 
 Use this only inside `/context:align`.
 
-1. Start from `align-segments`.
-2. Inspect it through semantic CLI views, not shell parsing: `context workflow show --payload align-segments --view segment --unwrap --format json`, `context workflow show --payload align-segments --view source-mapping --unwrap --format json`, `context workflow show --payload align-segments --view blocks --token-budget 2000 --unwrap --format json`, and `context workflow show --payload align-segments --view windows --unwrap --format json`. Read and obey `generation_policy` before authoring any title, summary, rationale, or planned Section wording. Use `source-mapping` for source-to-block id ranges before writing coarse-read `evidence_blocks`; drill into content with `--source <source-id>`, `--heading <prefix>`, `--window <window-id|src-N:M>` (`src-N:M` means the M-th window under `source_alias` src-N from `--view windows`), or a larger `--token-budget <n>`. If a budgeted view returns `truncated: true`, follow `how_to_explore[]` commands before expanding the budget. `--unwrap` only removes the workflow metadata envelope; it does not change the selected view.
-3. Query existing knowledge for reusable names before proposing new term/service/system/action Nodes. `context mdrive glossary match <name>` returns deterministic `match.kind`, `match.matched`, and `match.rank`; exact title/slug/alias hits should usually become references to the existing Node, not duplicate candidates.
-4. Produce coarse-read anchors and neutral content signals as JSON. Pick `density_profile` using `references/density-profile.md`; content signals describe text shape only, not final Node type. Submit the artifact through stdin with `context align --coarse-read - --format json`. Prefer omitting `schema_version`; the CLI infers single-source vs batch from shape. The latest `align-coarse-read` payload is only the most recent checkpoint; durable multi-source reading notes live in `align-candidate-ledger.source_readings`. For multiple sources, submit one envelope with `coarse_reads[]`; each entry must use the current coarse-read fields (`source_id`, `density_profile`, `reading_anchors`, `section_proposals`), not retired `reading_notes` / `block_readings`.
-5. Produce candidate ops batches as JSON. Before each batch, refresh the Node classification gates in `references/gates.md`; their TTL is one batch or about ten candidates, whichever comes first. Candidate slugs/titles are provisional: if a source heading says "方案", "架构", "流程", "策略", "演练", or similar scope/process language, do not preserve that wording unless the final Node type really needs it. Use `local:<name>` only inside the current batch; submit each batch through stdin with `context align --ops - --format json`. Prefer omitting `schema_version`; the CLI normalizes candidate ops to the current schema. `--ledger-digest <digest>` is optional; usually omit it and pass it only when you intentionally want stale-batch rejection for a high-assurance retry. The CLI reducer assigns durable candidate ids. For `merge_into`, `supersede`, and `reject`, include the required `*_label_hint` fields from the visible candidate labels.
-6. Read the CLI-written candidate ledger and aggregate with `context workflow show --payload align-candidate-ledger --view ledger --unwrap --format json` and `context workflow show --payload align-candidate-aggregate --view aggregate --unwrap --format json`. To revisit one source's coarse-read notes, add `--source <source-id>` to the ledger view; candidates do not carry source ids, so add `--status` or `--candidate-id` only when you also need candidate rows. Treat aggregate fields as mechanical statistics and warnings, not semantic recommendations. Review `anomaly_signals[]`; address clear mistakes with another ops batch, otherwise continue. These signals are warnings and do not by themselves block finalizing.
-7. If the CLI returns `agent_hints[]`, follow them before retrying. Legacy-protocol hints mean the submitted payload/schema is retired; switch to the beta.8 schema named in the hint instead of reshaping old fields.
-8. Before producing `align-structure-decision`, refresh and apply `references/gates.md`: classify Node type in order (`action` scale + process evidence, then concrete/term `entity`, then child-bearing `domain`), reject fake Entities only when at least two suspicious signals match, keep `term` separate from concrete A/B tags, and provide required `action_gate` / `domain_gate` fields. Classification is about the content referent, not the source title. After type is chosen, rewrite the Node title to fit that type: Entities name concrete objects or atomic terms, Domains name grouping scopes, and Actions name executable processes.
-9. Produce `align-structure-decision` as JSON with finalized nodes, `contains_parent`, `depends_on`, and one `block_ownership[]` entry per coverable block. Node titles and summaries must follow the latest `generation_policy` language; do not default to English scaffolding such as "How-To", "Strategy", or "Architecture" when the workspace language is not English. Do not automatically add the original source title as an alias. Submit it through stdin with `context align --finalize -`; the CLI resolves the current align-segments payload. Prefer stable `llm_slug_hint` values for `contains_parent_ref`, `from_ref`, `to_ref`, owners, and section owners while the final slug is still being normalized.
+### Step 1 — Start From Align Scan
+
+Start with `context align --scan --format json`. Read `align_route.mode`, `align_route.next_command`, and `align_route.reasons` before choosing any write path.
+
+### Step 2 — Inspect Views
+
+Inspect it through semantic CLI views, not shell parsing: `context workflow show --payload align-segments --view segment --unwrap --format json`, `context workflow show --payload align-segments --view source-mapping --unwrap --format json`, `context workflow show --payload align-segments --view blocks --token-budget 8000 --unwrap --format json`, and `context workflow show --payload align-segments --view windows --page-size 10 --compact-hints --unwrap --format json`. Read and obey `generation_policy` before authoring any title, summary, rationale, or planned Section wording. Default `source-mapping` is a compact per-source index; add `--source <source-id>` only when you need that source's block id map. `blocks` is the text-bearing view: budgeted rows include full block `text` plus `text_preview`, so do not call another full-text path just to read selected align blocks. Use `window_read_plan`, `windows[].read_strategy`, `windows[].content_size`, `windows[].selector`, and `windows[].batch_selector` to skip low-signal windows, use inline tiny windows, batch neighboring small windows, or drill only selected large windows. Drill into content with `--source <source-id>`, `--heading <prefix>`, `--window <window-id|src-N:M[,selector...]>` (`src-N:M` means the M-th window under `source_alias` src-N from `--view windows`; comma-separated selectors fetch several windows in one call), or a larger `--token-budget <n>`. Prefer one focused read around 15K-30K chars / 4K-8K tokens; treat 50K chars / 12K tokens as the upper band for a single focused read. Rerun the windows view without `--compact-hints` only when exact per-row commands are needed. `--unwrap` only removes the workflow metadata envelope; it does not change the selected view.
+
+### Step 3 — Reuse Existing Knowledge
+
+Query existing knowledge for reusable names before proposing new term/service/system/action Nodes. `context mdrive glossary match <name>` returns deterministic `match.kind`, `match.matched`, and `match.rank`; exact title/slug/alias hits should usually become references to the existing Node, not duplicate candidates.
+
+### Step 4 — Default Path: Direct Finalize
+
+When `align_route.next_command` points to `context align --finalize -`, do not run coarse-read, candidate ops, ledger, or aggregate. Inspect the evidence you need, produce one `align-structure-decision`, and submit it to the returned finalize command. Do not infer route thresholds from source count, token count, or window size; the CLI already made that decision.
+
+Before producing `align-structure-decision`, refresh and apply `references/gates.md`: classify Node type in order (`action` scale + process evidence, then concrete/term `entity`, then child-bearing `domain`), reject fake Entities only when at least two suspicious signals match, keep `term` separate from concrete A/B tags, and provide required `action_gate` / `domain_gate` fields. Classification is about the content referent, not the source title. After type is chosen, rewrite the Node title to fit that type: Entities name concrete objects or atomic terms, Domains name grouping scopes, and Actions name executable processes.
+
+### Step 5 — Staged Path: Batched Review
+
+Use this path only when `align_route.next_command` points to `context align --coarse-read -` or the CLI explicitly returns a batched-review hint. This path is for large or ambiguous scans where the CLI requires a checkpoint before final structure.
+
+Submit coarse-read anchors and neutral content signals with `context align --coarse-read - --format json`. Pick `density_profile` using `references/density-profile.md`; content signals describe text shape only, not final Node type. Prefer omitting `schema_version`; the CLI infers single-source vs batch from shape. The latest `align-coarse-read` payload is only the most recent checkpoint; durable multi-source reading notes live in `align-candidate-ledger.source_readings`. For multiple sources, submit one envelope with `coarse_reads[]`; each entry must use the current coarse-read fields (`source_id`, `density_profile`, `reading_anchors`, `section_proposals`), not retired `reading_notes` / `block_readings`.
+
+After coarse-read is stored, submit candidate ops with `context align --ops - --format json`. Before each batch, refresh the Node classification gates in `references/gates.md`; their TTL is one batch or about ten candidates, whichever comes first. Candidate slugs/titles are provisional: if a source heading says "方案", "架构", "流程", "策略", "演练", or similar scope/process language, do not preserve that wording unless the final Node type really needs it. Use `local:<name>` only inside the current batch. Prefer omitting `schema_version`; the CLI normalizes candidate ops to the current schema. `--ledger-digest <digest>` is optional; usually omit it and pass it only when you intentionally want stale-batch rejection for a high-assurance retry. The CLI reducer assigns durable candidate ids. For `merge_into`, `supersede`, and `reject`, include the required `*_label_hint` fields from the visible candidate labels.
+
+Then read the candidate state with `context workflow show --payload align-candidate-ledger --view ledger --unwrap --format json` and `context workflow show --payload align-candidate-aggregate --view aggregate --unwrap --format json`. To revisit one source's coarse-read notes, add `--source <source-id>` to the ledger view; candidates do not carry source ids, so add `--status` or `--candidate-id` only when you also need candidate rows. Treat aggregate fields as mechanical statistics and warnings, not semantic recommendations. Review `anomaly_signals[]`; address clear mistakes with another ops batch, otherwise continue to finalize. These signals are warnings and do not by themselves block finalizing.
+
+### Step 6 — Follow Hints
+
+At any point, if the CLI returns `agent_hints[]`, follow the provided `command` / `next_action` before retrying. Legacy-protocol hints mean the submitted payload/schema is retired; switch to the named current schema instead of reshaping old fields.
+
+### Step 7 — Finalize Structure
+
+Produce `align-structure-decision` as JSON with finalized nodes, `contains_parent`, `depends_on`, and one `block_ownership[]` entry per coverable block. Node titles and summaries must follow the latest `generation_policy` language; do not default to English scaffolding such as "How-To", "Strategy", or "Architecture" when the workspace language is not English. Do not automatically add the original source title as an alias. Submit it through stdin with `context align --finalize -`; the CLI resolves the current align-segments payload. Prefer stable `llm_slug_hint` values for `contains_parent_ref`, `from_ref`, `to_ref`, owners, and section owners while the final slug is still being normalized.
 
    If `align-segments.incremental.mode` is `incremental`, finalize is a delta merge. Submit only the Nodes and ownership supported by the current scanned sources; reference previous finalized Nodes when they are parents, dependencies, domain children, owners, or visibility targets. Absence of an old Node or edge is not a delete signal. Do not redeclare an old parent/domain just to attach a new child. `sections[].owner` must be a Node declared in the current payload; previous finalized Nodes can be referenced structurally but do not receive new section plans from this incremental payload. Existing or previously removed Node slugs cannot change `node_type`; `context align --scan --full` does not bypass that guard. Use a new slug for a different type, or retire the old slug through `context drop` or explicit structure correction before re-aligning.
 
    For code-projection Nodes, "existing knowledge file" and "previous finalized prose ownership" are different states. A freshly projected code Node can be reused by declaring the same slug in the current finalize payload and planning only prose-owned Sections for the current evidence. Compile merges the prose source and Sections into the existing code Node while preserving code metadata and code-owned Sections. Prose Sections must cite document evidence, not `aspect:code:*` source refs.
 
-   `nodes[].planned_sections` is the distinct set of Section kinds planned for that Node. List each kind at most once; do not copy `sections[].section_kind` one-for-one when a Node has multiple Sections of the same kind.
+   `nodes[].planned_sections` is the distinct set of Section kinds used as compile scaffolding for that Node, not a hard completion gate. List each kind at most once; do not copy `sections[].section_kind` one-for-one when a Node has multiple Sections of the same kind.
+
+   Each `sections[].block_ids` entry must be one contiguous run of citation-eligible blocks from one source. If one conceptual Section spans gaps, split it into multiple `sections[]` plans or include the intervening citation-eligible blocks. The CLI rejects non-contiguous plans at finalize so compile does not have to rediscover the split later.
 
    For large finalize decisions, use `block_ownership_defaults[]` instead of enumerating every block. Each default names a `source_id` plus the same ownership fields as a block-level entry except `block_id`; the CLI expands it across that source's coverable blocks. Put only exceptions in `block_ownership[]`, which override defaults for their `block_id`. Keep the payload on stdin; do not generate temp JSON files just to list hundreds of ownership rows.
 
@@ -73,7 +102,7 @@ Use this only inside `/context:align`.
    }
    ```
 
-   Submit it with `context align --finalize-patch - --format json`. Add `--payload-digest` only when you intentionally want an explicit stale guard. If issues remain, patch the remaining issue paths; if validation passes, the CLI commits the finalized workflow artifacts.
+   Submit it with `context align patch draft --input - --format json`. Add `--payload-digest` only when you intentionally want an explicit stale guard. If issues remain, patch the remaining issue paths; if validation passes, the CLI commits the finalized workflow artifacts.
 
    After finalize has succeeded, do not resend the full structure just to correct a few block roles. Submit a narrow ownership patch against the current finalized ownership digest:
 
@@ -93,7 +122,7 @@ Use this only inside `/context:align`.
    }
    ```
 
-   Submit it with `context align --ownership-patch - --format json`. Keep `base_digest` in the patch body when you want stale ownership rejection. Use `context schema align-ownership-patch` when uncertain.
+   Submit it with `context align patch ownership --input - --format json`. Keep `base_digest` in the patch body when you want stale ownership rejection. Use `context schema align-ownership-patch` when uncertain.
 
 Never write raw, cache, knowledge, `/tmp`, or workspace scratch files. Never pipe `context ... --format json` through `jq`, `head`, `tail`, `sed`, `cat`, `2>&1`, Python, Node.js, or shell scripts. Never read host persisted output files such as Claude `tool-results/**`; rerun a narrower `context workflow show` command instead. Never submit old candidate-table, decision-patch, or full-tree payloads.
 

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

@@ -2,7 +2,7 @@
 name: skill-compile-close
 description: >
   Packaged skill invoked by `/context:compile`; not a user slash command. Runs after every draft
-  iteration. Triggers `context compile --close`, which in one invocation
+  iteration. Triggers `context compile close`, which in one invocation
   refreshes locator-only evidence, canonicalizes source refs, compacts and verifies the final workspace,
   rebuilds the knowledge index, appends a changelog
   entry, rebuilds section fingerprints + incremental cache, and
@@ -25,18 +25,18 @@ command. It does not hand-edit rendered knowledge.
 
 ## TL;DR — Non-negotiables
 
-- CLI-driven. `context compile --close` performs deterministic close writes first (locator refresh, source_ref canonicalization, compact, index/changelog), verifies the final workspace, then rebuilds section fingerprints + incremental cache and archives compile scratch files. Use the command's stdout + exit code; that's the close's full output.
+- CLI-driven. `context compile close` performs deterministic close writes first (locator refresh, source_ref canonicalization, compact, index/changelog), verifies the final workspace, then rebuilds section fingerprints + incremental cache and archives compile scratch files. Use the command's stdout + exit code; that's the close's full output.
 - **Agent NEVER edits rendered knowledge from the close stage.** The CLI is the sole writer for articles, the index, and the changelog. If verify reports an error here, route it back, not around:
   - Content / Section issues (`invalid-section-mount`, `body-ad-hoc-heading`, `dangling-source-alias`) → user re-runs `/context:compile` (draft loop fixes its own Section actions; the close stage does not patch)
   - Structural issues (`contains-cycle`, `edge-dangling-node`, `duplicate-slug`, `invalid-node-type`, `domain-same-file-child`) → user runs `/context:align` to revise the plan
   - Source issues (`dropped-source-reference`) → user runs `/context:drop <id>` to complete the drop
 - Exit 0 → summarise node/section totals, verify, `recompiled`, `locator_updates`, `rebuilt`, fingerprint rebuild count, archive status / archived file count, and any `ready_with_debt` coverage warnings when printed; then stop.
 - Exit 2 → report the full issue list verbatim + point at the right re-entry command above. Do not hand-open the affected rendered article.
-- Coverage warning choice: `ready_with_debt` means close succeeded and unresolved coverage remains visible. First inspect `context workflow show --payload coverage-candidates --view coverage-summary --token-budget 2000 --unwrap --format json`; use each group's neutral `available_actions[]` and narrow with `--view coverage --type <issue-type>` or `--node <slug>` when needed. You may either continue with the warning recorded, or run an uncovered-only repair/skip round. If all unresolved candidates are intentionally excluded for the same reason, use `context compile --coverage-skip-unresolved --coverage-disposition-node <slug> --reason "<reason>"`; otherwise inspect `context schema coverage-disposition`.
+- Coverage warning choice: `ready_with_debt` means close succeeded and unresolved coverage remains visible. First inspect `context workflow show --payload coverage-candidates --view coverage-summary --token-budget 2000 --unwrap --format json`; use each group's neutral `available_actions[]` and narrow with `--view coverage --type <issue-type>` or `--node <slug>` when needed. You may either continue with the warning recorded, or run an uncovered-only repair/skip round. If all unresolved candidates are intentionally excluded for the same reason, use `context compile coverage <slug> --skip-unresolved --reason "<reason>"`; otherwise inspect `context schema coverage-disposition`.
 - Materialized knowledge means either a CLI-written knowledge article, or an explicit no-write placeholder from align: `planned_sections: []` plus source/context/graph support. A compile skip action records reviewed evidence, but it does not by itself materialize an arbitrary finalized Node.
-- Never re-run `context compile --draft` from close to paper over verify failures. Draft failures belong in the draft loop.
+- Never re-run `context compile draft` from close to paper over verify failures. Draft failures belong in the draft loop.
 - Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `WORKSPACE_DIR`, `.context`, knowledge files, or `/tmp` workflow artifacts.
-- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `compile --close` before the append, locator-only source moves are refreshed, non-canonical but hash-valid `source_ref` locators are canonicalized, and high-signal coverage candidates already backed by active Sections are marked covered. No pre-check needed.
+- Derivable files self-heal: missing `_index.md` or `changelog.md` is rebuilt inside `context compile close` before the append, locator-only source moves are refreshed, non-canonical but hash-valid `source_ref` locators are canonicalized, and high-signal coverage candidates already backed by active Sections are marked covered. No pre-check needed.
 - LLM-assisted repair (`--fix-with-llm`) is not available in the current release.
 - Output language: summary prose matches the user's language; CLI output, issue codes, file paths stay as printed.
 - Successful close archives CLI scratch artifacts through the output lifecycle and rebuilds the user-level incremental cache. Current align state is internal CLI state, not a file protocol. The CLI owns this lifecycle — the agent must not move, delete, or archive workspace output files by hand.
@@ -44,7 +44,7 @@ command. It does not hand-edit rendered knowledge.
 
 <reference>
 
-## Stages inside `context compile --close`
+## Stages inside `context compile close`
 
 Close is one in-process command with one exit code:
 
@@ -63,17 +63,17 @@ Close is one in-process command with one exit code:
 | Outcome | Agent action |
 |---|---|
 | Exit 0, 0 issues | Summarise those counts in the user's language: Nodes touched; Sections added / updated / superseded / deprecated / skipped; `recompiled`; `locator_updates`; `rebuilt`; verify green. Stop. |
-| Exit 0, warnings only | Summarise + list warnings verbatim. For coverage warnings, name both choices: continue with `ready_with_debt`, or run an uncovered-only repair/skip round through `context compile --coverage-skip-unresolved` or `context schema coverage-disposition`. Stop. |
+| Exit 0, warnings only | Summarise + list warnings verbatim. For coverage warnings, name both choices: continue with `ready_with_debt`, or run an uncovered-only repair/skip round through `context compile coverage <slug> --skip-unresolved --reason "<reason>"` or `context schema coverage-disposition`. Stop. |
 | Exit 2, Section / content issue | Surface the full issue list; point the user at re-running `/context:compile` (the draft loop owns Section writes). Do NOT Edit the affected rendered article. |
 | Exit 2, `compile-close-finalized-node-missing-knowledge` | If the missing Node has real citation evidence, point the user at `/context:compile` for that Node. If it is intentionally navigation-only or placeholder-only, point the user at `/context:align` to make it explicit no-write with `planned_sections: []` and context-only/ignored relation or placeholder blocks. |
 | Exit 2, structural issue (cycle, duplicate slug, `invalid-node-type`, `domain-same-file-child`) | Surface the full issue list; point the user at `/context:align` to revise structure. Do not re-run compile. |
 | Exit 2, `dropped-source-reference` | Surface the source-id; point the user at `/context:drop <id>` to complete the drop cleanup. |
 
-The close stage never edits rendered knowledge on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. Use the CLI issue code and hint printed by `context compile --close` for the error→command mapping.
+The close stage never edits rendered knowledge on the agent side. Every verify error routes back to the correct upstream command (compile / align / drop), never sideways into a hand Edit. Use the CLI issue code and hint printed by `context compile close` for the error→command mapping.
 
 ## Changelog entry shape
 
-`context compile --close` appends one markdown list item per run to
+`context compile close` appends one markdown list item per run to
 the changelog with aggregate counts — not a multi-line
 block:
 
@@ -90,7 +90,7 @@ item convention (see the drop skill for the exact shape).
 
 ### Step 1 — Invoke close
 
-Run `context compile --close`. The caller (typically `/context:compile`) may have already invoked it; check for existing output before re-running.
+Run `context compile close`. The caller (typically `/context:compile`) may have already invoked it; check for existing output before re-running.
 
 ### Step 2 — Interpret
 
@@ -120,7 +120,7 @@ Stop. Do not auto-invoke follow-on commands.
 
 ### Step 5 — Self-verify
 
-- [ ] `context compile --close` ran exactly once per close call — if not, **Step 1**.
+- [ ] `context compile close` ran exactly once per close call — if not, **Step 1**.
 - [ ] If exit 2, every error is surfaced to the user with a re-entry command (compile / align / drop); no silent ignores — **Step 3**.
 - [ ] No agent-hand edits to rendered knowledge — if any, revert; the close stage is read-only for knowledge content.
 - [ ] No Read / Glob / Grep / Write was used against `WORKSPACE_DIR`; CLI-owned output archival is allowed.

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

@@ -6,7 +6,7 @@ description: >
   existing Sections if any), classifies every raw fragment into a Section
   kind via the priority chain, writes `content` + optional `summary` + `source_refs[]`,
   and emits a compile draft JSON document. The CLI
-  validates the actions via `context compile --draft <slug> --input - --plan`.
+  validates the actions via `context compile draft <slug> --input -`.
   Activates when `/context:compile` iterates across the confirmed align plan.
 tools:
   - Bash
@@ -19,11 +19,12 @@ Classify raw evidence for one Node into `add` / `skip` (and on refresh: `update`
 ## TL;DR — Non-negotiables
 
 - One Node per invocation — `target_node` MUST equal `node.slug`; no cross-Node writes. Finish the current Node's draft quality checks before the caller moves to another Node's review/apply loop.
-- Agent emits JSON only; no markdown, no direct workspace file writes. The caller passes the JSON to `context compile --draft <slug> --input - --plan --prepare`; the CLI stores workflow payloads. `--save-input` is only for an explicit debug scratch copy.
-- Evidence boundary: treat `raw_snippets[]` as complete. Only `raw_snippet_indexes.citation_eligible` may be cited; `context_only` and secondary-shared snippets are background. `request_full_text` may expose full visible evidence text for inspection, including primary evidence; read returned page text from `request_full_text.pages[].text`. Long blocks are paged, so follow `request_full_text.pages[].next_command` when `has_more` is true; `raw_snippets[].quote` mirrors the same page text beside citation metadata, and it does not change citation eligibility. If a secondary-shared or `context_only` block holds facts that need 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/` to recover a token. Instead: for the digest of any workflow payload use `context workflow show --payload <name> --digest-only --format text` (prints just the digest); for substructure use explicit semantic views such as `context compile --context <slug> --view source-refs --token-budget 2000 --format json`, `context workflow show --payload node-context --view source-refs --token-budget 2000 --unwrap --format json`, or `context workflow show --payload prepare --view issues --unwrap --format json`; follow returned `how_to_explore[]` when the view is truncated. For write commands that take `--payload-digest`, omit the flag entirely and let the CLI auto-resolve the latest payload for the current workflow scope.
+- Agent emits JSON only; no markdown, no direct workspace file writes. The caller passes the JSON to `context compile draft <slug> --input - --prepare`; the CLI stores workflow payloads. `--save-input` is only for an explicit debug scratch copy.
+- Evidence boundary: treat `raw_snippets[]` as complete. Only `raw_snippet_indexes.citation_eligible` may be cited; `context_only` and secondary-shared snippets are background. `request_full_text` may expose full visible evidence text for inspection, but use the narrow text view (`context compile context <slug> --request-full-text <block_id> --view text --format json`) and read `items[].text`; long blocks are paged, so follow `items[].next_command` when present. `request_full_text.pages[].text` and `raw_snippets[].quote` may mirror the same page text in full NodeContext outputs, and it does not change citation eligibility. If a secondary-shared or `context_only` block holds facts that need 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/` to recover a token. Instead: for the digest of any workflow payload use `context workflow show --payload <name> --digest-only --format text` (prints just the digest); for substructure use explicit semantic views such as `context compile context <slug> --view source-refs --token-budget 2000 --format json`, `context workflow show --payload node-context --view source-refs --token-budget 2000 --unwrap --format json`, or `context workflow show --payload prepare --view issues --unwrap --format json`; follow returned `next_command` for paged views and `how_to_explore[]` when the view is truncated. For write commands that take `--payload-digest`, omit the flag entirely and let the CLI auto-resolve the latest payload for the current workflow scope.
 - 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` by the [Section Kind Canon](#section-kind-canon), also exposed as `section_kind_priority` in `context schema compile-draft`. First matching form wins. A `decision` needs at least two surfaced alternatives plus a reason; bare "we use X because Y" is `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_refs[]`, choosing values from `raw_snippets[].source_ref`. Use a single-element array for one citation. Treat each source ref as an opaque citation token; never fabricate, parse, dereference, or cite navigation-only blocks as evidence for a content Section.
 - 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.
@@ -32,7 +33,7 @@ Classify raw evidence for one Node into `add` / `skip` (and on refresh: `update`
 - `skip` is the honest default when raw adds nothing. Bare `skip` (no `source_refs[]`) is only for deterministic no-ops such as unchanged input or pure navigation. When a snippet was reviewed and intentionally not written, emit `skip` with `source_refs[]` from that snippet so semantic review can record `reviewed_no_write`.
 - Any Node may legitimately compile to no Sections when the provided snippets contain only navigation (`Parent` / `Children` / `Related` / `Relations`) or placeholder text that explicitly says no detailed content is available. Emit `skip`; do not turn align summaries, parent/child lists, sibling links, or placeholders into `description` Sections. The align graph and Node metadata preserve structure; active Sections need citation-eligible content.
 - FAQ collections attach to the most specific finalized Node (Entity → Action → Domain fallback); never create a standalone FAQ container.
-- Output language: Node-facing summaries and user-facing draft explanations follow `NodeContext.generation_policy.language` when present; otherwise match the raw material. Draft `content` is source-bound: prefer the cited source language when it differs from the workspace language, and do not translate quoted English facts into Chinese just to satisfy workspace language. Preserve product names, code identifiers, CLI flags, slugs, `block_id` / `source_ref` tokens, and exact quoted evidence as printed. Kind / confidence / identifier fields stay English.
+- Output language: Node-facing summaries and user-facing draft explanations follow `NodeContext.generation_policy.language` when present; otherwise match the raw material. Section `summary` may follow either the workspace language or the source-bound `content` language; do not rewrite it only to switch languages. Draft `content` is source-bound: prefer the cited source language when it differs from the workspace language, and do not translate quoted English facts into Chinese just to satisfy workspace language. Preserve product names, code identifiers, CLI flags, slugs, `block_id` / `source_ref` tokens, and exact quoted evidence as printed. Kind / confidence / identifier fields stay English.
 - Stable output: keep action order aligned with evidence order — that ordering is the only stability concern the CLI cannot enforce. The CLI rejects unknown fields (timestamps, random ids, host/scratch paths) and canonicalises stored payloads; fixed rules and schema come from this skill, so only the current NodeContext should vary between repeated Node draft calls.
 
 ## Edge cases — consult references when:
@@ -54,7 +55,7 @@ Canonical shape: `context schema node-context --format yaml` (or `--format json`
 
 Boundary recap (rules not captured by the schema enums):
 
-- `mentions[]` are raw positions that named this Node; `raw_snippets[]` are the wider context blocks around those positions, or the changed raw blocks selected by `context compile --scan-changes`. These two arrays are the evidence floor — never reach outside them.
+- `mentions[]` are raw positions that named this Node; `raw_snippets[]` are the wider context blocks around those positions, or the changed raw blocks selected by `context compile scan`. These two arrays are the evidence floor — never reach outside them.
 - `node.sources[]` are the only sources that may be cited as `src-N`. `node.context_sources[]` contribute `raw_snippets[]` for comparison or background only and must not be cited unless the CLI has also placed that source in `node.sources[]`.
 - `source_id` is the source registry id (e.g. `local:billing`); `src-N` aliases only appear inside `source_ref` strings — copy `raw_snippets[].source_ref` verbatim into draft `source_refs[]`.
 
@@ -188,6 +189,7 @@ For each classified snippet:
    - `source_support` is a lexical diagnostic, not the final semantic judge. Do not stuff raw text into `content` just to raise matched-term counts.
    - There is no separate default `evidence-echo` warning. Treat "echo" as an anti-pattern: raw copied only to show basis/evidence, while `source_ref` already provides traceability.
    - For `description` / `spec`, a concise summary plus the cited bullet list is acceptable when the bullets are the useful user-facing knowledge. It becomes echo only when the copied text is not meant to be read as active knowledge.
+   - For `example` Sections that cite a code, config, or command fence, keep `content` centered on the cited fenced block. Put framing prose such as "basic configuration example" in `summary`, or cite a separate prose block in a separate action when that prose is itself source-backed knowledge.
 3. If `content` is longer than 200 characters, add `summary`. Summary is LLM-authored reader/query aid: one plain paragraph, no Markdown, about `content.length / 10`, minimum 10 characters, recommended maximum 120. The CLI reports missing, long, short, or formatted summaries as warning hints only; it does not auto-generate them and does not treat them as evidence failures. `source_support` hard-term matching checks `content` (and legacy `detail` when present), not `summary`; keep summaries faithful to `content`, but do not copy raw-only keywords into `summary` for lexical scoring.
 4. If the cited block contains documentation/reference URLs, preserve them in `content`. Link-only blocks are still useful knowledge; use `kind: description` with a concise "相关链接" identity when no more specific kind applies.
 5. Omit `confidence` for ordinary confirmed claims. Assign `confidence` per the [Confidence rubric](#confidence-rubric) only when the evidence is not confirmed.
@@ -198,7 +200,7 @@ Rendered knowledge starts with optional `c4a:summary`, then the active `content`
 
 ### Step 4 — Emit the JSON
 
-Emit one compile draft JSON document for the caller to pass to `context compile --draft <slug> --input - --plan --prepare`. No markdown wrapper, no leading prose, no trailing commentary.
+Emit one compile draft JSON document for the caller to pass to `context compile draft <slug> --input - --prepare`. No markdown wrapper, no leading prose, no trailing commentary.
 
 ### Step 5 — Self-verify
 

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

@@ -16,7 +16,7 @@ decisions only; the CLI reviews, applies, and writes every workspace change.
 
 ## TL;DR — Non-negotiables
 
-- Input is the full compile prepare payload. Compact summaries are only a pointer; if needed, load the full payload with the `workflow_payload.show_command` from `context compile --draft ... --prepare`.
+- Input is the full compile prepare payload. Compact summaries are only a pointer; if needed, load the full payload with the `workflow_payload.show_command` from `context compile draft ... --prepare`.
 - Do not inspect workspace storage directly or run ad-hoc scripts to reconstruct candidates. Use only `items[]`, `evidence[]`, `source_support` diagnostics, `candidates[]`, `previous_decisions[]`, and `judge_handoff`.
 - Output exactly one JSON or YAML document with `schema_version: "compile.judge-decisions.v1"` and `decisions[]`.
 - Keep one decision per prepared `item_id`, preserving prepare order.

package/plugin/skills/skill-context-query/SKILL.md

@@ -127,7 +127,7 @@ the user's wording indicates newly captured material is not yet knowledge.
 
 <procedures>
 
-## Step 1: Classify problem intent
+### Step 1 — Classify Problem Intent
 
 Determine what the user is trying to learn. Choose the appropriate command from the Query Route table above.
 
@@ -155,7 +155,7 @@ Determine what the user is trying to learn. Choose the appropriate command from
   - Action: Run `context query --intent recall --profile <reconcile-*> --query "..."`
   - ❌ Never use for ordinary questions
 
-## Step 2: Execute query & interpret response
+### Step 2 — Execute Query And Interpret Response
 
 Run the command from Step 1. Read the CLI output carefully.
 
@@ -174,7 +174,7 @@ Run the command from Step 1. Read the CLI output carefully.
 - ✓ **`node_view` says `visible: complete` / `visibility.complete=true`** → Do not run `section_search` merely to check completeness; use `section_search` only when you need keyword narrowing or ranking inside the Node
 - ✓ **Entries returned** → Proceed to Step 3
 
-## Step 3: Compose answer from returned structure
+### Step 3 — Compose Answer From Returned Structure
 
 Use only the returned Node/Section structure and content. Do not synthesize beyond what was returned.
 
@@ -206,7 +206,7 @@ To dive deeper into any system, ask me for more details or let me know which Nod
 **Why show structure first?** Even when you know keywords, structure queries reveal the full landscape.
 Agents should explore Nodes first, then use section_search for details within a chosen Node.
 
-## Step 4: Explore further (if user requests)
+### Step 4 — Explore Further When Requested
 
 Once Node scope is clear, user may ask for deeper exploration.
 

package/scripts/build-plugin.ts

@@ -116,7 +116,7 @@ function rewriteClaudeSlashCommandsForCursor(body: string): string {
     .replace(/\/context:([a-z-]+)/g, (_match, slug: string) =>
       slug === "context" ? "/context" : `/context-${slug}`
     )
-    .replace(/^## Your task$/gm, "## Workflow")
+    .replace(/^## Your [Tt]ask$/gm, "## Workflow")
     .replace(/\bPackaged skill invoked by\b/g, "Internal procedure invoked by")
     .replace(/\bnot a user slash command\b/g, "not a user command");
 }
@@ -352,7 +352,7 @@ function stripHtmlComments(markdown: string): string {
 function publicSkillBody(command: CommandSource, publicName: string): string {
   const claudeCommand = claudeCommandForSlug(command.slug);
   const rewrittenBody = rewritePackagedSkillReferences(command.body, publicEntrySkillPath)
-    .replace(/^## Your task$/gm, "## Workflow");
+    .replace(/^## Your [Tt]ask$/gm, "## Workflow");
   return `---\nname: ${publicName}\ndescription: >\n  ${command.description} Equivalent to Claude ${claudeCommand}; use the local \`context\` CLI for workspace writes.\ntools:\n  - Bash\n---\n\n# ${command.title}\n\nPublic C4A Context entry for agents that expose skills instead of Claude slash commands.\n\n- Public entry: \`${publicName}\`\n- Claude equivalent: \`${claudeCommand}\`\n- CLI primitive prefix: \`context ...\`\n- Internal procedures live under \`${INTERNAL_PROCEDURES_DIR}/\`; read each referenced file in full before following that step.\n\n---\n\n${rewrittenBody.trimEnd()}\n`;
 }
 

package/templates/aspects/code/prompt.md

@@ -37,8 +37,11 @@ The bucket contains:
 - The code aspect uses `evidence.mode: none`: it does not generate
   `raw/.evidence` block manifests. Symbols, files, and edges are already
   represented by the bucket JSONL indexes.
-- Formal code DSL query and logical code `source_ref` support are tracked by a
-  later version; this aspect only prepares the raw snapshot contract.
+- `context compile --code` converts package and symbol rows into code-owned
+  Sections with code `source_ref` values such as
+  `src-1#package:<package>@<hash>` and
+  `src-1#symbol:<locator>:<kind>@<hash>`. These refs resolve against the raw
+  code snapshot JSONL indexes, not against prose evidence blocks.
 - Runner raw extraction results are intentionally not written as a separate
   bucket file. Future consumers should read `digests.jsonl` and the flat
   package/symbol/edge projections instead.