@c4a/context 0.6.1 → 0.6.2

package/docs/guides/agent-guide.md

@@ -5,25 +5,39 @@ 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
 `confirmed_by: managed-session`.
 
+After the first managed status evaluation, use
+`context run --managed --until blocked-or-complete --format json` when the
+current work can advance through consecutive mechanical routes. The CLI
+executes only a unique immediate non-read command, re-evaluates after each
+receipt, and stops before Agent interpretation, configuration, missing
+authority, diagnostics, or multiple commands. Continue from the returned
+`workflow.current`.
+
 This is execution authority, not project configuration. Do not add it to
 `defineProject`, environment files, or committed workspace state, and do not
 carry it into a new conversation. It never grants a new source boundary or
@@ -44,8 +58,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
 
@@ -61,15 +76,31 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 
 - `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.
+- `.tmp/context-runtime/lifecycle/` is the ignored, CLI-managed draft candidate
+  ledger and confirmed structure state for an open lifecycle round.
+- `knowledge/` contains approved Markdown, the durable
+  `knowledge/structure.yaml` projection, and (only when needed) the compact
+  `knowledge/decisions.json` rejected candidate ID-to-fingerprint map.
+- `knowledge/structure.yaml.source_inputs` contains only source, collection,
+  and consumed snapshot hash for closed prose targets. It lets status detect a
+  changed or unfinished target without retaining lifecycle snapshots.
 - `dist/` contains generated package outputs.
+- `.tmp/agent-payloads/` is the recommended location for transient inputs written
+  by the Agent for CLI commands. It is not enforced, but avoids introducing
+  top-level scratch directories; remove these files after the corresponding
+  stage or apply succeeds unless the user explicitly wants to retain them.
 - file and Lark documents from one date live as sibling files under `sources/file/<date>/` and `sources/lark/<date>/`; each date directory has one shared `manifest.json`.
-- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks.
+- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks. Successful close removes completed lifecycle and review runtime state.
 
 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:
 
@@ -78,12 +109,12 @@ Present only the current workflow surface:
 | 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:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory and updates that directory's single `manifest.json`. |
 | 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. |
+| Confirm prose structure | `alignProse` validates and stages CLI-managed lifecycle structure. 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. |
+| Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `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
@@ -104,7 +135,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 +145,10 @@ align:lark:<source-name>:architecture
 dist/<source-name>-kb/
 ```
 
-Prose align/compile paths derive from collection, containment, and slug.
+Every prose View requires a stable filename `slug`. The CLI derives its path
+from collection, slug, and optional `containment`; omit `path` from the input.
+Supply `containment` 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 +186,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 +223,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 +250,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 +307,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 +321,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,
@@ -301,7 +346,7 @@ knowledge/codegraph/<module>/symbol/<slug>.md
 If the module or resulting path shape looks wrong, stop and repair the
 module registration before running extraction. An extra repeated package
 segment below the module may indicate an over-broad source boundary. Do not write ad hoc scripts to
-count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
+count packages, parse `package.json`, or sample the lifecycle candidate ledger.
 
 ## Review Rules
 
@@ -320,7 +365,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 +375,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.
 
@@ -348,6 +391,7 @@ 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 existing-knowledge --query <title-or-stable-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
@@ -356,41 +400,41 @@ 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. Before introducing a new Node identity,
+use the targeted `existing-knowledge` View returned by the read plan to inspect
+approved stable refs; do not inspect `knowledge/**` directly. 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 +446,18 @@ 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 already identifies the surrounding `dist/` directory. Its OKF
+roots stay flat (`wikis/`, `guides/`, `rules/`, and `feats/`), so do not ask for
+a second distribution namespace. Ask separately whether the author wants a
+short Skill prefix; if so, maintain the complete final Skill directory name in
+the template.
 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 +471,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,28 +43,72 @@ 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.
 
-The default `knowledge-query` skill carries the structure-first query
-discipline: start from OKF directory indexes, use
+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. Users can edit any template file
-under `src/package-templates/kb/` before build to create their own skills,
-prompts, routing rules, or package instructions.
+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 well. 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
+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>/`, with `wikis/index.md` as the required
-default KB entry.
+subtrees under `dist/<package-name>/`. The required template entry and final
+output path are both `wikis/index.md`.
 
 Current collection mapping:
 
@@ -95,13 +139,22 @@ occupies `wikis/**/index.md`.
 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
+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
@@ -114,12 +167,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 +207,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 +225,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 +241,13 @@ 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.