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

package/README.md

@@ -117,11 +117,12 @@ include `{{packageName}}`, `{{displayName}}`, `{{knowledgeCount}}`,
 `{{knowledgeGroups}}`, `{{knowledgeItems}}`, `{{knowledgeTree}}`, and
 `{{buildInventory}}`.
 
-Every KB package defaults `distribution.knowledgeNamespace` to its package
-`name`, producing a short single-level knowledge directory. Set the field
-explicitly when a multi-segment namespace such as
-`personal-user.123/package` is required. Context isolates OKF roots under the
-complete value; Skill names remain author-maintained and independent.
+Every KB package emits flat roots such as `wikis/`, `guides/`, `rules/`, and
+`feats/`. The package `name` defines only the `dist/<package-name>/` boundary;
+it is not repeated inside knowledge paths. Context still accepts
+`distribution.knowledgeNamespace` from older workspaces, but the legacy value
+no longer changes build output and new declarations do not need it. Skill names
+remain author-maintained and independent.
 
 For advanced routing and retrieval, a template may carry a local script such as
 `query.ts`, with a Skill describing when and how an Agent should call it. The
@@ -134,7 +135,8 @@ The SDK stays declarative. It may describe reads, writes, phases, review, and
 package selection, but the CLI owns source materialization, capture, extraction,
 review application, approved Markdown materialization, verification, and build.
 Do not replace CLI lifecycle operations with direct edits to `sources/`,
-`unapproved/`, `knowledge/`, or `dist/`.
+`knowledge/`, `dist/`, or the ignored `.tmp/context-runtime/lifecycle/` runtime
+state. The CLI owns that runtime state and removes it after a successful close.
 
 ## Documentation
 

package/README.zh-CN.md

@@ -97,15 +97,16 @@ kb/
 
 模板使用 Handlebars 变量，可以作用于文件内容和路径。常用变量包括 `{{packageName}}`、`{{displayName}}`、`{{knowledgeCount}}`、`{{knowledgeGroups}}`、`{{knowledgeItems}}`、`{{knowledgeTree}}` 和 `{{buildInventory}}`。
 
-每个 KB 包默认使用包 `name` 作为 `distribution.knowledgeNamespace`，生成简短的
-单级知识目录。需要 `personal-user.123/package` 这类多段目录时可以显式配置该字段。
-Context 会按照完整 namespace 隔离各个 OKF 根目录；Skill 名称仍由作者独立维护。
+每个 KB 包直接输出扁平的 `wikis/`、`guides/`、`rules/`、`feats/` 等根目录；包 `name`
+只用于确定 `dist/<package-name>/` 边界，不会再次写入知识路径。旧工作区中的
+`distribution.knowledgeNamespace` 仍可被读取，但不再改变构建结果；新声明无需配置它。
+Skill 名称继续由作者独立维护。
 
 如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
 
 ## 状态边界
 
-SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`unapproved/`、`knowledge/` 或 `dist/` 来替代 CLI 生命周期操作。
+SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`knowledge/`、`dist/` 或被忽略的 `.tmp/context-runtime/lifecycle/` 运行态来替代 CLI 生命周期操作；成功 close 后 CLI 会清理该运行态。
 
 ## 参考文档
 

package/docs/getting-started.md

@@ -13,10 +13,21 @@ bun install
 context status --format json
 ```
 
+Use `--language zh-CN` (or `--language en`) during initialization when the
+generated README, AGENTS contract, and package starter templates should use a
+specific language. Context stores this choice in `package.json`; it does not
+guess from the shell locale or Agent conversation.
+
 Use `--dev` when testing a local link or prepared pack before the matching SDK
 version is published. It writes a `file:` dependency to the SDK resolved beside
 the active CLI. Published users can omit it and install the versioned SDK from
 the registry.
+
+Without `project-dir`, init uses the dedicated `context/` directory. Initializing
+inside a non-empty directory that is not already a Context workspace is blocked
+before any files are written; use the returned `--allow-nonempty` command only
+after confirming that the existing files should share the workspace root.
+
 When operating through an Agent plugin, use the installed Context continuation
 entry from the project root after initialization. It consumes
 `workflow.current`, loads only the selected resources, and calls lower-level
@@ -216,7 +227,7 @@ continuation entry. The
 normal sequence is:
 
 1. capture the source into committed snapshots;
-2. investigate evidence and confirm `unapproved/structure.yaml`;
+2. investigate evidence and confirm the CLI-managed lifecycle structure;
 3. compile every source-bound View from confirmed structure;
 4. review/apply the complete candidate batch once;
 5. run close once, then verify and build when packages are declared.
@@ -287,18 +298,21 @@ context review html architecture --open
 Use the generated HTML page to approve or reject candidates. If the browser does
 not open automatically, use the emitted `file://` URL. When
 finished, open `Payload` and copy the review decision Payload into the agent chat.
-Uniform decisions use one JSON line; exceptions add JSONL lines. The
-agent writes that pasted payload to a normal temporary file under the workspace
-`.tmp/` directory and runs:
+Uniform decisions use one JSON line; exceptions add JSONL lines. The agent
+writes that pasted payload to the recommended workspace scratch area,
+`.tmp/agent-payloads/`, and runs:
 
 ```bash
 context review apply <payload-file>
 ```
 
 Do not hand-write approved Markdown. `context review apply` owns materialization
-from `unapproved/entities.jsonl` into `knowledge/`.
-Do not store review payloads through scratch files outside `.tmp/` or by
-editing workspace config.
+from the CLI-managed lifecycle candidate ledger into `knowledge/`. The runtime
+ledger is ignored and is removed after a successful close; durable rejected
+candidate fingerprints, when any, are kept in `knowledge/decisions.json`.
+The location is a recommendation rather than a CLI restriction. Do not create a
+top-level scratch directory or edit workspace config merely to retain a review
+payload.
 
 ## 5. Build Packages
 
@@ -326,14 +340,11 @@ Choose an agent knowledge-base package when agents should consume the reviewed
 knowledge as a reusable package. After the user chooses this output shape,
 declare it with `kbPackage()`.
 
-The package name becomes its stable single-level knowledge namespace by
-default. Ask for a custom namespace only when the user needs another value. An
-explicit namespace may contain several concise lowercase path segments, such
-as `group/package` or `personal-user.123/package`; each segment may use letters
-and numbers joined by hyphens or dots. Do not infer custom values from
-downstream platform identifiers. Ask separately whether the author wants a
-short Skill prefix, then maintain the complete final Skill directory name in
-the template.
+The package name already identifies the surrounding `dist/` directory. The OKF
+roots inside it stay flat (`wikis/`, `guides/`, `rules/`, and `feats/`), so do
+not ask for a second distribution namespace. Ask separately whether the author
+wants a short Skill prefix, then maintain the complete final Skill directory
+name in the template.
 
 The default `knowledge-query` skill teaches agents how to query copied OKF root
 directories structure-first, starting with `wikis/`, cite

package/docs/guides/agent-guide.md

@@ -30,6 +30,14 @@ without another question. Review uses the CLI's atomic `context review
 approve-all ... --managed` route; valid structure staging records
 `confirmed_by: managed-session`.
 
+After the first managed status evaluation, use
+`context run --managed --until blocked-or-complete --format json` when the
+current work can advance through consecutive mechanical routes. The CLI
+executes only a unique immediate non-read command, re-evaluates after each
+receipt, and stops before Agent interpretation, configuration, missing
+authority, diagnostics, or multiple commands. Continue from the returned
+`workflow.current`.
+
 This is execution authority, not project configuration. Do not add it to
 `defineProject`, environment files, or committed workspace state, and do not
 carry it into a new conversation. It never grants a new source boundary or
@@ -68,11 +76,21 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 
 - `src/index.ts` declares sources, phases, and packages.
 - `sources/repo/index.yaml`, `sources/file/index.yaml`, and `sources/lark/index.yaml` declare sources.
-- `unapproved/entities.jsonl` is the committed draft/rejected/deprecated ledger.
-- `knowledge/` contains approved Markdown.
+- `.tmp/context-runtime/lifecycle/` is the ignored, CLI-managed draft candidate
+  ledger and confirmed structure state for an open lifecycle round.
+- `knowledge/` contains approved Markdown, the durable
+  `knowledge/structure.yaml` projection, and (only when needed) the compact
+  `knowledge/decisions.json` rejected candidate ID-to-fingerprint map.
+- `knowledge/structure.yaml.source_inputs` contains only source, collection,
+  and consumed snapshot hash for closed prose targets. It lets status detect a
+  changed or unfinished target without retaining lifecycle snapshots.
 - `dist/` contains generated package outputs.
+- `.tmp/agent-payloads/` is the recommended location for transient inputs written
+  by the Agent for CLI commands. It is not enforced, but avoids introducing
+  top-level scratch directories; remove these files after the corresponding
+  stage or apply succeeds unless the user explicitly wants to retain them.
 - file and Lark documents from one date live as sibling files under `sources/file/<date>/` and `sources/lark/<date>/`; each date directory has one shared `manifest.json`.
-- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks.
+- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks. Successful close removes completed lifecycle and review runtime state.
 
 Do not create hidden workspace state directories.
 
@@ -91,12 +109,12 @@ Present only the current workflow surface:
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
 | Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory and updates that directory's single `manifest.json`. |
 | Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
-| Confirm prose structure | `alignProse` validates and stages `unapproved/structure.yaml`. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
+| Confirm prose structure | `alignProse` validates and stages CLI-managed lifecycle structure. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
 | Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |
 | Review and apply | Use `context review html` and `context review apply`. Approved prose pages are source-mirrored; rewrite/compression problems should return to structure/compile repair before apply. |
 | Close, verify, build | Run `context close`, `context verify`, then `context build`. Close derives `knowledge/structure.yaml`, approved edge projection, and the final verify gate. |
 | Code extraction | Use `context source inspect <source-name>` and the declared extract phase preview before code draft writes. |
-| Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `unapproved/`, `dist/`, or `.tmp` to simulate lifecycle actions. |
+| Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `dist/`, or `.tmp` to simulate lifecycle actions. |
 
 Judgment behavior is part of evidence views, source span resolvers, repair
 hints, review/status diagnostics, OKF indexes, and package query discipline. Do
@@ -127,8 +145,9 @@ align:lark:<source-name>:architecture
 dist/<source-name>-kb/
 ```
 
-Prose align/compile paths derive from collection and slug. `containment` is
-optional and should be supplied only for an intentional parent/child hierarchy;
+Every prose View requires a stable filename `slug`. The CLI derives its path
+from collection, slug, and optional `containment`; omit `path` from the input.
+Supply `containment` only for an intentional parent/child hierarchy;
 independent collection entries stay directly under the collection.
 Codegraph paths use the registered date/module grouping before the symbol slug.
 
@@ -327,7 +346,7 @@ knowledge/codegraph/<module>/symbol/<slug>.md
 If the module or resulting path shape looks wrong, stop and repair the
 module registration before running extraction. An extra repeated package
 segment below the module may indicate an over-broad source boundary. Do not write ad hoc scripts to
-count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
+count packages, parse `package.json`, or sample the lifecycle candidate ledger.
 
 ## Review Rules
 
@@ -372,6 +391,7 @@ context run align:<type>:<source>:<collection> --view read-plan --format json
 context run align:<type>:<source>:<collection> --view source-index --compact --format json
 context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
 context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view existing-knowledge --query <title-or-stable-ref> --format json
 context run align:<type>:<source>:<collection> --view schema --format json
 context run align:<type>:<source>:<collection> --validate --input <structure.yaml> --format json
 context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
@@ -380,9 +400,12 @@ context run align:<type>:<source>:<collection> --stage --input <structure.yaml>
 
 Read source material only through these evidence views. `source-index` gives a
 compact refs-first map when run with `--compact`; use `span-detail` /
-`span-text` only for exact evidence. The CLI applies deterministic boundary
-repairs internally and returns only blockers that need Agent judgment. For
-oversized Views, use the returned structural diagnostics while classifying
+`span-text` only for exact evidence. Before introducing a new Node identity,
+use the targeted `existing-knowledge` View returned by the read plan to inspect
+approved stable refs; do not inspect `knowledge/**` directly. The CLI applies
+deterministic boundary repairs internally and returns only blockers that need
+Agent judgment. For oversized Views, use the returned structural diagnostics
+while classifying
 child Nodes from evidence. Stage only after validation state is `ready`; stage
 opens the final `structure-summary` report for the current Route's confirmation
 gate. Ask a separate structure-design question only when evidence supports
@@ -430,15 +453,11 @@ dist/<name>-kb/
 This is an agent knowledge-base package. It is the recommended first output for
 agent consumption; the internal `skills/` folder follows agent installation
 conventions.
-The package name is the default single-level
-`distribution.knowledgeNamespace`. Ask for an override only when the user
-needs another value; an explicit namespace may contain several concise
-lowercase path segments, such as `group/package` or
-`personal-user.123/package`, with letters and numbers joined by hyphens or
-dots. The namespace applies only to OKF output roots. Ask separately whether
-the author wants a short Skill prefix; if so, maintain the complete final Skill
-directory name in the template. Do not infer custom values from downstream
-platform identifiers.
+The package name already identifies the surrounding `dist/` directory. Its OKF
+roots stay flat (`wikis/`, `guides/`, `rules/`, and `feats/`), so do not ask for
+a second distribution namespace. Ask separately whether the author wants a
+short Skill prefix; if so, maintain the complete final Skill directory name in
+the template.
 The default `knowledge-query` skill teaches agents to query copied OKF root
 directories structure-first, starting with `wikis/`, cite
 page/section evidence, use structure/build metadata when present, and report

package/docs/guides/package-outputs.md

@@ -43,8 +43,7 @@ least one `SKILL.md` and `wikis/index.md`.
 The default `src/package-templates/kb/` template is only a starting point.
 Inspect the generated `dist/<package-name>/` before calling it usable.
 
-KB packages use their package name as a single-level knowledge namespace by
-default:
+KB packages use flat package-relative knowledge roots:
 
 ```ts
 kbPackage({
@@ -53,44 +52,43 @@ kbPackage({
 });
 ```
 
-This keeps the build folder name independent from install paths and produces
-paths such as:
+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/component-lib-kb/index.md
-guides/component-lib-kb/...
-rules/component-lib-kb/...
-feats/component-lib-kb/...
+wikis/index.md
+guides/...
+rules/...
+feats/...
 ```
 
-Ask for a custom namespace only when the user needs something other than the
-package name. An explicit value may contain multiple safe lowercase path
-segments:
-
-```ts
-distribution: { knowledgeNamespace: "platform/component-lib" }
-```
-
-Each segment may contain letters and numbers joined by hyphens or dots; keep
-the complete value concise and stable. Context treats it as an opaque knowledge
-path and does not infer downstream platform identifiers or classify package
-content.
+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`. Context never prepends the knowledge
-namespace to a Skill name.
+example `skills/android-query/SKILL.md`. Package-root layout never renames a
+Skill.
 
-The default `knowledge-query` skill carries the structure-first query
-discipline: start from OKF directory indexes, use
+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. Its final template-author section
+requires package authors to replace or edit the generic routing when the
+package needs project-specific terminology, entry points, known limits, or
+task workflows. Authors may explicitly accept the generic default when it is
+intentionally sufficient.
+
+The same inventory exposes `structure.relationship_coverage`. It records
+whether selected codegraph pages have current source-backed AST relationship
+metadata, how many codegraph views were selected, and how many package-visible
+edges were emitted. An empty edge list is therefore explicit evidence of a
+coverage state, not permission to invent a dependency.
 
 The generated `wikis/` directory is the default OKF root and follows the C4A OKF
 Profile. Internal production collections are mapped into package OKF roots such
@@ -103,9 +101,8 @@ contain Markdown with OKF fields and C4A extension fields at the top level, plus
 `visibility`, and `code_symbols` are not nested under `context`, and page
 frontmatter does not contain `source_refs`. The package root is an agent
 package; the OKF-compatible interchange surface is the selected OKF root
-subtrees under `dist/<package-name>/`. The required logical template entry is
-`wikis/index.md`; a namespaced package writes it to
-`wikis/<knowledge-namespace>/index.md`.
+subtrees under `dist/<package-name>/`. The required template entry and final
+output path are both `wikis/index.md`.
 
 Current collection mapping:
 
@@ -136,7 +133,8 @@ 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.
+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
@@ -144,6 +142,13 @@ The default threshold is 50 selected knowledge pages. Use Handlebars variables s
 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
@@ -230,12 +235,10 @@ We can also skip package output for now and keep only knowledge/.
 Which one should I declare first?
 ```
 
-If the user chooses the Agent knowledge-base package, explain that its package
-name is already the default knowledge namespace. Ask for an override only when
-the user needs a different single- or multi-segment path. Ask separately whether
-its Skills need a short prefix. Treat these as independent choices: the
-knowledge namespace controls only OKF roots, while the author maintains final
-Skill names.
+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.

package/docs/reference/package-templates.md

@@ -52,20 +52,15 @@ llmsPackage({
 | `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. |
+| `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 })`.
 
-## Knowledge Distribution Namespace
+## Flat Package Roots
 
-`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.
+`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:
 
@@ -77,39 +72,32 @@ rules/...
 feats/...
 ```
 
-For `name: "component-lib-kb"` with no explicit distribution, `context build`
-writes:
+For `name: "component-lib-kb"`, `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/...
+wikis/index.md
+guides/...
+rules/...
+feats/...
 ```
 
-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.
+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
-`knowledgeNamespace`.
+the package name.
 
 ## Template Variables
 
@@ -122,8 +110,8 @@ 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. |
+| `{{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. |
@@ -181,14 +169,14 @@ 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.
 - `wikis/index.md`, the editable OKF bundle entry page for the generated
-  `dist/<package-name>/wikis/<knowledge-namespace>/` directory.
-
-These are logical template paths. The package distribution namespace changes
-their final output paths as described above.
+  `dist/<package-name>/wikis/` directory.
 
 During `context build`, the root `wikis/index.md` is rendered from the template.
 The builder always provides an index for every selected OKF root. With the
@@ -199,7 +187,7 @@ its pages instead of producing one index per path segment.
 ## OKF Directory Indexes
 
 The generated
-`dist/<package-name>/wikis/<knowledge-namespace>/` tree is the required default
+`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
@@ -235,11 +223,13 @@ Default navigation rules:
   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
 
@@ -301,11 +291,9 @@ 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.
+`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. When `workflow.current.reason_code` is