@c4a/context-cli 0.6.2 → 0.6.4

package/providers/context/resources/manuals/guides/lark-resources.md

@@ -0,0 +1,121 @@
+---
+id: context.sdk.lark-resources
+kind: procedure
+mediaType: text/markdown
+---
+
+# Lark Resource Materialization
+
+Lark documents can contain evidence that is not present in the readable text
+body. Context handles these resources mechanically during `captureLark`; the
+Agent does not download, summarize, or reconstruct them itself.
+
+## Resource policy
+
+| Resource | Default capture behavior |
+|---|---|
+| Image and attachment | Download the original file and link it from the Markdown projection. |
+| Sheet | Read the complete selected sheet, render a Markdown table, and retain a CSV snapshot. |
+| Base | Read the selected table/view with pagination, render a Markdown table, and retain a canonical JSON snapshot. |
+| Whiteboard and diagram | Retain a readable preview plus the raw structured export. |
+| Synced block | Resolve the exact source block, project its body, and retain a Markdown evidence snapshot. |
+| Poll | Preserve exported options and metadata as non-interactive Markdown; warn when the export omits them. |
+| Bookmark, citation, sub-document, chat, and generic embed | Preserve a stable navigation reference and provenance. |
+| Video | Preserve a stable reference by default; download only when `resources.videos` is `bundle`. |
+
+Required inline resources fail closed when their stable identity, bytes, or
+complete structured data cannot be obtained. When the remote API explicitly
+confirms that a referenced whiteboard or diagram no longer exists, Context
+preserves an unavailable-resource notice with the reason code
+`document.resource.source-missing`, reports a warning, and continues capture;
+it does not pretend that the deleted content was materialized. When the current
+identity can read the document body but the API explicitly returns
+`authorization/permission_denied` for an embedded resource, Context records
+`document.resource.permission-denied`, keeps the stable resource identity in
+the audit layer, renders the same unavailable-resource notice, and continues
+with a warning. Missing scopes, transient network errors, malformed payloads,
+and unclassified authorization failures still block capture. Reference-only
+resources remain explicit in the capture report. Unknown non-empty XML blocks
+stay auditable in the raw XML and receive a warning; the CLI does not infer
+their meaning.
+
+## Storage lifecycle
+
+Resources have three distinct locations:
+
+```text
+sources/lark/<date>/
+├── <module>.md
+├── manifest.json
+└── assets/<module>/
+    ├── source.xml
+    ├── capture-report.json
+    └── materialized/**
+knowledge/assets/<resource-kind>/<content-sha256>.<ext>
+dist/<package>/others/assets/<resource-kind>/<content-sha256>.<ext>
+```
+
+- `sources/` is the captured source and audit layer. `source.xml` preserves the
+  structured source, one `capture-report.json` closes fidelity and resource
+  handling for the document, and `materialized/` contains downloaded files and
+  structured exports. Resource descriptors are consolidated in the report;
+  capture does not create one metadata file per embedded resource.
+- The date-level `manifest.json` is a compact inventory. It records hashes,
+  asset roles, the report path, and status summaries without duplicating the
+  complete report.
+- `knowledge/assets/` contains only resources referenced by approved pages.
+  Paths are content-addressed, so identical bytes are reused and changed bytes
+  produce a new identity. Review apply rewrites page links mechanically;
+  verification compares the underlying content identity, so this deterministic
+  path projection does not count as a change to a verbatim section.
+  Markdown files below `knowledge/assets/` remain evidence resources and are
+  never interpreted as approved knowledge pages or structure views.
+- `others/assets/` is the portable package projection. Build copies only
+  resources referenced by selected package pages and rewrites their relative
+  links. Audit-only source files are not distributed.
+
+Deleting an approved page allows unreferenced `knowledge/assets` files to be
+cleaned. A missing approved or packaged resource is a verification error rather
+than a silent broken link.
+
+Source assets are part of the reproducible evidence snapshot and should not be
+ignored when the workspace is versioned. Repositories with many binary source
+assets can use Git LFS for `materialized/` while keeping Markdown, XML, JSON, and
+CSV directly reviewable in Git. The workspace must remain private when the
+captured source or screenshots are access-controlled.
+
+## SDK configuration
+
+Defaults are suitable for ordinary documents:
+
+```ts
+captureLark({ source: handbook });
+```
+
+Projects can opt into bundled video and adjust deterministic byte limits:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
+The limits are capture constraints, not semantic filters. Context does not
+decide which resources are important from their business content.
+
+## Agent behavior
+
+Use the capture command returned by the current Route. Inspect the structured
+resource summary and fidelity diagnostics; do not manually edit `sources/`,
+`knowledge/assets/`, or package links. Required materialization failures other
+than a confirmed source-side deletion or an explicit resource-level permission
+denial must be resolved by recapturing after access or source problems are
+fixed. Accepted failures remain visible as warnings and unavailable-resource
+notices; they are never represented as downloaded evidence. Review shows
+available previews, references, and warnings so the human or managed policy can
+assess the page with its non-text evidence.

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -67,6 +67,7 @@ wikis/index.md
 guides/...
 rules/...
 feats/...
+others/assets/...
 ```
 
 Do not ask for another distribution namespace. Older workspaces may still
@@ -94,6 +95,27 @@ package needs project-specific terminology, entry points, known limits, or
 task workflows. Authors may explicitly accept the generic default when it is
 intentionally sufficient.
 
+When approved pages reference materialized document resources, Context keeps
+their production copies in content-addressed `knowledge/assets/` paths. New KB
+setup should offer Git raw delivery first. It rewrites package links to either
+an automatically derived raw prefix or an explicit author-provided prefix.
+Context does not check whether resource files are committed, pushed, or
+remotely readable; that is the package author's responsibility. With no
+explicit prefix, supported remotes use an immutable commit URL. An explicit
+prefix can contain `{commit}` when the Context workspace is in Git, or name a
+mutable branch when that lifecycle is intentional; a literal prefix also works
+when resources are published from a separate repository.
+
+Workspaces without usable Git or an explicit raw prefix can choose bundled
+delivery, which copies only selected resources to `others/assets/`, or explicit
+omission, which does not copy resources and reports that links remain
+unresolved. Bundled output may
+optionally install `sharp` in the workspace and configure
+`assets.optimize`; Context itself has no image dependency. Optimization changes
+only `dist/`, content-addresses smaller WebP output, and leaves `sources/` and
+`knowledge/assets/` unchanged. Source audit XML and capture reports are never
+distributed as reader assets. See [Lark Resource Materialization](./lark-resources.md).
+
 The same inventory exposes `structure.relationship_coverage`. It records
 whether selected codegraph pages have current source-backed AST relationship
 metadata, how many codegraph views were selected, and how many package-visible

package/providers/context/resources/manuals/reference/code-extractors.md

@@ -0,0 +1,94 @@
+---
+id: manual.reference.code-extractors
+kind: procedure
+mediaType: text/markdown
+---
+
+# Code Extractor Selection
+
+Use this manual only when the current code-extraction Route asks the Agent to
+choose or declare an extractor. The CLI reports repository facts; the Agent
+chooses how those facts become source-backed code knowledge.
+
+## Inspect Before Declaring
+
+Run every read-only inspection command returned by the extraction-scope Gate.
+The result identifies each confirmed module and its recognized `manifests`.
+Treat these as deterministic technology signals, not as product semantics:
+
+| Signal | Technology candidate |
+|---|---|
+| `package.json` | TypeScript, TSX, JavaScript, or JSX |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pyproject.toml` or `setup.py` | Python |
+| `pom.xml` or `build.gradle` | Java or JVM |
+| multiple manifests | a mixed module that may need more than one extractor |
+
+Do not select `extractTs()` merely because a repository contains some
+TypeScript. Decide against the exact confirmed module and include boundary. A
+mixed module may compose multiple structural passes; parser selection is not an
+exclusive repository-wide switch.
+
+## Selection Order
+
+Use the narrowest reusable capability that covers the confirmed source:
+
+1. Use a Context-owned phase when its contract matches the source.
+2. Otherwise use a reusable structural package inside `extractCustom()`.
+3. If no reusable package covers the syntax or repository protocol, implement a
+   project-owned adapter and keep it in the Context workspace.
+
+Current reusable capabilities are:
+
+| Source fact | Preferred capability | Lifecycle integration |
+|---|---|---|
+| TypeScript/TSX package or file scope | `extractTs()` | Context-owned phase |
+| Go declarations, imports, calls, and common HTTP routes | `@c4a/extract-go` | call from `extractCustom()` |
+| Rush workspace packages, tags, dependencies, entries, and owners | `@c4a/extract-rush` | call from `extractCustom()`; may complement a language extractor |
+| React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements TypeScript symbols |
+| Rust, Python, Java/JVM, or an unsupported framework/protocol | no assumed built-in parser | project-owned `extractCustom()` adapter |
+
+An optional package does not create a new CLI phase. Add it as an explicit
+workspace dependency, then map its structural facts to candidates in the
+project callback. Do not add a parser package when its documented coverage does
+not match the inspected source.
+
+## Read The Contract Before Extending
+
+Before editing `src/index.ts`, read the relevant installed public manual or
+package README. Do not infer APIs from bundled JavaScript.
+
+- Context lifecycle and `extractCustom()`:
+  `node_modules/@c4a/context/docs/reference/project-api.md`
+- Generic plugin protocol:
+  `node_modules/@c4a/extract/README.md`
+- TypeScript:
+  `node_modules/@c4a/extract-ts/README.md`
+- Go:
+  `node_modules/@c4a/extract-go/README.md`
+- Rush:
+  `node_modules/@c4a/extract-rush/README.md`
+
+If an optional package is not installed, use this capability matrix to decide
+whether it is relevant, add only that dependency, and then read its shipped
+README before implementing the callback.
+
+A project-owned adapter may use an existing parser, compiler API, or command
+whose output is deterministic. It must return source-backed candidates through
+`extractCustom()`; it must not write lifecycle, knowledge, or Review files.
+Framework-specific classification and rendering remain in the project. The CLI
+and structural parser must not infer product meaning.
+
+## Decision To Report
+
+Before the first extraction preview, state briefly:
+
+- the inspected module and manifest signals;
+- the selected Context phase or structural package;
+- whether coverage is complete or which facts remain project-owned; and
+- why another available extractor is not needed.
+
+If no current capability can parse the source reliably, stop at configuration
+and report the missing generic capability. Do not silently emit an empty
+codegraph or reuse an unrelated parser.

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

@@ -37,6 +37,10 @@ kbPackage({
     foldDirectoryIndexes: true,
     maxInlineEntries: 50,
   },
+  assets: {
+    delivery: "git-raw",
+    urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+  },
 });
 ```
 
@@ -58,8 +62,56 @@ 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 }`. |
+| `assets` | no | Resource delivery: Git raw links, bundled files, or explicit omission. New KB setup should offer Git raw first. Omit for legacy byte-for-byte bundling. |
 | `distribution` | no | Legacy input accepted from older workspaces. It no longer changes package paths and should not be added to new declarations. |
 
+Use Git raw delivery when resources are published from a Git repository.
+Without `urlPrefix`, the Context workspace must be inside Git; GitHub remotes
+are derived automatically and pinned to the current commit. Other hosts and
+workspaces outside Git accept an explicit HTTPS prefix; Context appends the
+project-relative `knowledge/assets/...` path. Context does not check whether
+the resources are committed, pushed, or remotely readable; publishing them is
+the package author's responsibility.
+`{commit}` is replaced when present. A literal branch in the prefix is allowed
+but intentionally follows that mutable branch. The configured raw host must be
+reachable by the eventual package consumers.
+
+```ts
+assets: {
+  delivery: "git-raw",
+  urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
+}
+```
+
+When the workspace is not in Git and has no explicit raw prefix, choose bundled
+delivery or explicit omission:
+
+```ts
+assets: { delivery: "bundle" }
+assets: { delivery: "omit" } // keeps unresolved links and reports them
+```
+
+Bundled resources are copied byte-for-byte unless image optimization is
+configured. When optimizable PNG/JPEG resources exceed 20 MiB, build and status
+return `package.assets.optimization-recommended`. To optimize bundled output:
+
+```bash
+bun add -D sharp
+```
+
+```ts
+assets: {
+  delivery: "bundle",
+  optimize: { processor: "sharp", mode: "lossless-webp" },
+}
+```
+
+`optimize.mode: "webp"` additionally accepts `quality` from 1 to 100. Both modes accept
+an optional positive `maxDimension`; images are never enlarged. Context adopts
+a generated image only when it is smaller, uses a digest-derived `.webp` path,
+and rewrites package links. A configured but missing processor blocks before
+the previous `dist/` package is replaced.
+
 `template` is required. Do not call `kbPackage({ name })` or
 `llmsPackage({ name })`.
 

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

@@ -215,6 +215,13 @@ extraction phases, review gates, close/build, and packages explicitly. The CLI
 then routes work through `context status`, `context run <phase-id>`, `context
 review html/apply`, `context close`, `context verify`, and `context build`.
 
+For Agent and automation output, use `context verify --format json --compact`.
+It returns deterministic groups, counts, affected-scope totals, and a few
+representative samples instead of repeating every issue. Read the complete,
+auditable issue set only when needed with `context verify --view diagnostics
+--page-size 25 --format json`; follow its executable pagination command without
+inventing overlapping file ranges.
+
 ### Status declaration coverage
 
 `context status --format json --view full` includes a `declarationGraph` and
@@ -327,6 +334,21 @@ Markdown snapshot:
 captureLark({ source: handbook });
 ```
 
+Embedded resources are materialized with deterministic defaults. Video remains
+reference-only unless a project opts into bundling, and byte limits prevent an
+unexpected document from expanding the workspace without bound:
+
+```ts
+captureLark({
+  source: handbook,
+  resources: {
+    videos: "bundle",
+    maxBytesPerResource: 20 * 1024 * 1024,
+    maxTotalBytes: 200 * 1024 * 1024,
+  },
+});
+```
+
 Phase id:
 
 ```text
@@ -340,19 +362,33 @@ 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 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
+readable Markdown, and materializes required inline resources such as images,
+attachments, Sheets, Bases, whiteboards, diagrams, and synced blocks. Navigation
+resources and default video capture remain explicit references. The projection
+does not infer or summarize document meaning. Its fidelity and resource reports close discovered blocks
 against converted and intentionally skipped blocks and reports evidence
 completeness separately from Markdown projection quality. Unknown non-empty XML
 blocks receive a generic, auditable, non-interactive projection and do not block
-downstream work. Missing source content or unresolved external-resource identity
-remains an evidence error and prevents downstream Review.
+downstream work. A remote whiteboard or diagram explicitly confirmed as deleted
+is preserved as an unavailable-resource notice with
+`document.resource.source-missing` and a warning. An embedded resource whose
+export is explicitly rejected as `authorization/permission_denied` is retained
+the same way with `document.resource.permission-denied`. Missing scopes,
+unresolved external-resource identity, retryable failures, and unclassified
+authorization errors remain evidence errors and prevent downstream Review.
 Snapshot files live under `sources/lark/<date>/` as sibling document files
-tracked by one date-level `manifest.json`. Access credentials and transient
+tracked by one compact date-level `manifest.json`. Each module keeps one raw
+`source.xml`, one consolidated `capture-report.json`, and its actual downloaded
+or structured resources under `assets/<module>/materialized/`; it does not emit
+one descriptor file per embedded resource. Access credentials and transient
 signed media URLs are not written into the workspace.
 
+Approved resource bytes are projected to content-addressed
+`knowledge/assets/<kind>/` paths. KB build copies selected resources to
+`others/assets/<kind>/` inside the package and rewrites page links. See
+[Lark Resource Materialization](../guides/lark-resources.md) for the complete
+resource table and storage lifecycle.
+
 Use a typed document reference in project declarations:
 
 ```ts
@@ -709,6 +745,41 @@ Review summary and source-backed evidence). It must not write `knowledge/`,
 Review snapshots directly. Context owns those files and preserves rejected and
 unchanged-approved decisions across reruns.
 
+#### Optional structural extractors
+
+For the manifest-to-capability decision and unsupported-language extension
+boundary, read [Code Extractor Selection](./code-extractors.md) before declaring
+the phase.
+
+`extractCustom()` may consume optional community packages without making them
+Context CLI dependencies:
+
+```ts
+import { indexGoRepository } from "@c4a/extract-go";
+import { extractCustom } from "@c4a/context";
+
+extractCustom({
+  id: "extract:service:codegraph",
+  sources: [service],
+  collection: "codegraph",
+  extract: async ({ projectRoot }) => {
+    const facts = await indexGoRepository(resolveServiceCheckout(projectRoot));
+    return { candidates: buildServiceCandidates(facts) };
+  },
+});
+```
+
+Available structural libraries include:
+
+- `@c4a/extract-go`: Go declarations, imports, calls, and common HTTP routes;
+- `@c4a/extract-rush`: Rush projects, tags, entries, dependencies, and owners;
+- `@c4a/extract-ts`: TypeScript extraction and `extractReactRouterRoutes()`.
+
+The packages return syntax and repository facts only. They do not classify
+product meaning, choose candidate identities, or write lifecycle state. The
+knowledge project owns that mapping. Context CLI does not auto-install these
+packages and does not expose a built-in Go or Rush phase.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:

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

@@ -8,9 +8,11 @@ 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. Before removing the
-transient snapshots, it retains only each closed prose target's source,
-collection, and consumed snapshot hash under `source_inputs`.
+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,

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

@@ -10,6 +10,14 @@ 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.
 
+Before declaring a phase, run the extraction-scope Gate's inspection Action for
+every confirmed module. Read all reported `manifests`, including mixed-module
+signals, then use the route-selected Code Extractor Selection manual to choose
+`extractTs`, an optional structural package inside `extractCustom`, or a
+project-owned adapter. Read the selected package's public SDK/README before
+editing `src/index.ts`; never infer its API from bundled output. Do not silently
+substitute the TypeScript extractor for Go, Rust, or another unsupported source.
+
 `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
@@ -48,3 +56,18 @@ 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.
+
+Prefer a reusable structural library over a project-local parser when one
+matches the confirmed source: `@c4a/extract-go` for Go facts,
+`@c4a/extract-rush` for Rush workspace facts, and
+`extractReactRouterRoutes()` from `@c4a/extract-ts` for React Router facts.
+These are optional project dependencies consumed inside `extractCustom()`;
+they are not built-in CLI phases. Keep product-specific classification and
+candidate rendering in the project, and do not ask the CLI or parser to infer
+business meaning.
+
+For Rust, Python, Java/JVM, or another source without a matching reusable
+extractor, keep the lifecycle in `extractCustom()` and implement only the
+missing project adapter. If reliable syntax facts cannot be produced, stop at
+configuration and report the generic capability gap rather than emitting an
+empty or guessed graph.

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

@@ -39,7 +39,11 @@ 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. Never hand-write or repair captured snapshots. If a selected local
+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/knowledge-review.md

@@ -10,6 +10,16 @@ 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;

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

@@ -35,3 +35,24 @@ maintain the complete final Skill directory name in the template, such as
 
 Package output is incremental: a built package is current only for the approved
 knowledge and template digests recorded by its receipt.
+
+When declaring a new KB package, make resource delivery an explicit author
+choice. Offer Git raw when the workspace is in Git or the author supplies a
+raw `urlPrefix`; it keeps package payloads small and uses either the derived
+commit-pinned URL or that explicit prefix. Context does not check whether those
+files are committed, pushed, or remotely readable; that remains the package
+author's responsibility. If neither Git nor an explicit prefix is available,
+offer bundled resources or explicit omission; omission keeps unresolved links
+and must be described as such. Do not infer repository identity or invent a raw
+host URL.
+
+Large image optimization applies only to bundled delivery. Without an `assets`
+declaration, existing workspaces continue to copy selected resources
+byte-for-byte. If build or status reports
+`package.assets.optimization-recommended`, explain that the current package is
+valid but contains more than 20 MiB of eligible PNG/JPEG resources. Do not
+install a dependency or edit project configuration automatically. If the user
+chooses to optimize the package, use the exact reported setup command and add
+the reported `kbPackage().assets.optimize` value. The processor is installed in the
+Context workspace, not bundled into Context itself. Optimization changes only
+`dist/`; source snapshots and approved resources remain unchanged.

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`.

package/providers/context/resources/procedures/source-capture-detailed.md

@@ -54,6 +54,19 @@ contract, so any manual edit breaks idempotency.
 Lark capture obtains the structured XML representation and produces two
 separate artifacts: XML audit evidence and a deterministic readable Markdown
 projection. Do not treat raw XML as Markdown and do not rewrite it yourself.
+The CLI also materializes supported embedded resources and returns a closed
+`resource_materialization` report. Required images, attachments, Sheets, Bases,
+whiteboards, diagrams, and synced blocks must be materialized before downstream
+Review. Polls and navigation references remain explicit non-interactive
+projections; video is reference-only unless the project SDK opts into bundling.
+If the remote API explicitly confirms that a referenced whiteboard or diagram
+no longer exists, preserve the unresolved placeholder and the structured
+`document.resource.source-missing` warning, then continue through the Route.
+This is an audited source-side deletion, not successful materialization. Access,
+network, parameter, and unknown resource failures still block downstream work.
+Do not manually download resources or patch links. Approved resources move to
+`knowledge/assets/`, and package build projects selected resources to
+`others/assets/`.
 Inspect `evidence_status` and `projection_status` separately. An evidence error
 means the source body, external content, or a stable resource locator could not
 be preserved, so the workflow must not proceed to Align, Compile, or Review.

package/providers/context/resources/procedures/verify-and-repair.md

@@ -14,6 +14,18 @@ is stale, the legal repair is `context close --format json`. Otherwise, repair
 the source-bound candidate or project declaration named by the root diagnostic,
 then run verification again.
 
+When every blocking finding is an approved document `source_ref` drift or an
+unresolved required-resource placeholder, and each affected source already has
+a declared pending structure target, the current prose align/compile round is
+the repair path. Continue that Route before running verification again. This
+exception does not apply to missing sources, malformed approved knowledge,
+unrelated verification errors, or findings without a matching pending target.
+
+When a complete replacement candidate batch is ready for Review, stable prose
+candidate ids may intentionally match their currently approved pages. Review
+that batch before deterministic close and final verification; the pending
+replacement is not an approved-identity conflict.
+
 Do not delete candidates, approved pages, snapshots, or structure slots to make
 verification pass. Derived diagnostics should not be handled as independent
 root failures.

package/providers/context/resources/semantic/align/gates.md

@@ -249,7 +249,7 @@ Each source must include `rationale` when inferred and at least one of `source_r
 ## Final Reflection
 
 - Entity cannot pick a legal tag, or depends on its upstream title to make sense -> write it as a Section under the upstream Node or change type before submit.
-- Action only supports one Section -> write it as a Section instead of an Action, or add source-backed structure that reaches at least two distinct Section kinds / one child Action. The CLI does not use source prose keywords to grant an exception.
+- Action only supports one Section -> confirm its standalone retrieval value, write it as a Section under its owner, or add another source-backed Section / child Action. Multiple source-backed Sections may use the same kind; the CLI does not manufacture semantic variety to validate an Action.
 - Action "steps" are parallel options/configs -> route to Entity `comparison` / `spec` / `description`.
 - Domain has no children -> delete it or merge it into a larger Domain.
 
@@ -267,7 +267,7 @@ checks as deterministic diagnostics:
 | `node.thin_concrete_entity` | A concrete Entity has one Section and no child Nodes. | Keep it only when it has stable standalone retrieval value; otherwise merge it into the owning Node. |
 | `node.children_should_be_sections` | One parent contains many same-source, single-section child Entities with no stable shape tag. | Merge those children into parent Sections unless the user confirms each child has standalone lookup value. |
 | `node.term_expanded_beyond_definition` | A `term` Entity has grown past a compact definition or owns children. | Move rules, procedures, designs, and examples to the owning Node; keep the term entry narrow. |
-| `node.action_too_thin` | An Action has fewer than two distinct planned Section kinds and no child Action. | Downgrade it to a Section under the owning Node, add a distinct Section kind, or add a child Action; the CLI does not infer a single-section exception from source text. |
+| `node.action_too_thin` | An Action has one planned Section and no child Action. | Confirm its standalone retrieval value, keep it as a Section under the owning Node, add another source-backed Section, or add a child Action. This warning does not require artificial Section-kind diversity. |
 | `node.domain_without_children` | A Domain has no source-backed `contains` child edge. | Add supported children, keep an explicitly confirmed no-write placeholder, or reclassify the Node. |
 | `tags.child_inherits_system` | A child Entity repeats its parent `system` / `application` scope tag. | Retag by the child’s own shape/scope, or keep the child as a Section if it is only a local aspect. |
 | `edge.confidence_invalid` | An edge declares a confidence value outside the current schema. | Use only `possible` or `hypothesis`, or omit the field for source-certain relations. |