@c4a/context-cli 0.5.29-alpha.1

package/README.md

@@ -0,0 +1,122 @@
+# @c4a/context-cli
+
+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:
+
+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`.
+
+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.
+
+## Install
+
+```bash
+# Install the CLI globally (recommended — puts `context` 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
+
+# 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
+```
+
+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.
+
+## Quick tour
+
+```bash
+# Initialize a workspace in the current project
+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)
+context capture https://example.feishu.cn/docx/<token>
+context capture ./docs/design.md
+context capture --inbox
+context capture-code            # extract TypeScript structure
+
+# In Claude Code, align → compile → drop are agent-driven
+/context:align                   # agent classifies raw into a Node tree; user confirms
+/context:compile                 # agent writes Section-level actions for each Node; CLI renders
+/context:drop feishu:doc:xxx --reason "obsolete"
+/context:status
+```
+
+## Workspace layout
+
+Embedded layout (default):
+
+```
+.context/
+├── config.yaml                  # workspace name, schema version, aspects
+├── raw/                         # immutable captured sources (CLI-owned)
+│   ├── _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
+├── 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
+├── archive/                     # dropped but restorable raw / knowledge artifacts
+└── aspects/<name>/prompt.md     # per-aspect capture prompt templates
+```
+
+Root layout (`context init --layout root`) uses the same tree directly in the current directory: `config.yaml`, `raw/`, `output/`, `knowledge/`, `archive/`, `aspects/`, and `inbox/` live at repo root. Root layout is intended for dedicated knowledge repositories; initialization refuses to run if those C4A-owned entries already exist.
+
+`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.
+
+## 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 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 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. |
+
+CLI commands that require a workspace exit with a workspace-not-found error if run outside a directory tree containing either embedded `.context/` layout or root layout; `context init` is the only command that creates one.
+
+## Development
+
+Source lives at [`packages/context-cli/`](./src) in the c4a monorepo.
+
+```bash
+bun run --filter @c4a/context-cli build      # bundle CLI + render plugin.json
+bun run --filter @c4a/context-cli test       # unit + integration tests
+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`.
+
+## License
+
+MIT.