@c4a/context-cli 0.6.2 → 0.6.3

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

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/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/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/views/source-boundary.yaml

@@ -0,0 +1,6 @@
+schema: agent-graph.resource.v1
+id: context.source-boundary
+kind: context-view
+mediaType: text/markdown
+description: Stable registered source identities and boundaries without lifecycle progress.
+materializer: actions/materialize-context-view.yaml

package/providers/context/schemas/repository-source-recovery.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "context.repository-source-recovery.v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "repositories"],
+  "properties": {
+    "schema": {
+      "const": "context.repository-source-recovery.v1"
+    },
+    "repositories": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source", "mode", "path"],
+            "properties": {
+              "source": { "type": "string", "minLength": 1 },
+              "mode": { "const": "local" },
+              "path": { "type": "string", "minLength": 1 }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source", "mode"],
+            "properties": {
+              "source": { "type": "string", "minLength": 1 },
+              "mode": { "const": "clone" },
+              "path": { "type": "string", "minLength": 1 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/providers/context/actions/ensure-repository-sources.yaml

@@ -1,5 +0,0 @@
-schema: agent-graph.action.v1
-id: ensure-repository-sources
-runner: command
-effect: external
-command: context source ensure --format json