@c4a/context 0.6.0-alpha.1

package/docs/guides/package-outputs.md

@@ -0,0 +1,171 @@
+# Package Outputs
+
+Package outputs are generated folders under `dist/`. They turn approved
+knowledge from `knowledge/` into a shape that another consumer can install,
+read, or import.
+
+Package output is a human decision gate. Do not add package declarations until
+the user chooses the intended consumer and output shape.
+
+Package build consumes approved and closed knowledge. If status reports that
+close is required, run deterministic close before build. Current close derives
+`knowledge/structure.yaml`, persists approved edge projection, and runs the
+final verify gate without rewriting approved Markdown. References, changelog,
+package index, and section fingerprint rebuilds are not current close output.
+
+## Recommended First Output: Agent Knowledge-Base Package
+
+Choose an agent knowledge-base package first when the knowledge should help
+Coding Agents work with the project. After the user chooses this semantic
+output shape, implement it with `kbPackage()`.
+
+Typical output:
+
+```text
+dist/<package-name>/
+├── AGENTS.md
+├── skills/
+│   └── knowledge-query/
+│       └── SKILL.md
+└── wikis/
+    ├── index.md
+    └── ...
+```
+
+Choose this when the user wants:
+
+- agent-facing guidance generated from the reviewed knowledge;
+- a package that can be installed as an agent knowledge base;
+- a starting point that can later be refined into task-specific skills.
+
+The underlying `kbPackage()` declaration requires a template containing at
+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
+`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.
+
+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
+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.
+
+`index.md` is reserved for OKF bundle and directory indexes. Source documents
+may be named `index.md`, but generated concept pages must use a non-reserved
+name such as `index-page.md`; `context build` rejects copied knowledge that
+occupies `wikis/**/index.md`.
+
+`src/package-templates/kb/wikis/index.md` is the bundle entry page template.
+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
+`knowledgeGroups`, `knowledgeItems`, and `knowledgeTree` when a project needs
+custom navigation. Before customizing it, read
+`node_modules/@c4a/context/docs/reference/template-variables.md`.
+
+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
+with `select.exclude`.
+
+Template prose must not become a second knowledge source. If a template
+describes package coverage, scope, known gaps, or known limits, it must cite
+approved knowledge, `context-build-inventory.json`, or rendered structure data
+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.
+
+## Alternative Output: LLM Text
+
+Choose an LLM text bundle when the user wants a single text bundle for model
+context, RAG import, or manual reading. After the user chooses this semantic
+output shape, implement it with `llmsPackage()`.
+
+Typical output:
+
+```text
+dist/<package-name>/
+└── llms.txt
+```
+
+Choose this when the user wants:
+
+- one consolidated text file;
+- a format that is easy to copy, index, or upload elsewhere;
+- no agent skill packaging yet.
+
+## Skip Package Output
+
+The user may choose to stop after approved Markdown. In that case, keep
+`packages: []` and do not run `context build`.
+
+Approved knowledge still lives in:
+
+```text
+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.
+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.
+
+Recommended question shape:
+
+```text
+The reviewed knowledge is approved. The next decision is how to package it.
+
+Recommended: agent knowledge-base package
+dist/<name>-kb/
+├── AGENTS.md
+├── skills/knowledge-query/SKILL.md
+└── wikis/
+    ├── index.md
+    ├── <group>/index.md
+    └── <group>/...
+
+This is best if agents should use the knowledge as a reusable knowledge base.
+
+Alternative: LLM text bundle
+dist/<name>-llms/
+└── llms.txt
+
+This is best if you need one text bundle for model/RAG import.
+
+We can also skip package output for now and keep only knowledge/.
+
+Which one should I declare first?
+```
+
+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

@@ -0,0 +1,274 @@
+# Package Templates
+
+Packages project approved knowledge into `dist/<package-name>/`.
+
+For the user-facing decision process, read
+[Package Outputs](../guides/package-outputs.md) first. This reference only
+documents the API and template behavior.
+
+## Package Factories
+
+```ts
+import { llmsPackage, kbPackage } from "@c4a/context";
+```
+
+### `kbPackage`
+
+```ts
+kbPackage({
+  name: "component-lib-kb",
+  template: {
+    path: "src/package-templates/kb",
+    vars: { displayName: "Component Library KB" },
+  },
+  select: {
+    collections: ["architecture", "sop"],
+    okfRoots: ["wikis", "guides"],
+    include: ["architecture/component-lib/**", "sop/component-lib/**"],
+    exclude: ["**/internal/**"],
+  },
+});
+```
+
+### `llmsPackage`
+
+```ts
+llmsPackage({
+  name: "component-lib-llms",
+  template: "src/package-templates/llms",
+  select: { include: ["codegraph/component-lib/**"] },
+});
+```
+
+## Required Fields
+
+| Field | Required | Meaning |
+|---|---:|---|
+| `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/`. |
+
+`template` is required. Do not call `kbPackage({ name })` or
+`llmsPackage({ name })`.
+
+## Template Variables
+
+Templates are rendered with Handlebars. Variables are available in both file
+contents and file paths.
+
+Built-in variables:
+
+| Variable | Meaning |
+|---|---|
+| `{{packageName}}` | Package name from the declaration. |
+| `{{packageKind}}` | `kb` or `llms`. |
+| `{{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. |
+| `{{knowledge}}` | Concatenated selected approved Markdown bundle. |
+| `{{approvedKnowledge}}` | Alias for `{{knowledge}}`. |
+| `{{knowledgeItems}}` | Array of selected approved knowledge page metadata for loops. |
+| `{{knowledgeGroups}}` | Selected approved knowledge pages grouped by OKF root and first directory segment; each item also exposes `internal_collection`. |
+| `{{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. |
+
+Custom variables come from `template.vars`.
+
+For loops, conditionals, comments, and record fields, read
+[Template Variables](./template-variables.md).
+
+## Template Examples
+
+Installed examples:
+
+```text
+node_modules/@c4a/context/templates/package-templates/kb/
+node_modules/@c4a/context/templates/package-templates/llms/
+```
+
+Workspace convention:
+
+```text
+src/package-templates/
+├── kb/
+│   ├── AGENTS.md
+│   ├── wikis/
+│   │   └── index.md
+│   └── skills/
+│       └── knowledge-query/
+│           └── SKILL.md
+└── llms/
+    └── llms.txt
+```
+
+`kbPackage()` is for an agent knowledge-base package. The package still uses a
+`skills/` folder internally because Claude/Codex consume reusable agent
+instructions from that convention. Its template must contain at least one
+`SKILL.md` file and `wikis/index.md`. A template with only `AGENTS.md` is a
+placeholder document package, not a usable kb package, and `context build`
+rejects it.
+
+The default kb template includes:
+
+- `skills/knowledge-query/SKILL.md`, a reusable skill that teaches agents to
+  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
+  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/` 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.
+
+## 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:
+wiki-like collections under `wikis/`, guide-like collections under `guides/`,
+rule-like collections under `rules/`, and feature namespace output under
+`feats/`.
+
+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.
+- 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.
+- `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.
+
+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.
+
+## C4A OKF Profile
+
+Approved Markdown and kb package OKF output are an OKF superset:
+
+- 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;
+- 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="..." -->`
+  comments;
+- do not add frontmatter `source_refs`; page-level provenance is derived from
+  section source refs when needed;
+- do not add `context` or `schema` fields.
+
+Accepted section `source_ref` forms:
+
+```text
+src-N#symbol:<symbol-id>:<kind>@<digest>
+src-N#span:<heading-hint> L<start>-<end>@<span-hash>
+```
+
+`#span:` refs retain source snapshot line ranges for human review, diffing, and
+stable re-pinning. They resolve against committed file/lark document snapshots,
+not the code symbol index.
+
+The kb package root may contain agent files such as `AGENTS.md` and `skills/`.
+The OKF-compatible surface is the selected `wikis/`, `guides/`, `rules/`, and
+`feats/` subtrees.
+
+## Build Behavior
+
+`context build`:
+
+1. Selects approved Markdown from `knowledge/`.
+2. Renders all files from `template.path`.
+3. Copies selected approved Markdown into the package output.
+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
+   `context-build-inventory.json`.
+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" }`,
+`{ "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
+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.
+
+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
+`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
+current closed state.
+
+Before writing output, `context build` validates that rendered template paths
+are safe, unique, and do not collide with copied knowledge paths. For example,
+a template file that renders to `wikis/codegraph/foo.md` is rejected if
+selected knowledge such as `knowledge/codegraph/foo.md` maps to that same OKF
+output path. Rename the template file or use `select.exclude` when the
+collision is intentional.
+
+After writing KB output, `context build` checks selected OKF root `index.md`
+files and generated child directory indexes. If an index link is broken, fix
+the package template, approved knowledge path, or directory index generation,
+then rerun `context build`; do not patch `dist/` directly as the durable fix.
+
+If a template describes package coverage, scope, known gaps, or known limits,
+it must cite approved knowledge, `context-build-inventory.json`, or
+explicitly rendered structure data. Otherwise build reports a
+template-boundary diagnostic. Keep factual claims in approved knowledge and
+structure; templates only package and route that material.
+
+After build, inspect the output shape. `context build` and `context verify`
+validate protocol structure; they do not decide whether the selected knowledge
+is meaningful enough for the user.
+
+## Select Patterns
+
+Package selection is evaluated in this order:
+
+1. `collections` filters by internal approved collection, for example
+   `architecture`, `sop`, `standards`, or `feats`.
+2. `okfRoots` filters by output root after OKF mapping: `wikis`, `guides`,
+   `rules`, or `feats`.
+3. `include` patterns are matched against approved paths relative to
+   `knowledge/`.
+4. `exclude` patterns remove matches after the previous filters.
+
+Path patterns are relative to `knowledge/`.
+
+```ts
+select: {
+  collections: ["architecture", "sop"],
+  okfRoots: ["wikis", "guides"],
+  include: ["architecture/component-lib/**", "sop/component-lib/**"],
+  exclude: ["**/internal/**"],
+}
+```
+
+If `include` is omitted, all approved knowledge is included unless excluded.
+When `collections` or `okfRoots` are present, a file must pass those filters
+before include/exclude path matching is considered.