@c4a/context-cli 0.6.1-beta.3 → 0.6.1-beta.5

package/providers/context/resources/manuals/reference/package-templates.md

@@ -58,20 +58,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:
 
@@ -83,39 +78,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
 
@@ -128,8 +116,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. |
@@ -187,14 +175,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
@@ -205,7 +193,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
@@ -241,11 +229,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
 
@@ -307,11 +297,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

package/providers/context/resources/manuals/reference/project-api.md

@@ -55,10 +55,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.
+For prose Views, provide a stable filename `slug` and omit `path`; the CLI
+derives the path. Omit `containment` when the page is an independent collection
+entry, producing `knowledge/<collection>/<slug>.md`. Set `containment` only
+when the approved structure intentionally places the page under a parent path;
+it is not a required source/module wrapper.
 
 The registry stores this as one date entry containing several `modules` entries,
 and materializes each module at `sources/repo/<date>/<module>`.
@@ -185,7 +186,10 @@ with the next declared command in `workflow.current.commands`.
 Each command item declares its effect and availability. The current route's
 `gate` identifies the decision and authority boundary. Write commands are bound
 to the workflow revision; after one succeeds, rerun status instead of reusing
-the old command.
+the old command. An external command also declares
+`execution.target: agent-host`; execute it as a top-level Agent-host action so
+network and credential-store access are not lost inside a restricted child
+sandbox.
 
 ### `allSources("repo")`
 
@@ -251,6 +255,10 @@ context review approve-all <collection> --managed --format json
 context review approve-all --all --managed --format json
 ```
 
+The default JSON result reports counts and change totals without listing every
+candidate id or materialized path. Add `--verbose` only when debugging requires
+the complete candidate and page details.
+
 Managed structure confirmation and Review use only the revision-bound commands
 returned by `workflow.current`. Source boundaries and unread source bodies,
 external operations, payload validation, deterministic close, and verification
@@ -330,9 +338,17 @@ Register each source with
 flag: `--url`, `--doc-token`, or `--wiki-token`. Multiple documents may share
 one date batch; when `--module` is omitted, the CLI derives an opaque,
 credential-safe module id. Capture reads the
-remote document through the CLI runner, writes normalized snapshot files under
-`sources/lark/<date>/` as sibling document files tracked by one date-level `manifest.json`, and does not write access credentials into the
-workspace.
+remote document through the CLI runner as structured Docx XML. Context keeps a
+redacted XML audit asset, projects supported blocks deterministically into
+readable Markdown, and registers external resources such as document citations,
+images, video, whiteboards, and Base references in the snapshot manifest even
+when their binary content is not downloaded. The projection does not infer or
+summarize document meaning. Its fidelity report closes discovered blocks against
+converted and intentionally skipped blocks; a non-empty unsupported block is a
+fidelity error and prevents downstream Review until capture support is fixed.
+Snapshot files live under `sources/lark/<date>/` as sibling document files
+tracked by one date-level `manifest.json`. Access credentials and transient
+signed media URLs are not written into the workspace.
 
 Use a typed document reference in project declarations:
 
@@ -380,15 +396,56 @@ context run align:file:<source-name>:architecture --view structure-summary --inp
 context run align:file:<source-name>:architecture --stage --input <structure.yaml> --format json
 ```
 
+When `workflow.current.batch` is present, several independent document slots
+can be prepared in one Agent pass and validated or staged through one command:
+
+```yaml
+schema: context.prose.structure-batch.v1
+items:
+  - phase_id: align:file:<source-a>:architecture
+    input: .tmp/agent-payloads/<source-a>-structure.yaml
+  - phase_id: align:file:<source-b>:architecture
+    input: .tmp/agent-payloads/<source-b>-structure.yaml
+```
+
+```bash
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --validate --format json
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --stage --managed --format json
+```
+
+Batch preflight validates every payload before writing. Stage writes ready
+slots serially; it does not merge documents or decide their semantic shape.
+
+Align results expose a recommended `payload_target.path` under
+`.tmp/agent-payloads/`. Agents should use it for transient structure inputs and
+may remove the file after a successful stage. The CLI continues to accept an
+explicit alternative path; this is an authoring convention, not validation.
+
+For the ordinary path, `read-plan` is a complete authoring packet: it includes
+the payload contract, a budgeted canonical source-ref map, exact source-body
+resources, and a direct `--stage` command. Read the bodies, author the payload,
+and run that stage command. Request `source-index` only when the packet reports
+omitted refs, and request `existing-knowledge` only when reusing or checking an
+approved identity. The separate schema and validate views are optional
+diagnostic tools, not required lifecycle steps.
+
 `--validate`, `--stage`, and `--confirm` are mutually exclusive operations. An
 `--input` without an operation is rejected unless the selected view explicitly
 consumes that input. Deterministic boundary repairs run internally before the
-result is returned. Successful validation returns a stage command with the
+result is returned. `self_healed` includes input/output Section counts, the
+number of original Sections split, and structural reason codes. Stage performs validation before writing and returns the
+same diagnostics on failure; in managed mode, a valid stage also confirms the
+structure. Successful standalone validation returns a stage command with the
 same file path. JSON run output keeps `next_action` first;
 schema and full reports stay behind explicit Views, while `--verbose` restores
 the full phase result and repeated contracts. Long diagnostics return a compact
 first page plus an exact diagnostics continuation command.
 
+Validation returns `state: ready | repair-required | invalid`. Only `ready`
+sets `valid: true` and may proceed to stage. `error_free: true` with
+`state: repair-required` means no error diagnostic remains, but a declared
+confirmation blocker still requires repair; it is not a successful result.
+
 `existing-knowledge` is the authoring-time lookup for approved identities. It
 returns stable NodeRefs, ViewRefs, titles, tags, collections, and section counts
 without exposing workspace storage paths. `--query` performs deterministic
@@ -420,7 +477,20 @@ After capture, the capture phase itself exposes collection-neutral `read-plan`,
 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.
+scan `sources/` or `.tmp` to invent evidence. They may read only the exact
+source-body files selected as required resources by the current Route; those
+files carry stable content digests and must be read in full before a receipt is
+reported. Read all required direct paths, then execute the Route's single
+`resources.after_read.command`; the CLI writes and carries the merged receipt
+set without requiring Agent-authored JSON. That acknowledgement response
+already contains the re-evaluated `workflow.current`, so no additional status
+command is needed.
+
+Generated Context Views use the same content-addressed rule. Materialization
+returns a receipt-set path and an exact post-read command. Read the complete
+file, then execute that command; unchanged content remains current across
+workflow revisions, while write and external commands still require the exact
+current revision.
 
 Compile `read-plan`, `blockers`, and `diagnostics` Views are workspace-read-only
 and may run concurrently. Compile `--validate`, compile `--stage`, structure
@@ -457,9 +527,9 @@ compile:file:<source-name>:architecture
 compile:lark:<source-name>:architecture
 ```
 
-Compile requires confirmed `unapproved/structure.yaml`. It freezes the current
-structure for the compile round; if the user wants to change nodes, section
-ownership, or relationships, return to the align/structure gate.
+Compile requires confirmed CLI-managed lifecycle structure. It freezes the
+current structure for the compile round; if the user wants to change nodes,
+section ownership, or relationships, return to the align/structure gate.
 
 Common commands:
 
@@ -543,7 +613,7 @@ package from a larger monorepo source.
 Use `context source inspect <date>/<module>` to list detected module/package
 boundaries before choosing the source. Use `context run <phase-id> --dry-run
 --format json` to check the resolved modules, file counts, symbol counts, and
-candidate estimate before writing `unapproved/entities.jsonl`. The dry-run
+candidate estimate before writing the ignored lifecycle candidate ledger. The dry-run
 preview also includes `knowledgeTree` and `knowledgePathExamples`, which show
 where approved Markdown will land after review apply.
 Its module and total summaries distinguish `discoveredFiles`, `analyzedFiles`,
@@ -586,6 +656,56 @@ 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`.
 
+### `extractCustom`
+
+Use a project-owned extractor when code facts cannot be represented by the
+TypeScript symbol extractor, for example a language-specific parser or an
+aggregated repository protocol:
+
+```ts
+extractCustom({
+  id: "extract:service:protocol",
+  sources: [service],
+  collection: "codegraph",
+  extract: async ({ projectRoot }) => ({
+    candidates: [{
+      nodeRef: "service/protocol",
+      kind: "protocol",
+      visibility: "exported",
+      module: "service",
+      markdown: renderProtocol(projectRoot),
+      evidence: [{
+        source: "20260811/service",
+        file: "src/protocol.ts",
+        symbol: "protocol",
+        kind: "variable",
+        digest: "0123456789ab",
+      }],
+      review: {
+        title: "Service protocol",
+        summary: "Aggregated protocol boundary.",
+        signals: ["source-backed"],
+        reason: "Review the project-owned extraction.",
+      },
+    }],
+  }),
+});
+```
+
+`sources` is the complete registered repo scope for the phase. Every candidate
+and edge carries structured `evidence`; the CLI validates that evidence against
+the declared sources, creates canonical `source_ref` values, writes the symbol
+index, candidate ledger and Review snapshots atomically, and records a phase
+fingerprint. `context status` therefore treats this phase exactly like another
+pending code extraction target, and Review can verify snapshot freshness
+without a placeholder `extractTs` phase.
+
+The extractor returns knowledge semantics (`nodeRef`, rendered Markdown,
+Review summary and source-backed evidence). It must not write `knowledge/`,
+`.tmp/context-runtime/lifecycle/candidates.jsonl`, extraction fingerprints or
+Review snapshots directly. Context owns those files and preserves rejected and
+unchanged-approved decisions across reruns.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:
@@ -625,7 +745,8 @@ structure slots and every declared `pendingStructureTargets` item in the round;
 codegraph waits for every pending extract phase in the confirmed module round.
 Candidate count/hash therefore describes the complete current batch rather than
 one page, source slot, or module. Deterministic close later merges all active
-slots into `knowledge/structure.yaml`.
+slots into `knowledge/structure.yaml`, retains only their source, collection,
+and consumed snapshot hash as `source_inputs`, then removes the lifecycle slots.
 
 `status.structureBatch` lists unclassified, configuration-required, pending,
 and active structure slots together with the execution policy for the round.
@@ -656,8 +777,9 @@ customPhase("custom:20260712/sample:review", async (ctx) => {
 });
 ```
 
-Custom phases are an escape hatch. Prefer built-in factories for source,
-extract, review, and package workflows. The supported runtime helpers are:
+Custom phases are an orchestration escape hatch. Use `extractCustom()` instead
+when project code needs to publish codegraph candidates. The supported runtime
+helpers are:
 
 - `ctx.ensureSources(...)` for repo source readiness.
 - `ctx.extract.ts(...)` for declared TypeScript extraction.

package/providers/context/resources/manuals/reference/template-variables.md

@@ -97,13 +97,13 @@ 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. |
+| `knowledgeNamespace` | string | Legacy configured namespace when an older workspace still declares one; otherwise empty. It does not change output paths. |
+| `namespacedKnowledge` | boolean | Always `false`; retained so older templates remain renderable. |
 | `skillsRoot` | string | Skills root, currently `skills`. |
-| `wikisRoot` | string | Final wikis root, 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`. |
+| `wikisRoot` | string | Final wikis root: `wikis`. |
+| `guidesRoot` | string | Final guides root: `guides`. |
+| `rulesRoot` | string | Final rules root: `rules`. |
+| `featsRoot` | string | Final feats root: `feats`. |
 | `skillName` | string | Author-maintained name of the Skill currently being rendered. Empty outside a `skills/<name>/...` template. |
 | `skillPath` | string | Final package-relative `SKILL.md` path for the Skill currently being rendered. Empty outside a Skill template. |
 | `knowledgeCount` | number | Selected approved Markdown file count. |
@@ -145,7 +145,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. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
 | `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
 | `pathWithinCollection` | Path below the OKF root, for example `component-lib/symbol/button.md`. |
@@ -183,7 +183,7 @@ 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. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `title` | Display title; defaults to `name`, or the OKF root title for a root group. |
 | `count` | Number of selected pages in this group. |
 | `hasIndex` | Whether the active package navigation policy generates `indexPath`. |
@@ -242,6 +242,7 @@ 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
-paths, API entry points, or task-focused navigation before `context build`.
+The output is only a starter. Edit the files under
+`src/package-templates/kb/` when the package needs different reading paths or
+navigation before `context build`. An unchanged generated starter must instead
+be explicitly accepted through the current package-template Review Route.

package/providers/context/resources/procedures/close-and-build.md

@@ -8,7 +8,9 @@ mediaType: text/markdown
 
 Close deterministically derives `knowledge/structure.yaml` from approved
 Markdown and the confirmed structure snapshots. It validates the rebuilt
-projection; it does not rewrite approved page bodies.
+projection; it does not rewrite approved page bodies. Before removing the
+transient snapshots, it retains only each closed prose target's source,
+collection, and consumed snapshot hash under `source_inputs`.
 
 Build runs only after close and verification are current. It writes declared
 packages under `dist/` and records an inventory receipt with added, updated,

package/providers/context/resources/procedures/code-extraction.md

@@ -26,5 +26,25 @@ semantic knowledge. After confirmation, process exactly one pending extraction
 target and evaluate again.
 
 Do not open Review while another extraction target in the same batch remains.
-Unchanged approved symbols do not need another decision; new, changed, or
-unapproved candidates remain subject to the current Review policy.
+Unchanged approved or rejected symbols do not need another decision; new or
+changed candidates remain subject to the current Review policy.
+
+For TypeScript sources, Context also carries extractor-reported AST relations
+between selected symbols. A relation is projected only when both endpoints
+resolve uniquely inside the selected module; external, unselected, and
+ambiguous endpoints are counted as omissions instead of guessed. The extract
+receipt reports `relationships.detected`, `emitted`, and omission counts.
+Review materializes those source-backed relations with the approved symbol,
+and deterministic close refreshes the typed edge projection.
+
+Zero edges remain a valid result. Read `close.relationshipCoverage` or the
+package inventory's `structure.relationship_coverage` to distinguish a current
+source-backed extraction that found no approved edges from an older or
+otherwise unknown relationship mode. Never infer missing edges from symbol
+co-occurrence, filenames, or package size.
+
+When the built-in TypeScript extractor cannot represent the code source, use a
+declared `extractCustom` phase. The project-owned callback returns candidate
+semantics plus structured source evidence; Context owns canonical refs,
+fingerprints, candidate storage, Review snapshots, freshness, and rerun cleanup.
+Do not use a generic `customPhase` callback to write lifecycle files directly.

package/providers/context/resources/procedures/document-capture.md

@@ -20,6 +20,20 @@ documents grants source-read permission for those named modules. A mention,
 possible-source discussion, or register-only request does not. An explicit
 refusal always wins.
 
+When that permission is already present in the conversation, execute the
+Gate's returned authority-carrying command. In managed mode it runs the
+deterministic capture batch until the next real blocker; in ordinary mode it
+reevaluates status with `context.source-read`. The authority remains in the
+current command chain and is never persisted in the project. Never bypass the
+Route by running a bare capture phase.
+
+Document capture is an external action. Execute a returned command with
+`execution.target: agent-host` through the Agent host so its network and
+credential-store access remain available; do not nest it inside a restricted
+child sandbox. If the CLI reports an external-environment requirement, retry
+the same returned command through the host. Never downgrade credential
+protection as a recovery step.
+
 Capture targets are a batch. Process one current target, evaluate status again,
 and continue until the graph reports the batch complete. Never treat one
 successful module as completion of the whole batch.

package/providers/context/resources/procedures/document-classification.md

@@ -13,6 +13,9 @@ example, or a fixed content-specific prompt.
 Read the current collection-neutral evidence view, explain a short
 evidence-backed recommendation and its output implications, then obtain the
 user decision unless the current session explicitly delegates this gate.
+Read every Route-selected `context.source-body/*` resource in full. Index and
+heading metadata support navigation but are not evidence that the document
+body was read.
 
 After the decision, declare the complete align, compile, and review lifecycle
 for the same canonical source and collection. Re-evaluate instead of assuming

package/providers/context/resources/procedures/package-output.md

@@ -11,21 +11,27 @@ agents or text consumers. Explain the available Context package kinds and their
 directory shape before asking the user to choose.
 
 After confirmation, declare the package in `src/index.ts` using the SDK schema
-resource. Templates may customize presentation, but they must not overwrite
+resource. The current Route's `configuration.contract` lists the supported
+output choices, required fields, mechanical defaults, and follow-up status
+command; do not infer another factory or hidden default. Templates may customize presentation, but they must not overwrite
 approved knowledge paths or remove required indexes.
 
-An Agent knowledge-base package uses its package name as a stable single-level
-knowledge namespace by default. Explain that default after the package name is
-confirmed. Ask for a custom namespace only when the user needs another value;
-it 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. Declare an override as
-`kbPackage({ distribution: { knowledgeNamespace } })`; do not derive it from
-an unstated downstream identity or rewrite template prose.
+Generated generic templates carry a mechanical digest marker. Before the first
+build, replace or edit the declared template source, or explicitly accept the
+unchanged generic default through the current Route. Editing the template
+changes its digest and resolves the review without a separate command.
+Acceptance records only that decision; Context does not judge template prose
+or infer audience, scope, or navigation semantics.
 
-Ask separately whether the author wants a short optional Skill prefix. If so,
+An Agent knowledge-base package writes flat package-relative roots such as
+`wikis/`, `guides/`, `rules/`, and `feats/`. The package name already provides
+the surrounding `dist/<package-name>/` boundary. Do not ask the user for a
+distribution namespace or add `distribution.knowledgeNamespace` to a new
+declaration.
+
+Ask whether the author wants a short optional Skill prefix. If so,
 maintain the complete final Skill directory name in the template, such as
-`skills/android-query/`. Knowledge namespaces never rename Skills.
+`skills/android-query/`. Package-root layout never renames Skills.
 
 Package output is incremental: a built package is current only for the approved
 knowledge and template digests recorded by its receipt.

package/providers/context/resources/procedures/prose-align.md

@@ -14,10 +14,55 @@ and block boundaries when they preserve coherent reading units; fixed line
 windows are only a fallback for unstructured text. A page may contain multiple
 sections, each with its own continuous evidence span.
 
+The default `read-plan` is the authoring packet for ordinary documents. It
+includes the payload contract, a compact canonical source-ref map, exact source
+body resources, the recommended scratch path, and the direct stage command.
+Do not separately request `schema`, `source-index`, or `existing-knowledge`
+unless the packet reports truncation or the task specifically needs an existing
+approved identity. Those views are diagnostics and large-source fallbacks, not
+mandatory workflow steps.
+
+Every `context.source-body/*` item selected in `workflow.current.resources`
+is source evidence, not supporting metadata. Read the complete Markdown file
+when its `read_state` is `read-required`. A source index, heading tree, token
+count, or successful capture never substitutes for body reading. A matching
+content digest receipt may be reused only while that text remains available in
+the current conversation. After reading every selected direct path, execute the
+single `resources.after_read.command`. For a generated Context View, execute
+its materialization command, read its complete file, then execute its exact
+`next_action.command`. Context carries the merged receipt file forward. A Route
+revision change does not invalidate unchanged bytes, but every lifecycle
+command remains revision-bound.
+
+When the route returns `payload_target`, write the Agent-authored structure input
+to its recommended `.tmp/agent-payloads/` path. This scratch area is separate
+from CLI-owned `.tmp/context-runtime/` and can be discarded after a successful
+stage. The recommendation does not restrict an explicit user-selected path.
+
 Stage all required source/collection slots before batch Review. Structure
 confirmation is an explicit gate. A confirmation applies only to the staged
 slot digest shown by the route; if the digest changes, confirm again.
 
+When the current Route exposes `batch`, author every listed target payload in
+one Agent planning pass, then write the small batch manifest to `batch.input`.
+Use `batch.validate.command` for a read-only all-target check or
+`batch.stage.command` to validate every target before any stage begins and then
+write the ready slots serially. The manifest contains only each `phase_id` and
+its structure payload `input` path; it does not merge document semantics or let
+the CLI choose page structure. A failed preflight writes no slot. If a later
+filesystem write fails, the result identifies completed slots and the Route
+remains recoverable.
+
+`--stage` performs the same validation and deterministic self-repair as
+`--validate`; use the separate validation command only for a diagnostics-only
+pass. In a managed conversation, a valid stage also records structure
+confirmation in the same write. Validation states are literal: `ready` may
+stage, `repair-required` may not, and `invalid` contains errors. `valid` is true
+only for `ready`; `error_free` distinguishes a blocker-only result from one
+containing errors. `self_healed` reports the input and output Section counts,
+how many original Sections were split, and the structural reason codes used by
+the repair.
+
 Independent read-only evidence views may run in parallel. Structure stage,
 confirmation, compile writes, and Review application are serial lifecycle
 mutations; execute them in the order selected by `workflow.current`.

package/providers/context/resources/procedures/source-boundary.md

@@ -30,6 +30,12 @@ them. A date-only inspection addresses the batch; `<date>/<module>` addresses
 one source. Register a confirmed multi-source request as one serial batch
 mutation instead of running registry writes in parallel.
 
+To retire a registered source, first run `context source remove <source-id>
+--format json`. This is a read-only preview that lists every project, candidate,
+or approved-knowledge reference. Only after those references are intentionally
+resolved may the route use `--yes`; the CLI never silently deletes referenced
+knowledge or another source's materialized files.
+
 Repository readiness checks are mechanical and may run after the boundary is
 registered. Clone, fetch, checkout, install, build, test, and other external
 repository operations need separate authority. File and remote-document