@c4a/context-cli 0.5.41-beta.7 → 0.6.0-alpha.6

package/plugins/codex/skills/continue/references/internal-procedures/skill-prose-compile.md

@@ -0,0 +1,265 @@
+---
+name: skill-prose-compile
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Uses confirmed Context document structure to create source-bound draft prose
+  candidates through `context.compile-actions.v1`, without reading raw
+  snapshots directly.
+tools:
+  - Bash
+---
+
+# skill-prose-compile
+
+Compile confirmed document structure into reviewable draft knowledge.
+
+## TL;DR
+
+- Use this after `context status` reports `structure-ready` or
+  `needs-prose-compile`, or when the user explicitly asks to compile confirmed
+  prose structure into draft pages.
+- The input is already confirmed `context.structure.v1`; do not redesign node
+  ownership, page paths, or relationships here. Return to prose align if those
+  are wrong.
+- Read compile context through CLI views only: `read-plan`, `node-context`, and
+  `schema`. Use align evidence views only when the compile view or validation
+  output gives a specific source ref that needs exact text.
+- Emit `context.compile-actions.v1`; the CLI mirrors source spans, derives
+  `content_mode`, writes review candidates, and enforces source-bound evidence.
+- The `summary` field in each action is the Agent-authored behavior half only:
+  compact source-backed recall text for the cited section. The CLI separately
+  renders the reachability half from confirmed typed edges into review metadata;
+  do not invent edge summaries or relation fields in the action payload.
+- Default to omitted `content` so the CLI mirrors the cited source span.
+  Do not write explicit `content`. If the evidence cannot be represented as a
+  faithful mirrored continuous span, split the section or return to prose align
+  for a confirmed structure change.
+- Before choosing section kind, summary, skip/update, weak-evidence handling, or
+  structure repair, read the current procedure references listed by the CLI as
+  `semantic_reference_files`. These are the migrated compile judgment rules, not
+  summaries.
+- Do not produce or validate compile actions from this entry file alone. If the
+  relevant `semantic_reference_files` have not been read in the current turn,
+  stop and read them first.
+
+<reference>
+
+## User-Facing Gates
+
+Use semantic labels, not SDK function names:
+
+| Gate | Say this | Do not say this first |
+|---|---|---|
+| Compile context | "I will inspect the confirmed structure and each node's planned evidence before drafting sections." | `node-context`, `context.compile-actions.v1` |
+| Source-bound draft | "I will mirror supported source spans into reviewable draft pages and attach summary/kind metadata." | `compileProse` |
+| Non-mirror evidence | "This section cannot be compiled as-is because the evidence is not one faithful source mirror; we need to split or revise the structure." | "The agent can rewrite this automatically." |
+| Structure mismatch | "This compile cannot proceed because the confirmed structure no longer matches the evidence; we need to return to structure confirmation." | Editing `knowledge/` or `unapproved/` directly |
+
+## Runtime Discipline
+
+- Follow `context status`, `routing.next_commands`, compile view
+  `next_action`, and validation diagnostics. Treat CLI commands as the source
+  of truth.
+- Use only the returned `next_action.command` for the next required write.
+  Treat `allowed_actions[]` as permission for read-only insertions; it is not a
+  menu of alternate write paths.
+- Treat `agent_hints[]` as temporary diagnostics. If an agent hint conflicts
+  with a status route, compile view `next_action`, or validation result, follow
+  the top-level route.
+- Do not use direct file tools, shell scripts, `jq`, `sed`, `cat`, `head`,
+  `tail`, Python, or Node.js to inspect `sources/`, `unapproved/`,
+  `knowledge/`, `dist/`, or CLI-managed `.tmp` as a substitute for Context
+  views.
+- Run one write at a time. Do not parallelize compile stage, review apply,
+  close, or build writes.
+- Compile does not get a second, looser rule set. If a rule conflicts with the
+  current CLI schema or diagnostics, follow the CLI and repair the payload.
+- Write digest/hash flags are stale guards. Use values returned by the CLI; do
+  not parse stdout fragments or host tool-result files to reconstruct them.
+- If a payload is too large for a heredoc, stage it under
+  `.tmp/agent-payloads/<run-id>/...` in the workspace root and redirect stdin
+  from that file. Never reuse fixed `/tmp/c4a-*` names, and never place agent
+  scratch payloads under CLI-managed `.tmp/context-cli/`, `sources/`,
+  `unapproved/`, `knowledge/`, `dist/`, review output, or package output
+  directories.
+
+## Compile Views
+
+Recommended read order:
+
+```bash
+context run compile:<type>:<source>:<collection> --view read-plan --format json
+context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json
+context run compile:<type>:<source>:<collection> --view schema --format json
+```
+
+Use CLI-returned `available_view_refs`, `planned_sections`, `local_sources`, and
+`next_action.command`. Do not reconstruct the structure by opening
+`unapproved/structure.yaml` or `knowledge/structure.yaml` directly.
+
+## Procedure References
+
+These are current compile rules for source-bound drafting, judgment, semantic
+repair, and close handoff.
+
+| Decision | Reference |
+|---|---|
+| Compile action drafting, section kind, coverage, summaries, content intent | [skill-prose-compile/references/internal-procedures/compile-actions.md](skill-prose-compile/references/internal-procedures/compile-actions.md) |
+| Action/domain compile gates | [skill-prose-compile/references/internal-procedures/compile-actions/references/action-domain-gates.md](skill-prose-compile/references/internal-procedures/compile-actions/references/action-domain-gates.md) |
+| Notes, refresh/update, and structural challenges | [skill-prose-compile/references/internal-procedures/compile-actions/references/notes.md](skill-prose-compile/references/internal-procedures/compile-actions/references/notes.md), [skill-prose-compile/references/internal-procedures/compile-actions/references/refresh-and-update.md](skill-prose-compile/references/internal-procedures/compile-actions/references/refresh-and-update.md), [skill-prose-compile/references/internal-procedures/compile-actions/references/structural-challenges.md](skill-prose-compile/references/internal-procedures/compile-actions/references/structural-challenges.md) |
+| Support, duplicate, replacement, conflict, weak evidence, and relation judgment | [skill-prose-compile/references/internal-procedures/compile-judgment.md](skill-prose-compile/references/internal-procedures/compile-judgment.md), [skill-prose-compile/references/internal-procedures/semantic-judgment.md](skill-prose-compile/references/internal-procedures/semantic-judgment.md) |
+| Leakage, ownership, temporal evidence, disposition, omit, and user confirmation | [skill-prose-compile/references/internal-procedures/semantic-judgment/references/leakage-and-ownership.md](skill-prose-compile/references/internal-procedures/semantic-judgment/references/leakage-and-ownership.md), [skill-prose-compile/references/internal-procedures/semantic-judgment/references/temporal-and-evidence.md](skill-prose-compile/references/internal-procedures/semantic-judgment/references/temporal-and-evidence.md), [skill-prose-compile/references/internal-procedures/semantic-judgment/references/disposition-semantics.md](skill-prose-compile/references/internal-procedures/semantic-judgment/references/disposition-semantics.md), [skill-prose-compile/references/internal-procedures/semantic-judgment/references/scope-review-and-omit.md](skill-prose-compile/references/internal-procedures/semantic-judgment/references/scope-review-and-omit.md), [skill-prose-compile/references/internal-procedures/semantic-judgment/references/user-confirmation.md](skill-prose-compile/references/internal-procedures/semantic-judgment/references/user-confirmation.md) |
+| Close gate and current close output boundaries | [skill-prose-compile/references/internal-procedures/close-gate.md](skill-prose-compile/references/internal-procedures/close-gate.md) |
+
+## Compile Contract
+
+The compile action payload uses `schema_version: context.compile-actions.v1`.
+Compile may:
+
+- mirror source spans as `verbatim`;
+- emit `skip` decisions when no source-backed body should be written. `skip`
+  does not produce a placeholder candidate; generated parent-index pages use
+  the parent-index compile path, not an action payload placeholder.
+
+Relationships and cross references do not go into verbatim body. In current
+output they stay in `structure.yaml` typed edges; this workflow does not render
+relationship reference blocks.
+
+</reference>
+
+<procedures>
+
+### Step 1 — Open Compile Context
+
+Run:
+
+```bash
+context run compile:<type>:<source>:<collection> --view read-plan --format json
+```
+
+Use the returned node list, source overview, and next action. If the CLI says
+the structure is missing, unconfirmed, stale, frozen against the wrong
+snapshot, or invalid, return to prose align or source capture as indicated.
+
+### Step 2 — Inspect One Node
+
+For each node that should become draft knowledge, run:
+
+```bash
+context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json
+context run compile:<type>:<source>:<collection> --view schema --format json
+```
+
+Read the compile references listed by `semantic_reference_files` before
+classifying section kind, summary, support, skip/update, weak evidence, or
+structure repair.
+
+Do not treat those references as optional background. They are the current
+compile drafting, judgment, and semantic-repair procedures.
+
+When exact evidence text is needed, use the CLI-returned source ref with the
+current evidence view. Do not open snapshot files directly.
+
+### Step 3 — Draft And Validate Actions
+
+Create a `context.compile-actions.v1` payload for the selected view. Prefer
+omitted `content` with `source_refs[]` so the CLI mirrors source spans.
+If the source evidence is non-contiguous or contains separable examples,
+configuration blocks, lists, or procedures, split the compile actions when the
+confirmed structure supports that split. If the structure is too coarse, return
+to prose align and ask the user to confirm a section split instead of writing
+summarized body text. Explicit `content` / `content_intent` is not part of the
+current compile contract.
+
+For small payloads, use stdin/heredoc. For larger payloads, write a scratch file
+under `.tmp/agent-payloads/<run-id>/` and pass it through `--input`. Scratch
+files are disposable agent working files; they are never compile state and must
+not be read back as a substitute for CLI views.
+
+Validate:
+
+```bash
+context run compile:<type>:<source>:<collection> --validate --input <compile-actions.yaml> --format json
+```
+
+Repair diagnostics by routing them to the right decision:
+
+- source ref or planned-section mismatch -> reread node-context, or return to
+  structure confirmation if ownership is wrong;
+- unsupported kind or op -> use the schema view and current compile references;
+- explicit content -> omit `content` and mirror source, or return to align for
+  a section split;
+- weak evidence, duplicate, conflict, omit, or scope issue -> use the compile
+  judgment / semantic judgment references and ask the user when required;
+- frozen structure mismatch -> rerun status and return to align/capture as
+  directed.
+
+Use typed diagnostics as the repair contract:
+
+- `reason_code`, `path`, and `missing[]` identify what to fix;
+- warnings are not write blockers unless the response marks them blocking or
+  the next action says so;
+- weak evidence, duplicate, conflict, temporal, leakage, ownership, and scope
+  issues are semantic review issues, not formatting problems;
+- raw/source-ref pointer diagnostics are evidence checks, not content-quality
+  judges.
+
+When validation returns a new `next_action.command`, follow that exact command.
+When it returns blocking diagnostics without a write command, repair and
+validate again. Do not stage a compile payload just because the YAML shape looks
+valid.
+
+### Step 4 — Stage Draft Candidates
+
+Stage only after validation has no errors:
+
+```bash
+context run compile:<type>:<source>:<collection> --stage --input <compile-actions.yaml> --format json
+```
+
+After staging, return to `context status`. If status reaches
+`compile-ready-for-review`, delegate review to
+`skill-review-gate.md`.
+
+### Step 5 — Close Handoff
+
+After review apply, return to `context status`. If status says
+`compile-close-needed`, run deterministic close:
+
+```bash
+context close --format json
+```
+
+Close derives `knowledge/structure.yaml` and edge projection from approved
+knowledge, then runs the final verify gate. It must not rewrite approved
+verbatim body. References, changelog, package index, and section fingerprint
+rebuilds are not current close output.
+
+Then route to package output when status reaches `ready-to-build`.
+
+### Step 6 — Self-verify Checklist
+
+- [ ] Compile started from confirmed structure, not a new structure proposal.
+- [ ] Node context and schema came from compile phase views.
+- [ ] Compile references were read before choosing kind/summary/support.
+- [ ] Actions mirror source by default and do not invent body text.
+- [ ] No explicit reader-visible `content` was written by the Agent.
+- [ ] Relationships are expressed as structure edges, not inserted into
+  verbatim text.
+- [ ] No direct edits were made to `sources/`, `.tmp`, `unapproved/`,
+  `knowledge/`, review HTML, or `dist/`.
+
+### Final Report
+
+Report in the user's language. Include only:
+
+- view refs compiled in this round;
+- candidate ids staged and whether they contain verbatim or empty sections;
+- validation warnings that still matter for review;
+- whether review, close, verify, or build is the next status route.
+
+Do not report internal payload digests, source-ref hashes, internal workspace
+paths, absolute paths, scratch file paths, or raw CLI JSON unless the user asks
+for debug output.
+
+</procedures>

package/plugins/codex/skills/continue/references/internal-procedures/skill-review-gate.md

@@ -0,0 +1,98 @@
+---
+name: skill-review-gate
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Opens the review UI, waits for user decisions, applies copied JSONL payloads,
+  and prevents agent-authored approval/rejection decisions unless the user
+  explicitly requests the scoped quick-decision path.
+tools:
+  - Bash
+---
+
+# skill-review-gate
+
+Run the human review gate. The user decides approval or rejection.
+
+## TL;DR
+
+- The agent never approves or rejects candidates on the user's behalf.
+- Use `context review html <collection> --open` for visual review.
+- `<collection>` is an internal production collection such as `architecture`,
+  `sop`, `decision`, or `standards`; it is not an OKF package root such as
+  `wikis`, `guides`, or `rules`.
+- If browser opening fails or the host cannot make a path clickable, provide the
+  `file://` URL.
+- Apply only the JSONL payload copied by the user from the review UI.
+- Do not parse `unapproved/entities.jsonl`, `.tmp`, or HTML internals with
+  scripts to synthesize decisions.
+- If the user explicitly asks for quick or automated approval/rejection, use
+  `context review approve <candidate-id> --collection <collection>` /
+  `context review reject <candidate-id> --collection <collection>` or `--all`;
+  these commands still enforce the current scoped candidate-id gate.
+
+<procedures>
+
+### Step 1 — Open Review
+
+For the internal collection reported by status, run:
+
+```bash
+context review html <collection> --open
+```
+
+Tell the user where the page opened. If needed, provide a clickable
+`file://.../<collection>.html` URL or the exact path printed by the CLI. Do
+not assume a fixed review filename; review scope is collection or `--all`.
+Do not substitute OKF package roots (`wikis`, `guides`, `rules`) for this
+argument; review scope is the internal collection namespace.
+
+Explain that this page is the human gate between draft candidates and approved
+knowledge. Approved entries become Markdown under `knowledge/`; rejected entries
+stay in the committed ledger and are not written as knowledge pages. The agent
+must not choose these states.
+
+### Step 2 — Wait For Payload
+
+Ask the user to review candidates in the HTML page, open Payload, copy the
+compact JSONL payload, and paste it into the agent chat. The payload records the
+user's decisions, usually as a default decision plus exceptions, so it should
+not be expanded into pretty JSON unless the user asks.
+
+The user should not need to create a payload file manually. Do not continue
+until the user supplies that payload.
+
+If the user instead explicitly asks the agent to use the quick approval or
+rejection path, do not synthesize JSONL. Run the scoped quick command with the
+candidate id shown by review/list/status and either `--collection <collection>`
+or `--all`.
+
+### Step 3 — Apply Payload
+
+After the user pastes the payload into chat, the agent writes it to a normal
+temporary file under the current workspace `.tmp/` directory and runs:
+
+```bash
+context review apply <payload-file>
+```
+
+Do not accept or emit alternate `{ "decisions": [...] }` JSON. Use only
+`context.review.decisions.v1` JSONL.
+Do not use unsupported scratch, workflow, compile, or `.context/config.yaml`
+commands to store this payload.
+
+### Step 4 — Return To Status
+
+Run `context status` after apply. If it reports package output choice, return to
+`skill-continue-workflow.md`.
+
+### Step 5 — Self-verify Checklist
+
+- [ ] Every decision came from the user's copied payload. If not, stop and
+  discard the agent-authored decision, unless the user explicitly requested a
+  scoped quick command and that command used `--collection` or `--all`.
+- [ ] Payload was applied through `context review apply`. If not, return to
+  **Step 3**.
+- [ ] No direct edits were made to `knowledge/` or `unapproved/`. If not, report
+  the protocol error.
+
+</procedures>

package/plugins/codex/skills/continue/references/internal-procedures/skill-source-scope/references/capture-source.md

@@ -0,0 +1,180 @@
+---
+name: capture-source
+description: >
+  Capture local Markdown or Lark/Feishu document sources through registered
+  Context sources and declared capture phases. Use the local `context` CLI for
+  workspace writes.
+tools:
+  - Bash
+---
+
+# Capture
+
+Current capture discipline for document sources. The executable path is source
+registration plus the declared capture phase flow:
+
+- local Markdown/MDX file source: `context source add file <name> --local <path>`
+  followed by `context run capture:file:<name> --format json`;
+- Lark/Feishu source: `context source add lark <name> ...` followed by
+  `context run capture:lark:<name> --format json`;
+- refresh: rerun the same declared capture phase after status or the user asks
+  for recapture.
+
+Use only commands surfaced by the current status output or capture phase.
+
+---
+
+## Workflow
+
+Capture is entirely CLI-driven — your role is to register the right source,
+declare the matching capture phase, run the current `context run capture:*`
+command, and relay its output. Never hand-write captured source snapshots: the
+CLI owns normalisation (NFC, BOM strip, line endings) and the `content_hash`
+contract, so any manual edit breaks idempotency.
+
+### Code capture diagnostics
+
+Do not run hand-written dependency preflight commands before code extraction or
+document capture. The CLI owns configured runner/plugin resolution and returns
+structured `agent_hints[]` when a runner or remote-document helper is missing or
+misconfigured.
+
+If code extraction capture fails with install or runner hints, surface the CLI's `agent_hints[]` command exactly as printed. Ask the user once whether to run that command on their behalf when it touches shared state. If approved, run the exact command from `agent_hints[0].command`, then retry the same capture command. If declined, leave the command visible so the user can run it manually. Do not inline extraction packages, do not hand-write code snapshots, and do not continue with partial capture.
+
+Invocation note: document capture and code extraction do not run through `npx`.
+Use the installed `context` CLI and the declared phase command returned by
+`context status` or the phase view. When external helpers are missing, surface
+the CLI's structured install hints instead of substituting your own package
+manager or version.
+
+### Route by source boundary
+
+Before choosing a local Markdown capture route, honor the surrounding task context. Driver documents such as run instructions, handbooks, READMEs, plans, feedback issues, corpus/index/manifests, and batch lists are not Context sources unless the user explicitly asks to ingest them. Capture only ingest targets that are already explicit in the user request; if they are missing, ask one clarification instead of capturing the driver document.
+
+- One or more local `.md` / `.mdx` files or a local documentation folder to ingest →
+  register one file source with the user-confirmed source name and boundary:
+  `context source add file <name> --local <file-or-folder>`. For an explicit
+  batch inside a broader folder, preserve the user's include list on source
+  registration. Default file capture handles `.md`. If the CLI reports
+  document-site files such as `.mdx`, `_meta.json`, sidebars, or docs config,
+  stop and confirm whether the selected boundary is a documentation site before
+  changing capture configuration. For MDX documentation sites that use
+  `_meta.json`, declare `mdxJsonDocs()` on `captureFile` in `src/index.ts`;
+  keep `_meta.json` only when it is route metadata for the selected document
+  folder. The CLI captures it as metadata and generates
+  `__context_route_metadata.md` as mechanical route evidence; it also extracts
+  static MDX component props/children into `__context_mdx_component_text.md`
+  when components carry user-facing text. Declare
+  `captureFile({ source: source("<name>"), processor: mdxJsonDocs() })`, then
+  run `context run capture:file:<name> --format json`. If the selected MDX page
+  is empty or only mounts runtime-rendered content, tell the user that capture
+  found a document-site shell and ask for the rendered-site or data-source
+  boundary instead of inventing body text.
+- A Lark/Feishu URL, doc token, or wiki token → register one Lark source:
+  `context source add lark <name> --url <url>` or the matching token flag.
+  Declare `captureLark({ source: source("<name>") })`, then run
+  `context run capture:lark:<name> --format json`.
+- Mixed local document and Lark document batches are separate sources unless
+  the current CLI explicitly offers a combined source contract. Do not write an
+  Agent-side URL/file loop.
+- Refresh or recapture request for an already registered file/Lark source →
+  rerun the same declared capture phase. The CLI appends a new snapshot only
+  when content changes and never overwrites prior snapshots.
+- Code package extraction is not document capture. Route code source selection
+  through `skill-source-scope` extraction preview and the declared extract
+  phase. Do not invent a document capture path for code.
+- Conversation notes, decisions, and revision intents are not document capture
+  sources in the current workflow unless the CLI status or project-specific
+  phase exposes an explicit note source contract. If absent, record the user
+  guidance in the conversation and use it as pre-align hints, not as a snapshot
+  write.
+
+Do not discover files with `find` / `ls` when the user already supplied paths.
+If the include set is large, summarize it and ask for confirmation before
+registration; do not read file bodies before capture permission is clear.
+
+### Output Handling
+
+Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
+
+- Run `context status --format json` and use its `state`, `routing`, and
+  `next_commands`.
+- If status reports `captured-ready-to-investigate`, suggest the returned
+  `context run align:<type>:<source>:<collection> --view read-plan --format json`
+  command and hand off to `skill-prose-align`.
+- If status reports `needs-structure` or `structure-ready`, follow the returned
+  align/compile command instead of naming a generic slash command.
+- If status reports `compile-ready-for-review`, route to the review gate.
+- If the source was code-only and status reports pending code projection,
+  follow the CLI-owned extract/compile route returned by status.
+
+Never suggest prose compile or hand-built document knowledge for a code-only
+source. Code sources become active knowledge only through the declared
+extraction/review route returned by `context status`.
+
+If capture is rejected because another phase or write gate is active, do not
+discard it automatically. Explain the active state from `context status`, follow
+that phase when it is the intended task, and ask the user before discarding
+in-progress work when a current project command exists. If the user expected a
+different repository/workspace, change to the confirmed workspace root before
+retrying capture.
+
+## Final Report
+
+Report in the user's conversation language. Translate section headings into the user's language instead of copying the English labels below verbatim. Optimize for human readability: use document titles instead of source ids, package names instead of internal source id strings, and human-readable kind labels ("local markdown", "Feishu doc", "code package") instead of internal tokens. Do not surface content hashes, snapshot digests, internal payload identifiers, or absolute file paths.
+
+Stable structure:
+
+1. Completion headline. Single line with the action verb plus core counts: how
+   many sources were captured this round, broken down by `new` / `updated` /
+   `unchanged`. Capture data from the current `context run capture:* --format
+   json` result summary, or per-source statuses when no aggregate is returned.
+2. Per-source list grouped by status. Show each captured source under one of three groups (`new` / `updated` / `unchanged`); within each group list the document title (`source.title`), kind label, and a short delta indicator for updated sources (for example added/removed line counts when the CLI returns them; otherwise "content changed"). Cache-hit code packages belong in `unchanged`. Omit groups that are empty.
+3. Pending phase signals. When `context status --format json` reports follow-up
+   work tied to this capture (sources pending align, sources pending compile,
+   refreshed sources pending recompile, code sources pending projection),
+   summarize each as a single line naming the work and which sources are
+   affected. Omit the section entirely when there is no pending follow-up.
+4. Next step. Single command suggestion driven by status: the returned
+   `context run align:<type>:<source>:<collection> ...` command when structure work is
+   pending, the returned `context run compile:<type>:<source>:<collection> ...`
+   command when prose compile work is pending, or the CLI-owned code projection
+   command when code projection is pending. If nothing is pending, say so
+   explicitly.
+
+Do not include raw CLI diagnostics, agent_hints content, schema names, or phase
+payload identifiers in the report. Those belong in earlier troubleshooting
+output, not in the completion summary.
+
+## Reference
+
+### Missing Dependency Recovery
+
+If the CLI returns `agent_hints[]` for a missing code runner or plugin package, stop and surface the hint. Ask the user once for permission to run `agent_hints[0].command` (the CLI has already picked the correct package manager — `npm install -g` or `bun install -g` — based on how `context` itself was installed). If approved, run that exact command via `Bash` and then retry the same capture; if declined, leave the command visible for manual install. Never substitute a different package manager or version.
+
+If the CLI prints a missing-dependency error like `lark-cli not installed`, walk the user through installation:
+
+1. Ask once up-front whether to proceed with install. If no → stop and tell the user to install manually from the tool's official README, then re-run.
+2. `WebFetch` the tool's official README (for `lark-cli` that's `https://github.com/larksuite/cli/blob/main/README.md#quick-start-ai-agent`).
+3. For each command the README prescribes for the user's platform, show the command then call `Bash`. The host's per-tool permission prompt is the user's confirmation surface; don't add extra y/n questions between commands.
+4. Stop on any failure; surface stderr verbatim.
+5. After success, tell the user to rerun the current Context command that
+   failed.
+
+### Language Policy
+
+Your prose to the user follows the user's conversation language. CLI commands, flag names, URLs, env-var names, binary names, source-ids stay English.
+
+### Invariants
+
+- Captured source snapshots are immutable post-write — the CLI only ever appends new snapshots.
+- The source registry is authoritative; derived index files are not Agent phase
+  inputs.
+- Local `.md` / `.mdx` source identity follows the captured file's stable origin path, not its H1/title. If the user edits the title but captures the same path again, the CLI appends a new snapshot to the same `local:*` source.
+- In `--format json`, code capture runner cache state is authoritative in `result.runner.cacheMode`: `prepared` means a workspace runner was prepared, `cached` means workspace cache hit, and `bypass` means `--no-runner-cache` used a temporary runner directory instead of the workspace runner cache.
+- Code extraction runner evidence is derived by the CLI from emitted source files. Do not ask users to configure `evidence.mode`; rerun capture after fixing the runner emit output.
+- Code extraction snapshots ship with `evidence.mode: none`; symbols/files/edges are indexed inside the code bucket. Do not ask users to inspect or repair a code `.evidence` manifest.
+- Code extraction/projection is separate from document capture. Materialize code
+  knowledge through the declared extract/code projection flow before prose align
+  attaches documentation to code Nodes.
+- On duplicate capture of the same URL: identical `content_hash` → CLI skips with `unchanged`; different hash → CLI appends a new snapshot.