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

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,64 @@
-# @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.
+## Install
 
-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.
+```bash
+npm install -g @c4a/context-cli
+context plugin install
+```
 
-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 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.
 
-## Global Plugin + Project Workspace
+The public Agent entries are:
 
-```bash
-# Install the CLI and refresh available global agent commands/skills.
-npm install -g @c4a/context-cli
+- `/context:init` creates a project-local Context workspace.
+- `/context:continue` reads the current workspace state and continues from the
+  next action.
 
-# Create a standalone context project.
-context init context
+`/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 follows `context status` and CLI diagnostics rather than guessing the
+next command. It may execute safe mechanical steps, but it stops at human gates
+and external source-repository operations.
+
+## 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 +67,116 @@ node_modules/@c4a/context/docs/reference/project-api.md
 node_modules/@c4a/context/docs/reference/package-templates.md
 ```
 
-Template examples ship at:
-
-```text
-node_modules/@c4a/context/templates/package-templates/
-```
+The workspace state is split across:
 
-Agents should read these files instead of probing `node_modules/@c4a/context/dist`
-with temporary scripts.
+- `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.
 
-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).
+Do not repair lifecycle state by manually deleting or rewriting these
+directories. Use the command or next action returned by the CLI.
 
-## Project-local quick tour
+## Status-Driven Workflow
 
-```bash
-# Create a standalone context project.
-bunx @c4a/context-cli init context
-cd context
-bun install
+The project workflow is declared in `src/index.ts` and routed by
+`context status`:
 
-# Or initialize the current directory as the project root.
-bunx @c4a/context-cli init . --name my-product-context
-bun install
+| 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` |
 
-# 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
+Building a package completes the currently active approved state; it does not
+freeze the workspace. New sources can be added and processed later.
 
-# 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
+## Command Groups
 
-# 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.
+```bash
+# Plugin installation and diagnostics
+context plugin install
+context plugin status
 
-# 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>
+# Workspace state
+context init [project-dir]
+context status
 
-# 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
+# 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]
 
-# Inspect declared phases and let status suggest the next step.
-context status
+# Declared phases and review
 context run --list
-context run extract:sample-lib:codegraph --dry-run
+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
 ```
 
-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`.
+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`.
 
-## Current Workflow Model
+## Human Gates And Evidence
 
-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:
+- 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.
+- Review decisions come from the user. The Agent must not invent approval or
+  rejection payloads.
+- Package output is chosen after approved knowledge exists; package templates
+  are project configuration, not a second factual 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.
+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.
 
-| 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.
+## 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