@c4a/context 0.6.1 → 0.6.3

package/docs/guides/package-outputs.md

@@ -43,28 +43,80 @@ 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/...
+others/assets/...
+```
+
+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.
+
+When approved pages reference materialized document resources, Context keeps
+their production copies in content-addressed `knowledge/assets/` paths. Build
+copies only the resources selected by package pages to `others/assets/` and
+rewrites relative Markdown links. Source audit XML and capture reports stay in
+the production workspace; they are not distributed as reader assets. See
+[Lark Resource Materialization](./lark-resources.md).
+
+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 +147,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 +175,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 +215,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 +233,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 +249,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.

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,54 @@ 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 | Legacy input accepted from older workspaces. It no longer changes package paths and should not be added to new declarations. |
 
 `template` is required. Do not call `kbPackage({ name })` or
 `llmsPackage({ name })`.
 
+## Flat Package Roots
+
+`name` identifies the package boundary under `dist/`. Context does not repeat
+that name inside the package's knowledge roots.
+
+Templates keep a logical, consumer-neutral layout:
+
+```text
+skills/knowledge-query/SKILL.md
+wikis/index.md
+guides/...
+rules/...
+feats/...
+```
+
+For `name: "component-lib-kb"`, `context build` writes:
+
+```text
+skills/knowledge-query/SKILL.md
+wikis/index.md
+guides/...
+rules/...
+feats/...
+```
+
+The builder maps copied knowledge, generated indexes, links, and inventory
+records into these roots without rewriting Markdown prose or inferring a
+downstream registry identity. New declarations should omit `distribution`.
+Older declarations that still contain `distribution.knowledgeNamespace` remain
+loadable, but the value does not change output paths or the build fingerprint.
+
+Use `{{wikisRoot}}`, `{{rulesRoot}}`, `{{guidesRoot}}`, or `{{featsRoot}}` in
+Skill templates so references share the package-root contract. These variables
+render to the flat root names above.
+
+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
+the package name.
+
 ## Template Variables
 
 Templates are rendered with Handlebars. Variables are available in both file
@@ -62,6 +110,11 @@ Built-in variables:
 |---|---|
 | `{{packageName}}` | Package name from the declaration. |
 | `{{packageKind}}` | `kb` or `llms`. |
+| `{{knowledgeNamespace}}` | Legacy configured namespace when an older workspace still declares one; otherwise empty. Do not use it for new output paths. |
+| `{{namespacedKnowledge}}` | Always `false`; retained only so older templates remain renderable. |
+| `{{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 +125,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`.
 
@@ -98,7 +151,9 @@ src/package-templates/
 │   │   └── index.md
 │   └── skills/
 │       └── knowledge-query/
-│           └── SKILL.md
+│           ├── SKILL.md
+│           └── scripts/
+│               └── search.mjs
 └── llms/
     └── llms.txt
 ```
@@ -116,22 +171,30 @@ The default kb template includes:
   query copied knowledge pages structure-first, cite page/section evidence, use
   `context-build-inventory.json` edge records for package-visible
   relationships, and report gaps instead of inventing unsupported answers. The
+  build inventory also exposes `structure.relationship_coverage` so a consumer
+  can distinguish an observed zero-edge result from unknown relationship
+  coverage. The
   default entry OKF root is `wikis/`; packages that select additional internal
   collections expose
   `guides/`, `rules/`, or `feats/` indexes when those roots are selected.
+- `skills/knowledge-query/scripts/search.mjs`, a dependency-free BM25 fallback
+  for exact terms, mixed keyword queries, and large Markdown indexes. It chunks
+  mechanically, returns inspectable paths and line ranges, and never replaces
+  source-backed relationship evidence.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
   `dist/<package-name>/wikis/` directory.
 
 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/` 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,39 +204,48 @@ 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
-specific skills, prompts, routing rules, and package instructions. Do not add a
-package-name skill by default; add one only when the user wants project-specific
-behavior beyond knowledge lookup.
+The generated templates are complete generic defaults. Before publishing,
+package authors should replace or edit `src/package-templates/kb/**` when the
+package needs project-specific skills, prompts, routing rules, terminology, or
+package instructions. If the generic behavior is intentionally sufficient,
+explicitly accept the unchanged default through the package-template Review
+Route. Do not add a package-name Skill by default; add one only when the user
+wants project-specific behavior beyond knowledge lookup.
 
-## C4A OKF Profile
+## Context OKF Profiles
 
-Approved Markdown and kb package OKF output are an OKF superset:
+Approved Markdown under `knowledge/` is the production source of truth:
 
 - top-level YAML frontmatter uses OKF fields such as `type`, `title`,
   `description`, `tags`, `timestamp`, and `resource`;
-- C4A extension metadata such as `sources`, `visibility`, and `code_symbols`
-  also lives at the top level;
+- Context production metadata such as `sources`, `node_type`, `visibility`,
+  `code_symbols`, relationship records, and `candidate_fingerprint` also lives
+  at the top level;
 - do not nest C4A extension metadata under `context`; fields such as
   `context.sources` and `context.code_symbols` are not part of the 0.6 profile;
 - section provenance lives in `<!-- context:section ... source_ref="..." -->`
@@ -182,6 +254,15 @@ Approved Markdown and kb package OKF output are an OKF superset:
   section source refs when needed;
 - do not add `context` or `schema` fields.
 
+Package knowledge pages under `dist/<package-name>/` use a consumer projection.
+They retain reader-facing fields such as `title`, `type`, `description`, `tags`,
+`timestamp`, and custom non-lifecycle fields. Node identity, `resource`,
+`sources`, Section evidence comments, and build-only fields are omitted from the
+page. `context-build-inventory.json` records the distributed path, approved
+knowledge path, node identity, source summary, and package-visible structure.
+Maintainers return to the mapped `knowledge/` page for exact `sources` and
+`source_ref` attribution. `knowledge/` is never rewritten by this projection.
+
 Accepted section `source_ref` forms:
 
 ```text
@@ -191,7 +272,7 @@ src-N#span:<heading-hint> L<start>-<end>@<span-hash>
 
 The code symbol form includes the source-relative file so same-name symbols in
 different files resolve to one exact symbol-index row. Consumers should still
-treat the complete `source_ref` as opaque. Codegraph pages keep
+treat the complete `source_ref` as opaque. Production codegraph pages keep
 `candidate_fingerprint` at the top level and do not duplicate this evidence in
 `code_origin`.
 
@@ -209,7 +290,7 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 
 1. Selects approved Markdown from `knowledge/`.
 2. Renders all files from `template.path`.
-3. Copies selected approved Markdown into the package output.
+3. Projects selected approved Markdown into consumer-oriented package pages.
 4. For `llmsPackage`, appends selected knowledge to `llms.txt` when the template
    does not already use `{{knowledge}}` or `{{approvedKnowledge}}`.
 5. Writes deterministic package inventory such as
@@ -217,7 +298,9 @@ The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
 6. Writes output under `dist/<package-name>/`.
 
 `context-build-inventory.json` records what was selected and why. Each selected
-file includes `selected_by` entries such as `{ "kind": "collection" }`,
+file includes `selected_by` entries such as `{ "kind": "collection" }` and a
+`production_metadata` object for selected page-level production fields. Child
+and relationship records use the inventory's canonical structure projection,
 `{ "kind": "okf_root" }`, `{ "kind": "include" }`, or
 `{ "kind": "default" }`. The inventory also exposes package-visible typed
 edges under `structure.edge_records`; these records are filtered to edges whose
@@ -225,9 +308,15 @@ 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: "flat"`, `knowledge_namespace: null`, and the four package-relative
+OKF roots. Selected file and group records expose both the logical `okf_root`
+and final `okf_root_path`, so consumers do not need to infer paths.
+
 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