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

package/docs/reference/package-templates.md

@@ -27,6 +27,10 @@ kbPackage({
     include: ["architecture/component-lib/**", "sop/component-lib/**"],
     exclude: ["**/internal/**"],
   },
+  navigation: {
+    foldDirectoryIndexes: true,
+    maxInlineEntries: 50,
+  },
 });
 ```
 
@@ -47,10 +51,66 @@ llmsPackage({
 | `name` | yes | Lowercase path-safe package name. Output goes to `dist/<name>/`. |
 | `template` | yes | Project-relative template directory or `{ path, vars }`. |
 | `select` | no | Approved knowledge selector. Omit to include all approved knowledge. Supports internal `collections`, OKF `okfRoots`, and `include` / `exclude` path patterns relative to `knowledge/`. |
+| `navigation` | no | KB directory-index policy. Defaults to `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }`. |
+| `distribution` | no | Final knowledge-root namespace for a KB package. Defaults to `{ knowledgeNamespace: name }`; set it explicitly for a custom single- or multi-segment path. |
 
 `template` is required. Do not call `kbPackage({ name })` or
 `llmsPackage({ name })`.
 
+## Knowledge Distribution Namespace
+
+`name` identifies the build folder under `dist/` and is also the default
+single-level `distribution.knowledgeNamespace`. An explicit namespace may be
+one segment or a slash-separated sequence of safe lowercase path segments. A
+segment may contain letters and numbers joined by hyphens or dots, allowing
+identifiers such as `personal-user.123/package`. Keep every segment short,
+stable, and recognizable. Context treats the complete value as an opaque
+knowledge path and does not assign downstream meanings to individual segments.
+
+Templates keep a logical, consumer-neutral layout:
+
+```text
+skills/knowledge-query/SKILL.md
+wikis/index.md
+guides/...
+rules/...
+feats/...
+```
+
+For `name: "component-lib-kb"` with no explicit distribution, `context build`
+writes:
+
+```text
+skills/knowledge-query/SKILL.md
+wikis/component-lib-kb/index.md
+guides/component-lib-kb/...
+rules/component-lib-kb/...
+feats/component-lib-kb/...
+```
+
+The builder applies the knowledge mapping to template paths, copied knowledge,
+generated indexes, links, and inventory records. It does not apply the
+knowledge namespace to `skills/`, rewrite Markdown prose, or infer path
+segments from downstream platform identifiers. An explicit
+`distribution: { knowledgeNamespace: "platform/component-lib" }` produces the
+same shape under that multi-segment namespace instead.
+
+Because every KB package has a knowledge namespace, Skill templates must not
+hard-code flat package paths such as `wikis/index.md` or
+`rules/standards/index.md`.
+Use `{{wikisRoot}}`, `{{rulesRoot}}`, `{{guidesRoot}}`, or `{{featsRoot}}`
+instead. `context build` and `context status` reject flat Markdown links and
+inline-code paths in `skills/**/*.md` with
+`package/template-namespace-reference-flat`. This check is generic package
+validation; it does not depend on a downstream registry or distribution tool.
+
+Each rendered Skill must live at `skills/<skill-name>/SKILL.md`, and its YAML
+frontmatter `name` must equal `<skill-name>`. Use `{{skillName}}` in custom
+Skill templates. Skill names are author-maintained: when a short prefix is
+useful, rename the template directory to the complete final name, such as
+`skills/android-query/`; Context does not derive it from
+`knowledgeNamespace`.
+
 ## Template Variables
 
 Templates are rendered with Handlebars. Variables are available in both file
@@ -62,6 +122,11 @@ Built-in variables:
 |---|---|
 | `{{packageName}}` | Package name from the declaration. |
 | `{{packageKind}}` | `kb` or `llms`. |
+| `{{knowledgeNamespace}}` | Final KB knowledge namespace. Defaults to the package name; empty only for non-KB packages. |
+| `{{namespacedKnowledge}}` | Whether the package is a KB package with a knowledge namespace. |
+| `{{skillName}}` | Current author-maintained Skill directory name. |
+| `{{skillPath}}` | Current Skill's final package-relative `SKILL.md` path. |
+| `{{wikisRoot}}`, `{{guidesRoot}}`, `{{rulesRoot}}`, `{{featsRoot}}` | Final package-relative OKF root paths. |
 | `{{displayName}}` | Display name. Defaults to a title-cased `packageName`; override with `template.vars.displayName`. |
 | `{{knowledgeCount}}` | Number of selected approved Markdown files. |
 | `{{knowledgeTimestamp}}` | Latest `timestamp` from selected approved Markdown, or `1970-01-01T00:00:00.000Z` when empty. |
@@ -72,7 +137,7 @@ Built-in variables:
 | `{{knowledgeTreeNodes}}` | Nested path tree for custom navigation. |
 | `{{knowledgeTree}}` | Markdown tree preview. |
 | `{{knowledgeItemsMarkdown}}` | Markdown page list. |
-| `{{knowledgeGroupsMarkdown}}` | Markdown first-level group list with links to OKF root index paths. |
+| `{{knowledgeGroupsMarkdown}}` | Markdown navigation for the current index: direct page links for folded directories and links to generated indexes for expanded directories. |
 
 Custom variables come from `template.vars`.
 
@@ -120,18 +185,22 @@ The default kb template includes:
   collections expose
   `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
-  `dist/<package-name>/wikis/` directory.
+  `dist/<package-name>/wikis/<knowledge-namespace>/` directory.
+
+These are logical template paths. The package distribution namespace changes
+their final output paths as described above.
 
 During `context build`, the root `wikis/index.md` is rendered from the template.
-The builder also creates `index.md` files for directories under selected OKF
-roots when a directory does not already contain one. Keep OKF root indexes
-shallow by default: link to the next-level directories there, then let
-child indexes expose their own subdirectories and pages.
+The builder always provides an index for every selected OKF root. With the
+default navigation policy, smaller child directories are folded into their
+nearest generated ancestor index, so a short collection can link directly to
+its pages instead of producing one index per path segment.
 
 ## OKF Directory Indexes
 
-The generated `dist/<package-name>/wikis/` tree is the required default KB
-entry surface. Internal collections are mapped into OKF roots during build:
+The generated
+`dist/<package-name>/wikis/<knowledge-namespace>/` tree is the required default
+KB entry surface. Internal collections are mapped into OKF roots during build:
 `codegraph`, `business`, and `product` go to `wikis/`; `architecture`, `sop`,
 `faq`, `decision`, and `incident` go to `guides/`; `standards` and `test` go to
 `rules/`; and `feats` goes to `feats/`. Treat `wikis/` as the structured
@@ -141,24 +210,30 @@ a relationship.
 
 Default navigation rules:
 
-- `wikis/index.md` is the required default bundle index. It should describe the
-  package and list only the next-level directories. Other selected OKF roots
-  use their own `<okf-root>/index.md` when present or generated.
-- `<okf-root>/<group>/index.md` and deeper directory indexes are generated by
-  `context build` when missing.
+- `wikis/index.md` is the required default bundle index. Other selected OKF
+  roots always use their own `<okf-root>/index.md`.
+- With `foldDirectoryIndexes: true`, a non-root directory gets its own
+  `index.md` only when its descendant knowledge-page count is greater than
+  `maxInlineEntries`. The default threshold is `50`.
+- A folded directory is not discarded. Its pages are listed in the nearest
+  generated ancestor index, grouped by their relative directory path.
+- The threshold counts selected knowledge pages in the path tree. It does not
+  inspect Markdown line counts, headings, or content semantics.
+- Set `foldDirectoryIndexes: false` to generate an `index.md` for every
+  directory, matching the fully expanded navigation shape.
 - A generated directory index uses OKF frontmatter with `type: Knowledge
   Directory`, `title`, `description`, `tags`, `timestamp`, `resource`,
   `package`, `package_kind`, and `knowledge_count`.
-- Directory indexes list child directories first, then pages directly under the
-  directory.
+- Directory indexes list generated child indexes first, then pages from folded
+  paths.
 - `context build` validates links in OKF root indexes and generated
   child `index.md` files. Relative links must resolve to files inside
   `dist/<package-name>/`; broken links are reported as
   `package/index-link-invalid`.
 - If a project needs curated default navigation, edit the template-owned
-  `wikis/index.md`. Child `<okf-root>/**/index.md` paths are generated
-  directory indexes; template files or copied knowledge pages that collide with
-  those paths are rejected during build/status preflight.
+  `wikis/index.md`. Template files or copied knowledge pages that collide with
+  an index path selected by the current navigation policy are rejected during
+  build/status preflight.
 
 Users are expected to customize these template files. Edit
 `src/package-templates/kb/**` before `context build` to define project
@@ -225,9 +300,17 @@ endpoints are present in the selected package. Use those edge records for
 relationship citations inside the package instead of assuming the workspace
 `knowledge/structure.yaml` file is bundled.
 
+For KB packages, the inventory records `package.distribution` as
+`layout: "namespaced"` with the final `knowledge_namespace` and OKF root paths.
+Non-KB package types can remain `layout: "flat"`. Selected file and group
+records expose both the logical `okf_root` and final `okf_root_path`, so
+installers can inspect the layout without parsing paths or rewriting package
+content.
+
 Build expects approved knowledge to be closed when the project has source-bound
-document knowledge. If status says `compile-close-needed`, run
-`context close --format json` before build. Current close derives
+document knowledge. When `workflow.current.reason_code` is
+`route.close.projection-stale`, run the exact returned close command. Current
+close derives
 `knowledge/structure.yaml`, persists approved edge projection, and runs the
 final verify gate. References, changelog, package index, and section
 fingerprint rebuilds are not current close output; build only packages the

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,11 @@ knowledge/codegraph/module-a/...
 knowledge/codegraph/module-b/...
 ```
 
+For prose Views, omit `containment` when the page is an independent collection
+entry. The CLI then derives `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 +139,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 +171,15 @@ 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`.
+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-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.
+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.
 
 ### `allSources("repo")`
 
@@ -202,7 +207,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 +223,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 +245,21 @@ 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.
+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`
 
@@ -347,6 +365,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 +374,23 @@ 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;
+`--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. Successful 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.
 
+`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 +411,22 @@ 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.
+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
+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.
+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`
 
@@ -431,27 +459,22 @@ 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`
 
@@ -518,8 +541,12 @@ candidate estimate before writing `unapproved/entities.jsonl`. 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 +558,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 +570,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,19 +580,6 @@ 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:
-
-```bash
-context review migrate-codegraph-refs
-context verify
-```
-
-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.
-
 ### `reviewValidity`
 
 Declare the review step for a collection:

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 | KB knowledge namespace; defaults to the package name and may be explicitly overridden. Empty for non-KB packages. |
+| `namespacedKnowledge` | boolean | Whether the KB package has a knowledge namespace. |
+| `skillsRoot` | string | Skills root, currently `skills`. |
+| `wikisRoot` | string | Final wikis root, such as `wikis/component-lib-kb` or `wikis/platform/component-lib`. |
+| `guidesRoot` | string | Final guides root, such as `guides/component-lib-kb` or `guides/platform/component-lib`. |
+| `rulesRoot` | string | Final rules root, such as `rules/component-lib-kb` or `rules/platform/component-lib`. |
+| `featsRoot` | string | Final feats root, such as `feats/component-lib-kb` or `feats/platform/component-lib`. |
+| `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 package-relative OKF root; for KB packages it includes the distribution namespace. |
 | `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 package-relative OKF root; for KB packages it includes the distribution namespace. |
 | `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,14 +227,14 @@ 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.
+- 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
 `src/package-templates/kb/wikis/index.md` to add project-specific reading

package/index.d.ts

@@ -1,8 +1,8 @@
-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";
@@ -18,6 +18,9 @@ export type PackageTemplateInput = string | {
     path: string;
     vars?: Record<string, TemplateVarValue>;
 };
+export type PackageDistributionDefinition = {
+    knowledgeNamespace: string;
+};
 export type BasePackageDefinition = {
     name: string;
     reads: readonly PhaseResourceReference[];
@@ -28,6 +31,8 @@ export type BasePackageDefinition = {
 };
 export type KbPackageDefinition = BasePackageDefinition & {
     kind: "package.kb";
+    navigation: PackageNavigationDefinition;
+    distribution?: PackageDistributionDefinition;
 };
 export type LlmsPackageDefinition = BasePackageDefinition & {
     kind: "package.llms";
@@ -47,6 +52,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;