@c4a/context 0.6.0-alpha.1

package/docs/guides/agent-dialogue.md

@@ -0,0 +1,325 @@
+# Agent Dialogue
+
+This guide defines how agents should talk to users while operating a Context
+workspace.
+
+## Principle
+
+Talk about the user decision first, then the implementation detail.
+
+Do not start a human gate by exposing internal API names, default option names,
+or placeholder commands. The user needs to understand:
+
+- what decision is being made;
+- what will happen after they approve;
+- what files or knowledge shape will be affected;
+- what alternatives they can choose.
+
+CLI commands, source names, phase ids, status values, payload keys, and
+`source_ref` values are protocol text. Keep those exact when needed, but do not
+make them the main explanation.
+
+## Human Gate Question Form
+
+When the decision has a small fixed option set, use the host's native
+multi-choice tool when available:
+
+- Claude Code: `AskUserQuestion`
+- Codex: use the available native user-input tool, for example
+  `request_user_input` when it is exposed
+- Cursor Plan Mode: `AskQuestion`
+
+If no native question tool is available, fall back to Markdown `A/B/C` choices.
+Each option must include a short impact statement. Do not ask an open-ended
+free-text question when the actual workflow has two or three known branches.
+The option labels must be semantic user choices, not API or factory names. Use
+implementation names such as `alignProse`, `compileProse`, `kbPackage`, or
+`llmsPackage` only in a technical follow-up, command, or `src/index.ts` change
+summary.
+
+Examples:
+
+- document structure gate: continue material investigation vs add user
+  structure guidance vs narrow the captured source;
+- package output: agent knowledge-base package vs LLM text bundle vs skip for
+  now;
+- stale approved page: create a replacement review candidate vs confirm the
+  existing content is still valid;
+- orphaned approved page: mark the page deprecated vs keep it as unverifiable
+  knowledge.
+
+## Source Boundary Gate
+
+Bad:
+
+```text
+Please provide source name:
+context source add repo <name> --local <repo-or-subdir>
+```
+
+Good:
+
+```text
+Next we need to choose the knowledge source.
+
+If you want one manual for only this package, choose the package directory as
+the source boundary. If you want one manual for the whole subspace, choose the
+subspace root.
+
+The source name becomes part of source refs, phase ids, and package names.
+Approved knowledge paths are derived from collection, containment, and slug;
+NodeRef/ViewRef are identity fields, not path strings:
+knowledge/<collection>/<containment>/<slug>.md
+repo:<source-name>#...
+dist/<source-name>-kb/...
+
+If the user already gave a path and only the source name is missing, still
+explain what the name means:
+
+- if the path is one package/module, the name appears once in source refs and
+  phase ids;
+- if the path is a parent monorepo/subspace, the name is a parent namespace and
+  child modules can appear below it later;
+- current extraction should inspect a parent source first, then extract from
+  a confirmed package/subdirectory boundary.
+
+For a multi-module subspace package shape, a parent name such as product-ui
+can group children like:
+knowledge/codegraph/product-ui/component-web/...
+knowledge/codegraph/product-ui/component-lynx/...
+
+For the current first extraction, I will still ask you to confirm the concrete
+package/subdirectory boundary before reading code.
+```
+
+Only after that explanation should the agent show the concrete command it will
+run.
+
+## Document Read Permission Gate
+
+Bad:
+
+```text
+Running capture:file:docs now.
+```
+
+Good:
+
+```text
+The source is registered, but registration did not read the document body.
+
+The next operation will read this local Markdown file or folder and write a
+committed snapshot under `sources/file/<source-name>/`. That snapshot is used
+later for review, verify, and fresh-clone reproduction.
+
+Please confirm that I may read this document source now. After you confirm, I
+will declare the capture phase in `src/index.ts`, summarize that change, and
+run the capture command.
+```
+
+For Lark / Feishu:
+
+```text
+The source is registered, but registration did not fetch the remote document.
+
+The next operation will read the Lark/Feishu document you provided and write a
+normalized snapshot under `sources/lark/<source-name>/`. The snapshot is
+committed by default so verify can work offline and after a fresh clone. Access
+credentials stay in the Lark CLI; they are not written to this workspace. If
+your business repository wants to ignore this snapshot, that is a repository
+policy decision and verify will report degraded offline evidence later.
+
+Please confirm that I may read this remote document now.
+```
+
+Do not run capture preview, capture, or refresh before this permission is clear.
+
+## Document Investigation Gate
+
+Bad:
+
+```text
+Run align:file:docs:architecture or compile:file:docs:architecture?
+```
+
+Good:
+
+```text
+The document source has been captured into a committed snapshot.
+
+Capture summary:
+- documents: <count>
+- title tree: <top-level titles or heading groups>
+- evidence views: read-plan, source-index --compact, span-detail, span-text
+
+Next I will investigate the material and propose a structure draft. That draft
+decides:
+
+- which knowledge pages should exist;
+- which sections belong to each page;
+- which relationships have source-backed evidence;
+- which questions remain unresolved.
+
+Confirming the structure will freeze paths, section ownership, relationships,
+and compile order for this round. No approved Markdown is written before review.
+
+You can choose:
+A. Continue material investigation and let me propose the structure draft.
+B. First give structure preferences, such as expected domains or naming.
+C. Go back and narrow or correct the captured source.
+```
+
+After the user chooses, update `src/index.ts` if the matching align/compile
+phases are not declared yet, then summarize the change. For example:
+
+```text
+I updated the project flow to add document structure planning and source-bound
+compile for `product-docs`. No approved Markdown is written yet. The next gate
+is a structure draft for your confirmation.
+```
+
+If the user asks for one page per source document, explain that it is modeled as
+a simple structure draft. It still goes through structure confirmation and
+source-bound compile; there is no separate shortcut that writes final page body
+directly from capture.
+
+## Extraction Scope Gate
+
+Bad:
+
+```text
+是否按 Context 默认范围继续？
+extractTs({
+  source: source("component-lib"),
+  collection: "codegraph",
+  // include defaults to ["src/**/*.{ts,tsx}"]
+  // exportedOnly defaults to true
+})
+```
+
+Good:
+
+```text
+The source is ready and resolves to one package.
+
+Proposed extraction:
+- read TypeScript/TSX files under `src/`;
+- only include exported symbols such as components, functions, types, and props;
+- create draft candidates for human review;
+- no approved Markdown is written until you review the candidates.
+
+This means files outside `src/` and non-exported/internal helpers are skipped.
+If you want docs, tests, examples, or internal APIs included, say that before
+extraction.
+
+I will first generate a preview without writing candidates. The preview will
+show the file count, symbol count, candidate count, and planned `knowledge/`
+tree. I will only run extraction after that preview matches your expectation.
+```
+
+Mention `extractTs`, `include`, `exportedOnly`, or `reviewValidity` only if the
+user asks for implementation details, or when editing `src/index.ts` in a code
+summary.
+
+## Review Gate
+
+Bad:
+
+```text
+Run reviewValidity and apply payload.
+```
+
+Good:
+
+```text
+Draft candidates are ready. The next step is human review.
+
+Open the review HTML, approve or reject candidates, then copy the Payload back
+into chat. I will only apply the payload you provide; I will not approve or
+reject candidates on your behalf. Review decides which draft entries become
+approved Markdown under `knowledge/`, and which entries stay rejected in the
+ledger.
+
+You do not need to save a payload file; I will write a temporary file and run
+the apply command.
+```
+
+## Package Gate
+
+Bad:
+
+```text
+Choose one: skills, llms, both, none.
+```
+
+Good:
+
+```text
+Approved knowledge is ready. Now choose how it should be packaged.
+
+Recommended first output is an agent knowledge-base package:
+dist/<name>-kb/
+├── AGENTS.md
+├── skills/knowledge-query/SKILL.md
+└── wikis/
+    ├── index.md
+    ├── <group>/index.md
+    └── <group>/...
+
+This gives agents a reusable knowledge-query skill plus copied approved
+knowledge pages. The
+default query skill starts from OKF indexes, cites page/section evidence, uses
+structure/build metadata when present, and reports gaps rather than inventing
+unsupported answers. The template under `src/package-templates/kb/` is editable
+before build, including `wikis/index.md` for bundle scope and query guidance.
+The root index should stay shallow by default: it lists next-level directories,
+and `context build` generates child directory indexes so users can browse from
+bundle to group to page.
+```
+
+Offer the alternatives as user-facing choices:
+
+- Agent knowledge-base package: creates `dist/<name>-kb/` for agents to query
+  and cite approved knowledge pages.
+- LLM text bundle: creates `dist/<name>-llms/` for one text/RAG import bundle.
+- Skip for now: leaves approved Markdown in `knowledge/` without a `dist/`
+  package.
+
+Do not offer `both` as a shortcut. If the user wants multiple outputs, declare
+one package first, build and inspect it, then ask before adding another. Use
+`kbPackage` / `llmsPackage` only after the user has chosen the semantic output
+shape.
+
+## Evidence Maintenance Gates
+
+When approved knowledge still exists but the source evidence changed, explain
+that the approved page remains usable but is no longer fully current against
+the latest snapshot.
+
+Use semantic choices:
+
+- Create an updated draft for review: best when the source change may require
+  wording, scope, or facts to change. This creates a replacement candidate and
+  still requires review.
+- Confirm the current page is still valid: best when the source change is only
+  formatting, typo cleanup, or otherwise does not affect the approved content.
+  This re-binds the page to the current evidence without changing its body.
+
+When an approved page points to a source document that no longer exists in the
+current snapshot, do not offer replacement or re-binding. Use semantic choices:
+
+- Mark the page as deprecated: removes it from later package output while
+  preserving audit history.
+- Keep it as source-orphaned knowledge: leaves it approved, but verify/status
+  will keep reporting an evidence warning.
+
+## Reporting
+
+Keep reports short and state transitions oriented:
+
+- commands run;
+- current state;
+- what changed;
+- the next human decision, if any.
+
+Do not paste long raw CLI transcripts unless the user asks for exact output.

package/docs/guides/agent-guide.md

@@ -0,0 +1,313 @@
+# Agent Guide
+
+This guide is for Coding Agents operating a Context workspace.
+
+## Start Here
+
+1. If a public Agent entry is available, use the installed Context continuation command/skill from the project root; the exact slash command or skill name is host-specific.
+2. If you are implementing that entry or operating without plugins, run `context status`.
+3. Execute safe mechanical CLI `next:` steps instead of merely reporting them.
+   Stop and ask at `Human gate:` next steps, placeholder next steps, human
+   decision gates, or external source-repo operations.
+4. Before editing `src/index.ts`, read [Project API](../reference/project-api.md).
+5. Before declaring or repairing packages, read [Package Outputs](./package-outputs.md)
+   and [Package Templates](../reference/package-templates.md).
+6. Before asking a human gate question, read [Agent Dialogue](./agent-dialogue.md).
+
+If the installed docs are unavailable, run `bun install` in the Context workspace.
+
+## Dialogue Language
+
+Use the user's current conversation language for explanations, questions,
+confirmations, and final summaries. Treat CLI output, commands, flags, file
+paths, ids, status values, JSONL payload keys, and `source_ref` tokens as
+protocol text: copy those exactly and do not translate them.
+
+At human gates, explain the product decision and impact before internal API
+details. Do not start with `extractTs`, `include`, `exportedOnly`,
+`reviewValidity`, placeholder commands, or raw TypeScript snippets unless the
+user asks for implementation detail. The required dialogue patterns are in
+[Agent Dialogue](./agent-dialogue.md).
+
+## Do Not Self-Discover The SDK
+
+Do not write temporary scripts to inspect `node_modules/@c4a/context/dist/index.js`
+or infer API shapes from bundled output. The public contract is documented in:
+
+```text
+node_modules/@c4a/context/docs/reference/project-api.md
+node_modules/@c4a/context/docs/reference/package-templates.md
+```
+
+## Workspace State Rules
+
+- `src/index.ts` declares sources, phases, and packages.
+- `sources/repo/index.yaml`, `sources/file/index.yaml`, and `sources/lark/index.yaml` declare sources.
+- `unapproved/entities.jsonl` is the committed draft/rejected/deprecated ledger.
+- `knowledge/` contains approved Markdown.
+- `dist/` contains generated package outputs.
+- file and Lark snapshots live under `sources/file/<name>/` and `sources/lark/<name>/`.
+- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks.
+
+Do not create hidden workspace state directories.
+
+## Workflow Entrypoints
+
+Present only the current workflow surface:
+
+| Task | Current route |
+|---|---|
+| Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
+| Capture document sources | Run the declared `capture:file:<source>` or `capture:lark:<source>` phase only after read permission. Capture writes committed snapshots under `sources/file/<name>/` or `sources/lark/<name>/`. |
+| Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
+| Confirm prose structure | `alignProse` validates and stages `unapproved/structure.yaml`. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
+| Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |
+| Review and apply | Use `context review html` and `context review apply`. Approved prose pages are source-mirrored; rewrite/compression problems should return to structure/compile repair before apply. |
+| Close, verify, build | Run `context close`, `context verify`, then `context build`. Close derives `knowledge/structure.yaml`, approved edge projection, and the final verify gate. |
+| Code extraction | Use `context source inspect <source-name>` and the declared extract phase preview before code draft writes. |
+| Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `unapproved/`, `dist/`, or `.tmp` to simulate lifecycle actions. |
+
+Judgment behavior is part of evidence views, source span resolvers, repair
+hints, review/status diagnostics, OKF indexes, and package query discipline. Do
+not describe unsupported commands or unsupported lifecycle state as alternate
+routes.
+
+## Source Safety
+
+The CLI never silently clones, checks out, resets, fetches, installs, builds, or
+runs scripts inside source repositories. If a repo operation is needed, ask the
+user first.
+
+`missing-source` is a human gate. In user-facing language, describe the next
+action as adding a knowledge source, not as filling CLI placeholders. Treat this
+as a source boundary decision. Explain that the source name is a stable prefix
+that appears in source refs and phase ids. Approved paths are derived from
+collection, containment, and slug. NodeRef/ViewRef are identity fields, not path strings:
+
+```text
+knowledge/<collection>/<containment>/<slug>.md
+repo:<source-name>#symbol:...
+file:<source-name>/<document>#span:...
+lark:<source-name>/<document>#span:...
+capture:file:<source-name>
+align:lark:<source-name>:architecture
+dist/<source-name>-kb/
+```
+
+Approved paths are not derived directly from the source name. Align/compile
+derive them from collection, containment, and slug; extraction and structure
+planning may choose containment that reflects package/module shape when the
+source boundary intentionally covers multiple modules.
+
+Ask what the user wants the source to cover: a single local Markdown/MDX document,
+a local Markdown/MDX directory, an article/documentation repository as a file
+source, a Lark/Feishu document URL or token, a local code repo/package, a remote
+Git repo/package, or a multi-module namespace. Do not infer the source from cwd,
+parent directories, monorepo layout, package names, or git remotes. Do not ask
+for a raw source name as an isolated parameter; propose one only after the
+boundary is clear.
+
+If the user already provided a path and the remaining question is only the
+source name, still explain the boundary implication before asking for
+confirmation. A package/module path means the source name becomes the stable
+source-ref, phase-id, and package-output identity. A parent monorepo/subspace
+path means the source name is a source namespace for possible child modules,
+and current extraction must inspect that parent before choosing concrete
+package/subdirectory boundaries. Approved paths still come from collection,
+containment, and slug.
+
+Current execution supports repo sources, local Markdown/MDX file sources, and Lark /
+Feishu document sources. Local
+repo/package sources are registered with `context source add repo <name>
+--local <path>`; the materialized `sources/repo/<name>` entry is an ignored
+symlink to the selected checkout or subdirectory view. Local Markdown/MDX sources
+are registered with `context source add file <name> --local <path>` plus any
+needed `--include` patterns, captured with `captureFile`, then planned through
+`alignProse` and compiled with
+`compileProse`. A one-file-to-one-page outcome is a degenerate structure plan,
+not a separate content path. Remote Git operations require explicit user approval before any
+clone/checkout; clone into an ignored local path, checkout the requested commit,
+then register that local checkout. Do not commit cloned source content. Lark /
+Feishu sources are registered as document sources, captured through the Lark
+capture phase, and written as committed snapshots under `sources/lark/<name>/`;
+do not fetch or import Lark content with ad hoc scripts.
+
+Extraction scope is also a human gate. If no extract phase is declared, explain
+what code area and symbol policy will become draft knowledge, then ask which
+registered source and file/symbol range to ingest. Do not inspect the source
+repository to choose packages or globs on the user's behalf.
+
+For monorepos, one source may conceptually cover the whole repo/subspace or one
+package/subdirectory. Explain that the source name becomes a source-ref and
+phase-id namespace. A parent source name can support grouped codegraph NodeRefs
+such as `knowledge/codegraph/product-ui/component-web/...` and
+`knowledge/codegraph/product-ui/component-lynx/...`. In the current executable
+flow, use the whole repo/subspace only for inspection/planning. If the user wants
+a focused package manual and chooses `packages/button`, register that
+subdirectory as its own source and write
+`extractTs({ source: source("button"), ... })`. Do not use
+`include: ["packages/button/src/**"]` to choose a package from a larger source;
+`include` only filters files inside the selected source.
+
+Follow the source inspection pattern when scope is unclear: run
+`context source inspect <source-name> --format json`, show the candidate package
+paths from that CLI output, wait for the user to choose the package path(s), then
+declare sources/phases. If the extraction preview reports modules outside the
+confirmed source boundary, stop before review and repair the source declaration.
+
+Before running extraction, prefer:
+
+```bash
+context source inspect <source-name> --format json
+context run <extract-phase-id> --dry-run --format json
+```
+
+Use the `preview.sources[].modules[]`, `candidateEstimate`, and `agent_hints`
+fields as the authoritative scope check. To the user, call it a preview without
+writing candidates; avoid the internal CLI term. Also show `knowledgeTree` and
+`knowledgePathExamples` before first extraction. Explain that approved pages
+will be written under paths derived from collection, containment, and slug:
+
+```text
+knowledge/<collection>/<containment>/<slug>.md
+```
+
+If the source name, optional module segment, or resulting path shape looks
+wrong, stop and ask whether to rename the source or change the source boundary
+before running extraction. A source that already points at one package/module
+root should not repeat the package name in the path. A source rename after
+extraction is a migration, not a cosmetic change. Do not write ad hoc scripts to
+count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
+
+## Review Rules
+
+- Use `context review html <collection> --open` for visual review. If the
+  browser cannot be opened, provide the emitted `file://` URL to the user.
+- Use `context review list <collection>` only for a textual overview.
+- Ask the user to paste the copied JSONL payload into chat. The agent writes
+  that pasted payload to a temporary scratch file and runs `context review apply
+  <payload-file>` only after the user has reviewed and provided the payload.
+- Do not synthesize review payloads from HTML, JSON, runtime snapshots, or
+  candidate ids.
+- Do not default candidates to approved/rejected on behalf of the user.
+- If the user explicitly authorizes a quick or automated decision, use
+  `context review approve <candidate-id> --collection <collection>` /
+  `context review reject <candidate-id> --collection <collection>` or `--all`.
+  These commands still enforce the scoped candidate-id gate.
+- Do not expand compact review JSONL into pretty JSON unless the user asks.
+- Do not edit approved Markdown by hand as part of review apply.
+
+## Prose Align And Compile Rules
+
+After document capture, do not ask the user to choose an SDK path. Explain the
+product sequence:
+
+1. investigate material through Context evidence views;
+2. propose a structure draft with nodes, section plans, supported edges, and
+   unresolved items;
+3. ask the user to confirm the structure, because confirmation freezes paths,
+   section ownership, relationships, and compile order for this round;
+4. compile source-bound draft pages from confirmed structure;
+5. send compiled drafts through human review, then close and build.
+
+One file per page is still possible, but it is represented as a simple
+structure draft. It does not bypass structure confirmation or compile.
+
+Material investigation:
+
+```bash
+context run align:<type>:<source>:<collection> --view read-plan --format json
+context run align:<type>:<source>:<collection> --view source-index --compact --format json
+context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view schema --format json
+context run align:<type>:<source>:<collection> --validate --input <structure.yaml> --format json
+context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
+context run align:<type>:<source>:<collection> --stage --input <structure.yaml> --format json
+```
+
+Read source material only through these evidence views. `source-index` gives a
+compact refs-first map when run with `--compact`; use `span-detail` /
+`span-text` only for exact evidence. `structure-summary` is the review surface
+for the structure confirmation gate. Do not inspect `sources/` or `.tmp`
+directly.
+
+Compile:
+
+```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
+context run compile:<type>:<source>:<collection> --validate --input <compile-actions.yaml> --format json
+context run compile:<type>:<source>:<collection> --stage --input <compile-actions.yaml> --format json
+```
+
+Default compile actions should mirror source spans into `verbatim` body and
+attach summary/kind/source refs. Explicit reader-visible content is not part of
+the current compile action contract; split evidence or return to structure
+confirmation instead. Relationships and cross references are structure typed
+edges in current output; this workflow does not render relationship reference
+blocks. Never inject relation markers into verbatim body.
+
+## Package Rules
+
+If `context status` says `needs-package-output`, treat it as a human gate.
+First read [Package Outputs](./package-outputs.md). Then explain the package
+decision using concrete output trees, not unexplained labels.
+
+Recommended first option:
+
+```text
+dist/<name>-kb/
+├── AGENTS.md
+├── skills/knowledge-query/SKILL.md
+└── wikis/
+    ├── index.md
+    ├── <group>/index.md
+    └── <group>/...
+```
+
+This is an agent knowledge-base package. It is the recommended first output for
+agent consumption; the internal `skills/` folder follows agent installation
+conventions.
+The default `knowledge-query` skill teaches agents to query copied OKF root
+directories structure-first, starting with `wikis/`, cite
+page/section evidence, use structure/build metadata when present, and report
+gaps instead of inventing unsupported answers. Tell the user that
+`src/package-templates/kb/` is editable before build, so they can customize the
+query skill or add project-specific skills when needed.
+
+Selected OKF root subtrees such as `wikis/`, `guides/`, `rules/`, and
+`feats/` follow the C4A OKF Profile. The package root contains agent
+installation files; the OKF-compatible interchange surface is the selected OKF
+root directories. Tell the user they can customize
+`src/package-templates/kb/wikis/index.md` before build to describe package
+scope and query guidance. The default root index should list only next-level
+directories. `context build` generates child directory indexes such as
+`<okf-root>/<group>/index.md` for deeper navigation.
+
+Alternative:
+
+```text
+dist/<name>-llms/
+└── llms.txt
+```
+
+This is an LLM text bundle output for one model/RAG import file.
+
+The user may also skip package output for now and keep only `knowledge/`.
+
+Do not offer `both` as a shortcut. If the user wants multiple outputs, declare
+one package first, build and inspect it, then ask before adding another.
+
+Every package needs a template path. Treat `src/package-templates/kb` and
+`src/package-templates/llms` as editable starting points, not final deliverables.
+The agent knowledge-base package template must contain at least one `SKILL.md` and
+`wikis/index.md`; otherwise it is a hollow package and should not be reported
+as usable. Template paths also must not collide with copied knowledge paths.
+When a collision is reported, rename the template file or exclude the knowledge
+path before build.
+
+Do not present a clean `context build`, clean `context verify`, or file count as
+proof that the output is useful. Inspect the generated package shape against the
+user's chosen output contract.