@c4a/context 0.6.1-beta.1 → 0.6.1-beta.2

package/docs/guides/agent-guide.md

@@ -5,20 +5,26 @@ 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.
+2. If you are implementing that entry or operating without plugins, run
+   `context status --format json`.
+3. Treat `workflow.current` as the current-step authority. Read every
+   `resources.required` item, execute only returned commands with their
+   revision/authority flags unchanged, and rerun status after each action.
+   A phase-local `next_action` may continue pagination or validation inside the
+   current operation; it never replaces the workspace route.
 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).
+6. Before asking a human gate question, read the dialogue resource selected in
+   `workflow.current.resources.required`; use [Agent Dialogue](./agent-dialogue.md)
+   only for stable cross-gate principles.
 
 ## Current-conversation fully managed mode
 
 When the user explicitly requests fully managed operation in the current
 conversation, use `context status --managed --format json` and keep `--managed`
-on the commands returned by that loop. Eligible classification, extraction
+only on commands that actually include it. Preserve every returned
+revision/authority flag. Eligible classification, extraction
 scope, structure confirmation, Review, and package-output gates may proceed
 without another question. Review uses the CLI's atomic `context review
 approve-all ... --managed` route; valid structure staging records
@@ -44,8 +50,9 @@ 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).
+user asks for implementation detail. The current gate's dialogue pattern is
+selected by `workflow.current.resources`; [Agent Dialogue](./agent-dialogue.md)
+explains stable cross-gate principles.
 
 ## Do Not Self-Discover The SDK
 
@@ -69,7 +76,13 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 
 Do not create hidden workspace state directories.
 
-## Workflow Entrypoints
+## Workflow resources and entrypoints
+
+Long procedures, semantic judgment rules, schemas, and current workspace views
+are published as Context workflow resources. Status returns only the resources
+selected for the current route. Read required resources before acting; use
+recommended resources only when the current evidence or diagnostic needs them.
+Do not preload every workflow resource or SDK manual.
 
 Present only the current workflow surface:
 
@@ -104,7 +117,8 @@ identity. Do not invent semantic date suffixes. The concrete repo selector
 appears in source refs, phase ids, and codegraph paths:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/<collection>/<slug>.md
+knowledge/<collection>/<containment>/<slug>.md  # intentional hierarchy only
 repo:<date>/<module>#symbol:...
 file:<source-name>/<document>#span:...
 lark:<source-name>/<document>#span:...
@@ -113,7 +127,9 @@ align:lark:<source-name>:architecture
 dist/<source-name>-kb/
 ```
 
-Prose align/compile paths derive from collection, containment, and slug.
+Prose align/compile paths derive from collection and slug. `containment` is
+optional and should be supplied only for an intentional parent/child hierarchy;
+independent collection entries stay directly under the collection.
 Codegraph paths use the registered date/module grouping before the symbol slug.
 
 Ask what the user wants the source to cover: a single local Markdown/MDX document,
@@ -151,25 +167,34 @@ do not fetch or import Lark content with ad hoc scripts.
 If the user requests multiple documents together, register and declare all of
 them before capture. The user's explicit batch request supplies one read scope,
 but it does not imply a mainline collection unless the user explicitly chose
-one. Follow `routing.command_plan`: run
-`immediate` items directly and run `after-human-confirmation` items only after
-the current conversation contains that confirmation. Do not ask for another
-date name or repeat the collection gate per document.
+one. Follow `workflow.current.commands`: run `immediate` items directly and run
+`after-human-confirmation` items only after the current conversation contains
+that confirmation. Preserve the returned workflow revision and authority flags
+exactly. Do not ask for another date name or repeat the collection gate per
+document.
 
 ## Current-step protocol
 
-Treat `context status --format json` `routing` as the complete protocol for the
-current step:
+Treat `context status --format json` `workflow.current` as the complete
+protocol for the current step:
 
-- `human_gate.required` says whether user input is required;
-- `human_gate.kind` says which product decision is being made;
-- `human_gate.confirmation` and `persistence` distinguish conversation-only
-  permission from decisions persisted by a workspace command;
+- `availability` distinguishes an immediately executable route from a human
+  decision or a blocked route;
+- `gate` identifies the decision, its authority, and whether a managed session
+  may resolve it;
 - `configuration` identifies the exact project file and declaration action when
   no CLI command is valid yet;
-- `commands_available` reports whether a command plan exists; and
-- `command_plan[].availability` says whether each command runs immediately or
-  only after user confirmation.
+- `commands[].availability` says whether each command runs immediately or only
+  after user confirmation;
+- `resources.required` is the complete mandatory context for this route;
+- `resources.recommended` is optional follow-up context; and
+- `after_action.evaluate` requires status to be evaluated again after the
+  action.
+
+Read a resource `path` directly. If a resource provides `command`, execute that
+revision-bound Context command and read the returned file. Long procedures and
+semantic rules live in these resources; they are loaded progressively, not
+discarded or shortened into the status response.
 
 Status also returns `declarationGraph` and `configurationGaps`. These expose
 capture, align, compile, and Review coverage for each canonical document source
@@ -179,19 +204,21 @@ by the structure must have an exact compile route for the same source. Do not
 run a compile command from another collection as a fallback. A
 `reviewValidity({ scope: "all" })` declaration covers every collection.
 
-When status is `captured-ready-to-classify`, execute its immediate capture-phase
-evidence commands before adding align/compile declarations. Inspect every
-unclassified target, explain the evidence behind the proposed mainline
-collection, and wait for user confirmation. Filenames, URLs, source titles, and
-collection names are hints, not sufficient classification evidence by
-themselves.
+When `workflow.current.reason_code` is
+`route.document.classification-required`, execute its read-only
+`inspection_action` commands before adding align/compile declarations. Inspect
+every unclassified target, explain the evidence behind the proposed mainline
+collection, and wait for user confirmation. Filenames, URLs, source titles,
+and collection names are hints, not sufficient classification evidence.
 
 Also inspect `pendingStructureTargets`. A non-empty list means captured document
 work remains outside the active structure snapshots, even if the current package
 is already built. Follow `needs-prose-configuration` first when declarations are
 missing, then run the exact returned align command. Continue in the same
 workspace; do not replace a valid earlier structure round or create a second
-workspace merely to add the next document.
+workspace merely to add the next document. Missing declarations are selected
+by `route.prose.configuration-required`; do not branch on an old top-level
+`needs-prose-configuration` state.
 
 Use `structureBatch` for the complete multi-source slot overview. Evidence View
 commands are workspace-read-only and parallel-safe; structure stage/confirm,
@@ -204,24 +231,26 @@ another declared slot remains pending in the same round. Compile every View from
 all slots first, open one collection-level Review, and let deterministic close
 merge the active slots into `knowledge/structure.yaml`.
 
-Do not infer permission from the presence of a command. Do not infer a command
-from prose when `commands_available=false`; complete the returned configuration
-action and rerun status instead.
+Do not infer permission from the presence of a command. When
+`workflow.current.commands` is empty, do not derive a lifecycle command from
+prose; complete the returned `configuration` action or resolve the returned
+gate, then rerun status.
 
 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. Status reports
-`needs-extract-phase` with `routing.configuration` until that confirmed scope is
-declared; only a declared phase can advance to `ready-to-extract` and return an
+repository to choose packages or globs on the user's behalf. The
+`route.extract.configuration-required` Route carries
+`workflow.current.configuration` until that confirmed scope is declared; only
+a declared phase can select `route.extract.pending-target` and return an
 executable preview or extraction command.
 
 For a fresh mixed-source workspace, capture every confirmed file/Lark source
 first. If repo code is still unprocessed and document structure has not started,
-`context status` prioritizes `ready-to-extract` over document investigation.
-Complete the code extraction and its batch Review before starting prose align.
-Once a document structure draft exists, keep that current human gate and do not
-switch workflows mid-review.
+`context status` prioritizes `route.extract.pending-target` over document
+investigation. Complete code extraction and its batch Review before starting
+prose align. Once a document structure draft exists, keep that current human
+gate and do not switch workflows mid-review.
 
 For monorepos, the date is one registration batch and every selected package is
 a module under it. Stable codegraph paths omit that batch date and therefore
@@ -259,10 +288,11 @@ context run <extract-phase-id> --dry-run --format json
 After the preview, run codegraph extraction normally unless the user explicitly
 asked for CI/CD automation. The first normal run requires Review for all code
 candidates. Subsequent normal runs require Review only for added, changed, or
-removed symbols; unchanged approved symbols stay approved. Always inspect
-`next_action.human_gate`: `continue-codegraph-batch` means run status and finish
-the remaining confirmed module phases. Open one Review only after
-`pendingExtractPhases` is empty and the returned gate is `true`.
+removed symbols; unchanged approved symbols stay approved. After each result,
+run `context status --format json`. `continue-codegraph-batch` only requests
+workspace re-evaluation. Open Review only when
+`workflow.current.gate.id=knowledge-review`; otherwise execute the current
+route.
 
 For a non-interactive pipeline, use `context run <extract-phase-id>
 --auto-promote --format json`. This flag applies only to codegraph, applies its
@@ -272,21 +302,17 @@ and fails the command if close or verify fails. Read `autoPromotion.close` and
 the pipeline publishes packages, run `context build` after successful auto
 promotion. Never use auto promotion for semantic knowledge collections.
 
-If verify reports `approved-source-ref-ambiguous` on approved codegraph pages
-created by beta.5, do not send those pages back through Review and do not filter
-approved symbols away. Rerun the declared codegraph extraction phase to refresh
-the trusted file-aware symbol index, then run `context review
-migrate-codegraph-refs` and `context verify`. Tell the user that this preserves
-their decisions and approved content while upgrading evidence metadata. If the
-reported ref already contains `<file>:<symbol>:<kind>`, treat it as a duplicate
-symbol-index defect instead of a legacy migration.
-
 Use the preview `mode`, optional `entries`, `preview.sources[].modules[]`,
+`entryFiles`, exported/internal symbol counts, `candidateKinds`,
 `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.
 
+These are structural extractor facts. Do not turn kind counts or file paths
+into a product-specific recommendation unless the user or Agent supplies that
+judgment.
+
 Treat `NO_ENTRY_DETECTED` as a configuration failure: choose explicit
 `entries`, or use `mode: "scan"` when the intended scope is all matched files;
 never report an empty extraction as success. Report discovered, AST-analyzed,
@@ -320,7 +346,6 @@ count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
   `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 the compact review decision Payload into pretty JSON unless the user asks.
 - Do not edit approved Markdown by hand as part of review apply.
 
 ## Prose Align And Compile Rules
@@ -331,10 +356,9 @@ product sequence:
 1. investigate material through Context evidence views;
 2. propose a structure draft with nodes, section plans, supported edges, and
    unresolved items;
-3. repair validator blockers until `confirmation_ready=true`, stage the
-   structure, open its HTML report, then ask the user to confirm it because
-   confirmation freezes paths, section ownership, relationships, and compile
-   order for this round;
+3. resolve only the non-mechanical blockers until validation state is `ready`,
+   stage the structure, open its HTML report, then follow the current Route's
+   structure-confirmation gate;
 4. compile source-bound draft pages from confirmed structure;
 5. send compiled drafts through human review, then close and build.
 
@@ -356,41 +380,38 @@ context run align:<type>:<source>:<collection> --stage --input <structure.yaml>
 
 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. When validate returns
-`repair_confirmation_blockers`, follow its repair route without asking for
-preliminary approval. `--repair suggested-splits` mechanically handles
-non-contiguous source Sections. For oversized Views, use the returned child
-View and contains-edge suggestions while classifying child Nodes from evidence.
-Stage only after
-`confirmation_ready=true`; stage opens the final `structure-summary` report for
-the structure confirmation gate. Ask a separate structure-design question only
-when evidence supports multiple incompatible semantic choices, and make clear
-that it is not final review. Do not inspect `sources/` or `.tmp` directly.
+`span-text` only for exact evidence. The CLI applies deterministic boundary
+repairs internally and returns only blockers that need Agent judgment. For
+oversized Views, use the returned structural diagnostics while classifying
+child Nodes from evidence. Stage only after validation state is `ready`; stage
+opens the final `structure-summary` report for the current Route's confirmation
+gate. Ask a separate structure-design question only when evidence supports
+multiple incompatible semantic choices. 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
+context run compile:<type>:<source>:<collection> --validate --format json
+context run compile:<type>:<source>:<collection> --stage --format json
+context run compile:<type>:<source>:<collection> --view diagnostics --format json
 ```
 
-Compile each confirmed View sequentially, but do not stop for Review after each
-write. Follow `continue_compile_batch` until no planned View remains; then open
-one collection-level Review, apply one Payload, and run close once.
+Compile derives every candidate mechanically from the confirmed section ids,
+kinds, ownership, and source spans. One stage command validates the complete
+source/collection slot before atomically writing its candidates. The Agent does
+not author compile actions or rewrite reader-visible body. Re-evaluate status
+after the batch, finish any other structure slots, then open one
+collection-level Review, apply one Payload, and run close once.
 
-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.
+Relationships and cross references remain structure typed edges; compile does
+not infer them or inject relation markers into verbatim body.
 
 ## Package Rules
 
-If `context status` says `needs-package-output`, treat it as a human gate.
+If `workflow.current.reason_code` is `route.package.output-required`, 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.
 
@@ -402,13 +423,22 @@ dist/<name>-kb/
 ├── skills/knowledge-query/SKILL.md
 └── wikis/
     ├── index.md
-    ├── <group>/index.md
-    └── <group>/...
+    ├── <group-page>.md
+    └── <large-group>/index.md
 ```
 
 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 package name is the default single-level
+`distribution.knowledgeNamespace`. Ask for an override only when the user
+needs another value; an explicit namespace may contain several concise
+lowercase path segments, such as `group/package` or
+`personal-user.123/package`, with letters and numbers joined by hyphens or
+dots. The namespace applies only to OKF output roots. Ask separately whether
+the author wants a short Skill prefix; if so, maintain the complete final Skill
+directory name in the template. Do not infer custom values from downstream
+platform identifiers.
 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
@@ -422,8 +452,9 @@ 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.
+entries. By default, `context build` links small directory contents directly
+and generates a child index only when that directory contains more than 50
+selected knowledge pages.
 
 Alternative:
 

package/docs/guides/package-outputs.md

@@ -43,6 +43,45 @@ 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 their package name as a single-level knowledge namespace by
+default:
+
+```ts
+kbPackage({
+  name: "component-lib-kb",
+  template: "src/package-templates/kb",
+});
+```
+
+This keeps the build folder name independent from install paths and produces
+paths such as:
+
+```text
+skills/knowledge-query/SKILL.md
+wikis/component-lib-kb/index.md
+guides/component-lib-kb/...
+rules/component-lib-kb/...
+feats/component-lib-kb/...
+```
+
+Ask for a custom namespace only when the user needs something other than the
+package name. An explicit value may contain multiple safe lowercase path
+segments:
+
+```ts
+distribution: { knowledgeNamespace: "platform/component-lib" }
+```
+
+Each segment may contain letters and numbers joined by hyphens or dots; keep
+the complete value concise and stable. Context treats it as an opaque knowledge
+path and does not infer downstream platform identifiers or classify package
+content.
+
+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`. Context never prepends the knowledge
+namespace to a Skill name.
+
 The default `knowledge-query` skill carries the structure-first query
 discipline: start from OKF directory indexes, use
 `context-build-inventory.json` edge records for package-visible relationships,
@@ -57,14 +96,16 @@ 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 well. These roots contain Markdown with OKF fields and C4A extension fields at
-the top level, plus
+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 Markdown with OKF fields and C4A extension fields at the top level, plus
 `context:section` source_ref span comments. C4A extension fields such as `sources`,
 `visibility`, and `code_symbols` are not nested under `context`, and page
 frontmatter does not contain `source_refs`. The package root is an agent
 package; the OKF-compatible interchange surface is the selected OKF root
-subtrees under `dist/<package-name>/`, with `wikis/index.md` as the required
-default KB entry.
+subtrees under `dist/<package-name>/`. The required logical template entry is
+`wikis/index.md`; a namespaced package writes it to
+`wikis/<knowledge-namespace>/index.md`.
 
 Current collection mapping:
 
@@ -96,8 +137,9 @@ 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 starter, not a finished information architecture.
-It lists the next-level directories and lets `context build` generate child
-`index.md` files under selected OKF roots. Use Handlebars variables such as
+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`.
@@ -114,12 +156,12 @@ 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
-`wikis/index.md` and generated child `index.md` files so relative links and OKF
-bundle-root absolute links such as `/wikis/<group>/index.md` 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.
+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
 
@@ -154,8 +196,9 @@ knowledge/
 
 ## How To Ask The User
 
-When `context status` is `needs-package-output`, explain the choices with the output
-tree. Do not ask the user to pick from unexplained labels.
+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.
@@ -171,8 +214,8 @@ dist/<name>-kb/
 ├── skills/knowledge-query/SKILL.md
 └── wikis/
     ├── index.md
-    ├── <group>/index.md
-    └── <group>/...
+    ├── <group-page>.md
+    └── <large-group>/index.md
 
 This is best if agents should use the knowledge as a reusable knowledge base.
 
@@ -187,5 +230,15 @@ 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 package
+name is already the default knowledge namespace. Ask for an override only when
+the user needs a different single- or multi-segment path. Ask separately whether
+its Skills need a short prefix. Treat these as independent choices: the
+knowledge namespace controls only OKF roots, while the author maintains final
+Skill names.
+
 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.