@c4a/context-cli 0.6.0-beta.5 → 0.6.0-beta.7

package/README.md

@@ -19,8 +19,8 @@ stable protocol text and are not translated.
 ## Global Plugin + Project Workspace
 
 ```bash
-# Install or refresh global agent commands/skills.
-bunx @c4a/context-cli plugin install
+# Install the CLI and refresh available global agent commands/skills.
+npm install -g @c4a/context-cli
 
 # Create a standalone context project.
 context init context
@@ -30,6 +30,11 @@ bun install
 /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
@@ -55,7 +60,9 @@ node_modules/@c4a/context/templates/package-templates/
 Agents should read these files instead of probing `node_modules/@c4a/context/dist`
 with temporary scripts.
 
-For local checkout development and link installs, see [DEVELOPMENT.md](./DEVELOPMENT.md).
+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).
 
 ## Project-local quick tour
 
@@ -137,20 +144,28 @@ For project workflows, `context` is a semantic service. Agents should call the C
 | `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 testing before `@c4a/context` 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]` | 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` is the verified codegraph-only CI/CD mode. |
+| `context run <phase-id> [--dry-run] [--auto-promote]` | 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. 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 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 [--format json\|table]` | CLI | Workspace overview + a canonical `next:` hint. 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.
+
 ## Development
 
 Source lives at [`packages/context-cli/`](./src) in this workspace.