@c4a/context-cli 0.6.0-beta.8 → 0.6.1-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 context4ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,48 +1,71 @@
-# @c4a/context-cli
+# Context CLI
 
-Local knowledge workspace CLI for Context projects.
+[简体中文](./README.zh-CN.md)
 
-`@c4a/context-cli` is the **CLI** package — the `context` executable plus global agent plugin installer. The V1 workflow uses a globally installed CLI/plugin for agent commands, while each knowledge workspace keeps only project state and SDK dependency metadata.
+`@c4a/context-cli` provides the **Context CLI** and the global Agent plugin
+installer. The CLI manages project-local workspace state; the Agent plugin
+explains that state, asks for user decisions, and edits project configuration.
 
-This package ships:
+The CLI is Node/Bun compatible and does not call an LLM. Mechanical work belongs
+to the CLI, semantic judgment belongs to the Agent, and important decisions
+belong to the user.
 
-1. **`context` CLI** — a Node/Bun-compatible executable that manages project-local context workspaces, repo sources, extraction, review, package build, verify, and status guidance.
-2. **Global plugin installer** — `context plugin install` installs and refreshes the package-bundled plugin marketplace globally for Claude and Codex. It materializes the Codex plugin copy under `~/.codex/plugins/cache/c4a/context/local/`. The public plugin entrypoints are `init` and `continue`; `continue` is agent guidance, not a CLI primitive.
-3. **`plugin/` source** — human-maintained command/skill/manifest sources that `scripts/build-plugin.ts` compiles into installable marketplace trees.
+Markdown parsing is structural only: source headings remain inside citeable
+evidence spans, while their meaning, grouping, and knowledge type are never
+inferred by the CLI.
 
-The split follows a simple rule: mechanical work is the CLI's job; synthesis work is the agent's job. The CLI never calls an LLM. Naming surfaces are deliberately separate: `/context:init` and `/context:continue` are Claude slash commands, Cursor exposes prefixed entries such as `/context-init` / `/context-continue`, `Context: ...` / `context-*` is a public skill entry for skill-only agents, and `context ...` is the CLI primitive. There is no `context continue` CLI command.
-
-Agent-facing dialogue follows the user's current conversation language. CLI
-commands, flags, ids, status values, JSONL keys, and `source_ref` tokens remain
-stable protocol text and are not translated.
-
-## Global Plugin + Project Workspace
+## Install
 
 ```bash
-# Install the CLI and refresh available global agent commands/skills.
 npm install -g @c4a/context-cli
+context plugin install
+```
 
-# Create a standalone context project.
-context init context
+Global package installation also attempts a best-effort plugin refresh. Run
+`context plugin install` again after installing or upgrading Claude or Codex,
+then restart the Agent.
+
+The public Agent entries are:
+
+- `/context:init` creates a project-local Context workspace.
+- `/context:continue` reads the current workspace state and continues from the
+  next action.
+
+`/context:continue` is Agent guidance, not a CLI subcommand. There is no
+`context continue` command.
+
+For the shortest installed-package walkthrough, read
+[CLI Quickstart](./docs/quickstart.md).
+
+## CLI And Agent Responsibilities
 
+| Responsibility | Owner |
+|---|---|
+| Source registries, capture, extraction, review application, verify, and build | CLI |
+| Explaining choices, editing `src/index.ts`, proposing structure, and generating candidates from evidence | Agent |
+| Source permission, classification, review decisions, and package-output choice | User |
+
+The Agent treats `context status --format json` `workflow.current` as the
+current-step authority rather than guessing the next command. The default JSON
+view is compact: it contains the route, required resource locations, progress,
+counts, and aggregated diagnostics. Use `--view full` only for debugging. Long
+procedures and semantic rules remain complete Markdown resources selected by
+the route; progressive loading does not shorten or discard them.
+
+## Create Or Continue A Workspace
+
+```bash
+# Create a standalone workspace.
+context init context
 cd context
 bun install
+
+# Ask the Agent to continue from the current state.
 /context:continue
 ```
 
-Global installation runs `context plugin install` automatically for the
-available Claude and Codex CLIs. Plugin refresh is best-effort and does not
-make the CLI installation fail; rerun `context plugin install` manually after
-installing an agent CLI. Set `CONTEXT_CLI_SKIP_PLUGIN_INSTALL=1` to opt out.
-
-The global plugin calls `context ...` from the current project root.
-Agent commands follow CLI `next:` hints: they execute safe mechanical steps and
-stop at `Human gate:` / placeholder next steps, source registration, source scope
-selection, review, package output choice, or source-repo operations outside the
-CLI. Agents must not infer repo sources or extraction scope from the surrounding
-monorepo.
-
-After `bun install`, the workspace has an installed SDK manual:
+The generated `AGENTS.md` is the Agent's project-local operating guide. After
+dependency installation, SDK manuals are available at:
 
 ```text
 node_modules/@c4a/context/docs/README.md
@@ -51,140 +74,134 @@ node_modules/@c4a/context/docs/reference/project-api.md
 node_modules/@c4a/context/docs/reference/package-templates.md
 ```
 
-Template examples ship at:
+The workspace state is split across:
 
-```text
-node_modules/@c4a/context/templates/package-templates/
-```
+- `src/` for project declarations and package templates.
+- `sources/` for source registries and captured evidence.
+- `unapproved/` for draft, rejected, or deprecated candidates.
+- `knowledge/` for approved knowledge.
+- `dist/` for generated package output.
+- `.tmp/context-runtime/` for ignored logs, previews, reports, locks, and caches.
 
-Agents should read these files instead of probing `node_modules/@c4a/context/dist`
-with temporary scripts.
+Do not repair lifecycle state by manually deleting or rewriting these
+directories. Use the command or next action returned by the CLI.
 
-For the complete source, link, plugin, and npm-mode development workflow, see
-the workspace [DEVELOPMENT.md](../../DEVELOPMENT.md). CLI plugin-specific notes
-remain in this package's [DEVELOPMENT.md](./DEVELOPMENT.md).
+## Package Output
 
-## Project-local quick tour
+`context build` writes each declared package under `dist/<package-name>/`.
+Every KB package uses its package name as the default knowledge namespace, so
+its final OKF roots are shaped like
+`wikis/<package-name>/`, `guides/<package-name>/`,
+`rules/<package-name>/`, and `feats/<package-name>/`. A project may explicitly
+choose another safe single- or multi-segment namespace in `src/index.ts`;
+Skill names remain independent.
 
-```bash
-# Create a standalone context project.
-bunx @c4a/context-cli init context
-cd context
-bun install
+See the SDK manuals for the complete configuration and template contract:
 
-# Or initialize the current directory as the project root.
-bunx @c4a/context-cli init . --name my-product-context
-bun install
+- [Package outputs](../context/docs/guides/package-outputs.md)
+- [Package templates](../context/docs/reference/package-templates.md)
 
-# Register a local repo source when the agent-guided next step asks for it.
-# The ref should be a pinned commit SHA.
-context source add repo sample-lib --local ../sample-lib
+## Status-Driven Workflow
 
-# In a monorepo, register the chosen package/subdirectory as the source.
-# Do not register the parent monorepo and use extractTs.include as a package selector.
-context source add repo sample-lib --local ../packages/sample-lib
+The project workflow is declared in `src/index.ts` and routed by the bundled
+Context workflow graph behind `context status`. This graph is an internal CLI
+implementation detail; Context users and plugins consume only
+`workflow.current`, Context commands, and the selected resources:
 
-# Keep non-standard TypeScript entry roots in the Context project src/index.ts.
-# Do not add package.json entry fields or source files solely for Context.
-# extractTs({ source, collection: "codegraph", include: ["src/**/*.ts"], entries: ["src/api.ts"] })
-# Use mode: "scan" instead when every include-matched file is a scan root.
+| Stage | CLI surface |
+|---|---|
+| Source setup | `context source add repo/file/lark`, `context source add batch`, and `context source ensure` |
+| Document capture | Declared capture phases through `context run <phase-id>` |
+| Code extraction | Declared `extractTs` phases through `context run <phase-id>` |
+| Prose structure | `context run align:<type>:<source>:<collection> ...` evidence and validation views |
+| Prose compile | `context run compile:<type>:<source>:<collection> ...` evidence and validation views |
+| Review | `context review html`, scoped decisions, and `context review apply` |
+| Close and quality | `context close` and `context verify` |
+| Package output | `context build` |
 
-# Optional overrides when origin / HEAD cannot be inferred:
-context source add repo sample-lib \
-  --local ../sample-lib \
-  --remote https://git.example.com/sample-lib.git \
-  --ref <commit-sha>
+Building a package completes the currently active approved state; it does not
+freeze the workspace. New sources can be added and processed later.
 
-# Check source readiness. The CLI reports diagnostics and hints only;
-# it does not clone, checkout, reset, or otherwise mutate the source repo.
-context source ensure
+## Command Groups
 
-# Inspect declared phases and let status suggest the next step.
-context status
-context run --list
-context run extract:sample-lib:codegraph --dry-run
-```
-
-The current project-local protocol uses `src/index.ts`, `sources/`, `unapproved/`, `knowledge/`,
-`README.md`, `AGENTS.md`, and `package.json`. `dist/` contains generated package
-outputs and is rebuilt from approved knowledge and templates.
-Runtime scratch lives under `.tmp/context-runtime/` and is ignored. It may contain run logs, review HTML, previews, locks, and cache files; it is not the committed state source. Committed state is the combination of source registries and document snapshots under `sources/`, `unapproved/entities.jsonl`, approved Markdown under `knowledge/`, project code under `src/`, and project guidance in `README.md` / `AGENTS.md`.
+```bash
+# Plugin installation and diagnostics
+context plugin install
+context plugin status
 
-## Current Workflow Model
+# Workspace state
+context init [project-dir]
+context status
 
-The project-local workflow is status-driven. Register sources, declare phases in
-`src/index.ts`, then let `context status` and phase views route each gate:
+# Sources
+context source add repo [YYYYMMDD] --module <module> --local <repo-or-subdir>
+context source add file [YYYYMMDD] --module <module> --local <file-or-folder>
+context source add lark [YYYYMMDD] --module <module> --url <lark-url>
+context source add batch [YYYYMMDD] --input <yaml-or-json>
+context source ensure [source]
+context source inspect [source]
 
-Building a package completes the currently active structure snapshots, not the
-workspace forever. Additional captured documents remain in
-`pendingStructureTargets` until their own declared align/compile/review route is
-completed; they can be added without creating a new workspace.
+# Declared phases and review
+context run --list
+context run <phase-id> --dry-run
+context run <phase-id>
+context review html [collection] --open
+context review apply <payload-file>
+
+# Final quality and output
+context close
+context verify
+context build
+```
 
-| Gate | Current surface |
-|---|---|
-| Source setup | `context source add repo/file/lark`, `context source ensure`, and project source declarations. |
-| Document capture | Declared `capture:file:<source>` / `capture:lark:<source>` phases through `context run` after the source read gate. |
-| Prose structure | `alignProse` phases through `context run align:<type>:<source>:<collection> --view/--validate/--stage`, producing confirmed `unapproved/structure.yaml`. |
-| Source-bound prose compile | `compileProse` phases through `context run compile:<type>:<source>:<collection> --view/--validate/--stage`, producing review candidates from confirmed structure. |
-| Review/apply | `context review html` and `context review apply` own approval, rejection, scoped quick decisions, and source-mirrored approved Markdown materialization. |
-| Close/verify/build | `context close`, `context verify`, `context build`, package templates, OKF indexes, and generated `knowledge-query` skills own final package readiness. |
-
-Do not simulate lifecycle or retraction work by deleting files under `sources/`,
-`knowledge/`, `unapproved/`, `dist/`, or `.tmp`. Status and plugin guidance must
-route users back to the gate that owns the fix.
-
-## Agent Contract
-
-For project workflows, `context` is a semantic service. Agents should call the CLI and use returned source names, phase ids, candidate ids, package names, diagnostics, and `source_ref` values. They should not derive state by walking runtime cache directories.
-
-`source_ref` is an opaque citation token. Copy it into citations and decisions exactly as printed; do not parse it or dereference it as a file path. Human/report views may show source locations for inspection, but those values are not production workflow inputs.
-
-## Commands
-
-| Command | Role | Notes |
-|---|---|---|
-| `context plugin path` | CLI | Print the bundled plugin marketplace root. Installed packages normally use `dist/plugins`; source checkouts use the same path after build. |
-| `context plugin install [--agent claude\|codex\|all] [--dry-run]` | CLI | Install or refresh the bundled plugin marketplace globally for Claude and/or Codex. It replaces existing `context` marketplace entries and Codex cache owned by this package before reinstalling. |
-| `context plugin status [--agent claude\|codex\|all]` | CLI | Inspect bundled plugin path and agent CLI availability. |
-| `context init [project-dir] [--name <name>] [--dev]` | CLI | Create a project-local context workspace. Defaults to `context/`; use `.` to initialize the current directory. Use `--dev` for local checkout or prepared-pack testing before the matching `@c4a/context` version is published. |
-| `context source add repo <name> --local <repo-or-subdir> [--remote <url>] [--ref <sha>]` | CLI | Register a repo source and pin it to a commit. Local paths may point at a monorepo subdirectory; the CLI stores the git root plus subpath, and materializes the source view to the subdirectory. Remote and ref are inferred from local origin / HEAD when omitted. Short SHAs are resolved to full commits when the local repo is available. |
-| `context source ensure [name]` | CLI | Validate and materialize local source symlinks. Missing remotes only produce hints; the CLI does not clone or checkout automatically. |
-| `context source add batch [date] --input <file|->` | CLI | Register multiple repo, file, or Lark modules under one project write lock from YAML/JSON input. Repo modules are explicit; file/Lark modules may be derived when omitted. |
-| `context source list|get <name>` | CLI | Inspect the repo source registry and readiness metadata. |
-| `context source inspect [name]` | CLI | Detect module/package boundaries in registered repo sources without extraction. Use this before extracting monorepo roots; it prints package names, paths, versions when available, and suggested source registration commands. |
-| `context run --list` | CLI | List phases declared by `src/index.ts`. |
-| `context run <phase-id> [--dry-run] [--auto-promote] [--managed]` | CLI | Inspect or run one declared phase. Extract dry-run separates discovered, AST-analyzed, skipped, symbol, and relation counts. Missing/empty entries fail with `NO_ENTRY_DETECTED`; TypeScript aliases come from tsconfig/jsconfig `baseUrl` and `paths`. Codegraph defaults to first-run full Review and later delta-only Review; `--auto-promote` applies deterministic codegraph deltas, refreshes deterministic close when needed, then verifies. `--managed` is current-conversation authority propagated by an Agent, never project policy. Existing package outputs become stale and remain an explicit downstream build step. |
-| `context review html [collection] [--open]` | CLI | Render the local self-contained HTML review surface under `.tmp/context-runtime/review/`, emit a clickable `file://` URL, and optionally open it with the system browser. |
-| `context review list [collection]` | CLI | List draft candidates for CLI-oriented review. |
-| `context review apply <payload-file>` | CLI | Apply copied review decisions; approved entities materialize to `knowledge/`, rejected entities remain in `unapproved/entities.jsonl`. |
-| `context review approve|reject <candidate-id> --collection <collection>` / `--all` | CLI | Scoped quick marking for a single draft candidate when the user explicitly authorizes an automated or quick path. |
-| `context review approve-all [collection] --managed` / `--all --managed` | CLI | Atomically approve the current validated Review scope under explicit current-conversation fully managed authority. The flag is required and no policy is persisted. |
-| `context review migrate-codegraph-refs` | CLI | Upgrade legacy approved codegraph refs to `src-N#symbol:<file>:<symbol>:<kind>@<digest>`, remove redundant `code_origin`, and verify. Rerun declared codegraph extraction first; this metadata migration does not repeat Review. |
-| `context build` | CLI | Build declared project packages from approved knowledge into `dist/<package-name>/`. |
-| `context verify [--format table\|json]` | CLI | Validate the project skeleton, registry, unapproved ledger, approved Markdown, source refs, and package outputs. |
-| `context status [--managed] [--format json\|table]` | CLI | Workspace overview + a canonical `next:` hint. `--managed` resolves eligible human gates only for the explicitly authorized current conversation; source permission, external operations, validation, and verification remain enforced. Agent plugins expose this workflow as `/context:continue`; do not add or call `context continue`. |
-
-Commands that require a project exit with a workspace-not-found error if run outside a directory tree containing a `package.json` `context.project=true` / `context.entry` marker. `context init` is the command that creates one.
-
-For a beta.5 project that reports `approved-source-ref-ambiguous`, upgrade in
-this order: rerun each declared codegraph extraction phase to create the current
-file-aware symbol index, run `context review migrate-codegraph-refs`, then run
-`context verify`. The migration preserves approved content and review decisions;
-it changes only code evidence identity and removes the old `code_origin` copy.
+Run `context <command> --help` for current flags. Commands that require a
+workspace search upward for a `package.json` with `context.project=true` and a
+configured `context.entry`.
+
+## Human Gates And Evidence
+
+- The CLI never silently clones, checks out, resets, fetches, installs, builds,
+  or runs scripts in a source repository.
+- Source registration and source-body reading are separate permissions.
+- Extraction scope and document classification are confirmed before candidate
+  writes.
+- In ordinary mode, Review decisions come from the user and the Agent must not
+  invent payloads. Explicit current-conversation fully managed mode uses only
+  the atomic approval command returned by `workflow.current`.
+- Package output is chosen after approved knowledge exists; package templates
+  are project configuration, not a second factual source.
+
+CLI-returned source names, phase IDs, candidate IDs, diagnostics, and
+`source_ref` values are workflow tokens. A `source_ref` is an opaque evidence
+citation: copy it exactly and do not parse it as a filesystem path.
+
+## Further Reading
+
+- [CLI Quickstart](./docs/quickstart.md)
+- [SDK documentation index](../context/docs/README.md)
+- [Getting Started](../context/docs/getting-started.md)
+- [Agent Guide](../context/docs/guides/agent-guide.md)
+- [Agent Dialogue](../context/docs/guides/agent-dialogue.md)
+- [Project API](../context/docs/reference/project-api.md)
+- [Package Templates](../context/docs/reference/package-templates.md)
 
 ## Development
 
-Source lives at [`packages/context-cli/`](./src) in this workspace.
+For the complete source, link, plugin, and npm-mode workflow, see
+[`DEVELOPMENT.md`](../../DEVELOPMENT.md) and this package's
+[`DEVELOPMENT.md`](./DEVELOPMENT.md).
 
 ```bash
-./start.sh link                              # local checkout: build CLI, link global context, register SDK for init --dev
-bun run --filter @c4a/context-cli build      # bundle CLI + render dist/plugins
-bun run --filter @c4a/context-cli test       # unit + integration tests
+./start.sh link
+bun run --filter @c4a/context-cli build
 bun run --filter @c4a/context-cli typecheck
 bun run --filter @c4a/context-cli lint
+bun run --filter @c4a/context-cli test
 ```
 
-The package build writes installable plugin trees to `dist/plugins`, which is shipped in the npm tarball. `context plugin install` resolves that package-bundled path at runtime and installs it globally for Claude / Codex. For Codex, the installer also copies `dist/plugins/codex` into `~/.codex/plugins/cache/c4a/context/local/`, matching Codex's local-plugin cache convention. Do not edit generated build trees directly.
+Build writes the installable Claude, Codex, Cursor, and skill-only trees to
+`dist/plugins`. `context plugin install` installs from that package-bundled
+output. Do not edit generated plugin trees directly.
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,172 @@
+# Context CLI
+
+[English](./README.md)
+
+`@c4a/context-cli` 提供 **Context CLI** 和全局 Agent 插件安装能力。CLI 负责管理本地知识工作区的状态，Agent 插件负责解释状态、询问用户决策并修改项目配置。
+
+CLI 同时兼容 Node 和 Bun，本身不会调用 LLM。机械操作交给 CLI，语义判断交给 Agent，重要决策交给用户。
+
+CLI 对 Markdown 只做结构解析：源标题会保留在可引用的证据区间中，但标题的含义、分组方式和知识类型均不会由 CLI 推断。
+
+## 安装
+
+```bash
+npm install -g @c4a/context-cli
+context plugin install
+```
+
+全局安装 npm 包时也会尝试刷新插件，但不会因为插件安装失败而阻塞 CLI 安装。安装或升级 Claude、Codex 后，可以再次执行 `context plugin install`，然后重启 Agent。
+
+面向用户的 Agent 入口是：
+
+- `/context:init`：创建一个本地 Context workspace。
+- `/context:continue`：读取已有工作区的状态，并从下一步继续。
+
+`/context:continue` 是 Agent 工作指引，不是 CLI 子命令；不存在 `context continue` 命令。
+
+最简安装后流程参见 [CLI 快速开始](./docs/quickstart.md)。
+
+## CLI、Agent 和用户的分工
+
+| 职责 | 负责方 |
+|---|---|
+| 来源登记、内容读取、代码提取、应用审核、验证和构建 | CLI |
+| 解释选择、修改 `src/index.ts`、提出知识结构、基于证据生成候选 | Agent |
+| 来源授权、知识分类、审核决定和打包方式 | 用户 |
+
+Agent 把 `context status --format json` 返回的 `workflow.current` 作为当前步骤的权威协议，不会凭记忆猜下一条命令。默认 JSON 是紧凑视图，只包含当前路由、所需资源位置、进度、计数和聚合诊断；调试时才使用 `--view full`。长篇流程和语义规则仍以完整 Markdown 资源随包发布，由当前路由按需选择，渐进加载不会删减内容。
+
+## 创建或继续工作区
+
+```bash
+# 创建独立工作区
+context init context
+cd context
+bun install
+
+# 让 Agent 从当前状态继续
+/context:continue
+```
+
+初始化生成的 `AGENTS.md` 是 Agent 在当前项目中的操作指南。安装依赖后，SDK 手册位于：
+
+```text
+node_modules/@c4a/context/docs/README.md
+node_modules/@c4a/context/docs/guides/agent-guide.md
+node_modules/@c4a/context/docs/reference/project-api.md
+node_modules/@c4a/context/docs/reference/package-templates.md
+```
+
+工作区状态分布在：
+
+- `src/`：项目声明和知识包模板。
+- `sources/`：来源登记和已经读取的证据。
+- `unapproved/`：草稿、拒绝或废弃的知识候选。
+- `knowledge/`：审核通过的知识。
+- `dist/`：构建生成的知识包。
+- `.tmp/context-runtime/`：忽略的日志、预览、报告、锁和缓存。
+
+不要通过手动删除或改写这些目录来修复流程状态，应使用 CLI 返回的命令或下一步操作。
+
+## 知识包输出
+
+`context build` 会把声明好的知识包写入 `dist/<package-name>/`。每个 KB 包默认使用包名作为知识 namespace，因此最终 OKF 根目录形如
+`wikis/<package-name>/`、`guides/<package-name>/`、
+`rules/<package-name>/` 和 `feats/<package-name>/`。项目可以在
+`src/index.ts` 中显式指定其他安全的单段或多段 namespace；Skill 名称与它相互独立。
+
+完整配置和模板约定参见 SDK 手册：
+
+- [知识包输出](../context/docs/guides/package-outputs.md)
+- [知识包模板](../context/docs/reference/package-templates.md)
+
+## 状态驱动流程
+
+项目流程声明在 `src/index.ts` 中，由 `context status` 背后的 Context 工作图负责路由。这张图是 CLI 内部实现；用户和插件只消费 `workflow.current`、Context 命令以及当前路由选中的资源：
+
+| 阶段 | CLI 入口 |
+|---|---|
+| 来源设置 | `context source add repo/file/lark`、`context source add batch`、`context source ensure` |
+| 文档读取 | 通过 `context run <phase-id>` 执行声明好的 capture 阶段 |
+| 代码提取 | 通过 `context run <phase-id>` 执行声明好的 `extractTs` 阶段 |
+| 文档结构 | `context run align:<type>:<source>:<collection> ...` 的证据和校验视图 |
+| 文档编译 | `context run compile:<type>:<source>:<collection> ...` 的证据和校验视图 |
+| 人工审核 | `context review html`、范围化决定和 `context review apply` |
+| 收口与质量 | `context close`、`context verify` |
+| 知识包输出 | `context build` |
+
+一次构建只完成当前已经确认的知识状态，并不会冻结工作区。后续还可以继续添加和处理新的来源。
+
+## 命令分组
+
+```bash
+# 插件安装与诊断
+context plugin install
+context plugin status
+
+# 工作区状态
+context init [project-dir]
+context status
+
+# 知识来源
+context source add repo [YYYYMMDD] --module <module> --local <repo-or-subdir>
+context source add file [YYYYMMDD] --module <module> --local <file-or-folder>
+context source add lark [YYYYMMDD] --module <module> --url <lark-url>
+context source add batch [YYYYMMDD] --input <yaml-or-json>
+context source ensure [source]
+context source inspect [source]
+
+# 声明阶段与审核
+context run --list
+context run <phase-id> --dry-run
+context run <phase-id>
+context review html [collection] --open
+context review apply <payload-file>
+
+# 最终质量与输出
+context close
+context verify
+context build
+```
+
+当前参数以 `context <command> --help` 为准。需要工作区的命令会向上查找带有 `context.project=true` 和 `context.entry` 配置的 `package.json`。
+
+## 人工门禁与证据
+
+- CLI 不会悄悄在来源仓库中执行 clone、checkout、reset、fetch、install、build 或脚本。
+- 登记来源和读取来源正文是两次独立授权。
+- 写入知识候选前，需要确认代码提取范围和文档分类。
+- 普通模式下，审核决定来自用户，Agent 不能自行编造批准或拒绝结果；只有当前对话明确启用全托管时，才可执行 `workflow.current` 返回的原子批准命令。
+- 正式知识准备好后再选择打包方式；知识包模板是项目配置，不是第二份事实来源。
+
+CLI 返回的来源名称、阶段 ID、候选 ID、诊断和 `source_ref` 都是流程标识。`source_ref` 是不可拆解的证据引用，应原样复制，不能把它当作文件路径解析。
+
+## 继续阅读
+
+- [CLI 快速开始](./docs/quickstart.md)
+- [SDK 文档索引](../context/docs/README.md)
+- [快速开始](../context/docs/getting-started.md)
+- [Agent 指南](../context/docs/guides/agent-guide.md)
+- [Agent 对话指南](../context/docs/guides/agent-dialogue.md)
+- [项目 API](../context/docs/reference/project-api.md)
+- [知识包模板](../context/docs/reference/package-templates.md)
+
+## 开发
+
+完整的源码、链接、插件和 npm 产物流程参见
+[`DEVELOPMENT.md`](../../DEVELOPMENT.md) 和当前包的
+[`DEVELOPMENT.md`](./DEVELOPMENT.md)。
+
+```bash
+./start.sh link
+bun run --filter @c4a/context-cli build
+bun run --filter @c4a/context-cli typecheck
+bun run --filter @c4a/context-cli lint
+bun run --filter @c4a/context-cli test
+```
+
+构建会把 Claude、Codex、Cursor 和纯 Skill 形态的插件写入 `dist/plugins`。`context plugin install` 从包内构建产物安装插件，不要直接修改生成目录。
+
+## License
+
+MIT.