@c4a/context-cli 0.6.1 → 0.6.3

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

@@ -0,0 +1,248 @@
+---
+id: context.sdk.template-variables
+kind: procedure
+mediaType: text/markdown
+---
+
+# Template Variables
+
+Context package templates are rendered with Handlebars during `context build`.
+
+This reference covers the template variables available to files under
+`src/package-templates/**`. Templates can render values, loop over arrays,
+branch with conditionals, and use template-only comments. They cannot run
+JavaScript.
+
+## Syntax
+
+### Value
+
+```md
+Package: {{packageName}}
+Approved pages: {{knowledgeCount}}
+```
+
+Values support dotted paths:
+
+```md
+{{context.package}}
+```
+
+### Loop
+
+```md
+{{#each knowledgeItems}}
+- [{{title}}]({{href}}) - {{type}}
+{{/each}}
+```
+
+Nested loops are supported:
+
+```md
+{{#each knowledgeGroups}}
+## {{title}}
+
+{{#each items}}
+- [{{title}}]({{href}})
+{{/each}}
+{{/each}}
+```
+
+Inside a loop, `{{@index}}` is zero-based. Use the built-in `inc` helper when
+you need a one-based number:
+
+```md
+{{#each knowledgeItems}}
+{{inc @index}}. [{{title}}]({{href}})
+{{/each}}
+```
+
+### Conditional
+
+```md
+{{#if description}}
+Description: {{description}}
+{{/if}}
+```
+
+The block renders when the value exists, is not `false`, and is not an empty
+string or empty array.
+
+### Template-only Comments
+
+Use Handlebars comments, or HTML comments that start with `context:template`,
+for guidance that should not appear in the generated package:
+
+```md
+{{! This comment is removed by Handlebars. }}
+
+<!-- context:template
+Explain why this section exists and where to edit it.
+Read node_modules/@c4a/context/docs/reference/template-variables.md.
+-->
+```
+
+`context build` strips these comments from rendered output.
+
+## Helpers
+
+| Helper | Example | Meaning |
+|---|---|---|
+| `inc` | `{{inc @index}}` | Adds 1 to a numeric value. Useful for numbered lists. |
+| `json` | `{{json knowledgeGroups}}` | Renders a value as formatted JSON for debugging or machine-readable docs. |
+
+## Built-in Variables
+
+| Variable | Type | Meaning |
+|---|---|---|
+| `packageName` | string | Package name from `kbPackage()` / `llmsPackage()`. |
+| `packageKind` | string | `kb` or `llms`. |
+| `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: `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. |
+| `knowledgeTimestamp` | string | Latest selected approved Markdown `timestamp`, or epoch when empty. |
+| `knowledge` | string | Concatenated selected approved Markdown bundle. Use carefully; it can be large. |
+| `approvedKnowledge` | string | Alias for `knowledge`. |
+| `knowledgeItems` | array | One record per selected approved Markdown page. |
+| `knowledgeGroups` | array | Selected pages grouped by OKF root and the first directory segment under that root; each item also exposes `internal_collection`. |
+| `knowledgeTreeNodes` | array | Nested path tree for selected pages. Useful for custom navigation. |
+| `knowledgeTree` | string | Markdown tree preview of selected pages. |
+| `knowledgeItemsMarkdown` | string | Markdown list of up to 50 selected pages. |
+| `knowledgeGroupsMarkdown` | string | Markdown navigation for the current index. Folded directories render direct page links; expanded directories render links to generated indexes. |
+| `buildInventory` | object | Deterministic package build inventory, including selected files, selected-by reasons, collection summaries, and package-visible edge records. |
+| `buildInventoryJson` | string | Pretty JSON form of `buildInventory`. |
+| `buildInventoryPath` | string | Package-relative inventory path, currently `context-build-inventory.json`. |
+| `knowledgeStructure` | object or null | Selected-package projection derived from workspace `knowledge/structure.yaml` at build time. It contains only selected views, their nodes, and package-visible edges. Templates may inspect it, but the default package consumer should rely on `context-build-inventory.json`. |
+| `knowledgeStructureJson` | string | Pretty JSON form of `knowledgeStructure`, or `null`. |
+| `knowledgeStructurePath` | string | Workspace source structure path, currently `knowledge/structure.yaml`; the variable itself is not copied into the package unless a template renders selected structure data. |
+
+Custom variables from `template.vars` are also available.
+
+`buildInventory.structure.edge_records` contains typed edge records whose
+endpoints are visible in the selected package. Use those records when a
+template or generated skill needs package-local relationship evidence. The
+workspace `knowledge/structure.yaml` is not automatically copied into the
+package unless a project-specific template explicitly renders it.
+
+## `knowledgeItems`
+
+Each item contains:
+
+| Field | Meaning |
+|---|---|
+| `path` | Package-relative OKF path, for example `wikis/component-lib/symbol/button.md`. |
+| `sourcePath` | Approved knowledge path before OKF output mapping, for example `architecture/entity/button.md`. |
+| `approved_path` | Alias for `sourcePath`. |
+| `dist_path` | Alias for `path`. |
+| `internalCollection` | Internal approved collection, for example `architecture`. |
+| `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 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`. |
+| `href` | Link relative to the template file currently being rendered. Use this in custom templates. |
+| `hrefFromTemplate` | Alias for `href`. |
+| `hrefFromPackageRoot` | Link from a package-root file such as `AGENTS.md`, for example `./wikis/component-lib/symbol/button.md`. |
+| `hrefFromCollectionIndex` | Link from the current OKF root index, for example `./component-lib/symbol/button.md` for a `wikis` item. |
+| `title` | Page title from frontmatter, or a title derived from the file name. |
+| `type` | OKF `type` from frontmatter. |
+| `description` | OKF `description` from frontmatter, when present. |
+| `timestamp` | OKF `timestamp` from frontmatter, when present. |
+| `source` | First top-level `sources` entry without the `repo:` prefix, or the group name. |
+| `group` | First path segment under the OKF root. |
+| `parentPath` | Parent path below the OKF root. |
+| `depth` | Segment count below the OKF root. |
+| `segments` | Path segments below the OKF root. |
+| `tags` | Comma-separated tags from frontmatter. |
+
+Example:
+
+```md
+{{#each knowledgeItems}}
+- [{{title}}]({{href}}) — {{type}}{{#if description}}: {{description}}{{/if}}
+{{/each}}
+```
+
+## `knowledgeGroups`
+
+Each group contains:
+
+| Field | Meaning |
+|---|---|
+| `name` | First directory segment under the OKF root, or `root` for pages directly under the OKF root. |
+| `collection` | Internal approved collection for this group. |
+| `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 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`. |
+| `has_index` | Alias for `hasIndex`. |
+| `indexPath` | OKF-root-aware index path, for example `wikis/component-lib/index.md`, `guides/component-lib/index.md`, or `rules/index.md` for a root group. |
+| `indexHrefFromTemplate` | Link from the template file currently being rendered to `indexPath`. Check `hasIndex` before rendering it. |
+| `indexHrefFromCollectionIndex` | Link from the OKF root index to `indexPath`. |
+| `items` | `knowledgeItems` in the group. |
+
+Example:
+
+```md
+{{#each knowledgeGroups}}
+## {{title}} ({{count}})
+
+{{#if hasIndex}}
+[Open directory index]({{indexHrefFromTemplate}})
+{{/if}}
+{{#each items}}
+- [{{title}}]({{href}}) - {{type}}
+{{/each}}
+{{/each}}
+```
+
+## `knowledgeTreeNodes`
+
+`knowledgeTreeNodes` is a nested representation of selected pages. Each node
+contains:
+
+| Field | Meaning |
+|---|---|
+| `name` | Path segment name. |
+| `title` | Display title derived from `name`. |
+| `path` | Path below the OKF root. |
+| `depth` | Depth below the OKF root. |
+| `count` | Number of pages under this node. |
+| `items` | Pages directly under this node. |
+| `children` | Child nodes. |
+
+Use it when a package needs navigation by source, module, category, or symbol
+folder. Handlebars does not include recursive partials by default, so keep
+starter templates shallow or add project-specific sections for the levels you
+care about.
+
+## Starter `wikis/index.md`
+
+The default KB template uses the variables above to generate a starter index:
+
+- bundle count and timestamp in OKF frontmatter;
+- direct page links for directories folded by the active navigation policy;
+- links to generated directory indexes when a directory exceeds the configured
+  inline-entry threshold.
+
+`context build` always provides selected OKF root indexes. By default, a
+non-root directory gets its own index only when it contains more than 50
+descendant knowledge pages. Configure this with
+`kbPackage({ navigation: { foldDirectoryIndexes, maxInlineEntries } })`.
+
+The output is only a starter. Edit 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

@@ -0,0 +1,23 @@
+---
+id: procedure.close-and-build
+kind: procedure
+mediaType: text/markdown
+---
+
+# Close and build
+
+Close deterministically derives `knowledge/structure.yaml` from approved
+Markdown and the confirmed structure snapshots. It validates the rebuilt
+projection. When an approved page still points at a captured source asset,
+close may mechanically replace that target with its content-addressed
+`knowledge/assets` path; it does not rewrite reader-visible prose. 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,
+removed, and index changes.
+
+Run only the current route command, then evaluate again. A successful build
+means the currently declared scope is current; newly captured or newly declared
+targets can reopen earlier graph nodes.

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

@@ -0,0 +1,50 @@
+---
+id: procedure.code-extraction
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code extraction
+
+Code extraction operates on user-confirmed repository modules and source
+patterns. A source registration identifies the repository or module; the
+extraction declaration defines the code scope inside it.
+
+`include` filters files inside a selected source; it is not a package/module
+selector. Use source declarations to select repository modules. Use configured
+entry patterns when entry-led traversal is meaningful, or scan mode when the
+selected module intentionally has no package entry. Do not require source-code
+rewrites merely to create an extraction entry.
+
+Use a dry-run when the current route requests scope inspection. Report
+discovered files, AST-analyzed files, skipped files, symbols, and relations
+separately. Use resolved entry files, exported/internal counts, and symbol-kind
+counts as structural scope evidence only. Resolve TypeScript/JavaScript
+configuration and aliases through the extractor rather than guessing paths
+from imports. Explain the scope without treating filenames or symbol kinds as
+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 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

@@ -0,0 +1,49 @@
+---
+id: procedure.document-capture
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document capture
+
+Capture creates a reproducible local snapshot of a registered document source.
+It does not classify, summarize, approve, or build knowledge.
+
+Before capture:
+
+1. every registered document module must have a matching capture declaration;
+2. the user must have allowed the external read in the current conversation;
+3. execute only the current route command.
+
+An explicit request to capture, ingest, fetch, or read named file/remote
+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.
+
+The CLI owns normalization, snapshot identity, hashes, manifests, and
+idempotency. For Lark sources it also owns embedded-resource download,
+structured export, completeness reporting, and link projection. Required
+resource failures block the next phase; reference-only resources remain
+explicit in the report. Never hand-write or repair captured snapshots or their
+asset links. If a selected local
+boundary is a documentation site rather than plain Markdown, use the
+Context-provided processor/configuration diagnostic; do not invent rendered
+text or scan outside the confirmed boundary.

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

@@ -0,0 +1,22 @@
+---
+id: procedure.document-classification
+kind: procedure
+mediaType: text/markdown
+---
+
+# Document classification
+
+Classification chooses the main knowledge collection for a captured document.
+The choice must follow evidence investigation, not the URL, file name, a user
+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
+the declaration closed every document target.

package/providers/context/resources/procedures/evidence-maintenance.md

@@ -0,0 +1,20 @@
+---
+id: procedure.evidence-maintenance
+kind: procedure
+mediaType: text/markdown
+---
+
+# Evidence maintenance
+
+Approved knowledge can outlive a moved or temporarily unavailable source, but
+the resulting evidence state must stay explicit.
+
+- Re-pin only when the approved body still matches current source content and
+  only the evidence location changed.
+- Create a new candidate when source content changed.
+- Deprecate knowledge that should no longer be used.
+- Keep source-orphaned knowledge only after an explicit user decision and retain
+  the evidence warning.
+
+Use the affected `view_ref` values from the current diagnostic resource. Do not
+target maintenance by guessed paths or node names.

package/providers/context/resources/procedures/knowledge-review.md

@@ -0,0 +1,34 @@
+---
+id: procedure.knowledge-review
+kind: procedure
+mediaType: text/markdown
+---
+
+# Knowledge Review
+
+Review is the authority boundary between candidates and approved knowledge.
+Open one report for the complete current candidate set and apply only a payload
+that matches its collection scope and candidate-set digest.
+
+Before Review, Context checks both sides of approved page identity: whether a
+candidate path is already owned by another `view_ref` / `node_ref`, and whether
+the candidate `view_ref` is already approved at another path. Either conflict
+blocks Review. Follow the returned identity-coordination route: the default
+mechanical repair preserves the approved identity and approved path, then
+recompiles only the affected source. It keeps the candidate batch intact while
+replacing affected candidates in place. Changing an approved identity or moving
+an approved path is a migration and must never run without a separate, explicit
+authorization.
+
+Without explicit session-managed authority:
+
+- open the report returned by the route;
+- let the user approve or reject candidates;
+- apply the exact returned decision payload.
+
+With explicit session-managed authority, Context may approve the complete
+current batch atomically. The authority exists only in the current
+conversation. It does not bypass source permission, validation, close, or
+verify.
+
+After apply, re-evaluate. Do not infer that close or package output is current.

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

@@ -0,0 +1,37 @@
+---
+id: procedure.package-output
+kind: procedure
+mediaType: text/markdown
+---
+
+# Package output
+
+Package selection decides how approved knowledge is presented to downstream
+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. 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.
+
+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.
+
+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/`. 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/project-configuration.md

@@ -0,0 +1,21 @@
+---
+id: procedure.project-configuration
+kind: procedure
+mediaType: text/markdown
+---
+
+# Project configuration
+
+Use the current route facts and Context SDK documentation to make only the
+declaration requested by the route in `src/index.ts`.
+
+- Do not invent sources, modules, collections, or output types.
+- Ask for a user decision when the route is gated and no current-session
+  authority is present.
+- Keep source registration, capture, extraction, align, compile, review, and
+  package declarations paired by their canonical source and collection.
+- After editing, run `context status --format json` again. The workspace facts,
+  not the edit itself, determine whether the route is complete.
+
+The Context SDK API reference is a discoverable resource. Do not guess an API
+shape from older prompts or cached plugin text.

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

@@ -0,0 +1,68 @@
+---
+id: procedure.prose-align
+kind: procedure
+mediaType: text/markdown
+---
+
+# Prose structure alignment
+
+Alignment proposes source-bound knowledge structure. It does not write approved
+knowledge.
+
+Follow the current route's evidence view and input schema. Prefer source heading
+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/prose-compile.md

@@ -0,0 +1,23 @@
+---
+id: procedure.prose-compile
+kind: procedure
+mediaType: text/markdown
+---
+
+# Source-bound prose compilation
+
+Compile materializes review candidates from confirmed structure and source
+evidence. It never writes directly to approved knowledge.
+
+The CLI derives this projection mechanically from the confirmed section ids,
+kinds, and source spans. Run only the revision-bound compile command returned
+by the current Route. Do not create compile-action payloads or rewrite source
+content.
+
+One compile command validates every owned view first, then atomically
+materializes the source/collection candidate batch. In an explicitly managed
+conversation, the host loop may continue across the remaining deterministic
+compile slots after this procedure has been read; it re-evaluates revision and
+validation state after every write. The current structure view is optional
+inspection context because the CLI consumes the confirmed structure directly.
+Do not open a partial Review while planned views remain.

package/providers/context/resources/procedures/repository-source-recovery.md

@@ -0,0 +1,43 @@
+---
+id: procedure.repository-source-recovery
+kind: procedure
+mediaType: text/markdown
+---
+
+# Repository source recovery
+
+Repository checkout contents and materialized module links are local runtime
+inputs. Git stores their recovery recipe in `sources/repo/index.yaml`; it does
+not store the checkout, local aliases, or `sources/repo/<date>/<module>` links.
+
+Run the route's inspection action first. It groups logical modules by registered
+remote and pinned commit, so one physical checkout can restore every module in
+that group. Do not create one clone per module. Groups already marked `ready`
+need no decision; when every group is ready, the plan has no recovery action.
+
+For each missing physical checkout, ask the user to choose one option:
+
+1. provide an existing local Git checkout;
+2. name a bounded directory that the Agent may scan, then choose one of the
+   matching checkouts shown by the Agent; or
+3. explicitly allow Context to clone the registered repository into the
+   suggested `.tmp/repo/` target.
+
+Scanning and clone access are separate external authorities. Never scan an
+unspecified disk root. Never infer or substitute another remote, branch, tag,
+or nearby repository. A recovery clone uses the registered pinned commit so
+the existing knowledge state is reproducible. Updating knowledge to a newer
+upstream version is a later, explicit source update decision.
+
+After the user decides, submit one payload matching the route-selected recovery
+schema to the exact resolution command. Local mode validates origin, the pinned
+commit, and every required subpath without changing the supplied checkout.
+Clone mode performs a shallow partial checkout where supported, falls back to a
+shallow checkout, and uses sparse checkout only when every registered source is
+bounded to a subpath. Context then restores declared local aliases and
+materializes module links.
+
+Repository sources are ready only when every selected module resolves to the
+registered remote and pinned commit, every registered subpath exists, no local
+path was overwritten, Context materialization succeeds, and the current route
+no longer reports `route.source.repository-not-ready`.