@c4a/context-cli 0.5.33-alpha.4 → 0.5.35-alpha.3

package/package.json

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

package/plugin/README.md

@@ -67,10 +67,11 @@ From your project directory:
 
 1. **Init** — `/context:init` creates the `.context/` workspace;
 2. **Capture** — `/context:capture <url-or-path>` pulls in Feishu docs, local Markdown, code snapshots, and so on;
-3. **Align** — `/context:align` places raw material onto the Node structure;
-4. **Compile** — `/context:compile` lets the AI turn raw material into structured Sections;
-5. **Query** — `/context:query <question>` answers from local knowledge, citing Node and Section;
-6. **Drop** — `/context:drop <source-id>` reclaims deprecated material and its derived Sections.
+3. **Code projection** — for code snapshots, `/context:compile --code <source-slug>` materializes package/category/symbol Nodes such as `pkg`, `pkg/components`, and `pkg/symbol/button`;
+4. **Align** — `/context:align` places prose material onto the Node structure, including docs or examples that should attach to existing code symbol Nodes;
+5. **Compile** — `/context:compile` lets the AI turn prose material into structured Sections;
+6. **Query** — `/context:query <question>` answers from local knowledge, citing Node and Section; code workspaces can filter mixed evidence with `--evidence code|prose|all`;
+7. **Drop** — `/context:drop <source-id>` reclaims deprecated material and its derived Sections.
 
 Each step writes readable files and a changelog under `.context/`, so you can review or roll back at any time.
 

package/plugin/README_CN.md

@@ -67,10 +67,11 @@ bun add -g @c4a/context-cli
 
 1. **初始化** — `/context:init` 创建 `.context/` 工作目录；
 2. **采集** — `/context:capture <url-or-path>` 拉取飞书文档、本地 Markdown、代码快照等原始资料；
-3. **对齐** — `/context:align` 将原料归位至 Node 结构；
-4. **编译** — `/context:compile` 由 AI 将原料加工为结构化 Section；
-5. **检索** — `/context:query <问题>` 在本地知识中查询答案，返回 Node 与 Section 级引用；
-6. **撤回** — `/context:drop <source-id>` 回收废弃资料及其派生 Section。
+3. **代码投影** — 对代码快照执行 `/context:compile --code <source-slug>`，生成 `pkg`、`pkg/components`、`pkg/symbol/button` 这类 package/category/symbol Node；
+4. **对齐** — `/context:align` 将文档原料归位至 Node 结构，包括挂靠到已有 code symbol Node 的手册、示例和经验；
+5. **编译** — `/context:compile` 由 AI 将文档原料加工为结构化 Section；
+6. **检索** — `/context:query <问题>` 在本地知识中查询答案，返回 Node 与 Section 级引用；代码工作区可用 `--evidence code|prose|all` 区分代码证据和文档证据；
+7. **撤回** — `/context:drop <source-id>` 回收废弃资料及其派生 Section。
 
 每一步都会在 `.context/` 中留下可读文件与 changelog，支持随时回看与回滚。
 

package/plugin/commands/capture.md

@@ -14,11 +14,13 @@ length exemption for self-contained slash commands.
 
 Capture is entirely CLI-driven — your role is to route the right `context capture` invocation and relay its output. Never hand-write captured source snapshots: the CLI owns normalisation (NFC, BOM strip, line endings) and the `content_hash` contract, so any manual edit breaks idempotency.
 
-### Code capture dependency handling
+### Code capture diagnostics
 
-Do not run ad-hoc Node.js package-resolution preflights before `context capture --code`. The CLI owns dependency discovery and returns structured `agent_hints[]` when `@c4a/extract-ts` or another code-capture dependency is unavailable. Run the requested `context capture --code ...` or `context capture --code ... --plan --format json` command directly, then follow the CLI's `agent_hints[]` if it fails.
+Do not run hand-written dependency preflight commands before `context capture --code`. The CLI owns TypeScript runner/plugin resolution and returns structured `agent_hints[]` when the runner is missing or misconfigured.
 
-Invocation note: code capture does not run through `npx`. `context capture --code` resolves `@c4a/extract` and `@c4a/extract-ts` from the installed `@c4a/context-cli` package using its own runtime package resolution, prepares a user-cache aspect runner wrapper, and executes that wrapper directly. Do not substitute a hand-written resolver check for the CLI.
+If `context capture --code ...` fails with install or runner hints, surface the CLI's `agent_hints[]` install command exactly as printed. Ask the user once whether to run that command on their behalf; global installs touch shared state, so explicit confirmation is required before invoking `Bash`. If approved, run the exact command from `agent_hints[0].command`, then retry the original `context capture --code ...` invocation. If declined, leave the command visible so the user can run it manually. Do not inline `@c4a/extract-ts`, do not hand-write code snapshots, and do not continue with partial capture.
+
+Invocation note: code capture does not run through `npx`. `context capture --code` resolves `@c4a/extract` and `@c4a/extract-ts` from the installed `@c4a/context-cli` package using Node package resolution, prepares a user-cache aspect runner wrapper, and executes that wrapper directly. The plugin must therefore be available to the same global install that provides `context`.
 
 ### Route by argument
 
@@ -34,14 +36,14 @@ Invocation note: code capture does not run through `npx`. `context capture --cod
   - Present only candidate package name, module path, and version. Do not show file counts or the derived path filter.
   - If the plan returns exactly one candidate package, run `context capture --code <original-target-if-present> --module <candidate.path> --format json` immediately.
   - If the plan returns multiple candidate packages, ask the user which package paths to capture. If the host interaction supports multi-select, allow multi-select; otherwise ask the user to reply with one or more package paths/names.
-  - Then run `context capture --code` with one repeated `--module <path>` for every selected package. The CLI derives and stores path filtering silently from that selection.
+  - Then run `context capture --code <original-target-if-present>` with one repeated `--module <path>` for every selected package. The CLI derives and stores path filtering silently from that selection.
 - User asks to record conversation material, a decision, a revision intent, or a temporary observation → use note capture:
   - Classify once as `revision`, `decision`, or `brainstorm`; temporary observations are `brainstorm`. If unclear, ask one clarification.
   - For `revision` or `decision`, require an existing target. If missing, run `context query --intent node_lookup --query "<user words>"` and ask the user to confirm a Node or Section before writing.
   - Write the body to `context capture --note --intent <intent> --anchor <node-slug>[#<section-id>] --input -` for anchored notes, or omit `--anchor` for brainstorm.
   - For `revision`, organize the stdin Markdown with headings: `旧上下文`, `修改意图`, `新内容`, `验证条件`.
   - For `decision`, organize the stdin Markdown with headings: `议题`, `选项`, `决议`, `理由`.
-  - After capture, run `context status --view summary --format json` and base the user-facing next step on `next_step.command` / `workflow.next_step`.
+  - After capture, run `context status --format json` and base the user-facing next step on `next_step.command` / `workflow.next_step`.
 
 For stdin batches, use this shape:
 
@@ -58,12 +60,12 @@ Do not pipe the heredoc through another command, and do not discover files with
 
 Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
 
-- Run `context status --view summary --format json` and use its `next_step.command` / `workflow.next_step`.
+- Run `context status --format json` and use its `next_step.command` / `workflow.next_step`.
 - If status says aligned knowledge is missing or alignment is required → suggest `/context:align`.
 - If status says compile work is pending for Markdown / evidence-backed knowledge → suggest `/context:compile`. Mention `/context:align` only if the user wants to revise the structure.
-- If the capture was code-only and status suggests `context compile --code <slug>`, surface that exact command. Do not suggest bare `/context:compile` for code-only sources.
+- If the capture was code-only and status reports pending code projection, suggest the CLI-owned code route: `/context:compile --code <source-slug>` or `context compile --code <source-slug>`, followed by `context compile --close` when the CLI asks for close.
 
-Never suggest bare `/context:compile` when no align plan exists or when the only active source is `aspect:code` raw snapshot data. Use `context compile --code <slug>` for deterministic code projection, or `context source get <source-id>` when the user only wants to inspect the captured raw code source.
+Never suggest prose compile or hand-built code knowledge for a code-only source. Code snapshots become active knowledge only through `context compile --code`, which materializes package/category/symbol Nodes deterministically.
 
 If capture is rejected with `agent_hints[].code = "workflow-cross-family-rejected"`, do **not** run `context workflow abandon ...` automatically. First run or ask the user to run `context workflow status --format json` and explain that another workflow is active in this workspace. Continue that workflow when it is the intended task; ask the user before abandoning it when the user wants to discard that in-progress work. If the user expected a different repository/workspace, change to the confirmed workspace root before retrying capture.
 

package/plugin/commands/compile.md

@@ -1,6 +1,6 @@
 ---
 description: "Compile the confirmed align plan into knowledge articles: draft, semantic reconciliation, apply, then close."
-argument-hint: "[--plan | --code [slug]]"
+argument-hint: "[--plan]"
 allowed-tools: Bash(context:*)
 ---
 
@@ -25,11 +25,7 @@ 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 - --plan` so the CLI validates stdin draft content without writing active 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.
-- **`--code [slug]`** — run the CLI-owned code projection route directly with `context compile --code [slug]`; it does not enter draft/reconcile and uses the same deterministic implementation as `context align --code`.
-
-Code mode short-circuit: if `$ARGUMENTS` contains `--code`, run `context compile --code [slug]` immediately, relay the CLI output, and stop. Do not run the default compile doctor/draft/reconcile preflight for code projection.
-
-Code-only default routing: if `$ARGUMENTS` is empty, first run `context status --view summary --format json`. When its `next_actions[]` / `next_step.command` contain only `context compile --code ...` actions for active code sources, run `context compile --code` once with no slug so the CLI projects all actionable code sources, then run `context compile --close` only if the compile output says close is needed. If the code projection status asks for `context align --code <slug>` instead, run that dry-run diagnostic and stop with the reported conflict. Do not ask the user whether to run deterministic code projection after they invoked `/context:compile`.
+- **`--code [slug]`** — run the CLI-owned code projection route directly with `context compile --code [slug]`, report its output, then stop. This route does not enter doctor/draft/reconcile and uses the same deterministic implementation as `context align --code`. It materializes code snapshots into package/category/symbol Nodes; run `context compile --close` afterward only when the CLI asks for close.
 
 Delegated workflow mode:
 
@@ -44,7 +40,7 @@ Stable prompt/output policy: keep fixed protocol, schema, mount matrix, and work
 Preflight:
 
 1. Run `context doctor`; output-align group must be green. If it reports missing aligned knowledge, tell the user to run `/context:align` and stop. Incremental cache group warnings are informational here; only output-align errors block compile.
-2. Run `context mdrive workspace stats --format json`, `context source list --format json`, and `context status --view summary --format json`; record the before counts and `STATUS.semantic.refreshed_source_pending_compile.source_ids[]`. This status means newer raw snapshots exist; it does not mean finalized ownership or `node.sources[]` are already refreshed.
+2. Run `context mdrive workspace stats --format json`, `context source list --format json`, and `context status --format json`; record the before counts and `STATUS.semantic.refreshed_source_pending_compile.source_ids[]`. This status means newer raw snapshots exist; it does not mean finalized ownership or `node.sources[]` are already refreshed.
 3. Run `context compile --scan-changes --format json` and parse the JSON as `COMPILE_WORKSET`. If delegated workflow mode is explicitly authorized, run `context compile --scan-changes --delegated --format json` for this first scan instead. `--scan-changes` is the only workset scan flag; `--plan` is reserved for draft validation.
    - If `context workflow status --format json` has `current: null` but `last_published` is present, continue with `context compile --scan-changes`; the published finalized ownership is still the workspace structure truth. Use `context workflow list --format json` only when you need lineage/history diagnostics.
    - Compile JSON may include `source_finalize`; use it as lineage for the finalized ownership that produced the current Node set and citation ownership.