@c4a/context-cli 0.6.1 → 0.6.2

package/providers/context/resources/diagnostics/verification.md

@@ -0,0 +1,21 @@
+---
+id: diagnostic.verification
+kind: diagnostic
+mediaType: text/markdown
+---
+
+# Verification diagnostics
+
+Context reports one root diagnostic with counts and keeps derived findings in a
+separate detail view. Codes are stable machine identifiers; this document gives
+the shared recovery boundary.
+
+Content or provenance failures require a new source-bound candidate or an
+explicit evidence-maintenance decision. Projection-only failures can be
+repaired by deterministic close. A warning does not become success by being
+omitted from output.
+
+`approved-source-orphaned` is a persistent warning produced only after an
+explicit `keep-orphaned` decision. It records that the page remains usable by
+policy while its original source document cannot be resolved. It does not
+permit changed source content to bypass replacement Review.

package/providers/context/resources/diagnostics/workspace-state.md

@@ -0,0 +1,27 @@
+---
+id: diagnostic.workspace-state
+kind: diagnostic
+mediaType: text/markdown
+---
+
+# Invalid workspace state
+
+This route means Context could observe the workspace but could not prove a
+legal lifecycle action from its facts.
+
+Read the root diagnostics and their structured details. Repair the named
+project declaration or missing lifecycle artifact. Do not rerun completed
+phases, edit generated `knowledge/structure.yaml`, or delete runtime state as a
+shortcut.
+
+If the diagnostic reports a route/fact conflict, preserve the status output and
+stop lifecycle writes until the conflict is resolved.
+
+`diagnostic.compile-route-ambiguous` means project declarations assign more
+than one compile phase to the same source and collection. Make that ownership
+unique in `src/index.ts`; verification cannot choose one for you.
+
+`diagnostic.structure-snapshot-missing` means a persisted compile batch names a
+confirmed structure digest whose snapshot is absent. Restore that snapshot, or
+declare and confirm a new structure round for the affected source and
+collection. Do not edit digest fields to silence the diagnostic.

package/providers/context/resources/dialogue/code-extraction.md

@@ -0,0 +1,34 @@
+---
+id: dialogue.code-extraction
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code-extraction dialogue
+
+Describe the proposed code scope before SDK fields. State:
+
+- the confirmed repository module;
+- which files are included;
+- whether extraction follows configured/public entries or scans all matched
+  files;
+- whether internal symbols are included; and
+- that the first run or later deltas produce Review candidates rather than
+  approved Markdown.
+
+If a selected package lacks a standard entry, offer two Context-owned choices:
+configure source-relative API roots, or use scan mode for all declarations in
+the confirmed file scope. Do not ask the user to change source code or package
+metadata to satisfy Context.
+
+Run the route-selected dry-run first. Report discovered, AST-analyzed, skipped,
+symbol, relation, and candidate counts separately, plus resolved entries,
+exported/internal counts, symbol-kind counts, and the proposed knowledge tree.
+Treat those fields as structural scope evidence, not a semantic ranking. Stop
+when the preview crosses the confirmed module boundary or the module
+identity/path shape is wrong.
+
+For a multi-module round, finish every pending extraction target before opening
+one Review. For an unchanged repeat run, explain that no added, changed, or
+removed symbols need a decision. Mention `extractTs`, `include`, `entries`,
+`mode`, or `exportedOnly` only in technical configuration detail.

package/providers/context/resources/dialogue/document-capture.md

@@ -0,0 +1,29 @@
+---
+id: dialogue.document-capture
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document-capture dialogue
+
+Registration records a document boundary but does not read its body. Before the
+capture gate is resolved, explain that capture will:
+
+- read only the registered local or remote module;
+- write a normalized committed snapshot under the date directory;
+- update that date directory's shared `manifest.json`; and
+- provide offline evidence for Review, verify, and fresh-clone reproduction.
+
+For remote documents, credentials stay in the external document client and are
+not written to the workspace. Several requested documents may share the date,
+while each retains its own module and snapshot identity.
+
+Ask for permission to read the exact pending modules. Do not run capture,
+refresh, or capture preview before permission is clear. A request that
+explicitly says to ingest, fetch, capture, or read the named documents grants
+that scope; merely mentioning a possible source does not.
+
+If deterministic inspection detects `.mdx`, route metadata, sidebars, or a docs
+configuration, explain that the boundary looks like a documentation site and
+ask whether to use the Context document-site processor. Do not infer that
+choice from filenames alone.

package/providers/context/resources/dialogue/document-classification.md

@@ -0,0 +1,33 @@
+---
+id: dialogue.document-classification
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document-classification dialogue
+
+Do not recommend a collection before reading the collection-neutral evidence
+view and every required source-body resource. Summarize the observed document
+shape, explain one evidence-backed
+recommendation, and describe its package root:
+
+| Collection | Use when the evidence primarily represents | Package root |
+|---|---|---|
+| `business` | business domains, actors, objects, and non-technical domain knowledge | `wikis/` |
+| `product` | requirements, user behavior, user stories, and acceptance intent | `wikis/` |
+| `architecture` | system structure, module design, technical mechanisms, and platform/tooling design | `guides/` |
+| `sop` | procedures, runbooks, operations, maintenance, and troubleshooting steps | `guides/` |
+| `faq` | question-and-answer material intended for issue-oriented retrieval | `guides/` |
+| `standards` | normative rules, constraints, checklists, and quality/compliance requirements | `rules/` |
+| `decision` | explicit alternatives, selected choices, trade-offs, and decision records | `guides/` |
+| `incident` | incident timelines, impact, causes, response, and prevention | `guides/` |
+| `test` | test plans, validation scenarios, matrices, and acceptance cases | `rules/` |
+
+`codegraph` comes from code extraction and `feats` is not a document mainline
+collection. Filenames, URLs, titles, and example collection names are
+insufficient evidence.
+
+Ask the user to confirm exactly one mainline collection for the current source,
+unless session-managed authority resolves this gate. After confirmation,
+declare the complete align, compile, and Review lifecycle for the same source
+and collection, then re-evaluate because other captured targets may remain.

package/providers/context/resources/dialogue/evidence-maintenance.md

@@ -0,0 +1,26 @@
+---
+id: dialogue.evidence-maintenance
+kind: procedure
+mediaType: text/markdown
+---
+
+# Evidence-maintenance dialogue
+
+Explain that approved content remains present but its current source evidence
+has changed.
+
+For stale evidence, offer:
+
+- create an updated Review candidate when facts, wording, or scope may have
+  changed; or
+- re-pin the existing page only when the content is still valid and the change
+  is purely locational or otherwise body-neutral.
+
+For orphaned evidence, offer:
+
+- deprecate the page so later packages stop selecting it while audit history is
+  retained; or
+- keep it as source-orphaned knowledge with an explicit continuing warning.
+
+Do not describe re-pin as content refresh, and do not target maintenance by a
+guessed file path. Use the current diagnostic's exact `view_ref`.

package/providers/context/resources/dialogue/human-gates.md

@@ -0,0 +1,34 @@
+---
+id: dialogue.human-gates
+kind: procedure
+mediaType: text/markdown
+---
+
+# Human-gate dialogue
+
+Explain the user decision before implementation detail. State:
+
+- what is being decided;
+- what changes after confirmation;
+- which source boundary, knowledge shape, or output is affected; and
+- which meaningful alternatives exist.
+
+Use the user's conversation language. Keep commands, paths, ids, status values,
+payload keys, and `source_ref` values exact.
+
+When two or three fixed choices exist, prefer the host's native choice UI. If
+none is available, present concise A/B/C choices with one impact sentence each.
+Labels must describe user outcomes, not SDK factories or internal route names.
+Do not start with raw TypeScript, placeholder commands, `alignProse`,
+`compileProse`, `reviewValidity`, `kbPackage`, or `llmsPackage`.
+
+An explicit fully managed request in the current conversation resolves only
+delegatable gates. Use the returned managed route without asking those
+questions again. Managed authority is not project state: never persist it,
+reuse it in another conversation, use it to choose a source boundary, authorize
+an unread external source, approve an external operation, or hide validation
+and verification failures.
+
+Keep transition reports short: what changed, the current state, and the next
+decision or action. Do not paste a raw CLI transcript unless the user requests
+it.

package/providers/context/resources/dialogue/knowledge-review.md

@@ -0,0 +1,27 @@
+---
+id: dialogue.knowledge-review
+kind: procedure
+mediaType: text/markdown
+---
+
+# Knowledge-review dialogue
+
+Explain that Review is the boundary between draft candidates and approved
+Markdown. In ordinary mode:
+
+1. open the complete current Review report;
+2. let the user approve or reject candidates;
+3. ask them to copy the decision Payload back into the conversation; and
+4. apply only that exact Payload through the returned command.
+
+The user does not need to create a payload file; the Agent may write the pasted
+payload to ignored scratch storage for the CLI command. Never derive a payload
+from HTML, candidate ids, snapshots, or a default decision.
+
+Do not open Review for one page or module while another confirmed item in the
+same round is still being generated. If a repeat codegraph run has no delta,
+state that existing approvals were preserved and no Review gate remains.
+
+When the user explicitly requested fully managed operation, use only the
+revision-bound atomic approve command returned by the managed route. Do not
+synthesize per-candidate approval calls.

package/providers/context/resources/dialogue/package-output.md

@@ -0,0 +1,30 @@
+---
+id: dialogue.package-output
+kind: procedure
+mediaType: text/markdown
+---
+
+# Package-output dialogue
+
+Explain output shapes before SDK factory names. Offer:
+
+- an Agent knowledge-base package with `AGENTS.md`, a knowledge-query Skill,
+  approved OKF roots, and adaptive indexes;
+- one LLM text bundle for model context or RAG import; or
+- no package yet, leaving approved Markdown in `knowledge/`.
+
+For the Agent knowledge-base package, show a compact tree and explain that
+small directory contents are linked from the parent index while a directory
+with more than the configured threshold gets its own child index. Templates
+under `src/package-templates/` are editable presentation, not a second factual
+source.
+
+After the user chooses an Agent knowledge-base package, explain that its
+knowledge roots are flat inside `dist/<package-name>/`; do not ask for a second
+package namespace. Ask whether Skills need a short optional prefix, then
+maintain their complete final names in the template. Do not expose downstream
+layout terminology or ask for platform-specific identity fields.
+
+Do not offer a hidden `both` shortcut. If the user wants multiple outputs,
+declare and inspect one first, then obtain confirmation for the next. Mention
+`kbPackage` and `llmsPackage` only after the semantic output choice.

package/providers/context/resources/dialogue/source-boundary.md

@@ -0,0 +1,29 @@
+---
+id: dialogue.source-boundary
+kind: procedure
+mediaType: text/markdown
+---
+
+# Source-boundary dialogue
+
+Describe the boundary in user terms before showing a registration command. For
+code, distinguish a whole repository/subspace from one concrete package or
+subdirectory. For documents, distinguish one file, a local document directory,
+a documentation site, and a remote document.
+
+Explain the observable impact:
+
+- the date is one capture batch;
+- every confirmed source is a module inside that batch;
+- several code and document modules may share the date;
+- `date/module` appears in source refs and phase ids; and
+- stable codegraph knowledge paths use the module name without the date.
+
+Do not invent `-A`, `-B`, or sequence suffixes. If today's batch exists, append
+the newly confirmed module to it.
+
+When inspection finds several package boundaries, show their paths and ask
+which concrete boundaries should become sources. Explain that `include`
+filters files inside a source and cannot select a monorepo package. Only after
+the choice is explicit should the Agent use the route-selected registration
+schema and command.

package/providers/context/resources/dialogue/structure-confirmation.md

@@ -0,0 +1,44 @@
+---
+id: dialogue.structure-confirmation
+kind: procedure
+mediaType: text/markdown
+---
+
+# Structure-confirmation dialogue
+
+Present the staged structure as a proposal, not as approved knowledge. Explain
+that confirmation freezes the current round's:
+
+- knowledge pages and paths;
+- section ownership and source spans;
+- source-backed relationships; and
+- compile order.
+
+The final staged HTML report is the confirmation surface. Open it when the CLI
+returns it, report whether opening succeeded, and provide the file URL/path when
+it did not. Do not confirm from counts alone.
+
+Present these three outcomes in the user's language:
+
+- confirm the current staged structure digest;
+- revise the proposed structure and validate/stage it again; or
+- return to the source boundary when the current evidence scope is wrong.
+
+If staging changed the structure digest, any earlier confirmation no longer
+applies. When `workflow.current.gate.resolution` is `user`, explain the change
+and obtain a new confirmation. When it is `session-authority`, inspect the same
+report and continue without asking again. After resolution, execute only the
+revision-bound command returned by `workflow.current`; never construct or reuse
+a phase-local confirmation command.
+
+Deterministic boundary repairs are internal CLI maintenance and are not
+separate approval rounds. If `workflow.current.gate.resolution` is
+`session-authority`, inspect the final staged report and execute the returned
+resolution command without asking the user again. Otherwise ask for one final
+confirmation of the staged digest. Ask an earlier design question only when
+evidence supports multiple incompatible structures, and say clearly that it is
+not the final confirmation.
+
+One source document may map to one page, but that is still an ordinary
+structure proposal. A multi-source round confirms each source/collection slot;
+do not confuse one slot with completion of the entire document batch.

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -0,0 +1,259 @@
+---
+id: context.sdk.package-outputs
+kind: procedure
+mediaType: text/markdown
+---
+
+# Package Outputs
+
+Package outputs are generated folders under `dist/`. They turn approved
+knowledge from `knowledge/` into a shape that another consumer can install,
+read, or import.
+
+Package output is a human decision gate. Do not add package declarations until
+the user chooses the intended consumer and output shape.
+
+Package build consumes approved and closed knowledge. If status reports that
+close is required, run deterministic close before build. Current close derives
+`knowledge/structure.yaml`, persists approved edge projection, and runs the
+final verify gate without rewriting approved Markdown. References, changelog,
+package index, and section fingerprint rebuilds are not current close output.
+
+## Recommended First Output: Agent Knowledge-Base Package
+
+Choose an agent knowledge-base package first when the knowledge should help
+Coding Agents work with the project. After the user chooses this semantic
+output shape, implement it with `kbPackage()`.
+
+Typical output:
+
+```text
+dist/<package-name>/
+├── AGENTS.md
+├── skills/
+│   └── knowledge-query/
+│       └── SKILL.md
+└── wikis/
+    ├── index.md
+    └── ...
+```
+
+Choose this when the user wants:
+
+- agent-facing guidance generated from the reviewed knowledge;
+- a package that can be installed as an agent knowledge base;
+- a starting point that can later be refined into task-specific skills.
+
+The underlying `kbPackage()` declaration requires a template containing at
+least one `SKILL.md` and `wikis/index.md`.
+The default `src/package-templates/kb/` template is only a starting point.
+Inspect the generated `dist/<package-name>/` before calling it usable.
+
+KB packages use flat package-relative knowledge roots:
+
+```ts
+kbPackage({
+  name: "component-lib-kb",
+  template: "src/package-templates/kb",
+});
+```
+
+The package name already identifies the surrounding build folder, so the
+output does not repeat it inside each root:
+
+```text
+skills/knowledge-query/SKILL.md
+wikis/index.md
+guides/...
+rules/...
+feats/...
+```
+
+Do not ask for another distribution namespace. Older workspaces may still
+contain `distribution.knowledgeNamespace`; Context accepts that legacy input
+without using it to shape the package.
+
+Skill names are separate. Ask whether the author wants a short optional Skill
+prefix, then maintain the complete final template directory name directly—for
+example `skills/android-query/SKILL.md`. Package-root layout never renames a
+Skill.
+
+The default `knowledge-query` Skill is a complete generic query entry. It
+carries the structure-first query discipline: start from OKF directory indexes, use
+`context-build-inventory.json` edge records for package-visible relationships,
+inspect page `sources` / `context:section` source_ref metadata, cite
+page/section evidence, and report explicit gaps when the package does not cover
+a requested fact. It does not treat direct grep over bundled OKF root
+directories as the primary discovery path. When indexes do not narrow the
+scope, or a candidate page is too large to read directly, its bundled
+`scripts/search.mjs` provides deterministic BM25 ranking over mechanically
+bounded Markdown chunks. Search results are leads; page bodies and typed edge
+records remain the evidence. Its final template-author section
+requires package authors to replace or edit the generic routing when the
+package needs project-specific terminology, entry points, known limits, or
+task workflows. Authors may explicitly accept the generic default when it is
+intentionally sufficient.
+
+The same inventory exposes `structure.relationship_coverage`. It records
+whether selected codegraph pages have current source-backed AST relationship
+metadata, how many codegraph views were selected, and how many package-visible
+edges were emitted. An empty edge list is therefore explicit evidence of a
+coverage state, not permission to invent a dependency.
+
+The generated `wikis/` directory is the default OKF root and follows the C4A OKF
+Profile. Internal production collections are mapped into package OKF roots such
+as `wikis/`, `guides/`, `rules/`, or `feats/`; when selected, `context build`
+copies them into the package and generates root-aware directory indexes for them
+as needed. Selected OKF roots always have an index; smaller child directories
+are folded into their nearest generated ancestor index by default. These roots
+contain consumer-oriented Markdown with reader-facing frontmatter and no Context
+lifecycle comments. Node identity, source metadata, code symbol lists,
+relationship records, generated-child records, and candidate fingerprints are
+kept out of each page. `context-build-inventory.json` maps distributed paths to
+approved knowledge paths and exposes package-visible structure; exact Section
+evidence remains in the mapped `knowledge/` page. The package root is an agent
+package; the OKF-compatible interchange surface is the selected OKF root
+subtrees under `dist/<package-name>/`. The required template entry and final
+output path are both `wikis/index.md`.
+
+Current collection mapping:
+
+| Internal collection | Package path | Role |
+|---|---|---|
+| `codegraph` | `wikis/codegraph/` | Structured code entities and relationships. |
+| `business` | `wikis/business/` | Structured business entities and relationships. |
+| `product` | `wikis/product/` | Structured product entities, behavior, and relationships. |
+| `architecture` | `guides/architecture/` | Architecture explanations and design narratives. |
+| `sop` | `guides/sop/` | Procedures and runbooks. |
+| `faq` | `guides/faq/` | Question-oriented explanations and troubleshooting. |
+| `decision` | `guides/decision/` | Decision records and trade-off narratives. |
+| `incident` | `guides/incident/` | Incident timelines, response, and follow-up. |
+| `standards` | `rules/standards/` | Normative standards and constraints. |
+| `test` | `rules/test/` | Validation rules, scenarios, and acceptance checks. |
+| `feats` | `feats/` | Feature capability records. |
+
+`wikis/` is the structured entity-and-relationship layer. `guides/` and
+`rules/` may explain, operationalize, or constrain that knowledge; their
+placement does not create a relationship unless Context includes a typed edge.
+
+`index.md` is reserved for OKF bundle and directory indexes. Source documents
+may be named `index.md`, but generated concept pages must use a non-reserved
+name such as `index-page.md`; `context build` rejects copied knowledge that
+occupies `wikis/**/index.md`.
+
+`src/package-templates/kb/wikis/index.md` is the bundle entry page template.
+Tell the user it can be edited before build to describe the package scope,
+intended users, and query guidance.
+
+The default root index is a usable generic entry, not a project-specific
+information architecture.
+It links directly to pages in small child directories and to a child
+`index.md` when that directory exceeds the configured navigation threshold.
+The default threshold is 50 selected knowledge pages. Use Handlebars variables such as
+`knowledgeGroups`, `knowledgeItems`, and `knowledgeTree` when a project needs
+custom navigation. Before customizing it, read
+`node_modules/@c4a/context/docs/reference/template-variables.md`.
+
+Newly initialized generic templates must be replaced, edited, or explicitly
+accepted before the first build. `context status` exposes that choice as a
+package template Review Gate. Use only the revision-bound command returned by
+that Route to accept an unchanged generic default; edit files under
+`src/package-templates/` when customizing. Context compares file digests and
+records the decision without evaluating the meaning of template prose.
+
+Template paths are rendered before selected knowledge is copied. A rendered
+template path must not collide with a selected knowledge path. If the build
+reports a collision, rename the template file or exclude that knowledge path
+with `select.exclude`.
+
+Template prose must not become a second knowledge source. If a template
+describes package coverage, scope, known gaps, or known limits, it must cite
+approved knowledge, `context-build-inventory.json`, or rendered structure data
+inside the package. Otherwise `context build` reports a template-boundary
+diagnostic. Repair the template under `src/package-templates/`; do not patch
+`dist/` as the durable fix.
+
+KB package index links are also checked. `context build` validates every
+selected OKF root index and generated child `index.md` so relative links and
+OKF bundle-root absolute links resolve inside `dist/<package-name>/`. Broken
+index links are fixed by editing the template, approved knowledge path, or
+package declaration and rerunning `context build`; do not patch `dist/`
+directly as the durable fix.
+
+## Alternative Output: LLM Text
+
+Choose an LLM text bundle when the user wants a single text bundle for model
+context, RAG import, or manual reading. After the user chooses this semantic
+output shape, implement it with `llmsPackage()`.
+
+Typical output:
+
+```text
+dist/<package-name>/
+└── llms.txt
+```
+
+Choose this when the user wants:
+
+- one consolidated text file;
+- a format that is easy to copy, index, or upload elsewhere;
+- no agent skill packaging yet.
+
+## Skip Package Output
+
+The user may choose to stop after approved Markdown. In that case, keep
+`packages: []` and do not run `context build`.
+
+Approved knowledge still lives in:
+
+```text
+knowledge/
+└── ...
+```
+
+## How To Ask The User
+
+When `workflow.current.reason_code` is `route.package.output-required`,
+explain the choices with the output tree. Do not ask the user to pick from
+unexplained labels.
+Use the host's native multi-choice tool when available. If unavailable, fall
+back to a short Markdown A/B/C question. The option labels should be:
+agent knowledge-base package, LLM text bundle, and skip package output for now.
+
+Recommended question shape:
+
+```text
+The reviewed knowledge is approved. The next decision is how to package it.
+
+Recommended: agent knowledge-base package
+dist/<name>-kb/
+├── AGENTS.md
+├── skills/knowledge-query/SKILL.md
+└── wikis/
+    ├── index.md
+    ├── <group-page>.md
+    └── <large-group>/index.md
+
+This is best if agents should use the knowledge as a reusable knowledge base.
+
+Alternative: LLM text bundle
+dist/<name>-llms/
+└── llms.txt
+
+This is best if you need one text bundle for model/RAG import.
+
+We can also skip package output for now and keep only knowledge/.
+
+Which one should I declare first?
+```
+
+If the user chooses the Agent knowledge-base package, explain that its OKF
+roots are flat within `dist/<package-name>/`; do not ask for a second namespace.
+Ask whether its Skills need a short prefix. The author maintains final Skill
+names independently from package paths.
+
+Do not offer `both` as a shortcut. If the user wants multiple outputs, add one
+package first, verify the shape, then add another package after confirmation.
+The default adaptive index policy avoids one-page directory indexes. Configure
+`kbPackage().navigation` when a package needs a different inline-entry
+threshold or a fully expanded index at every directory.