@c4a/context-cli 0.5.29-alpha.1 → 0.5.29-beta.16

package/README.md

@@ -2,32 +2,43 @@
 
 Local knowledge workspace CLI for [c4a — Context For AI](https://github.com/context4ai/c4a).
 
-`@c4a/context-cli` ships three surfaces in a single npm package:
+`@c4a/context-cli` is the **CLI** package — the `context` executable plus its source-of-truth plugin templates. Plugin install trees are distributed separately through the [context4ai/context](https://github.com/context4ai/context) repo (Claude / Codex / Cursor / Vercel-style skills), generated by `bun run build:plugin` from `plugin/` source.
+
+This package ships:
 
 1. **`context` CLI** — a Node/Bun-compatible executable that captures documents, extracts code structure, and manages a local context workspace.
-2. **Claude Code plugin `context`** — slash commands (`/context:init`, `/context:capture`, `/context:align`, `/context:compile`, `/context:query`, `/context:drop`, `/context:purge`, `/context:status`, …) and a pipeline of eight skills (`align-scan`, `align-propose`, `align-finalize`, `compile-draft`, `compile-close`, `context-query`, `drop`, `semantic-reconcile`) whose SKILL.md + canonical `data-model.md` reference define the agent-driven align / compile / query / drop protocols.
-3. **Codex plugin `context`** — a `.codex-plugin/plugin.json` manifest that points Codex at the same `plugin/skills/` directory, exposed through the repo marketplace at `.agents/plugins/marketplace.json`.
+2. **`plugin/` source** — human-maintained command/skill/manifest sources that `scripts/build-plugin.ts` compiles into the four plugin install trees in the `context4ai/context` repo.
 
-The split follows a simple rule: mechanical work is the CLI's job; synthesis work (knowledge alignment, compilation, knowledge-side drop cleanup) is the Claude agent's job. The CLI never calls an LLM.
+The split follows a simple rule: mechanical work is the CLI's job; synthesis work (knowledge alignment, compilation, knowledge-side drop cleanup) is the agent's job. The CLI never calls an LLM. Naming surfaces are deliberately separate: `/context:*` is a Claude slash command, Cursor exposes prefixed command entries such as `/context-align` / `/context-compile`, `Context: ...` / `context-*` is a public skill entry for skill-only agents, `context ...` is the CLI primitive, and `context:skill-*` is an internal procedure invoked by the workflow.
 
 ## Install
 
 ```bash
-# Install the CLI globally (recommended — puts `context` on PATH).
+# 1. Install the CLI globally (required by every plugin path; `context` must be on PATH).
 bun install -g @c4a/context-cli
 context --version
 
-# Install as a Claude Code plugin (adds the /context:* slash commands).
-# The plugin assumes the CLI is on PATH; install -g first.
-claude plugin install @c4a/context-cli
+# 2. Install the plugin for your editor.
+# Claude Code:
+claude /plugin marketplace add context4ai/context
+claude /plugin install context@context
+
+# Codex CLI:
+codex marketplace add context4ai/context
+
+# Cursor:
+# Dashboard → Settings → Plugins → Import → https://github.com/context4ai/context
 
-# Add the Codex repo marketplace when working from the c4a monorepo.
-# The marketplace points at packages/context-cli/plugin.
-codex plugin marketplace add context4ai/c4a --sparse .agents/plugins packages/context-cli/plugin
+# Vercel-style skills (Windsurf / OpenCode / Cline / Copilot etc.):
+npx skills add github:context4ai/context skill-context-align
 ```
 
+All four plugin paths point at the [context4ai/context](https://github.com/context4ai/context) repo (generated from this package's `plugin/` source). They are independent of the npm CLI — the CLI is a hard prerequisite the plugin commands call out to via `$PATH`.
+
 When installed as a Claude Code plugin, the `postinstall` hook checks whether the `context` bin is already on PATH. If not, it prints the two commands you can run yourself (`bun install -g @c4a/context-cli` for registry installs, or `bun link` for a local build). It never spawns an install on your behalf — that would silently substitute a registry build for a local tarball / file: / github: plugin install.
 
+For local checkout development, link installs, or branch-specific plugin testing, see [DEVELOPMENT.md](./DEVELOPMENT.md).
+
 ## Quick tour
 
 ```bash
@@ -37,11 +48,17 @@ context init my-product --with-all-aspects
 # Dedicated knowledge repo: use the current directory as the data root
 context init my-kb --layout root --language English --minimal
 
-# Capture material into raw/ (CLI does the ingestion)
+# Start without aspects; append them later when needed
+context init my-kb --no-aspects
+context init --with-aspects code,openapi
+
+# Capture material as sources (CLI does the ingestion)
 context capture https://example.feishu.cn/docx/<token>
 context capture ./docs/design.md
 context capture --inbox
-context capture-code            # extract TypeScript structure
+context capture --code packages/extract --plan --format json
+context capture --code --module packages/extract --version-from package
+context capture --code          # refresh existing code capture config
 
 # In Claude Code, align → compile → drop are agent-driven
 /context:align                   # agent classifies raw into a Node tree; user confirms
@@ -50,28 +67,42 @@ context capture-code            # extract TypeScript structure
 /context:status
 ```
 
-## Workspace layout
+## Production Agent Contract
+
+For production Agent workflows, `context` is a semantic service. A local path is valid when it is the external capture input (`context capture ./docs/design.md`) or another user-supplied source target. Agent-authored workflow payloads use stdin plus CLI-owned payload handles, not scratch files. After capture succeeds, continue with the returned `source_id`, `block_id`, `source_ref`, `node_slug`, Section id, workflow payload name, scope id, digest, or query text.
+
+Workspace language is also part of the Agent contract. `config.yaml` can set `workspace.language` or `defaults.compile_language`; align and compile expose this as `generation_policy` in `align-segments` and NodeContext. Agents should generate Node titles, summaries, Section prose, and user-facing reports in that language while preserving product names, code identifiers, flags, slugs, `source_ref` values, and exact quoted evidence.
+
+Do not treat the workspace storage tree as the protocol. Agent-facing workflows should not read, list, grep, cat, or derive state from `.context/**`, `raw/**`, `knowledge/**`, `output/**`, archives, cache roots, or rendered Markdown files. Use `context workflow status/show` for workflow payloads, `context source ...` for source metadata, `context mdrive ...` and `context query` for knowledge, and `context status` / `context doctor` / `context verify` for semantic diagnostics.
+
+Agent-facing output should be stable by construction: shared protocol/schema/lookup context comes before task-specific objects, JSON key order is deterministic, and default output does not add current timestamps, random ids, storage paths, or host absolute paths. Existing knowledge is the registry. Use `context mdrive glossary list|match`, `context mdrive node list`, and `context query` to reuse term/service/system/action/domain handles; do not create or read a separate dynamic registry file.
+
+`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 clickable files for user inspection. Developer/debug-only `context debug ...` commands may expose storage paths for diagnostics, but those values are not production Agent workflow inputs.
+
+## Developer Storage Layout
+
+The following tree describes the CLI-owned storage implementation for developers and operators. It is not the production Agent workflow contract.
 
 Embedded layout (default):
 
 ```
 .context/
 ├── config.yaml                  # workspace name, schema version, aspects
-├── raw/                         # immutable captured sources (CLI-owned)
+├── raw/                         # immutable captured source bodies (CLI-owned; metadata lives in _sources.yaml)
 │   ├── _sources.yaml            # authoritative source registry
 │   ├── feishu/<date>-<slug>…md
 │   ├── local/<date>-<slug>…md
-│   └── aspect/code/<date>-<sha7>/
-├── output/                      # align pipeline scratch (not committed)
-│   ├── align.scan.yaml
-│   ├── align.propose.{md,yaml}
-│   ├── align.user-decisions.yaml
-│   ├── align.{md,final.input.yaml}
-│   └── bind.yaml
+│   └── aspect/code/<source-slug>/<snapshot-id>/
+├── output/                      # workflow scratch only; root contains directories, not files
+│   ├── align/                   # align proposal/review/debug scratch
+│   ├── compile/                 # compile context/draft/prepare/review scratch
+│   ├── drop/                    # drop plan/prepare/review scratch
+│   └── archive/                 # archived workflow scratch
+├── .cache/                      # ignored internal cache, including current align binding
 ├── knowledge/                   # synthesized articles (CLI-rendered, agent-directed)
 │   ├── _index.md                # workspace index (derivable, rebuilt by compile --close)
 │   ├── changelog.md             # append-only compile / drop log (derivable from git)
-│   ├── domain/ entity/ action/ concept/   # one directory per Node type
+│   ├── domain/ entity/ action/   # one directory per Node type
 ├── archive/                     # dropped but restorable raw / knowledge artifacts
 └── aspects/<name>/prompt.md     # per-aspect capture prompt templates
 ```
@@ -80,24 +111,23 @@ Root layout (`context init --layout root`) uses the same tree directly in the cu
 
 `context init` also creates `AGENTS.md` inside the C4A data root (`.context/` in embedded layout, current directory in root layout) and, when absent, a same-directory `CLAUDE.md` symlink pointing to `AGENTS.md`. Existing files are kept.
 
-Data model: Node (`domain` / `entity` / `action` / `concept`) + Section (ten kinds — see `plugin/skills/align-scan/references/data-model.md` shipped in the tarball for the canonical tables) + five logical Edge types.
+Data model: Node (`domain` / `entity` / `action`) + Section (ten kinds, mounted by node type) + derived traversal edges. Named concept-layer subjects are modeled as `entity` nodes with the `term` tag when their core content is a stable 1-3 sentence definition. Routing schemes, durable rules, data-shape descriptions, procedures, and design choices live inside the matching domain/entity/action Sections such as `spec`, `principle`, `decision`, `comparison`, or `warning`. `mdrive node list` and `mdrive query` expose a `node_class` (`domain`, `action`, `concrete_entity`, `term`) so glossary-style terms stay visible without flattening them into concrete services/systems.
 
 ## Commands
 
 | Command | Role | Notes |
 |---|---|---|
 | `context init [name]` | CLI | Create or append an embedded `.context/` workspace or a root-layout workspace; copy aspect templates and write `AGENTS.md`. |
-| `context capture <url \| ./path.md [./more.md...] \| --stdin \| --inbox \| --refresh>` | CLI | Ingest documents. Feishu URLs use `lark-cli`; local `.md` files can be captured one at a time, as variadic paths, or as newline-separated paths from stdin. Local source identity follows the captured file's stable origin path, so title edits append snapshots to the same source. Re-capturing an identical dropped source restores its source/raw archive entry without overwriting active knowledge edits. |
-| `context capture-code` | CLI | Snapshot TypeScript packages/symbols/edges. |
-| `context capture-aspect <name>` | CLI | Stub in the current release — every invocation exits non-zero with "planned for a future release". |
-| `context extract <path>` | CLI | Read-only debug print of an extraction; never writes workspace files. |
-| `context align --scan \| --save-scan-decisions <file\|-> \| --propose <file\|-> [--save-input] \| --save-user-decisions <file\|-> \| --finalize <file\|-> [--save-input]` | CLI | Workflow helpers driven by the `/context:align` skill pipeline. Domain commands own align protocol files; agents do not write them directly. |
-| `context compile --context <slug> [--save-output] \| --draft <slug> --input <file\|-> [--plan] [--save-input] \| --close` | CLI | Workflow helpers driven by the `/context:compile` skill pipeline. `--save-*` stores CLI-owned scratch copies under `output/` for close-time archival. |
-| `context mdrive <group> <verb>` | CLI | Knowledge primitive shell: node / section / edge / query / verify / glossary / workspace. Run `context mdrive --help` for subcommands. |
-| `context drop <source-id\|raw-path\|url> --plan` / `context drop --apply-plan <file\|-> --reason <text> [--yes]` | CLI | Plans and applies source retraction: archives affected active raw/knowledge under `archive/`, removes unsupported active Sections/empty Nodes, stamps `_sources.yaml.status=dropped`, appends `[drop]`, and verifies. |
+| `context capture <url \| ./path.md [./more.md...] \| --stdin \| --inbox \| --refresh \| --code [path]>` | CLI | Ingest external documents or code into the source registry. Feishu URLs use `lark-cli`; local `.md` files can be captured one at a time, as variadic paths, or as newline-separated paths from stdin. `--code` snapshots TypeScript packages/symbols/edges through the code aspect. For Agent interaction, run `context capture --code <path> --plan --format json` first, show only package name / module path / version, then capture with repeated `--module <path>`. After capture, continue with source ids and semantic handles, not storage paths. |
+| `context extract <path>` | CLI | Read-only developer/debug print of an extraction; never writes workspace files and is not part of the production Agent workflow. |
+| `context debug <workflow\|source\|workspace\|storage\|command\|snapshot> ...` | CLI | Developer/debug-only path diagnostics. Output is storage-coupled and not a production Agent workflow input. |
+| `context align --scan \| --finalize - --digest <segments-digest>` | CLI | Workflow helpers driven by the `/context:align` skill pipeline. `--scan` returns workflow payload names, scopes, digests, and `generation_policy` when workspace language is configured; agents inspect compact payload views with `context workflow show --view ... --unwrap` and semantic filters. `--unwrap` only removes the workflow metadata envelope; it does not change summary/detail behavior. Finalize by submitting an `align-structure-decision` document through stdin with the matching segments digest. `--schema <name>` prints the exact align workflow input schemas. |
+| `context compile --context <slug> --format json \| --node-cycle <slug> --input - --accept-safe-defaults \| --draft <slug> --input - --plan --prepare \| --close` | CLI | Workflow helpers driven by the `/context:compile` skill pipeline. The context entrypoint prepares durable NodeContext, generation policy, and coverage workflow payloads, then prints semantic payload handles; agents read citation handles through compact `workflow show` views. `--node-cycle` is the low-friction per-node path: it validates the submitted draft, prepares reconcile, accepts mechanically safe defaults, and applies only when no semantic judgment remains. Manual `--draft --prepare → reconcile review/apply` remains the fallback for questions and unsupported evidence. Normal handoff uses stdin plus workflow payload digests; `--save-input` is only an explicit debug scratch copy, not workspace truth. |
+| `context mdrive <group> <verb>` | CLI | Knowledge primitive shell: node / section / edge / query / verify / glossary / workspace. Node/query results include `node_class` to distinguish concrete entities from term definitions. `context mdrive verify workspace --experimental` adds heuristic quality warnings for very thin concrete entities and terms that have grown beyond definition shape; these are warnings, not entity-count limits. `context mdrive query --stats-only` prints only workspace counts; run `context mdrive --help` for subcommands. |
+| `context drop <source-id\|url> --plan [--save-output [file]]` / `context drop --apply-plan --reason <text> --yes` | CLI | Plans and applies source retraction through the current drop workflow. `drop --plan` stores the canonical `drop-plan` workflow payload and returns a digest; `--save-output` is only an optional human-readable scratch copy, not a later input. `reconcile prepare --mode drop` reads the current workflow plan, `reconcile review --prepare-digest <digest>` stores the ready review when semantic decisions are needed, and `drop --apply-plan` consumes the current workflow plan/review without plan or decisions files. |
 | `context purge [--yes]` | CLI | Permanently deletes every archive under `archive/` after a summary + confirmation; active `raw/` and `knowledge/` are not modified. |
 | `context verify` | CLI | Whole-workspace verify (schema, Section mount matrix, contains acyclicity, dropped-source references, dangling `src-N`, body ad-hoc headings, domain-inline-child, duplicate slug). |
-| `context doctor` | CLI | Four-layer diagnostics (output scan / propose / align / knowledge). |
+| `context doctor` | CLI | Workspace diagnostics for current workflow, align output, knowledge, caches, evidence, coverage, semantic ledger, and archive state. |
 | `context status [--format json\|table]` | CLI | Workspace overview + next-action suggestions. |
 | `/context:align`, `/context:compile`, `/context:drop`, `/context:purge` | Agent | Skill-driven wrappers around the CLI; align/compile/drop produce structured JSON/YAML per skill contract, purge delegates to CLI confirmation. |
 | `/context:context <free text>` | Agent | Fuzzy router over the above. |
@@ -115,7 +145,14 @@ bun run --filter @c4a/context-cli typecheck
 bun run --filter @c4a/context-cli lint
 ```
 
-The build chains `scripts/build-plugin.ts`, which reads the Claude and Codex plugin manifest templates and substitutes `__VERSION__` from `package.json`.
+The build chains `scripts/build-plugin.ts`, which reads the human-maintained `plugin/` source and generates self-contained install trees into the nested `c4a-plugins/` directory at the c4a repo root. That directory is an independent git repo (remote: [`context4ai/context`](https://github.com/context4ai/context)) and is `.gitignore`d by c4a. Before running `build:plugin` locally for the first time, clone it:
+
+```bash
+cd /path/to/c4a
+git clone https://github.com/context4ai/context.git c4a-plugins
+```
+
+Plugin marketplace releases are pushed from `c4a-plugins/`, separate from the npm tarball that `@c4a/context-cli` publishes. Do not edit generated build trees directly.
 
 ## License