@c4a/context-cli 0.5.29-beta.22 → 0.5.33-alpha.2

package/README.md

@@ -116,14 +116,22 @@ Data model: Node (`domain` / `entity` / `action`) + Section (ten kinds, mounted
 
 ## Commands
 
+Workflow payload exploration uses a single Agent-facing query protocol:
+
+- `--view` selects the semantic view, such as `source-refs`, `coverage-summary`, `coverage`, or `blocks`.
+- `--token-budget <n>` controls the returned context window size. Budgeted views report `token_budget`, `token_used`, `shown_count`, `total`, `omitted_count`, `truncated`, `selection_policy`, `item_id_field`, and `how_to_explore[]`.
+- `--source`, `--heading`, `--node`, `--type`, `--status`, `--candidate-id`, and `--item-id` only narrow a view. Agents should follow `how_to_explore[]` when `truncated: true` instead of piping JSON through shell tools or manually slicing payloads.
+- Citation-eligible entries appear in `items[]`; background-only entries appear in `context_items[]` when budget allows, with `context_omitted_count` reporting omitted background.
+
 | 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 \| --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 -` | 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; the CLI resolves the current align-segments payload automatically. `--schema <name>` prints the exact align workflow input schemas. |
-| `context compile --scan-changes [--delegated] \| --context <slug> \| --source-refs <slug> \| --node-cycle <slug> --input - --accept-safe-defaults \| --draft <slug> --input - --plan --prepare \| --close` | CLI | Workflow helpers driven by the `/context:compile` skill pipeline. `--scan-changes` returns the incremental compile workset; the context entrypoint prepares durable NodeContext, generation policy, and coverage workflow payloads, then prints semantic payload handles. `--source-refs <slug>` exposes the compact citation handle list for one Node without reading the full NodeContext. `--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 (`status: applied` / `partial-applied` / `review-required`). Manual `--draft --prepare → reconcile review/apply` remains the fallback for questions and unsupported evidence. `--delegated` is a one-time, workflow-level authorization recorded on the initial scan/context/draft/node-cycle command; it lets the CLI auto-accept low-risk weak source support but never bypasses unsupported evidence, type drift, schema errors, or destructive gates. Normal handoff uses stdin and current workflow payloads; digest flags are optional stale guards, not values agents need to extract. `--save-input` is only an explicit debug scratch copy, not workspace truth. |
+| `context align --scan \| --finalize -` | 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 `align-segments` through `context workflow show --payload align-segments --view blocks --token-budget 2000 --unwrap --format json`, then narrow with `--source`, `--heading`, or CLI-provided `how_to_explore[]`. `--unwrap` only removes the workflow metadata envelope. Finalize by submitting an `align-structure-decision` document through stdin; the CLI resolves the current align-segments payload automatically. `--schema <name>` prints the exact align workflow input schemas. |
+| `context compile --scan-changes [--delegated] \| --context <slug> [--view source-refs] \| --node-cycle <slug> --input - --accept-safe-defaults \| --draft <slug> --input - --plan --prepare \| --close` | CLI | Workflow helpers driven by the `/context:compile` skill pipeline. `--scan-changes` returns the incremental compile workset; the context entrypoint prepares durable NodeContext, generation policy, and coverage workflow payloads, then prints semantic payload handles. `--view source-refs --token-budget 2000` is a budgeted projection of `NodeContext.raw_snippets[]` for copying citation handles into draft `source_refs[]`; it is not a separate data source. Coverage payloads are inspected with `context workflow show --payload coverage-candidates --view coverage-summary --token-budget 2000 --unwrap --format json` and narrowed with `--view coverage --type <issue-type>` or `--node <slug>`. `--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 (`status: applied` / `partial-applied` / `review-required`). Manual `--draft --prepare → reconcile review/apply` remains the fallback for questions and unsupported evidence. `--delegated` is a one-time, workflow-level authorization recorded on the initial scan/context/draft/node-cycle command; it lets the CLI auto-accept low-risk weak source support but never bypasses unsupported evidence, type drift, schema errors, or destructive gates. Normal handoff uses stdin and current workflow payloads; digest flags are optional stale guards, not values agents need to extract. `--save-input` is only an explicit debug scratch copy, not workspace truth. |
+| `context workflow show --payload <name> --view <view> [--token-budget <n>]` | CLI | Inspect workflow payloads through semantic views. High-frequency views are `node-context --view source-refs`, `coverage-candidates --view coverage-summary`, `coverage-candidates --view coverage`, and `align-segments --view blocks`. Follow returned `how_to_explore[]` commands for narrowing or budget expansion. |
 | `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; `--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 --decisions -` 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. |