@c4a/context-cli 0.5.29-beta.18 → 0.5.29-beta.21

package/plugin/skills/skill-compile-draft/references/notes.md

@@ -0,0 +1,34 @@
+# Note snippets
+
+Consult this reference when **any `raw_snippets[].source_type` is `"note"`**. Note snippets came from `context capture --note` and carry conversation material (revisions, decisions, brainstorms) rather than primary source documents.
+
+## TL;DR
+
+Note snippets are **prioritization hints, not write authority**. `note_intent`, `anchored_to[]`, and `revision_kind` may suggest update / supersede / complement / skip, but they never authorize a write without semantic review.
+
+## How to route a note snippet
+
+When a `raw_snippets[]` entry has `source_type: "note"`:
+
+1. **Compare against the anchor first.** If `anchored_to[]` names this Node or one of its Sections, treat that target as the candidate for `update` / `supersede` / `add` (as a complement) / `skip`. **Do not create a new Node** from the note title here — that is an align-time concern.
+
+2. **Use `note_intent` and `revision_kind` to bias the action**:
+
+   | `note_intent` | typical action |
+   |---|---|
+   | `revision` | `update` or `supersede` against the anchored Section |
+   | `decision` | `add` a `decision` Section when no equivalent exists; otherwise `update` |
+   | `brainstorm` | usually `skip` unless the brainstorm explicitly confirms a fact the Node should record |
+
+   `revision_kind` (`replace` / `clarify` / ...) refines the choice within `revision`.
+
+3. **No-write reviewed-no-write case.** If the note says "don't modify active knowledge yet" or the correct outcome is no-write after review, emit `skip` with `source_refs[]` containing the note's `raw_snippets[].source_ref`. This lets semantic review record `reviewed_no_write` instead of treating the skip as an unreviewed no-op.
+
+4. **Bare skip is not allowed for notes.** A bare `skip` (no `source_refs[]`) is only for deterministic no-op cases such as unchanged input or pure navigation. Notes always carry an anchor and an intent; the skip must cite the note's source_ref.
+
+## Where this lives in the main procedure
+
+- **Step 2 — Classify**: run the note-first comparison **before** the generic kind priority chain. If the note resolves to `update` / `supersede` / `skip` (reviewed), record the action and move on; do not also process the same note through the generic chain.
+- **Step 5 — Self-verify**: every note snippet was either consumed by an anchored action or carried into a `skip` with `source_refs[]`.
+
+Notes never become structure_challenge or pending_ownership_challenge on their own. If a note describes a structural problem (missing Action, wrong parent, etc.), capture the underlying evidence in raw form and emit the challenge from that — see `references/structural-challenges.md`.

package/plugin/skills/skill-compile-draft/references/refresh-and-update.md

@@ -0,0 +1,71 @@
+# Refresh and update
+
+Consult this reference when **any** of the following holds:
+
+- `existing.sections[]` is non-empty (Node already has active knowledge; this is a refresh, not a first compile).
+- `incremental.status` is `unchanged` or `full-context` (non-default incremental signals).
+- `incremental.locator_only_changes[]` is non-empty (locator-only deltas without content changes).
+
+For first compile of a fresh Node with `incremental.status === "changed-only"`, skip this file.
+
+## Incremental status handling
+
+| `incremental.status` | What to do |
+|---|---|
+| `changed-only` (default) | Normal path — main SKILL.md procedure applies as written. |
+| `unchanged` | Emit exactly one `skip` action with a brief reason. Do not iterate snippets. |
+| `full-context` | Draft from the full fallback. **Preserve `unknown_inputs[]` reasons** in any abort/retry explanation so the caller sees why the fallback was needed. |
+
+The CLI may deterministically skip unchanged output or update locator-only evidence before writing. **Do not force rewrites to bypass fingerprint skip** — those skips are part of the protocol, not a problem to route around.
+
+## Locator-only changes
+
+`incremental.locator_only_changes[]` entries always carry `agent_action: "none"` and `handled_by: "compile-close"`. **Do not emit a draft action for those Sections** unless the same Section also appears in `changed_blocks[]` with a real content change.
+
+## Reconciling with `existing.sections[]`
+
+When `existing.sections[]` is non-empty, every `section-N` id you read here is a potential `update` / `supersede` / `deprecate` target. Walk the existing Sections in order and decide:
+
+| Raw evidence vs existing Section | op |
+|---|---|
+| Raw still supports the existing claim unchanged | Emit nothing (or one summarising `skip`) |
+| Raw clarifies or rephrases without changing meaning | `update` — same `section-N` stays active |
+| Raw changes meaning (new spec value, reversed decision) | `supersede` — old flips to `deprecated`; new gets fresh `section-N+k` |
+| Raw removes the supporting evidence | `deprecate` with `reason` |
+
+### `supersede` vs `update` semantics
+
+`supersede` preserves the audit trail so readers see the prior policy — **critical for specs / decisions / principles**. Use `supersede` whenever the new statement *replaces* the old one's content; use `update` only for typo / wording fixes / detail additions that do not change meaning.
+
+`deprecate` is for "old rule removed without replacement". It needs a `reason`.
+
+### `update` / `supersede.new` mechanics
+
+- `update` keeps the same `section-N` id; provide new `content` (optional `summary`, optional new `source_refs[]`) but do not include `kind` unless the kind itself is changing.
+- `supersede.new` is a fresh Section; it needs `kind`, `content`, `source_refs[]`, and may carry `summary`, `refers_to_nodes[]`, and `confidence` per the same rules as `add`.
+- `deprecate` only needs `target_section_id` and `reason`. Do not pass `content` or `source_refs[]`.
+
+## Output schema (refresh ops)
+
+```jsonc
+	{
+	  "actions": [
+	    { "op": "update", "target_section_id": "section-3",
+	      "content": "...",
+	      "refers_to_nodes": null,
+	      "source_refs": ["src-1#api L18-21@c0d4e5f61728"] },
+	    { "op": "supersede", "target_section_id": "section-5",
+	      "reason": "raw published a new retention value",
+	      "new": { "kind": "spec", "content": "...",
+	               "refers_to_nodes": ["..."],
+	               "source_refs": ["src-1#limits L30-34@9d1e2f3a4b5c"] } },
+    { "op": "deprecate", "target_section_id": "section-2", "reason": "..." }
+  ]
+}
+```
+
+## How this slots into the main procedure
+
+- **Step 1 — Sanity-check**: when `existing.sections[]` is non-empty, read every `section-N` id and `status` (active vs deprecated) before classifying snippets. When `incremental.status` is `unchanged`, short-circuit with one `skip`.
+- **Step 2 — Classify**: still walk the kind priority chain for each citation-eligible snippet; the reconciliation table above governs which `op` to emit for snippets that map to an existing Section.
+- **Step 5 — Self-verify**: every `update` / `supersede` / `deprecate` targets a known `section-N` from `existing.sections[]`. If not, return here.

package/plugin/skills/skill-compile-draft/references/structural-challenges.md

@@ -0,0 +1,76 @@
+# Structural and ownership challenges
+
+Consult this reference when the cited evidence **cannot be written as a Section under the current align structure**:
+
+- The evidence describes a coherent process that should be its own `action` Node (not a Section here).
+- The evidence implies a missing `depends_on` edge between Nodes.
+- The evidence belongs under a different parent Node.
+- A finalized shared-block split leaves this Node with only secondary, non-citable evidence.
+- A visible `context_only` or secondary-shared block contains facts that need citation, requiring an ownership upgrade.
+
+In these cases, do **not** force the content into a Section. Emit a challenge action instead; the CLI stores it as a workflow payload and compile-close exposes it as debt until an align resolution handles it.
+
+## When to challenge vs. when to skip
+
+| Situation | Action |
+|---|---|
+| Evidence is a repeatable procedure with steps that clearly warrant a sub-Action | `structure_challenge` with `kind: missing_action_node` |
+| Evidence depends on a Node that the current align graph does not link to this Node | `structure_challenge` with `kind: missing_depends_on_edge` |
+| Evidence belongs under a different parent | `structure_challenge` with `kind: wrong_parent` |
+| A finalized shared block split removed all primary evidence from this Node | `structure_challenge` with `kind: wrong_shared_block_split` |
+| The Node should not exist (its evidence belongs elsewhere) | `structure_challenge` with `kind: extra_action_node` |
+| A `context_only` or secondary-shared block holds facts this Node needs to cite | `pending_ownership_challenge` with `requested_role: "shared"` or `"owned"` |
+
+Supported `structure_challenge.kind` values: `missing_action_node`, `extra_action_node`, `wrong_shared_block_split`, `missing_depends_on_edge`, `wrong_parent`.
+
+`pending_ownership_challenge.requested_role` is `owned` (the Node should be sole author) or `shared` (the Node should join an existing owners list).
+
+## Required fields
+
+```jsonc
+{
+  "op": "structure_challenge",
+  "challenge_id": "ch_0001",
+  "kind": "missing_action_node",
+  "node_slug": "<matches node.slug>",
+  "action_tag": "rollout-runbook",
+  "summary": "The cited evidence is a repeatable procedure.",
+  "source_ref": "src-1#ops L40-55@c0d4e5f61728",
+  "reason": "Align must review structure before compile writes process prose."
+}
+```
+
+```jsonc
+{
+  "op": "structure_challenge",
+  "challenge_id": "ch_0002",
+  "kind": "wrong_shared_block_split",
+  "node_slug": "<matches node.slug>",
+  "unresolved_target": "rollout-runbook",
+  "reason": "The finalized shared block split leaves this Node with only secondary, non-citable evidence."
+}
+```
+
+```jsonc
+{
+  "op": "pending_ownership_challenge",
+  "challenge_id": "och_0001",
+  "node_slug": "<matches node.slug>",
+  "block_id": "2f4b8c1e9a03",
+  "requested_role": "shared",
+  "reason": "A visible context_only or secondary shared block contains facts that need citation."
+}
+```
+
+Different `kind` values demand different sub-fields. The CLI returns `agent_hints[].correct_shape` on shape errors; follow that hint rather than guessing.
+
+## What these are NOT
+
+- **Not a substitute for `skip`** when raw simply has no write-worthy fact for this Node.
+- **Not a Section.** Challenges never appear in active knowledge; they only travel through workflow state.
+- **Not a free upgrade path.** `request_full_text` may expose visible evidence text for inspection, but it does not change citation eligibility. If you need to cite secondary content, emit `pending_ownership_challenge` — do not paraphrase the secondary content into a Section.
+
+## How this slots into the main procedure
+
+- **Step 3 — Build actions**: when evidence implies a missing Action, missing `depends_on`, wrong parent, or needed ownership upgrade, emit the corresponding challenge instead of writing a Section.
+- **Step 5 — Self-verify**: no Section write cites a `context_only` or secondary-shared block; if any did, replace the Section with a `pending_ownership_challenge`.

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

@@ -101,6 +101,6 @@ candidate list is empty, emit `new` with an empty compared list and
 ### Step 4 — Emit Judge Decisions
 
 Return only the `compile.judge-decisions.v1` document. The caller passes it
-directly to `context reconcile review --prepare-digest <digest> --decisions -`.
+directly to `context reconcile review --decisions -`.
 
 </procedures>

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

@@ -1,34 +1,30 @@
 ---
 name: skill-context-query
 description: >
-  Packaged skill invoked by `/context:query`; not a user slash command. The agent uses
-  `context query` hit/miss/select results first, supplements only with scoped
-  query views when needed, and answers with Node slug, Section id,
-  and compact node/section citations plus explicit gaps for unsupported claims.
+  Packaged skill invoked by `/context:query`; not a user slash command. 
+  Uses structure-first strategy: inspect orientation, resolve unknown Nodes with node_lookup,
+  open known Nodes with node_view, then query Section details with section_search. Always
+  cite Node slug and Section id.
   Activates when `/context:query` is invoked or when an agent needs to
   answer a question using local Context workspace knowledge with citations.
 tools:
   - Bash
 ---
 
-# skill-context-query — answer from local knowledge with CLI citations
+# skill-context-query — structure-first knowledge exploration with citations
 
-Answer a user question from the local Context workspace without reading
-workspace files directly. The CLI is the only source of local knowledge.
+Answer user questions by exploring the local Context workspace structure first,
+then retrieving specific content within that structure. The CLI is the only source
+of local knowledge; never read workspace files directly.
 
 ## TL;DR — Non-negotiables
 
-- First evidence-bearing tool call should be the ordinary default query: `context query "$ARGUMENTS"`. One optional `context query --intent orientation` or empty `context query` call may run before it when this conversation has no usable workspace map; orientation is only for choosing a better query/scope and is never evidence for the answer.
-- Do not Read, Glob, Grep, or Write `raw/`, `knowledge/`, `archive/`, `decisions/`, or any workspace file to answer the question.
-- Use only `context query` output as evidence. If the CLI returns `miss` or fails, report that result instead of searching files yourself.
-- Every key conclusion must cite the returned `node` and `section` handles. Default query output intentionally omits source provenance; do not invent or parse source locators.
-- If returned entries do not support a conclusion, mark it as a gap. Do not turn missing local knowledge into a definite answer.
-- If the output asks for a narrower scope or shows multiple candidate slugs, choose one only when the user's wording makes it unambiguous; otherwise ask the user which `slug` to use.
-- If the output reports a broad, blocked, or truncated recall, follow that diagnostic: ask for a narrower Node, term, version, or scope; when entries are returned but truncated, answer from those entries and state the result is not exhaustive.
-- Do not use Python, Node.js, shell scripts, `ls`, `find`, `rg`, `cat`, or similar ad-hoc commands to inspect `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts.
-- If the question names a Node title, alias, or slug, state the actual Node slug used in the answer.
-- When the first query is insufficient, supplement only with scoped query views named in the Supplemental context section or anchors from entry `refers_to_nodes`.
-- Output language follows the user's conversation language. CLI flags, output column names, slugs, and Section ids stay as printed.
+- **Structure first**: When problem is vague, don't do semantic search; inspect `orientation`, use `node_lookup` only to find a slug, and use `node_view` to open a known Node.
+- **CLI only**: Use only `context query` output as evidence. Never Read/Glob/Grep/Write workspace files.
+- **Route by intent**: Classify problem intent (vague / clear Node / relationship / detail) and choose the right command; see Query Route table below.
+- **Orientation is navigation**: `context query --intent orientation` returns a budgeted `[Slug Map]` plus optional `[Summary]` hints for scope choice only; it is not direct answer evidence.
+- **Cite structure**: Every conclusion cites `[node/slug]` or `[node/section]`. If evidence does not support a claim, mark as gap.
+- **Handle diagnostics**: If CLI returns `select`, `miss`, `broad`, `raw-only`, or `truncated`, follow the hint: show user structure to choose from, ask for narrower scope, or suggest workflow.
 
 <reference>
 
@@ -46,25 +42,74 @@ returned row as a small evidence card.
 | `refers_to_nodes` | Optional supplemental anchors when present |
 | `slug` | Candidate handle when the output is asking you to choose a Node |
 | `message` | Miss, broad-query, blocked, or narrowing guidance |
+| `visibility` / `visible:` footer | Completeness signal for `node_view`; when `complete=true` / `visible: complete`, the shown Node Sections are exhaustive and there is no pagination |
 
 Supplemental context can come from:
 
 ```text
-context query --intent node_search --scope <slug>
+context query --intent node_view --scope <slug>
 context query --intent impact_analysis --scope <slug>
-context query --intent node_search --refers-to <slug>
+context query --intent node_view --refers-to <slug>
+context query --intent section_search --scope <slug> --query "<keywords>"
 ```
 
+## Query Route Decision Table
+
+Choose the `context query` command based on problem intent. **Structure queries take priority.**
+
+| Problem intent | Primary command | When to use |
+|---|---|---|
+| **Vague question, no Node named** User asks "what is X" / "what are the X types" | `context query --intent orientation` or `context query --intent node_lookup --query "<keyword>"` | User unsure which Node to focus on; show structure first |
+| **Node explicitly named** User mentions a specific service/system | `context query --intent node_view --scope <slug>` | User wants to open a specific known Node |
+| **Relationship / impact** User asks what depends on X / impact of changing X | `context query --intent impact_analysis --scope <slug>` | User asks about how a Node connects to others |
+| **Detail within known scope** (only after Node chosen) User asks for specific feature/behavior within chosen Node | `context query --intent section_search --scope <slug> --query "<detail>"` | User wants specific detail within an already-chosen Node |
+| **Very specific fact** (fallback, rarely needed) User asks for exact implementation location | `context query "$ARGUMENTS"` | Semantic fallback when structure queries don't suffice |
+| **Archive / reconciliation** User asks "find duplicates" / "check coverage" | `context query --intent recall --profile <reconcile-dedupe\|reconcile-support\|reconcile-refresh> --query "..."` | Only when user explicitly asks for audit/reconciliation |
+
+## Orientation output and budget
+
+`context query --intent orientation` is a navigation surface, not answer evidence.
+
+- JSON output keeps full Node `summary` fields when present.
+- Text output targets about 2000 tokens total. It prints `[Slug Map]` first, then `[Summary]`.
+- `[Slug Map]` uses finalized structure relationships and is for choosing the next `--scope <slug>`. If the workspace is too large, deeper layers are folded first.
+- `[Summary]` is truncated before the map. If output is still over budget, the command prints a continuation note. Drill down with scoped queries; there is no page-token pagination.
+- Use `context query --intent node_view --scope <slug>` for a Node overview, or `context query --intent section_search --scope <slug> --query "<keywords>"` for details inside that Node.
+- Use `context query --intent orientation --tag <tag>` or `context query --intent orientation --domain <slug>` to reduce the map before choosing a scope.
+- When `slug` and `title` are equivalent after normalization (for example `payment-api` and `Payment API`), text output shows only the slug.
+
+## BM25 Search Strategy
+
+When using `section_search`, `recall`, or `node_lookup`, the CLI uses BM25 (keyword-based, not embedding-based) for matching. BM25 requires explicit keyword coverage, so queries must be precise:
+
+- **Mix bilingual keywords**: Include both Chinese and English terms when querying—e.g., `"<chinese-term> <english-equivalent>"`, `"<product-name> <alternate-name>"`
+- **Include synonyms & aliases**: BM25 is keyword-literal, so if your query doesn't match Section content exactly, try related terms
+- **Use specific terminology**: Add version numbers, API names, or domain-specific terms to narrow results
+- **Scope to reduce noise**: Use `--scope <slug>` to focus on a single Node; broad queries may be blocked or produce low-quality matches
+
+Query intents that use BM25:
+- `context query --intent node_lookup --query "<short-keyword>"` — find candidate Nodes from slug, title, summary, aliases, and tags when direct slug/title/alias matching does not resolve the query
+- `context query --intent section_search --scope <slug> --query "<keywords>"` — find Section details using keyword matching within a known Node
+- `context query --intent recall --profile <profile> --query "<keywords>"` — archive audit and reconciliation queries using keyword matching
+
+Do NOT use BM25 strategy for:
+- `context query --intent node_view --scope <slug>` or `--node <slug>` — uses structure, not keywords
+- `context query --intent orientation` — uses structure, not keywords  
+- `context query --intent impact_analysis` — uses structure, not keywords
+
 ## Answer citation shape
 
-Use compact citations next to each key claim:
+Use compact citations keyed to evidence type:
 
 ```text
-<claim> [node / section]
+Node identity/title:        <claim> [slug]
+Section claim:              <claim> [node/section]
+Relationship/edge:          X → Y [relationship_type]
+Multiple sources:           <claim> [node/section, node/section]
 ```
 
 If multiple Sections support the same claim, cite the strongest one or two.
-Avoid citation-only dumps: summarize what the cited Section supports.
+Summarize what each cited Section supports; do not list citations without explanation.
 
 ## Gap shape
 
@@ -82,103 +127,105 @@ the user's wording indicates newly captured material is not yet knowledge.
 
 <procedures>
 
-## Step 1: Query
+## Step 1: Classify problem intent
 
-If `$ARGUMENTS` is empty or whitespace-only, ask the user for a question first;
-do not run the query.
+Determine what the user is trying to learn. Choose the appropriate command from the Query Route table above.
 
-If the current conversation has no useful workspace map and the user's question
-is broad, ambiguous, or asks what can be queried, run one orientation pass before
-the first evidence query:
+**Classification:**
 
-```bash
-context query --intent orientation
-```
+- **Vague problem** — user unsure which Node to focus on
+  - Indicators: asks "what is X", "what are the X types", "how to understand X", or question without Node anchor
+  - Action: Run `context query --intent orientation` to show available Nodes and structure; then pick a Node or ask for narrower scope
+  - **Note**: `node_lookup` resolves unknown Node names; `node_view` opens known Node structure; orientation always works regardless of workspace content
 
-Empty `context query` returns the same orientation map.
+- **Node explicitly named** — user mentions a specific service/system/concept
+  - Indicators: user names a specific Node or system, "tell me about X", "show me X"
+  - Action: Run `context query --intent node_view --scope <slug>` to explore that Node
 
-Orientation returns directly queryable slug/title structure and one query
-template. Use it only to choose a scope or show the user what can be queried.
-Do not answer from orientation output. Do not cite orientation output.
+- **Relationship / impact** — user asks how Nodes relate or what breaks if X changes
+  - Indicators: "what depends on X", "impact of X", "relationship between X and Y"
+  - Action: Run `context query --intent impact_analysis --scope <slug>` to show dependencies/relationships
 
-If the user already asked a concrete question but this conversation has no
-workspace map, you may run `context query --intent orientation` (or empty `context query`) and the first
-ordinary `context query "$ARGUMENTS"` concurrently. Use the evidence
-query for the answer; use orientation only for scoped follow-up if the first
-query is insufficient.
+- **Detail within known scope** — user already chose a Node, now asking for specific detail
+  - Indicators: (comes after Node is selected) user asks "how does X handle [feature]", "what features does X support"
+  - Action: Run `context query --intent section_search --scope <slug> --query "<detail-keywords>"` — use BM25 keywords for precise matching
 
-Run the ordinary query first:
+- **Archive / reconciliation** — user explicitly asks for dedup/audit/coverage
+  - Indicators: "find duplicates", "check source coverage"
+  - Action: Run `context query --intent recall --profile <reconcile-*> --query "..."`
+  - ❌ Never use for ordinary questions
 
-```bash
-context query "$ARGUMENTS"
-```
+## Step 2: Execute query & interpret response
 
-If the user explicitly asks for archive comparison, source cleanup audit, or
-semantic reconciliation candidates, use recall with the matching profile:
+Run the command from Step 1. Read the CLI output carefully.
 
-- duplicate / near duplicate / dedupe → `--profile reconcile-dedupe`
-- support check / source support → `--profile reconcile-support`
-- refresh / stale source comparison → `--profile reconcile-refresh`
+**Route based on response:**
 
-```bash
-context query --intent recall --profile reconcile-dedupe --query "$ARGUMENTS"
-```
+- ❌ **Command fails** → Report error and stop
+- ❌ **`miss`** (no knowledge found) → Report no local knowledge and stop
+- ⚠️ **`select`** (multiple candidate Nodes) → Show candidates to user; ask which Node to focus on
+  - Then: loop back to Step 1 with chosen Node scope
+- ⚠️ **`broad` / `blocked` recall** → Ask user for narrower scope (specific Node, term, version)
+  - Then: loop back to Step 1
+- ⚠️ **`raw-only` / `uncompiled`** → Say "raw source found but not yet in compiled knowledge"
+  - Only suggest `/context:align` + `/context:compile` if user wants it compiled
+- ⚠️ **`truncated`** (entries cut off) → Mark answer as "non-exhaustive"
+  - Proceed to Step 3; ask for narrowing only if user needs complete inventory
+- ✓ **`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
 
-Do not use recall archive profiles for ordinary questions.
+## Step 3: Compose answer from returned structure
 
-## Step 2: Read and gate
+Use only the returned Node/Section structure and content. Do not synthesize beyond what was returned.
 
-Read the command output before answering.
+**Response structure:**
 
-- If the command fails, report the CLI failure and stop.
-- If the output says `miss` or no local knowledge matched, report no local knowledge hit and stop.
-- If the output shows candidate slugs instead of evidence rows, ask for a specific `slug`, unless the user's wording already identifies one candidate.
-- If the output reports broad or blocked recall, stop and ask for a narrower Node, term, version, or scope before treating missing candidates as evidence of absence.
-- If the output reports truncated recall, answer from the returned evidence when entries exist, mark coverage as non-exhaustive, and ask for narrowing only if the user needs a complete inventory.
-- Keep a working set of returned rows with `node`, `section`, `kind`, `content`, and non-empty `refers_to_nodes`.
+1. **Start with core answer** — what the structure directly shows
+2. **Cite every claim** — `[node/slug]` for Node identity, `[node/section]` for facts
+3. **Include "Used nodes:" line** — if question named specific Nodes: "Using nodes: `<slug>`, `<slug>`"
+4. **Mark gaps** — if user asked for something not in returned structure: "Gap: no evidence for X"
+5. **Note truncation** — if CLI said `truncated`: "Non-exhaustive result — further narrowing available"
 
-## Step 3: Anchor explicit Node mentions
+**Example for structure-first query:**
+```
+User asks: "What systems handle X in our architecture?"
 
-If the user's question contains a likely Node title, alias, slug, code symbol,
-or version:
+Better query (structure-first): 
+  context query --intent orientation  # Shows all available Nodes
 
-1. Prefer exact slug, title, or alias matches from the query result.
-2. State the actual Node slug used.
-3. If the candidate set points to multiple plausible slugs, say which slugs were used and keep claims scoped to those slugs.
+Returns several candidate Nodes matching the question.
 
-## Step 4: Supplement only when needed
+Response:
+"Systems that handle X:
+- **<Node Title 1>** [<slug-1>] — responsibility and scope
+- **<Node Title 2>** [<slug-2>] — responsibility and scope
 
-Use supplemental commands only when the first query has entries but lacks
-enough surrounding structure to answer the question.
+To dive deeper into any system, ask me for more details or let me know which Node you want to explore."
+```
 
-Use supplements per the Supplemental context section, only after the first query
-and only for slugs present in returned entries, entry `refers_to_nodes`, or
-the user's explicit question. Use `refers_to_nodes` as extra anchors only when
-they appear in returned Sections. Do not discover extra anchors by reading
-workspace files.
+**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 5: Compose
+## Step 4: Explore further (if user requests)
 
-Answer only from the query and supplemental outputs.
+Once Node scope is clear, user may ask for deeper exploration.
 
-Required response behavior:
+**Supplemental query triggers:**
 
-1. Start with the direct answer if evidence supports one.
-2. Cite every key conclusion with Node slug and Section id.
-3. Include a short "Used nodes" line when the question was anchored by title, alias, slug, code symbol, or version.
-4. Include "Gap:" lines for requested points that are not supported.
-5. Include a blocked / broad-query note when recall hints require narrowing, or a truncated/non-exhaustive note when returned evidence is only a subset.
+- User asks about Node's relationships/dependencies → `context query --intent impact_analysis --scope <slug>`
+- User asks for full Node content after partial answer → `context query --intent node_view --scope <slug>`
+- User asks specific detail within chosen Node → `context query --intent section_search --scope <slug> --query "<keywords>"` 
+  - **Use BM25 strategy**: mix Chinese and English keywords for better matching (e.g., mix synonym or translated forms of the search term)
+- User names another Node in `refers_to_nodes` and asks about its relationship → `context query --intent node_view --refers-to <slug>`
 
-## Self-check before final answer
+**BM25 tips for supplemental queries:**
+- When searching for a detail, include both native and translated forms of terms
+- If first query is too broad, add more specific keywords or domain terminology instead of generic terms
+- Scope helps narrow BM25 results: `--scope <slug> --query "<specific-term> <synonym>"` is more precise than an unscoped broad query
 
-- [ ] First evidence-bearing tool call was ordinary `context query "$ARGUMENTS"` or an explicit reconcile `--intent recall` query. If an orientation command ran first or concurrently, it was only `context query --intent orientation` or empty `context query`, and an evidence-bearing `context query` command ran before answering — if not, go back to **Step 1**.
-- [ ] No direct file Read / Glob / Grep / Write was used against workspace local knowledge — if not, discard that evidence and go back to **Step 1**.
-- [ ] No ad-hoc script or shell file traversal was used against `WORKSPACE_DIR`, `.context`, or `/tmp` workflow artifacts — if not, discard that evidence and go back to **Step 1**.
-- [ ] Direct answer is given when evidence supports one — if not, go back to **Step 5**.
-- [ ] Every key conclusion has `node / section` — if not, go back to **Step 5**.
-- [ ] If the question carried a Node title / alias / slug / code symbol / version, the answer includes a "Used nodes" line — if not, go back to **Step 3** and **Step 5**.
-- [ ] Any unsupported conclusion is marked as a gap — if not, go back to **Step 5**.
-- [ ] Recall diagnostics are handled: broad/blocked asks for narrowing; truncated with entries answers with a non-exhaustive note — if not, go back to **Step 2** and **Step 5**.
-- [ ] Archive entries appear only for explicit reconcile profiles — if not, go back to **Step 1** with the correct profile.
+**Safety:**
+- ❌ Do NOT auto-fetch all `refers_to_nodes`; only query if user asks
+- ❌ Do NOT read workspace files to discover new Nodes
+- ✓ Only supplement with slugs already in returned structure or user's explicit question
 
 </procedures>

package/plugin/skills/skill-drop/SKILL.md

@@ -77,7 +77,7 @@ details.
 ```
 context drop --plan <source-id|url> --format json
 context reconcile prepare --mode drop --format json
-context reconcile review --prepare-digest <prepare-digest> --decisions - --view status
+context reconcile review --decisions - --view status
 context drop --apply-plan --reason "<text>" --yes
 ```
 
@@ -134,12 +134,11 @@ context reconcile prepare --mode drop --format json
 ```
 
 Invoke the packaged semantic reconcile procedure with that prepare payload. Use
-stdout `workflow_payload.digest` as `<prepare-digest>`.
 Pass the semantic reconcile decision document directly to review, preferably
 through stdin:
 
 ```
-context reconcile review --prepare-digest <prepare-digest> --decisions - --view status
+context reconcile review --decisions - --view status
 ```
 
 The review command persists the ready immutable review artifact for the current