@c4a/context-cli 0.6.0-beta.4 → 0.6.0-beta.6

package/README.md

@@ -55,7 +55,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
 
@@ -77,6 +79,11 @@ context source add repo sample-lib --local ../sample-lib
 # Do not register the parent monorepo and use extractTs.include as a package selector.
 context source add repo sample-lib --local ../packages/sample-lib
 
+# 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.
+
 # Optional overrides when origin / HEAD cannot be inferred:
 context source add repo sample-lib \
   --local ../sample-lib \
@@ -132,20 +139,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]` | CLI | Inspect or run one declared phase. Dry run prints reads/writes and, for extract phases when sources are ready, a resolved preview with modules, file counts, symbol counts, candidate estimates, and module error hints. It does not mutate project files. |
+| `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.