@c4a/context 0.6.1 → 0.6.2

package/docs/reference/project-api.md

@@ -27,7 +27,8 @@ Codegraph NodeRef/ViewRef and knowledge paths use the stable module name without
 the date:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/<collection>/<slug>.md
+knowledge/<collection>/<containment>/<slug>.md  # only for an intentional hierarchy
 knowledge/codegraph/<module>/symbol/<slug>.md
 repo:<date>/<module>#symbol:...
 file:<date>/<module>/<document>#span:...
@@ -48,6 +49,12 @@ knowledge/codegraph/module-a/...
 knowledge/codegraph/module-b/...
 ```
 
+For prose Views, provide a stable filename `slug` and omit `path`; the CLI
+derives the path. Omit `containment` when the page is an independent collection
+entry, producing `knowledge/<collection>/<slug>.md`. Set `containment` only
+when the approved structure intentionally places the page under a parent path;
+it is not a required source/module wrapper.
+
 The registry stores this as one date entry containing several `modules` entries,
 and materializes each module at `sources/repo/<date>/<module>`.
 Repo module names are project-wide codegraph identities and therefore cannot be
@@ -133,7 +140,7 @@ is a repo, file, or lark source:
 ```ts
 import { source } from "@c4a/context";
 
-const legacyDocs = source("product-docs");
+const productDocs = source("product-docs");
 ```
 
 ### `source(namespace, module)`
@@ -165,16 +172,18 @@ siblings under `sources/file|lark/<date>/` and share the date-level
 directory level.
 
 For a confirmed multi-document request, declare one capture phase per module.
-While any module is uncaptured, `context status --format json` reports either:
-
-- `needs-capture-phase` with `routing.configuration` when a module is not yet
-  declared in `src/index.ts`; or
-- `needs-capture` with every declared command in `routing.command_plan`.
-
-Each command-plan item says whether it is `immediate` or
-`after-human-confirmation`. The `routing.human_gate` object identifies the
-decision type and whether its result lives only in the current conversation or
-is persisted by a later workspace command.
+While any module is uncaptured, `context status --format json` selects either
+the `route.capture.configuration-required` Route with
+`workflow.current.configuration`, or the `route.capture.pending-target` Route
+with the next declared command in `workflow.current.commands`.
+
+Each command item declares its effect and availability. The current route's
+`gate` identifies the decision and authority boundary. Write commands are bound
+to the workflow revision; after one succeeds, rerun status instead of reusing
+the old command. An external command also declares
+`execution.target: agent-host`; execute it as a top-level Agent-host action so
+network and credential-store access are not lost inside a restricted child
+sandbox.
 
 ### `allSources("repo")`
 
@@ -202,7 +211,7 @@ review html/apply`, `context close`, `context verify`, and `context build`.
 
 ### Status declaration coverage
 
-`context status --format json` includes a `declarationGraph` and
+`context status --format json --view full` includes a `declarationGraph` and
 `configurationGaps` for document workflows. Each row reports capture, align,
 compile, and Review coverage for a canonical source plus collection. Gaps are
 non-blocking before structure confirmation. Once a structure is confirmed,
@@ -218,18 +227,20 @@ declarations are complete, status returns the exact align investigation command
 for the next target. A built package does not freeze the workspace or require a
 new workspace for later sources.
 
-Use `context status --format json --view summary` when only the current state,
-target, counts, diagnostics, and recommended command are needed. The full view
-retains source, phase, package, and lifecycle inventories.
+`context status --format json` defaults to the compact workflow route, target,
+progress, counts, and aggregated diagnostics. Use `--view full` only when
+source, phase, package, and lifecycle inventories are needed for debugging.
 
 ### Current-conversation managed execution
 
 `context status --managed --format json` exposes
 `executionMode: { mode: "managed", scope: "current-conversation" }` and resolves
 eligible human gates into immediate commands. The flag is deliberately absent
-from `defineProject`: callers must pass it on each status/run/review command in
-the authorized conversation. A later process or conversation gets ordinary
-human-gated behavior by default.
+from `defineProject`: callers start each workflow evaluation loop with managed
+status, then execute the returned revision-bound command unchanged. Returned
+commands carry a compact current-conversation marker instead of repeating every
+authority. A later process or conversation gets ordinary human-gated behavior
+by default.
 
 Managed Review is atomic and scope-validated:
 
@@ -238,10 +249,25 @@ context review approve-all <collection> --managed --format json
 context review approve-all --all --managed --format json
 ```
 
-Managed structure staging uses `context run <align-phase> --stage --managed
---input <structure.yaml> --format json`. Source boundaries and unread source
-bodies, external operations, payload validation, deterministic close, and
-verification errors are never bypassed.
+The default JSON result reports counts and change totals without listing every
+candidate id or materialized path. Add `--verbose` only when debugging requires
+the complete candidate and page details.
+
+Managed structure confirmation and Review use only the revision-bound commands
+returned by `workflow.current`. Source boundaries and unread source bodies,
+external operations, payload validation, deterministic close, and verification
+errors are never bypassed.
+
+For consecutive mechanical routes, the Agent may run:
+
+```bash
+context run --managed --until blocked-or-complete --format json
+```
+
+This is a bounded host loop over the same revisioned routes. It stops before
+read-only interpretation, project configuration, unresolved authority,
+diagnostics, or a non-unique command plan; it does not add another workflow
+entry or make semantic decisions.
 
 ### `captureFile`
 
@@ -306,9 +332,20 @@ Register each source with
 flag: `--url`, `--doc-token`, or `--wiki-token`. Multiple documents may share
 one date batch; when `--module` is omitted, the CLI derives an opaque,
 credential-safe module id. Capture reads the
-remote document through the CLI runner, writes normalized snapshot files under
-`sources/lark/<date>/` as sibling document files tracked by one date-level `manifest.json`, and does not write access credentials into the
-workspace.
+remote document through the CLI runner as structured Docx XML. Context keeps a
+redacted XML audit asset, projects supported blocks deterministically into
+readable Markdown, and registers external resources such as document citations,
+images, video, whiteboards, and Base references in the snapshot manifest even
+when their binary content is not downloaded. The projection does not infer or
+summarize document meaning. Its fidelity report closes discovered blocks
+against converted and intentionally skipped blocks and reports evidence
+completeness separately from Markdown projection quality. Unknown non-empty XML
+blocks receive a generic, auditable, non-interactive projection and do not block
+downstream work. Missing source content or unresolved external-resource identity
+remains an evidence error and prevents downstream Review.
+Snapshot files live under `sources/lark/<date>/` as sibling document files
+tracked by one date-level `manifest.json`. Access credentials and transient
+signed media URLs are not written into the workspace.
 
 Use a typed document reference in project declarations:
 
@@ -347,6 +384,7 @@ context run align:file:<source-name>:architecture --view read-plan --format json
 context run align:file:<source-name>:architecture --view source-index --compact --format json
 context run align:file:<source-name>:architecture --view span-detail --span <source-ref> --format json
 context run align:file:<source-name>:architecture --view span-text --span <source-ref> --format json
+context run align:file:<source-name>:architecture --view existing-knowledge --query <title-or-stable-ref> --format json
 context run align:file:<source-name>:architecture --view schema --format json
 context run align:file:<source-name>:architecture --view semantic-rules --format json
 context run align:file:<source-name>:architecture --validate --input <structure.yaml> --format json
@@ -355,14 +393,64 @@ context run align:file:<source-name>:architecture --view structure-summary --inp
 context run align:file:<source-name>:architecture --stage --input <structure.yaml> --format json
 ```
 
-`--validate`, `--stage`, `--confirm`, and `--repair` are mutually exclusive
-operations. An `--input` without an operation is rejected unless the selected
-view explicitly consumes that input. Successful validation returns a stage
-command with the same file path. JSON run output keeps `next_action` first;
+When `workflow.current.batch` is present, several independent document slots
+can be prepared in one Agent pass and validated or staged through one command:
+
+```yaml
+schema: context.prose.structure-batch.v1
+items:
+  - phase_id: align:file:<source-a>:architecture
+    input: .tmp/agent-payloads/<source-a>-structure.yaml
+  - phase_id: align:file:<source-b>:architecture
+    input: .tmp/agent-payloads/<source-b>-structure.yaml
+```
+
+```bash
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --validate --format json
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --stage --managed --format json
+```
+
+Batch preflight validates every payload before writing. Stage writes ready
+slots serially; it does not merge documents or decide their semantic shape.
+
+Align results expose a recommended `payload_target.path` under
+`.tmp/agent-payloads/`. Agents should use it for transient structure inputs and
+may remove the file after a successful stage. The CLI continues to accept an
+explicit alternative path; this is an authoring convention, not validation.
+
+For the ordinary path, `read-plan` is a complete authoring packet: it includes
+the payload contract, a budgeted canonical source-ref map, exact source-body
+resources, and a direct `--stage` command. Read the bodies, author the payload,
+and run that stage command. Request `source-index` only when the packet reports
+omitted refs, and request `existing-knowledge` only when reusing or checking an
+approved identity. The separate schema and validate views are optional
+diagnostic tools, not required lifecycle steps.
+
+`--validate`, `--stage`, and `--confirm` are mutually exclusive operations. An
+`--input` without an operation is rejected unless the selected view explicitly
+consumes that input. Deterministic boundary repairs run internally before the
+result is returned. `self_healed` includes input/output Section counts, the
+number of original Sections split, and structural reason codes. Stage performs validation before writing and returns the
+same diagnostics on failure; in managed mode, a valid stage also confirms the
+structure. Successful standalone validation returns a stage command with the
+same file path. JSON run output keeps `next_action` first;
 schema and full reports stay behind explicit Views, while `--verbose` restores
 the full phase result and repeated contracts. Long diagnostics return a compact
 first page plus an exact diagnostics continuation command.
 
+Validation returns `state: ready | repair-required | invalid`. Only `ready`
+sets `valid: true` and may proceed to stage. `error_free: true` with
+`state: repair-required` means no error diagnostic remains, but a declared
+confirmation blocker still requires repair; it is not a successful result.
+
+`existing-knowledge` is the authoring-time lookup for approved identities. It
+returns stable NodeRefs, ViewRefs, titles, tags, collections, and section counts
+without exposing workspace storage paths. `--query` performs deterministic
+case-insensitive exact/prefix/substring matching; `--collection`,
+`--node-type`, `--page-size`, and the returned continuation command narrow or
+page the same View. Use it after reading source evidence and before introducing
+a new Node identity. Structure validation remains the final duplicate gate.
+
 Align and compile evidence results include `semantic_rules`. Its `required`
 array is the rule subset selected for the current judgment, with a selection
 reason and content digest for each rule. `handle`, `digest`, and
@@ -383,22 +471,35 @@ cross multiple heading paths, without classifying document topics.
 
 After capture, the capture phase itself exposes collection-neutral `read-plan`,
 `source-index`, `span-detail`, `span-text`, and other read-only evidence views.
-Status reports `captured-ready-to-classify` until every captured target has an
-evidence-backed, user-confirmed align declaration. Align then adds `schema` and
-`structure-summary` for structure work. Agents should not inspect `sources/` or
-`.tmp` directly.
-
-Compile `read-plan`, `blockers`, `node-context`, and `schema` Views are also
-workspace-read-only and may run concurrently. `--validate`, `--stage`,
-structure confirmation, Review apply, and close are serial mutations.
+Status selects `route.document.classification-required` until every captured
+target has an evidence-backed, user-confirmed align declaration. Align then
+adds `schema` and `structure-summary` for structure work. Agents should not
+scan `sources/` or `.tmp` to invent evidence. They may read only the exact
+source-body files selected as required resources by the current Route; those
+files carry stable content digests and must be read in full before a receipt is
+reported. Read all required direct paths, then execute the Route's single
+`resources.after_read.command`; the CLI writes and carries the merged receipt
+set without requiring Agent-authored JSON. That acknowledgement response
+already contains the re-evaluated `workflow.current`, so no additional status
+command is needed.
+
+Generated Context Views use the same content-addressed rule. Materialization
+returns a receipt-set path and an exact post-read command. Read the complete
+file, then execute that command; unchanged content remains current across
+workflow revisions, while write and external commands still require the exact
+current revision.
+
+Compile `read-plan`, `blockers`, and `diagnostics` Views are workspace-read-only
+and may run concurrently. Compile `--validate`, compile `--stage`, structure
+confirmation, Review apply, and close are serial operations.
 
 Structure payloads use `schema_version: "context.structure.v1"` and canonical
 `file:` / `lark:` `#span` source refs. A one-file-to-one-page plan is represented
 as ordinary `nodes[]` and `views[]` in the structure. It does not bypass
 structure confirmation or compile. Continuity applies to each Section, while one View/Page may
-contain multiple independently retrievable continuous Sections. The optional
-`suggested-splits` repair can expand a broad cross-heading Section into Markdown
-structural groups without creating child Views.
+contain multiple independently retrievable continuous Sections. Deterministic
+boundary splitting is applied internally during validate/stage; it is not a
+separate Agent-authored payload or approval step.
 
 ### `compileProse`
 
@@ -423,35 +524,30 @@ compile:file:<source-name>:architecture
 compile:lark:<source-name>:architecture
 ```
 
-Compile requires confirmed `unapproved/structure.yaml`. It freezes the current
-structure for the compile round; if the user wants to change nodes, section
-ownership, or relationships, return to the align/structure gate.
+Compile requires confirmed CLI-managed lifecycle structure. It freezes the
+current structure for the compile round; if the user wants to change nodes,
+section ownership, or relationships, return to the align/structure gate.
 
 Common commands:
 
 ```bash
 context run compile:file:<source-name>:architecture --view read-plan --format json
-context run compile:file:<source-name>:architecture --view node-context --source <view-ref> --format json
-context run compile:file:<source-name>:architecture --view schema --format json
-context run compile:file:<source-name>:architecture --validate --input <compile-actions.yaml> --format json
-context run compile:file:<source-name>:architecture --stage --input <compile-actions.yaml> --format json
-```
-
-Compile remains one View per write for evidence isolation. After staging, follow
-`continue_compile_batch` to prepare the next View. Each canonical source plus
-collection is confirmed as an independent structure slot. When other captured
-align targets remain pending, status routes to those slots before opening one
-collection-level Review payload. `context close` is blocked while a planned
-View is unprepared, still draft, or rejected without a structure revision.
-
-Compile action payloads use `schema_version: "context.compile-actions.v1"`.
-By default, actions should omit body content and let the CLI mirror cited source
-spans into `verbatim` sections. Explicit reader-visible content is not accepted
-by the current compile action contract; split source evidence or return to the
-structure gate instead. The current approved section wire contract accepts `verbatim` and `empty`;
-it does not accept rewritten or mechanical projection modes.
-Relationships stay in `structure.yaml` typed edges in current output; do not
-inject relation markers into verbatim body.
+context run compile:file:<source-name>:architecture --validate --format json
+context run compile:file:<source-name>:architecture --stage --format json
+context run compile:file:<source-name>:architecture --view diagnostics --format json
+```
+
+Compile validates the complete confirmed source/collection slot before writing
+any candidate, then materializes the slot atomically. Section bodies are
+source-mirrored from the confirmed spans; the Agent does not create a separate
+compile-actions payload. Each canonical source plus collection remains an
+independent structure slot. When other captured align targets remain pending,
+status routes to those slots before opening one collection-level Review
+payload. `context close` is blocked while a planned View is unprepared, still
+draft, or rejected without a structure revision.
+
+Relationships stay in `structure.yaml` typed edges in current output; compile
+does not infer relationships or inject relation markers into verbatim body.
 
 ### `extractTs`
 
@@ -514,12 +610,16 @@ package from a larger monorepo source.
 Use `context source inspect <date>/<module>` to list detected module/package
 boundaries before choosing the source. Use `context run <phase-id> --dry-run
 --format json` to check the resolved modules, file counts, symbol counts, and
-candidate estimate before writing `unapproved/entities.jsonl`. The dry-run
+candidate estimate before writing the ignored lifecycle candidate ledger. The dry-run
 preview also includes `knowledgeTree` and `knowledgePathExamples`, which show
 where approved Markdown will land after review apply.
 Its module and total summaries distinguish `discoveredFiles`, `analyzedFiles`,
-`skippedFiles`, `symbols`, and `relations`; modules with skipped files include
-the reason, such as files not reachable from exports-mode entries.
+`skippedFiles`, `symbols`, and `relations`. Module summaries also expose the
+resolved `entryFiles`, exported/internal symbol counts, and a structural
+`candidateKinds` count. These fields describe extractor output only; the CLI
+does not infer which symbols are meaningful to a particular product or
+audience. Modules with skipped files include the deterministic traversal
+reason, such as files not reachable from exports-mode entries.
 
 Phase id shape:
 
@@ -531,8 +631,9 @@ Codegraph extraction has two execution policies:
 
 - `context run <phase-id>` is the Agent/user default. The first run sends every
   code symbol to Review. Later runs preserve unchanged approved symbols and send
-  only `add`, `update`, and `remove` deltas to Review. If there is no delta, the
-  result returns `next_action.human_gate=false` and the Agent continues.
+  only `add`, `update`, and `remove` deltas to Review. After every phase result,
+  the Agent re-evaluates `context status --format json`; only
+  `workflow.current` decides whether Review is now required.
 - `context run <phase-id> --auto-promote` is the explicit CI/CD path. It is valid
   only for `phase.extract.ts` codegraph phases, applies deterministic code deltas
   without Review, refreshes deterministic close when approved knowledge changed,
@@ -542,8 +643,9 @@ Codegraph extraction has two execution policies:
   separate pipeline step; existing package outputs are reported stale.
 
 This policy never auto-promotes architecture, business, decision, test, or
-other semantic knowledge. Agents must follow the returned
-`next_action.human_gate` instead of assuming every extraction requires Review.
+other semantic knowledge. Agents must not infer a human gate from a phase-local
+result. Human gates and their inspection/resolution Actions are exposed only by
+`workflow.current`.
 
 Approved codegraph sections use the local evidence form
 `src-N#symbol:<file>:<symbol>:<kind>@<digest>`. The file segment makes reverse
@@ -551,18 +653,55 @@ lookup exact when multiple files contain the same symbol name, kind, and digest;
 the complete ref remains opaque to agents. New pages keep only top-level
 `candidate_fingerprint` and do not emit `code_origin`.
 
-Projects created by the beta.5 protocol can upgrade approved pages without a
-second human decision. Rerun every declared codegraph extraction phase to write
-the current file-aware symbol index, then run:
+### `extractCustom`
 
-```bash
-context review migrate-codegraph-refs
-context verify
+Use a project-owned extractor when code facts cannot be represented by the
+TypeScript symbol extractor, for example a language-specific parser or an
+aggregated repository protocol:
+
+```ts
+extractCustom({
+  id: "extract:service:protocol",
+  sources: [service],
+  collection: "codegraph",
+  extract: async ({ projectRoot }) => ({
+    candidates: [{
+      nodeRef: "service/protocol",
+      kind: "protocol",
+      visibility: "exported",
+      module: "service",
+      markdown: renderProtocol(projectRoot),
+      evidence: [{
+        source: "20260811/service",
+        file: "src/protocol.ts",
+        symbol: "protocol",
+        kind: "variable",
+        digest: "0123456789ab",
+      }],
+      review: {
+        title: "Service protocol",
+        summary: "Aggregated protocol boundary.",
+        signals: ["source-backed"],
+        reason: "Review the project-owned extraction.",
+      },
+    }],
+  }),
+});
 ```
 
-Migration resolves each legacy ref against the trusted index and its existing
-origin metadata, removes `code_origin`, preserves the approved body and review
-state, and rolls back all page writes if final verification fails.
+`sources` is the complete registered repo scope for the phase. Every candidate
+and edge carries structured `evidence`; the CLI validates that evidence against
+the declared sources, creates canonical `source_ref` values, writes the symbol
+index, candidate ledger and Review snapshots atomically, and records a phase
+fingerprint. `context status` therefore treats this phase exactly like another
+pending code extraction target, and Review can verify snapshot freshness
+without a placeholder `extractTs` phase.
+
+The extractor returns knowledge semantics (`nodeRef`, rendered Markdown,
+Review summary and source-backed evidence). It must not write `knowledge/`,
+`.tmp/context-runtime/lifecycle/candidates.jsonl`, extraction fingerprints or
+Review snapshots directly. Context owns those files and preserves rejected and
+unchanged-approved decisions across reruns.
 
 ### `reviewValidity`
 
@@ -603,7 +742,8 @@ structure slots and every declared `pendingStructureTargets` item in the round;
 codegraph waits for every pending extract phase in the confirmed module round.
 Candidate count/hash therefore describes the complete current batch rather than
 one page, source slot, or module. Deterministic close later merges all active
-slots into `knowledge/structure.yaml`.
+slots into `knowledge/structure.yaml`, retains only their source, collection,
+and consumed snapshot hash as `source_inputs`, then removes the lifecycle slots.
 
 `status.structureBatch` lists unclassified, configuration-required, pending,
 and active structure slots together with the execution policy for the round.
@@ -634,8 +774,9 @@ customPhase("custom:20260712/sample:review", async (ctx) => {
 });
 ```
 
-Custom phases are an escape hatch. Prefer built-in factories for source,
-extract, review, and package workflows. The supported runtime helpers are:
+Custom phases are an orchestration escape hatch. Use `extractCustom()` instead
+when project code needs to publish codegraph candidates. The supported runtime
+helpers are:
 
 - `ctx.ensureSources(...)` for repo source readiness.
 - `ctx.extract.ts(...)` for declared TypeScript extraction.

package/docs/reference/template-variables.md

@@ -91,6 +91,15 @@ Read node_modules/@c4a/context/docs/reference/template-variables.md.
 |---|---|---|
 | `packageName` | string | Package name from `kbPackage()` / `llmsPackage()`. |
 | `packageKind` | string | `kb` or `llms`. |
+| `knowledgeNamespace` | string | Legacy configured namespace when an older workspace still declares one; otherwise empty. It does not change output paths. |
+| `namespacedKnowledge` | boolean | Always `false`; retained so older templates remain renderable. |
+| `skillsRoot` | string | Skills root, currently `skills`. |
+| `wikisRoot` | string | Final wikis root: `wikis`. |
+| `guidesRoot` | string | Final guides root: `guides`. |
+| `rulesRoot` | string | Final rules root: `rules`. |
+| `featsRoot` | string | Final feats root: `feats`. |
+| `skillName` | string | Author-maintained name of the Skill currently being rendered. Empty outside a `skills/<name>/...` template. |
+| `skillPath` | string | Final package-relative `SKILL.md` path for the Skill currently being rendered. Empty outside a Skill template. |
 | `knowledgeCount` | number | Selected approved Markdown file count. |
 | `knowledgeTimestamp` | string | Latest selected approved Markdown `timestamp`, or epoch when empty. |
 | `knowledge` | string | Concatenated selected approved Markdown bundle. Use carefully; it can be large. |
@@ -100,7 +109,7 @@ Read node_modules/@c4a/context/docs/reference/template-variables.md.
 | `knowledgeTreeNodes` | array | Nested path tree for selected pages. Useful for custom navigation. |
 | `knowledgeTree` | string | Markdown tree preview of selected pages. |
 | `knowledgeItemsMarkdown` | string | Markdown list of up to 50 selected pages. |
-| `knowledgeGroupsMarkdown` | string | Markdown list of first-level directories with links to their generated `index.md` files. |
+| `knowledgeGroupsMarkdown` | string | Markdown navigation for the current index. Folded directories render direct page links; expanded directories render links to generated indexes. |
 | `buildInventory` | object | Deterministic package build inventory, including selected files, selected-by reasons, collection summaries, and package-visible edge records. |
 | `buildInventoryJson` | string | Pretty JSON form of `buildInventory`. |
 | `buildInventoryPath` | string | Package-relative inventory path, currently `context-build-inventory.json`. |
@@ -130,6 +139,7 @@ Each item contains:
 | `internal_collection` | Alias for `internalCollection`. |
 | `collection` | Internal approved collection; alias for `internalCollection`. |
 | `okf_root` | OKF output root, for example `wikis`, `guides`, `rules`, or `feats`. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
 | `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
 | `pathWithinCollection` | Path below the OKF root, for example `component-lib/symbol/button.md`. |
@@ -167,10 +177,13 @@ Each group contains:
 | `internalCollection` | Internal approved collection; alias for `collection`. |
 | `internal_collection` | Alias for `internalCollection`. |
 | `okf_root` | OKF output root for this group, for example `wikis`, `guides`, `rules`, or `feats`. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `title` | Display title; defaults to `name`, or the OKF root title for a root group. |
 | `count` | Number of selected pages in this group. |
+| `hasIndex` | Whether the active package navigation policy generates `indexPath`. |
+| `has_index` | Alias for `hasIndex`. |
 | `indexPath` | OKF-root-aware index path, for example `wikis/component-lib/index.md`, `guides/component-lib/index.md`, or `rules/index.md` for a root group. |
-| `indexHrefFromTemplate` | Link from the template file currently being rendered to `indexPath`. Use this in custom templates. |
+| `indexHrefFromTemplate` | Link from the template file currently being rendered to `indexPath`. Check `hasIndex` before rendering it. |
 | `indexHrefFromCollectionIndex` | Link from the OKF root index to `indexPath`. |
 | `items` | `knowledgeItems` in the group. |
 
@@ -178,8 +191,11 @@ Example:
 
 ```md
 {{#each knowledgeGroups}}
-## [{{title}}]({{indexHrefFromTemplate}}) ({{count}})
+## {{title}} ({{count}})
 
+{{#if hasIndex}}
+[Open directory index]({{indexHrefFromTemplate}})
+{{/if}}
 {{#each items}}
 - [{{title}}]({{href}}) - {{type}}
 {{/each}}
@@ -211,15 +227,16 @@ care about.
 The default KB template uses the variables above to generate a starter index:
 
 - bundle count and timestamp in OKF frontmatter;
-- next-level directory links;
-- links to generated directory indexes such as `wikis/<group>/index.md` or
-  another selected OKF root's `<okf-root>/<group>/index.md`.
-
-`context build` also generates `index.md` files for directories under selected
-OKF roots when a directory does not already contain one. The root
-`wikis/index.md` should stay shallow by default; put detailed navigation in the
-generated child indexes or in custom template sections.
-
-The output is only a starter. Edit
-`src/package-templates/kb/wikis/index.md` to add project-specific reading
-paths, API entry points, or task-focused navigation before `context build`.
+- direct page links for directories folded by the active navigation policy;
+- links to generated directory indexes when a directory exceeds the configured
+  inline-entry threshold.
+
+`context build` always provides selected OKF root indexes. By default, a
+non-root directory gets its own index only when it contains more than 50
+descendant knowledge pages. Configure this with
+`kbPackage({ navigation: { foldDirectoryIndexes, maxInlineEntries } })`.
+
+The output is only a starter. Edit the files under
+`src/package-templates/kb/` when the package needs different reading paths or
+navigation before `context build`. An unchanged generated starter must instead
+be explicitly accepted through the current package-template Review Route.

package/index.d.ts

@@ -1,12 +1,12 @@
-import type { PackageSelectDefinition } from "./contracts.js";
+import type { PackageNavigationDefinition, PackageSelectDefinition } from "./contracts.js";
 import type { PhaseDefinition, PhaseResourceReference } from "./phases.js";
 import type { ProjectSourceDefinition } from "./sources.js";
-export type { CodegraphCollection, DocumentMainlineCollection, EntityStatus, KnowledgeCollection, MainlineCollection, MarkdownTransform, FileCaptureProcessorDefinition, OkfRoot, PackageKind, PackageSelectDefinition, TopLevelNamespace, } from "./contracts.js";
-export { assertDocumentMainlineCollection, assertKnowledgeCollection, assertMainlineCollection, assertOkfRoot, assertTopLevelNamespace, DOC_MAINLINE_COLLECTIONS, KNOWLEDGE_COLLECTIONS, MAINLINE_COLLECTIONS, OKF_ROOTS, TOP_LEVEL_NAMESPACES, } from "./contracts.js";
+export type { CodegraphCollection, DocumentMainlineCollection, EntityStatus, KnowledgeCollection, MainlineCollection, MarkdownTransform, FileCaptureProcessorDefinition, OkfRoot, PackageKind, PackageNavigationDefinition, PackageSelectDefinition, TopLevelNamespace, } from "./contracts.js";
+export { assertDocumentMainlineCollection, assertKnowledgeCollection, assertMainlineCollection, assertOkfRoot, assertTopLevelNamespace, DOC_MAINLINE_COLLECTIONS, DEFAULT_PACKAGE_NAVIGATION, KNOWLEDGE_COLLECTIONS, MAINLINE_COLLECTIONS, OKF_ROOTS, TOP_LEVEL_NAMESPACES, } from "./contracts.js";
 export { assertDocumentEvidenceSectionMetadata, DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION, DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES, DOCUMENT_SECTION_CONTENT_MODES, DOCUMENT_STRUCTURE_SCHEMA_VERSION, } from "./documentEvidence.js";
 export type { DocumentEvidenceSectionMetadata, DocumentEvidenceSectionValidationOptions, DocumentEvidenceSectionValidationStage, DocumentSectionContentMode, } from "./documentEvidence.js";
-export { alignProse, captureFile, captureLark, compileProse, customPhase, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, mdxJsonDocs, reviewValidity, } from "./phases.js";
-export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, ExtractTsPhaseDefinition, PhaseDefinition, PhaseResourceReference, ReviewValidityPhaseDefinition, ReviewValidityScope, } from "./phases.js";
+export { alignProse, captureFile, captureLark, compileProse, customPhase, extractCustom, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, mdxJsonDocs, reviewValidity, } from "./phases.js";
+export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, CustomCodeCandidateDraft, CustomCodeCandidateEdge, CustomCodeCandidateReview, CustomCodeEvidence, CustomCodeExtractionContext, CustomCodeExtractionResult, CustomCodeExtractor, ExtractCustomPhaseDefinition, ExtractTsPhaseDefinition, PhaseDefinition, PhaseResourceReference, ReviewValidityPhaseDefinition, ReviewValidityScope, } from "./phases.js";
 export { allSources, DEFAULT_FILE_SOURCES_REGISTRY_PATH, DEFAULT_LARK_SOURCES_REGISTRY_PATH, DEFAULT_REPO_SOURCES_REGISTRY_PATH, loadSourcesRegistry, resolveSourceReference, source, } from "./sources.js";
 export type { DocumentSourceDefinition, DocumentSourceReference, DocumentSourceType, FileSourceDefinition, FileSourceReference, FileSourceRegistryEntry, LarkSourceDefinition, LarkSourceReference, LarkSourceRegistryEntry, LoadSourcesRegistryOptions, ProjectSourceDefinition, RepoProjectSourceDefinition, RepoSourceDefinition, RepoSourceReference, RepoSourceRegistryEntry, RepoSourcesRegistry, SourceCollectionReference, SourceDefinition, SourceReference, SourcesRegistry, SourceType, } from "./sources.js";
 export type TemplateVarValue = string | number | boolean | null | Record<string, unknown> | readonly Record<string, unknown>[];
@@ -18,6 +18,10 @@ export type PackageTemplateInput = string | {
     path: string;
     vars?: Record<string, TemplateVarValue>;
 };
+export type PackageDistributionDefinition = {
+    /** @deprecated Accepted for older workspaces; package output roots are flat. */
+    knowledgeNamespace: string;
+};
 export type BasePackageDefinition = {
     name: string;
     reads: readonly PhaseResourceReference[];
@@ -28,6 +32,8 @@ export type BasePackageDefinition = {
 };
 export type KbPackageDefinition = BasePackageDefinition & {
     kind: "package.kb";
+    navigation: PackageNavigationDefinition;
+    distribution?: PackageDistributionDefinition;
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -47,6 +53,8 @@ export declare const kbPackage: (definition: {
     name: string;
     template: PackageTemplateInput;
     select?: PackageSelectDefinition;
+    navigation?: Partial<PackageNavigationDefinition>;
+    distribution?: PackageDistributionDefinition;
 }) => KbPackageDefinition;
 export declare const llmsPackage: (definition: {
     name: string;