@c4a/context-cli 0.5.29-alpha.1

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@c4a/context-cli",
+  "version": "0.5.29-alpha.1",
+  "type": "module",
+  "bin": {
+    "context": "./cli.js"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "ink": "^5.0.0",
+    "react": "^18.3.1",
+    "yaml": "^2.5.1"
+  },
+  "main": "./cli.js",
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "name": "context",
+  "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into an interlinked wiki with source-traced facts. CLI does mechanical work; agent drives compile/drop via skill protocols.",
+  "version": "0.5.29-alpha.1",
+  "author": {
+    "name": "c4a"
+  },
+  "license": "MIT",
+  "keywords": [
+    "context",
+    "knowledge-base",
+    "wiki",
+    "claude-plugin",
+    "c4a"
+  ]
+}

package/plugin/.claude-plugin/plugin.json.template

@@ -0,0 +1,16 @@
+{
+  "name": "context",
+  "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into an interlinked wiki with source-traced facts. CLI does mechanical work; agent drives compile/drop via skill protocols.",
+  "version": "__VERSION__",
+  "author": {
+    "name": "c4a"
+  },
+  "license": "MIT",
+  "keywords": [
+    "context",
+    "knowledge-base",
+    "wiki",
+    "claude-plugin",
+    "c4a"
+  ]
+}

package/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "context",
+  "version": "0.5.29-alpha.1",
+  "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into source-traced local knowledge, query with citations, and govern source updates.",
+  "author": {
+    "name": "c4a"
+  },
+  "homepage": "https://github.com/context4ai/c4a",
+  "repository": "https://github.com/context4ai/c4a/tree/main/packages/context-cli",
+  "license": "MIT",
+  "keywords": [
+    "context",
+    "knowledge-base",
+    "codex-plugin",
+    "agent-skills",
+    "c4a"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "C4A Context",
+    "shortDescription": "Local knowledge workspace skills for C4A.",
+    "longDescription": "Use the context CLI and bundled skills to capture project sources, align them to a Node tree, compile source-traced local knowledge, query with citations, and govern source drop or refresh workflows.",
+    "developerName": "c4a",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/context4ai/c4a",
+    "defaultPrompt": [
+      "Use C4A Context to answer from local knowledge with citations.",
+      "Use C4A Context to compile newly captured sources into local knowledge."
+    ]
+  }
+}

package/plugin/.codex-plugin/plugin.json.template

@@ -0,0 +1,35 @@
+{
+  "name": "context",
+  "version": "__VERSION__",
+  "description": "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into source-traced local knowledge, query with citations, and govern source updates.",
+  "author": {
+    "name": "c4a"
+  },
+  "homepage": "https://github.com/context4ai/c4a",
+  "repository": "https://github.com/context4ai/c4a/tree/main/packages/context-cli",
+  "license": "MIT",
+  "keywords": [
+    "context",
+    "knowledge-base",
+    "codex-plugin",
+    "agent-skills",
+    "c4a"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "C4A Context",
+    "shortDescription": "Local knowledge workspace skills for C4A.",
+    "longDescription": "Use the context CLI and bundled skills to capture project sources, align them to a Node tree, compile source-traced local knowledge, query with citations, and govern source drop or refresh workflows.",
+    "developerName": "c4a",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/context4ai/c4a",
+    "defaultPrompt": [
+      "Use C4A Context to answer from local knowledge with citations.",
+      "Use C4A Context to compile newly captured sources into local knowledge."
+    ]
+  }
+}

package/plugin/commands/align.md

@@ -0,0 +1,54 @@
+---
+description: "Align raw material into a candidate Node tree: scan → propose → user review → finalize. The CLI renders; the agent classifies."
+argument-hint: ""
+allowed-tools: Read, Bash(context:*)
+---
+
+## Your task
+
+Orchestrate the three-skill align pipeline. Workspace reads go through `context workspace`; workflow writes go through `context align` domain commands. Every rendered markdown artifact under `output/` is rendered by the CLI; your outputs are the structured JSON / YAML each skill consumes.
+
+First run `context workspace locate --format json` and use `ctxDir` from that JSON as `WORKSPACE_DIR`. In embedded layout it is the `.context/` directory; in root layout it is the current knowledge repo root. Use `WORKSPACE_DIR/output/...` below; do not assume `.context/output/...`.
+
+1. Run `context align --scan` to write `WORKSPACE_DIR/output/align.scan.yaml`. This is incremental by default: scan v2 separates `incremental.structure_changed[]` / `incremental.new_sources[]` from `incremental.content_changed_only[]`. Use `context align --scan --full` only when the user explicitly asks to rebuild the whole structure or when you are repairing a corrupted align artifact; it does not clean or reset the incremental cache.
+   - Read the scan with `context workspace read output/align.scan.yaml --format text`. If `incremental.unknown_sources[]` is non-empty, surface the reasons and ask the user whether to continue with a full scan or repair cache/source state first. Do not classify unknown input as unchanged.
+   - If `incremental.structure_changed.length + incremental.new_sources.length` is `0`, stop before align-scan / align-propose / align-finalize. Report `0 structural changes`; if `incremental.content_changed_only[]` is non-empty, tell the user those sources belong to `/context:compile`.
+2. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/SKILL.md` and follow its procedures. Use `context workspace read <path>` for evidence from the scan, then save the decisions with `context align --save-scan-decisions -`.
+3. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-propose/SKILL.md` and follow its procedures. Pass the resulting YAML to `context align --propose - --save-input` so the CLI writes `WORKSPACE_DIR/output/align.propose.md` + `.yaml` and keeps the consumed input as an archived workflow artifact.
+4. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-scan/references/user-question-contract.md`. Show `align.propose.md` to the user from `context workspace read output/align.propose.md --format text`, then gather only the decisions that affect business meaning, retrieval granularity, source validity, or user-visible organization. Use the host's multi-choice tool (Claude Code `AskUserQuestion`, Codex `ask_user_question`, Cursor Plan Mode `AskQuestion`); fall back to markdown A/B choices otherwise.
+   - Before asking, explain in 1-2 short sentences what you found and what the decision will affect.
+   - Ask in the user's language, but do not expose internal model terms such as Node, Section, Concept, Entity, Domain, contains, related_to, source_ref, raw, slug, or mount matrix.
+   - Do not ask implementation-only questions. Apply the safe default and mention it in the summary.
+   - Save the answers with `context align --save-user-decisions -` in the internal shape defined in the align-finalize reference.
+5. Read `${CLAUDE_PLUGIN_ROOT}/skills/align-finalize/SKILL.md` and follow its procedures. Pass the resulting YAML to `context align --finalize - --save-input` so the CLI writes `WORKSPACE_DIR/output/align.md` + `bind.yaml`.
+6. `context align --finalize` archives align intermediates under `WORKSPACE_DIR/output/archive/` and leaves only the current `align.md` + `bind.yaml` at the output root. Do not move, delete, or archive workspace `output/` files yourself; the CLI owns that lifecycle. Run `context doctor`; the output-align group must be green. On failure, fix the structured input and re-run step 5; never patch rendered files by hand.
+
+For large JSON / YAML payloads, use a direct heredoc into the `context` command:
+
+```bash
+context align --save-scan-decisions - <<'JSON'
+{
+  "scan_version": 2,
+  "workspace": "example",
+  "existing_nodes": [],
+  "new_candidates": [],
+  "ambiguous": [],
+  "orphans": [],
+  "decisions": { "notes": "" }
+}
+JSON
+```
+
+Do not pipe a heredoc through another command, and never redirect generated content into workspace files.
+
+Final report contract:
+
+- Report in the user's conversation language.
+- Keep a stable structure with these semantic sections; translate section headings into the user's conversation language instead of copying these English labels verbatim:
+  1. Completion headline.
+  2. A compact table with final Node count by type, deepest `contains` depth, and unmatched mention count.
+  3. If unmatched mention count is non-zero, list the mentions and state whether they are intentional demotions / rejected candidates or unresolved problems according to `context doctor` + `decisions.notes`; do not call intentional demotions a failed align when doctor is green.
+  4. Output files as clickable markdown links. Use absolute path targets without `file://`, for example `[align.md](/abs/path/.context/output/align.md)`. Always include `WORKSPACE_DIR/output/align.md` and `WORKSPACE_DIR/output/bind.yaml`; include the latest align archive directory if you mention archival.
+  5. Next step pointing at `/context:compile` to synthesise knowledge, or another `/context:align` pass to revise structure.
+- Do not expose internal model jargon beyond filenames, command names, and counts already printed by the CLI.
+- Never use Read / Glob / Grep / Write against `WORKSPACE_DIR`; use `context workspace` / `context mdrive` instead.

package/plugin/commands/capture-aspect.md

@@ -0,0 +1,17 @@
+---
+description: "Run a named aspect capture pipeline. Stub in the current CLI — every invocation exits non-zero with 'planned for a future release'."
+argument-hint: "<aspect-name>"
+allowed-tools: Bash(context:*)
+---
+
+## Your task
+
+`capture-aspect` is a placeholder. Every invocation, including `capture-aspect code`, exits non-zero with a deferred-to-a-future-release message; the pluggable aspect pipeline lands later.
+
+Run `context capture-aspect $ARGUMENTS` and relay the CLI's exit code + stderr verbatim. Do NOT route `code` to `/context:capture-code` — the two commands have different semantics, and the stub intentionally blocks this entry point so future aspect kinds land behind one consistent surface.
+
+Users who actually want to snapshot the repo's code structure today should be told to run `/context:capture-code` directly; mention it as a pointer in your reply. Do not auto-invoke it.
+
+Language policy: your explanatory prose follows the user's conversation language. Relay CLI stderr/stdout verbatim; command names, paths, source-ids, and quoted CLI phrases stay as printed.
+
+Never work around the stub by shelling into extraction directly or writing into workspace `raw/aspect/<name>/` by hand — the CLI is the sole writer of `raw/`.

package/plugin/commands/capture-code.md

@@ -0,0 +1,25 @@
+---
+description: "Extract TypeScript code structure (Package / Symbol / Edge) from the current git repository into raw/aspect/code/."
+argument-hint: ""
+allowed-tools: Bash(context:*)
+---
+
+## Your task
+
+Run `context capture-code` from anywhere inside the workspace — the CLI always scans the resolved workspace root, not the current subdirectory, so invoking it from a subfolder like `apps/web/src/` still snapshots the full repo. The CLI:
+
+- Requires the workspace to live inside a git checkout (needs `HEAD` sha).
+- Writes a bucket `raw/aspect/code/<YYYY-MM-DD>-<sha7>/` containing `packages.jsonl`, `symbols.jsonl`, `edges.jsonl`, `_meta.yaml`.
+- Updates `raw/aspect/code/latest` symlink and registers the snapshot in `raw/_sources.yaml` under source-id `aspect:code` (snapshots array entry carries `commit` + `script_hash`). Raw-side audit is kept via `_sources.yaml` snapshots + git history — the standalone `log.md` from earlier CLI generations is no longer maintained.
+- Skips with `unchanged, skipped` when the commit + script hash combination has already been captured.
+- Refuses with an actionable error when extraction finds zero scannable packages (rather than writing an empty bucket that Compile would later mistake for the full repo).
+
+Report whether a new bucket was produced or the run was a skipped idempotent re-run. When a fresh bucket lands, suggest the right next step:
+
+- Run `context workspace locate --format json` and use `ctxDir` as `WORKSPACE_DIR`.
+- `WORKSPACE_DIR/output/align.md` does not exist → suggest `/context:align` (code snapshot becomes align / compile material, but compile requires the structural plan from align first).
+- `WORKSPACE_DIR/output/align.md` exists → suggest `/context:compile`.
+
+Language policy: your explanatory prose follows the user's conversation language. CLI output, paths, source-ids, command names, commit hashes, and status tokens such as `unchanged, skipped` stay as printed.
+
+Do NOT write workspace `raw/aspect/code/` directly — only the CLI mutates that tree.

package/plugin/commands/capture.md

@@ -0,0 +1,67 @@
+---
+description: "Capture a URL / local .md file(s) / stdin path list / inbox / refresh all active remote sources into workspace raw/."
+argument-hint: "[url | ./path.md [./more.md...] | --stdin | --inbox | --refresh]"
+allowed-tools: Bash(context:*, brew:*, curl:*, sh:*, scoop:*, choco:*, lark-cli:*), WebFetch
+---
+
+<!--
+This command has no companion skill. Its protocol (argument routing +
+missing-dependency install flow) lives inline here per the slash-command
+length exemption in packages/context-cli/CLAUDE.md.
+-->
+
+## Your task
+
+Capture is entirely CLI-driven — your role is to route the right `context capture` invocation and relay its output. Never hand-write under workspace `raw/`: the CLI owns normalisation (NFC, BOM strip, line endings) and the `content_hash` contract, so any manual edit breaks idempotency.
+
+### Route by argument
+
+- `$ARGUMENTS` starts with `http://` / `https://` → `context capture $ARGUMENTS` (feishu URLs need `lark-cli`).
+- `$ARGUMENTS` is one or more local `.md` paths → local file batch: `context capture <path...>`.
+- User provides a long newline-separated path list → pass it to `context capture --stdin` with a direct heredoc.
+- `$ARGUMENTS` contains `--inbox` → `context capture --inbox`.
+- `$ARGUMENTS` contains `--refresh` → `context capture --refresh`.
+- User asks for `code` / `--type code` → redirect to `/context:capture-code`.
+
+For stdin batches, use this shape:
+
+```bash
+context capture --stdin <<'EOF'
+docs/a.md
+docs/b.md
+EOF
+```
+
+Do not pipe the heredoc through another command, and do not discover files with `find` / `ls` when the user already supplied the paths.
+
+### Output handling
+
+Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
+
+- Run `context workspace locate --format json` and use `ctxDir` as `WORKSPACE_DIR`.
+- `WORKSPACE_DIR/output/align.md` does not exist (first-time path) → suggest `/context:align` (required before compile).
+- `WORKSPACE_DIR/output/align.md` exists → suggest `/context:compile`. Mention `/context:align` as an option if the user wants to revise the structure.
+
+Never suggest `/context:compile` when no align plan exists — compile refuses to run without one.
+
+### Missing dependency recovery
+
+If the CLI prints a missing-dependency error like `lark-cli not installed`, walk the user through installation:
+
+1. Ask once up-front whether to proceed with install. If no → stop and tell the user to install manually from the tool's official README, then re-run.
+2. `WebFetch` the tool's official README (for `lark-cli` that's `https://github.com/larksuite/cli/blob/main/README.md#quick-start-ai-agent`).
+3. For each command the README prescribes for the user's platform, show the command then call `Bash`. The host's per-tool permission prompt is the user's confirmation surface; don't add extra y/n questions between commands.
+4. Stop on any failure; surface stderr verbatim.
+5. After success, tell the user to re-run their original `/context:*` command themselves.
+
+### Language policy
+
+Your prose to the user follows the user's conversation language. CLI commands, flag names, URLs, env-var names, binary names, source-ids stay English.
+
+### Invariants
+
+- `raw/<type>/*.md` and `raw/aspect/**` are immutable post-write — the CLI only ever appends new snapshots.
+- `raw/_sources.yaml` is the authoritative source registry; `raw/<type>/_index.md` files are derived caches (prefer files-on-disk when they disagree).
+- Local `.md` source identity follows the captured file's stable origin path, not its H1/title. If the user edits the title but captures the same path again, the CLI appends a new snapshot to the same `local:*` source.
+- `raw/aspect/code/latest` is a symlink to the most recent bucket — never hard-code a dated bucket name.
+- On duplicate capture of the same URL: identical `content_hash` → CLI skips with `unchanged`; different hash → CLI appends a new snapshot.

package/plugin/commands/compile.md

@@ -0,0 +1,89 @@
+---
+description: "Compile the confirmed align plan into knowledge articles: draft, semantic reconciliation, apply, then compile-close."
+argument-hint: "[--plan]"
+allowed-tools: Read, Bash(context:*)
+---
+
+<!--
+This command is slightly over the 30-line default because it carries
+the default-mode vs `--plan`-mode mode comparison inline; per the
+multi-mode exemption in packages/context-cli/CLAUDE.md, the mode
+contrast belongs here rather than split across skill references.
+The agent protocol itself still delegates to the compile-draft /
+compile-close skills.
+-->
+
+## Your task
+
+Synthesise the align plan into the workspace `knowledge/` directory. The agent produces `CompileDraftAgentOutput` per Node; the CLI writes everything. Workspace reads go through `context workspace`; workflow writes go through `context compile` / `context mdrive`, never through direct file tools.
+
+Modes:
+
+- **Default (no flag)** — draft plan + semantic reconciliation + apply writes + close.
+- **`--plan`** (opt-in when `$ARGUMENTS` contains `--plan`) — per Node, run `context compile --draft <slug> --input <file> --plan` so the CLI validates without touching `knowledge/`; surface a user-facing change list (new knowledge, replaced knowledge, unchanged knowledge, and why) while keeping internal Section ids / source refs in details only when needed, then **stop at the end of the per-Node loop — do NOT run close**. The user re-runs `/context:compile` without `--plan` to apply; that run does the real writes + close.
+
+Language policy: your explanatory prose and final reports follow the user's conversation language. CLI stdout/stderr, the canonical `processing <slug>` lines, paths, slugs, source refs, issue codes, flags, and command names stay as printed.
+
+Preflight:
+
+1. Run `context workspace locate --format json` and use `ctxDir` from that JSON as `WORKSPACE_DIR`. In embedded layout it is the `.context/` directory; in root layout it is the current knowledge repo root. Use `WORKSPACE_DIR/output/...` and `WORKSPACE_DIR/knowledge/...` below; do not assume `.context/...`.
+2. Require `output/align.md` + `output/bind.yaml`; check them with `context workspace list output --format json`. If missing, tell the user to run `/context:align` and stop.
+3. Run `context doctor`; output-align group must be green. Incremental cache group warnings are informational here; only output-align errors block compile. Run `context mdrive workspace stats --format json` and `context source list --format json` and record the before counts.
+4. Read `output/align.md` with `context workspace read output/align.md --format text`. Record Nodes in the order they appear in `frontmatter.nodes[]` — do NOT re-sort.
+5. Run `context compile --changes --format json` and parse the JSON as `COMPILE_WORKSET`.
+   - If `COMPILE_WORKSET.reason` is `no-changed-nodes`, report `no changed nodes`; stop before reading `compile-draft`, running any draft command, or running close.
+   - If `COMPILE_WORKSET.status` is `unknown-input`, continue conservatively using the Nodes listed in `COMPILE_WORKSET.nodes`; keep the `unknown_inputs[]` reasons in the final report.
+   - Otherwise process only `COMPILE_WORKSET.nodes`, preserving the `frontmatter.nodes[]` order. Per-Node `processing <slug>` echoes must match this order.
+
+Per-Node loop:
+
+1. For every workset Node, run `context compile --context <slug> --changed-only --save-output`. Use the JSON stdout as the NodeContext for the draft skill. When the workset requires full context, the CLI returns `incremental.status: "full-context"` with the `unknown_inputs[]` reasons while still using the changed-only entrypoint. The CLI stores the durable context scratch copy under `output/`. Do not expand the context with direct file tools; the NodeContext is the evidence boundary.
+2. Read `${CLAUDE_PLUGIN_ROOT}/skills/compile-draft/SKILL.md` and follow its procedures; keep the emitted draft JSON/YAML in memory.
+3. Pass the draft to `context compile --draft <slug> --input - --save-input --plan`. This validates schema, source refs, and mount matrix without touching `knowledge/`. On CLI rejection, read the error verbatim, fix the draft via the skill's self-verify, and retry up to 3 times.
+4. Run `context reconcile prepare --mode compile --node <slug> --draft WORKSPACE_DIR/output/compile.<slug>.draft.yaml --format json`. Feed that JSON to `${CLAUDE_PLUGIN_ROOT}/skills/semantic-reconcile/SKILL.md`.
+5. Pass the skill output to `context reconcile review --context <prepare-file-or-stdin> --decisions <decisions-file-or-stdin> --format json`. If questions are returned, ask the user in business language and rewrite unresolved `ask_user` items into final actions before applying.
+6. Default mode only: run `context reconcile apply --input <confirmed-decisions>`. This writes active knowledge, verifies, and records `decisions/semantic.yaml`. In `--plan` mode, stop after review and report the not-written decisions.
+7. Persistent failure → stop and surface the full rejection list; never edit rendered files to bypass.
+
+Close (default mode only — skip entirely in `--plan` mode):
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/skills/compile-close/SKILL.md` and follow its procedures; it triggers `context compile --close`, which verifies the workspace, refreshes locator-only evidence, rebuilds section fingerprints, and refreshes the incremental cache.
+2. Run `context verify` as a second pass if the skill escalated any issue. Run `context mdrive workspace stats --format json` and `context source list --format json` and diff against the before counts.
+3. Run `context mdrive node list --format json` to collect generated knowledge file paths for the final report. Use each item's `filePath` for clickable markdown links. Also include `WORKSPACE_DIR/knowledge/_index.md` and `WORKSPACE_DIR/knowledge/changelog.md`.
+
+`context compile --close` archives `compile.*` scratch files under `WORKSPACE_DIR/output/archive/` and copies the consumed `align.md` + `bind.yaml` into that archive, while keeping the current `align.md` + `bind.yaml` at the output root for future recompile/status. Do not move, delete, or archive workspace `output/` files yourself; the CLI owns that lifecycle.
+
+In plan mode, your final report is the aggregated user-facing change list across all Nodes + "re-run `/context:compile` without `--plan` to apply"; do not run `context compile --close` or `context verify` (they only make sense against a real write).
+
+Never claim success unless `context compile --close` exited 0 and `context verify` is green. The only exception is the `no-changed-nodes` gate, where you report that compile stopped before draft and no files were written. Never hand-write anything under workspace `knowledge/`, `_index.md`, or `changelog.md` — the CLI is the sole writer.
+Never use Read / Glob / Grep / Write against `WORKSPACE_DIR`; use `context workspace`, `context compile`, and `context mdrive`.
+For large draft payloads, feed stdin directly into the `context compile` command with a heredoc. Do not pipe a heredoc through another command and do not redirect generated content into workspace files:
+
+```bash
+context compile --draft billing-api --input - --save-input <<'JSON'
+{
+  "target_node": "billing-api",
+  "actions": [
+    { "op": "skip", "reason": "no new evidence in changed snippets" }
+  ]
+}
+JSON
+```
+
+Final report contract (default mode):
+
+- Report in the user's conversation language.
+- Keep a stable structure with these semantic sections; translate section headings into the user's conversation language instead of copying these English labels verbatim:
+  1. Completion headline.
+  2. Per-Node writes table with one row per Node in align frontmatter order. Columns: Node title or slug, type, and add / update / supersede / deprecate counts. Include skipped count only when non-zero.
+  3. Close stage with `context compile --close` result, final node/section totals, verify status, changelog stamp, incremental counts (`recompiled`, `locator_updates`, `rebuilt`), section fingerprint rebuild count, and archive directory for compile scratch files when present.
+  4. Before/after status diff table with at least total nodes, node counts by type, total sections, and last compile time.
+  5. Knowledge files as clickable markdown links. Use absolute path targets without `file://`, for example `[knowledge/entity/vmok.md](/abs/path/.context/knowledge/entity/vmok.md)`. Include `_index.md`, `changelog.md`, and every Node article returned by `context mdrive node list --format json`. Use the path relative to `WORKSPACE_DIR` as the link label.
+  6. Optional next step only when there is a concrete useful follow-up (for example recapture stale material or run `/context:align` to revise structure).
+- Do not say the user can inspect files without providing links.
+
+Final report contract (`--plan` mode):
+
+- Use the same stable shape where possible, but make the headline clearly indicate that this was a plan-only run.
+- Replace the close-stage section with a not-written section and tell the user to re-run `/context:compile` without `--plan` to apply.
+- Do not include knowledge file links for files that were not written.

package/plugin/commands/context.md

@@ -0,0 +1,30 @@
+---
+description: "Fuzzy router for context operations. Inspect the argument and route to the correct /context:* subcommand."
+argument-hint: "<free text | url | source-id | question>"
+allowed-tools: Read, Bash(context:*)
+---
+
+## Your task
+
+Inspect `$ARGUMENTS` and delegate to the most appropriate subcommand. Route without running anything of your own first — let the target subcommand drive.
+
+Any prose you speak to the user (clarifying questions, "routing to …" notes) follows the user's conversation language. Sub-command names (`/context:capture`, `/context:compile`), flag names, and source-ids stay English.
+
+Routing rules (first match wins):
+
+1. **Empty arguments** → run `/context:status`.
+2. **Starts with `http://` or `https://`, or ends in `.md`** → `/context:capture $ARGUMENTS`.
+3. **Equals `--inbox` or `--refresh`** → `/context:capture $ARGUMENTS`.
+4. **Matches `init`, `initialize`, `new workspace`, or looks like a plain workspace name** → `/context:init $ARGUMENTS`.
+5. **Matches `capture-aspect` or a bare `aspect` keyword** → `/context:capture-aspect $ARGUMENTS`. This rule must sit BEFORE the `code` rule below, because `capture-aspect code` is a stub (exits non-zero with "planned for a future release") and must NOT silently fall through to `/context:capture-code`.
+6. **Mentions `code`, `extract`, or `capture-code`** → `/context:capture-code` (extract debug → `/context:extract`).
+7. **Matches `align`, `structure`, `plan`, `node tree`** → `/context:align $ARGUMENTS`.
+8. **Matches `compile`, `recompile`, `synthesize`, or `build knowledge`** → `/context:compile $ARGUMENTS`.
+9. **Matches `drop`, `retract`, `delete source`, or passes a known source-id pattern (`feishu:*` / `local:*` / `aspect:*` / `oncall:*` / `meeting:*`)** → `/context:drop $ARGUMENTS`.
+10. **Matches `purge`, `clear archive`, `delete archive`, or `清理归档`** → `/context:purge $ARGUMENTS`.
+11. **Equals `status`, `health`, `overview`, `summary`, or asks for workspace/cache/plugin health** → `/context:status`.
+12. **Anything else** (likely a knowledge question) → `/context:query $ARGUMENTS`.
+
+If multiple rules apply, pick the most specific (URL beats word match). When in doubt, ask one clarifying question before dispatching.
+Never use Read / Glob / Grep / Write against `WORKSPACE_DIR`; plugin docs may be read via `${CLAUDE_PLUGIN_ROOT}`, but workspace content must go through `context` CLI commands.
+Do not use `context workspace` search/read as this router's knowledge fallback; route likely knowledge questions to `/context:query` so the query skill owns retrieval and citations.

package/plugin/commands/drop.md

@@ -0,0 +1,17 @@
+---
+description: "Drop a source: CLI plans cleanup, runs semantic reconciliation, then applies with decisions."
+argument-hint: "<source-id|raw-path|url> [--reason <text>] [--yes]"
+allowed-tools: Read, Bash(context:*)
+---
+
+## Your task
+
+Retract a source without losing the audit trail. The CLI owns source resolution, impact planning, semantic decision application, knowledge cleanup, source stamp, changelog append, and verify; the agent presents the impact plan and waits for confirmation.
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/drop/SKILL.md` and follow its procedures end to end, including the self-verify checklist at the end.
+
+Parse `$ARGUMENTS` for `<source-id|raw-path|url>`, optional `--reason <text>`, and optional `--yes`. Source validation is done by `context drop --plan`; if absent or already `dropped`, relay the CLI's error and stop. If `--reason` is missing but the user gave a clear natural-language reason, infer a concise reason; otherwise ask for it before applying the plan. `--yes` skips the original drop impact confirmation only; it never skips semantic `ask_user` questions.
+
+Language policy: any prose you speak directly to the user follows the user's conversation language. CLI output, source-ids, command names, file paths, flags, and issue codes stay as printed.
+
+Never Read / Glob / Grep / Write workspace files directly. All workspace access goes through `context drop --plan`, `context reconcile prepare --mode drop`, `context reconcile review`, `context drop --apply-plan --decisions`, `context source`, `context workspace`, and other `context` CLI commands.

package/plugin/commands/extract.md

@@ -0,0 +1,18 @@
+---
+description: "Debug helper: run @c4a/extract against a path and print the ExtractionResult (no files written)."
+argument-hint: "<path> [--format json|jsonl|pretty]"
+allowed-tools: Bash(context:*)
+---
+
+## Your task
+
+Run `context extract $ARGUMENTS` and stream the CLI's stdout back to the user.
+
+- The command is **state-required**: it runs only from inside a directory tree that already contains an embedded `.context/` workspace or root-layout workspace. Outside a workspace the CLI exits with a workspace-not-found error — relay it and suggest `/context:init`, do not try to guess a workspace location.
+- It is strictly read-only — never writes into workspace files.
+- Default format is `json`; `--format jsonl` is line-delimited per entity; `--format pretty` is human-readable.
+- Useful for inspecting what `/context:capture-code` would capture without creating a bucket.
+
+If the user wants to persist the extraction as a raw snapshot, redirect them to `/context:capture-code`.
+
+Language policy: stream CLI stdout/stderr verbatim. Any explanation you add follows the user's conversation language; paths, JSON keys, command names, flags, and error tokens stay as printed.

package/plugin/commands/init.md

@@ -0,0 +1,95 @@
+---
+description: "Initialize a context workspace in the current directory."
+argument-hint: "[name] [--layout embedded|root] [--language <text>] [--with-aspects <names>] [--with-all-aspects] [--minimal] [--focus <text>]"
+allowed-tools: Bash(context:*)
+---
+
+<!--
+This command has no companion skill. Its protocol (the focus multi-choice
+UX before `context init` runs) lives inline here per the slash-command
+length exemption in packages/context-cli/CLAUDE.md.
+-->
+
+## Your task
+
+Initialize a context workspace, including layout, default-language, and focus confirmation before creating it.
+
+### Step 1 — Ask about workspace layout (unless `$ARGUMENTS` already has `--layout`)
+
+Use the host's native multi-choice tool when available (Claude Code `AskUserQuestion`, Codex `ask_user_question`, Cursor Plan Mode `AskQuestion`); fall back to markdown choices otherwise.
+
+Question shape. Do not expose `embedded` / `root` as user-facing option labels; those are CLI tokens only. User-facing option labels may be localized (for example, Chinese labels can be `默认（.context/）` and `当前目录`):
+
+```
+Q. Where should C4A store this workspace?
+  A. Default (.context/) — create a `.context/` data directory inside the current project. (Recommended)
+  B. Current directory — use the current directory itself as the C4A data root.
+```
+
+Explain the tradeoff before asking:
+- Default (`.context/`) is for normal code repositories; C4A files live under `.context/`.
+- Current directory is only for a dedicated knowledge repository. The current directory must not already contain `.context/`, `config.yaml`, `raw/`, `knowledge/`, `output/`, `aspects/`, or `inbox/`. Existing `AGENTS.md` / `CLAUDE.md` in the selected C4A data root are kept rather than overwritten.
+
+Map the answer to CLI flags:
+- Default (`.context/`) → pass `--layout embedded`
+- Current directory → pass `--layout root`
+
+### Step 2 — Ask about default language (unless `$ARGUMENTS` already has `--language`)
+
+Ask one multi-choice question:
+
+```
+Q. What default language should agents use for user-facing replies in this workspace?
+  A. 中文 — maps to `Chinese`
+  B. English
+  C. Other — please describe.
+```
+
+The option label may be localized (for example `中文`), but the stored CLI value should remain stable. Pass the answer as `--language "Chinese"`, `--language "English"`, or the user's custom text.
+
+### Step 3 — Ask about workspace focus (unless user already passed `--focus`)
+
+Before running `context init`, ask the user **one** multi-choice question about the workspace's focus (the primary intent of this knowledge base). Use the host's native multi-choice tool when available (Claude Code `AskUserQuestion`, Codex `ask_user_question`, Cursor Plan Mode `AskQuestion`); fall back to markdown `A/B/C/D` choices otherwise. Keep it to one question with 2–4 options plus "Other" escape hatch; never dump 5+ at once.
+
+The question shape (adapt labels to the user's conversation language, keep machine tokens English):
+
+```
+Q. What will this workspace mainly hold?
+  A. Business product/R&D knowledge base — business architecture, requirements,
+     technical architecture, business modules and their supporting tech.         (Recommended)
+  B. Team technical knowledge base — tech stack, infra tools, conventions,
+     operations, decisions, on-call memos, etc.
+  C. Product / project user manual — user-facing intro, guides, handbook, Q&A.
+  D. Research / learning library on a topic — framework comparisons, selection
+     notes, wiki-style reading notes.
+  E. Other — please describe.
+```
+
+Interpret the answer:
+- Chose A–D → generate a 2–3 line focus description in the user's language. Phrase it as
+  "primarily X; supporting materials such as Y may also be filed here" rather than exclusion
+  language — workspaces absorb auxiliary material in practice. Pass it as `--focus "..."`.
+- Chose E or described freely → pass the user's text verbatim as `--focus "..."`.
+- User says "skip" / "don't care" → run `context init` without `--focus`.
+- `$ARGUMENTS` already contains `--focus "..."` → skip this step entirely.
+
+### Step 4 — Run init
+
+Run `context init $ARGUMENTS` with the selected `--layout`, `--language`, and `--focus` appended when those flags were not already present. The CLI handles skeleton build, `.gitignore`, `AGENTS.md`, `CLAUDE.md -> AGENTS.md`, and aspect templates inside the selected C4A data root.
+
+If the CLI errors (e.g. an existing workspace without `--with-aspects`, or root layout blockers), surface the error and the CLI's remediation hint.
+
+### Step 5 — Summarize
+
+Briefly state in the user's conversation language:
+- Workspace name
+- Layout and data root
+- Default language
+- Installed aspects
+- Whether `AGENTS.md` was created and whether `CLAUDE.md` was linked
+- Whether focus was recorded (show the first line if yes; mention the user can edit `config.yaml` later if not)
+- Suggest `/context:capture` as the natural next step
+
+CLI output, file paths, aspect names, flags, and command names stay as printed.
+
+Do NOT read, write, link, or edit workspace files yourself during init — the CLI is the sole writer for skeleton files, `AGENTS.md`, and `CLAUDE.md`.

package/plugin/commands/purge.md

@@ -0,0 +1,18 @@
+---
+description: "Permanently delete all archived dropped source/knowledge artifacts after confirmation."
+argument-hint: "[--yes]"
+allowed-tools: Bash(context:*)
+---
+
+## Your task
+
+Purge the workspace archive. This is destructive: it deletes all restorable
+artifacts under `archive/` that were created by `context drop --apply-plan`.
+It does not modify active `raw/` or active `knowledge/`.
+
+Run `context purge $ARGUMENTS`. If `--yes` is absent, the CLI prints a summary
+and asks for confirmation. Relay that summary in the user's language and do not
+try to inspect `archive/` yourself.
+
+Never Read / Glob / Grep / Write workspace files directly. All workspace access
+goes through `context purge`, `context source`, or `context workspace`.

package/plugin/commands/query.md

@@ -0,0 +1,13 @@
+---
+description: "Answer a local knowledge question through context query hit/miss/select results and cited supplemental views."
+argument-hint: "<question>"
+allowed-tools: Read, Bash(context:*)
+---
+
+## Your task
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/context-query/SKILL.md` and follow it end to end for `$ARGUMENTS`.
+
+This command is intentionally a thin entrypoint. Do not duplicate the query protocol here; the skill owns the hit/miss/select handling, supplemental lookup, citation, gap, and broad-query rules.
+
+Never use direct workspace file tools for local knowledge. Workspace context must come from `context query` commands only.

package/plugin/commands/status.md

@@ -0,0 +1,21 @@
+---
+description: "Print the current workspace overview (sources, raw counts, knowledge counts, last compile) and suggested next actions."
+argument-hint: ""
+allowed-tools: Bash(context:*)
+---
+
+## Your task
+
+Run `context status` from the workspace root only: for embedded layout, the project directory that contains `.context/`; for root layout, the data root itself. `status` is intentionally local-only and does not walk up from child directories. If you need to discover the workspace from a child directory, run `context workspace locate --format json`.
+
+Surface the CLI's output verbatim — its trailing suggestions are already actionable. Do not invent additional suggestions; the CLI decides what to recommend based on the workspace state. Typical recommendations you will see:
+
+- Run `/context:align` when there is active raw material but no align plan yet (compile's Stage 1 prerequisite).
+- Run `/context:compile` when align plan exists and raw is newer than the last compile.
+- Run `/context:capture-code` when the repo is a git checkout but no source-code snapshot has been captured yet.
+
+Recent CLI output may include `incremental.cache_status`, `incremental.pending_align`, and `incremental.pending_compile`. Surface those fields verbatim. If the user asks what they mean, explain that they show the local incremental cache health and queued align/compile work; cache warnings are informational unless the CLI output includes a blocking error or an explicit next action.
+
+If the CLI exits with a workspace-not-found error, stop and invite the user to run `/context:init` instead of guessing a workspace location.
+
+Language policy: surface the CLI output verbatim. Any extra explanation or workspace-not-found invitation follows the user's conversation language; command names, paths, status labels, source-ids, and issue codes stay as printed.