@c4a/context 0.6.1 → 0.6.3

package/docs/guides/agent-guide.md

@@ -5,25 +5,39 @@ This guide is for Coding Agents operating a Context workspace.
 ## Start Here
 
 1. If a public Agent entry is available, use the installed Context continuation command/skill from the project root; the exact slash command or skill name is host-specific.
-2. If you are implementing that entry or operating without plugins, run `context status`.
-3. Execute safe mechanical CLI `next:` steps instead of merely reporting them.
-   Stop and ask at `Human gate:` next steps, placeholder next steps, human
-   decision gates, or external source-repo operations.
+2. If you are implementing that entry or operating without plugins, run
+   `context status --format json`.
+3. Treat `workflow.current` as the current-step authority. Read every
+   `resources.required` item, execute only returned commands with their
+   revision/authority flags unchanged, and rerun status after each action.
+   A phase-local `next_action` may continue pagination or validation inside the
+   current operation; it never replaces the workspace route.
 4. Before editing `src/index.ts`, read [Project API](../reference/project-api.md).
 5. Before declaring or repairing packages, read [Package Outputs](./package-outputs.md)
    and [Package Templates](../reference/package-templates.md).
-6. Before asking a human gate question, read [Agent Dialogue](./agent-dialogue.md).
+6. Before asking a human gate question, read the dialogue resource selected in
+   `workflow.current.resources.required`; use [Agent Dialogue](./agent-dialogue.md)
+   only for stable cross-gate principles.
 
 ## Current-conversation fully managed mode
 
 When the user explicitly requests fully managed operation in the current
 conversation, use `context status --managed --format json` and keep `--managed`
-on the commands returned by that loop. Eligible classification, extraction
+only on commands that actually include it. Preserve every returned
+revision/authority flag. Eligible classification, extraction
 scope, structure confirmation, Review, and package-output gates may proceed
 without another question. Review uses the CLI's atomic `context review
 approve-all ... --managed` route; valid structure staging records
 `confirmed_by: managed-session`.
 
+After the first managed status evaluation, use
+`context run --managed --until blocked-or-complete --format json` when the
+current work can advance through consecutive mechanical routes. The CLI
+executes only a unique immediate non-read command, re-evaluates after each
+receipt, and stops before Agent interpretation, configuration, missing
+authority, diagnostics, or multiple commands. Continue from the returned
+`workflow.current`.
+
 This is execution authority, not project configuration. Do not add it to
 `defineProject`, environment files, or committed workspace state, and do not
 carry it into a new conversation. It never grants a new source boundary or
@@ -44,8 +58,9 @@ protocol text: copy those exactly and do not translate them.
 At human gates, explain the product decision and impact before internal API
 details. Do not start with `extractTs`, `include`, `exportedOnly`,
 `reviewValidity`, placeholder commands, or raw TypeScript snippets unless the
-user asks for implementation detail. The required dialogue patterns are in
-[Agent Dialogue](./agent-dialogue.md).
+user asks for implementation detail. The current gate's dialogue pattern is
+selected by `workflow.current.resources`; [Agent Dialogue](./agent-dialogue.md)
+explains stable cross-gate principles.
 
 ## Do Not Self-Discover The SDK
 
@@ -61,29 +76,45 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 
 - `src/index.ts` declares sources, phases, and packages.
 - `sources/repo/index.yaml`, `sources/file/index.yaml`, and `sources/lark/index.yaml` declare sources.
-- `unapproved/entities.jsonl` is the committed draft/rejected/deprecated ledger.
-- `knowledge/` contains approved Markdown.
+- `.tmp/context-runtime/lifecycle/` is the ignored, CLI-managed draft candidate
+  ledger and confirmed structure state for an open lifecycle round.
+- `knowledge/` contains approved Markdown, the durable
+  `knowledge/structure.yaml` projection, and (only when needed) the compact
+  `knowledge/decisions.json` rejected candidate ID-to-fingerprint map.
+- `knowledge/structure.yaml.source_inputs` contains only source, collection,
+  and consumed snapshot hash for closed prose targets. It lets status detect a
+  changed or unfinished target without retaining lifecycle snapshots.
 - `dist/` contains generated package outputs.
+- `.tmp/agent-payloads/` is the recommended location for transient inputs written
+  by the Agent for CLI commands. It is not enforced, but avoids introducing
+  top-level scratch directories; remove these files after the corresponding
+  stage or apply succeeds unless the user explicitly wants to retain them.
 - file and Lark documents from one date live as sibling files under `sources/file/<date>/` and `sources/lark/<date>/`; each date directory has one shared `manifest.json`.
-- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks.
+- `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks. Successful close removes completed lifecycle and review runtime state.
 
 Do not create hidden workspace state directories.
 
-## Workflow Entrypoints
+## Workflow resources and entrypoints
+
+Long procedures, semantic judgment rules, schemas, and current workspace views
+are published as Context workflow resources. Status returns only the resources
+selected for the current route. Read required resources before acting; use
+recommended resources only when the current evidence or diagnostic needs them.
+Do not preload every workflow resource or SDK manual.
 
 Present only the current workflow surface:
 
 | Task | Current route |
 |---|---|
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
-| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory and updates that directory's single `manifest.json`. |
+| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory, updates that directory's single `manifest.json`, and mechanically materializes supported Lark resources. Do not download or rewrite embedded resources outside the CLI. |
 | Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
-| Confirm prose structure | `alignProse` validates and stages `unapproved/structure.yaml`. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
+| Confirm prose structure | `alignProse` validates and stages CLI-managed lifecycle structure. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
 | Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |
 | Review and apply | Use `context review html` and `context review apply`. Approved prose pages are source-mirrored; rewrite/compression problems should return to structure/compile repair before apply. |
 | Close, verify, build | Run `context close`, `context verify`, then `context build`. Close derives `knowledge/structure.yaml`, approved edge projection, and the final verify gate. |
 | Code extraction | Use `context source inspect <source-name>` and the declared extract phase preview before code draft writes. |
-| Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `unapproved/`, `dist/`, or `.tmp` to simulate lifecycle actions. |
+| Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `dist/`, or `.tmp` to simulate lifecycle actions. |
 
 Judgment behavior is part of evidence views, source span resolvers, repair
 hints, review/status diagnostics, OKF indexes, and package query discipline. Do
@@ -104,7 +135,8 @@ identity. Do not invent semantic date suffixes. The concrete repo selector
 appears in source refs, phase ids, and codegraph paths:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/<collection>/<slug>.md
+knowledge/<collection>/<containment>/<slug>.md  # intentional hierarchy only
 repo:<date>/<module>#symbol:...
 file:<source-name>/<document>#span:...
 lark:<source-name>/<document>#span:...
@@ -113,7 +145,10 @@ align:lark:<source-name>:architecture
 dist/<source-name>-kb/
 ```
 
-Prose align/compile paths derive from collection, containment, and slug.
+Every prose View requires a stable filename `slug`. The CLI derives its path
+from collection, slug, and optional `containment`; omit `path` from the input.
+Supply `containment` only for an intentional parent/child hierarchy;
+independent collection entries stay directly under the collection.
 Codegraph paths use the registered date/module grouping before the symbol slug.
 
 Ask what the user wants the source to cover: a single local Markdown/MDX document,
@@ -151,25 +186,34 @@ do not fetch or import Lark content with ad hoc scripts.
 If the user requests multiple documents together, register and declare all of
 them before capture. The user's explicit batch request supplies one read scope,
 but it does not imply a mainline collection unless the user explicitly chose
-one. Follow `routing.command_plan`: run
-`immediate` items directly and run `after-human-confirmation` items only after
-the current conversation contains that confirmation. Do not ask for another
-date name or repeat the collection gate per document.
+one. Follow `workflow.current.commands`: run `immediate` items directly and run
+`after-human-confirmation` items only after the current conversation contains
+that confirmation. Preserve the returned workflow revision and authority flags
+exactly. Do not ask for another date name or repeat the collection gate per
+document.
 
 ## Current-step protocol
 
-Treat `context status --format json` `routing` as the complete protocol for the
-current step:
+Treat `context status --format json` `workflow.current` as the complete
+protocol for the current step:
 
-- `human_gate.required` says whether user input is required;
-- `human_gate.kind` says which product decision is being made;
-- `human_gate.confirmation` and `persistence` distinguish conversation-only
-  permission from decisions persisted by a workspace command;
+- `availability` distinguishes an immediately executable route from a human
+  decision or a blocked route;
+- `gate` identifies the decision, its authority, and whether a managed session
+  may resolve it;
 - `configuration` identifies the exact project file and declaration action when
   no CLI command is valid yet;
-- `commands_available` reports whether a command plan exists; and
-- `command_plan[].availability` says whether each command runs immediately or
-  only after user confirmation.
+- `commands[].availability` says whether each command runs immediately or only
+  after user confirmation;
+- `resources.required` is the complete mandatory context for this route;
+- `resources.recommended` is optional follow-up context; and
+- `after_action.evaluate` requires status to be evaluated again after the
+  action.
+
+Read a resource `path` directly. If a resource provides `command`, execute that
+revision-bound Context command and read the returned file. Long procedures and
+semantic rules live in these resources; they are loaded progressively, not
+discarded or shortened into the status response.
 
 Status also returns `declarationGraph` and `configurationGaps`. These expose
 capture, align, compile, and Review coverage for each canonical document source
@@ -179,19 +223,21 @@ by the structure must have an exact compile route for the same source. Do not
 run a compile command from another collection as a fallback. A
 `reviewValidity({ scope: "all" })` declaration covers every collection.
 
-When status is `captured-ready-to-classify`, execute its immediate capture-phase
-evidence commands before adding align/compile declarations. Inspect every
-unclassified target, explain the evidence behind the proposed mainline
-collection, and wait for user confirmation. Filenames, URLs, source titles, and
-collection names are hints, not sufficient classification evidence by
-themselves.
+When `workflow.current.reason_code` is
+`route.document.classification-required`, execute its read-only
+`inspection_action` commands before adding align/compile declarations. Inspect
+every unclassified target, explain the evidence behind the proposed mainline
+collection, and wait for user confirmation. Filenames, URLs, source titles,
+and collection names are hints, not sufficient classification evidence.
 
 Also inspect `pendingStructureTargets`. A non-empty list means captured document
 work remains outside the active structure snapshots, even if the current package
 is already built. Follow `needs-prose-configuration` first when declarations are
 missing, then run the exact returned align command. Continue in the same
 workspace; do not replace a valid earlier structure round or create a second
-workspace merely to add the next document.
+workspace merely to add the next document. Missing declarations are selected
+by `route.prose.configuration-required`; do not branch on an old top-level
+`needs-prose-configuration` state.
 
 Use `structureBatch` for the complete multi-source slot overview. Evidence View
 commands are workspace-read-only and parallel-safe; structure stage/confirm,
@@ -204,24 +250,26 @@ another declared slot remains pending in the same round. Compile every View from
 all slots first, open one collection-level Review, and let deterministic close
 merge the active slots into `knowledge/structure.yaml`.
 
-Do not infer permission from the presence of a command. Do not infer a command
-from prose when `commands_available=false`; complete the returned configuration
-action and rerun status instead.
+Do not infer permission from the presence of a command. When
+`workflow.current.commands` is empty, do not derive a lifecycle command from
+prose; complete the returned `configuration` action or resolve the returned
+gate, then rerun status.
 
 Extraction scope is also a human gate. If no extract phase is declared, explain
 what code area and symbol policy will become draft knowledge, then ask which
 registered source and file/symbol range to ingest. Do not inspect the source
-repository to choose packages or globs on the user's behalf. Status reports
-`needs-extract-phase` with `routing.configuration` until that confirmed scope is
-declared; only a declared phase can advance to `ready-to-extract` and return an
+repository to choose packages or globs on the user's behalf. The
+`route.extract.configuration-required` Route carries
+`workflow.current.configuration` until that confirmed scope is declared; only
+a declared phase can select `route.extract.pending-target` and return an
 executable preview or extraction command.
 
 For a fresh mixed-source workspace, capture every confirmed file/Lark source
 first. If repo code is still unprocessed and document structure has not started,
-`context status` prioritizes `ready-to-extract` over document investigation.
-Complete the code extraction and its batch Review before starting prose align.
-Once a document structure draft exists, keep that current human gate and do not
-switch workflows mid-review.
+`context status` prioritizes `route.extract.pending-target` over document
+investigation. Complete code extraction and its batch Review before starting
+prose align. Once a document structure draft exists, keep that current human
+gate and do not switch workflows mid-review.
 
 For monorepos, the date is one registration batch and every selected package is
 a module under it. Stable codegraph paths omit that batch date and therefore
@@ -259,10 +307,11 @@ context run <extract-phase-id> --dry-run --format json
 After the preview, run codegraph extraction normally unless the user explicitly
 asked for CI/CD automation. The first normal run requires Review for all code
 candidates. Subsequent normal runs require Review only for added, changed, or
-removed symbols; unchanged approved symbols stay approved. Always inspect
-`next_action.human_gate`: `continue-codegraph-batch` means run status and finish
-the remaining confirmed module phases. Open one Review only after
-`pendingExtractPhases` is empty and the returned gate is `true`.
+removed symbols; unchanged approved symbols stay approved. After each result,
+run `context status --format json`. `continue-codegraph-batch` only requests
+workspace re-evaluation. Open Review only when
+`workflow.current.gate.id=knowledge-review`; otherwise execute the current
+route.
 
 For a non-interactive pipeline, use `context run <extract-phase-id>
 --auto-promote --format json`. This flag applies only to codegraph, applies its
@@ -272,21 +321,17 @@ and fails the command if close or verify fails. Read `autoPromotion.close` and
 the pipeline publishes packages, run `context build` after successful auto
 promotion. Never use auto promotion for semantic knowledge collections.
 
-If verify reports `approved-source-ref-ambiguous` on approved codegraph pages
-created by beta.5, do not send those pages back through Review and do not filter
-approved symbols away. Rerun the declared codegraph extraction phase to refresh
-the trusted file-aware symbol index, then run `context review
-migrate-codegraph-refs` and `context verify`. Tell the user that this preserves
-their decisions and approved content while upgrading evidence metadata. If the
-reported ref already contains `<file>:<symbol>:<kind>`, treat it as a duplicate
-symbol-index defect instead of a legacy migration.
-
 Use the preview `mode`, optional `entries`, `preview.sources[].modules[]`,
+`entryFiles`, exported/internal symbol counts, `candidateKinds`,
 `candidateEstimate`, and `agent_hints`
 fields as the authoritative scope check. To the user, call it a preview without
 writing candidates; avoid the internal CLI term. Also show `knowledgeTree` and
 `knowledgePathExamples` before first extraction.
 
+These are structural extractor facts. Do not turn kind counts or file paths
+into a product-specific recommendation unless the user or Agent supplies that
+judgment.
+
 Treat `NO_ENTRY_DETECTED` as a configuration failure: choose explicit
 `entries`, or use `mode: "scan"` when the intended scope is all matched files;
 never report an empty extraction as success. Report discovered, AST-analyzed,
@@ -301,7 +346,7 @@ knowledge/codegraph/<module>/symbol/<slug>.md
 If the module or resulting path shape looks wrong, stop and repair the
 module registration before running extraction. An extra repeated package
 segment below the module may indicate an over-broad source boundary. Do not write ad hoc scripts to
-count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
+count packages, parse `package.json`, or sample the lifecycle candidate ledger.
 
 ## Review Rules
 
@@ -320,7 +365,6 @@ count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
   `context review approve <candidate-id> --collection <collection>` /
   `context review reject <candidate-id> --collection <collection>` or `--all`.
   These commands still enforce the scoped candidate-id gate.
-- Do not expand the compact review decision Payload into pretty JSON unless the user asks.
 - Do not edit approved Markdown by hand as part of review apply.
 
 ## Prose Align And Compile Rules
@@ -331,10 +375,9 @@ product sequence:
 1. investigate material through Context evidence views;
 2. propose a structure draft with nodes, section plans, supported edges, and
    unresolved items;
-3. repair validator blockers until `confirmation_ready=true`, stage the
-   structure, open its HTML report, then ask the user to confirm it because
-   confirmation freezes paths, section ownership, relationships, and compile
-   order for this round;
+3. resolve only the non-mechanical blockers until validation state is `ready`,
+   stage the structure, open its HTML report, then follow the current Route's
+   structure-confirmation gate;
 4. compile source-bound draft pages from confirmed structure;
 5. send compiled drafts through human review, then close and build.
 
@@ -348,6 +391,7 @@ context run align:<type>:<source>:<collection> --view read-plan --format json
 context run align:<type>:<source>:<collection> --view source-index --compact --format json
 context run align:<type>:<source>:<collection> --view span-detail --span <source-ref> --format json
 context run align:<type>:<source>:<collection> --view span-text --span <source-ref> --format json
+context run align:<type>:<source>:<collection> --view existing-knowledge --query <title-or-stable-ref> --format json
 context run align:<type>:<source>:<collection> --view schema --format json
 context run align:<type>:<source>:<collection> --validate --input <structure.yaml> --format json
 context run align:<type>:<source>:<collection> --view structure-summary --input <structure.yaml> --format json
@@ -356,41 +400,41 @@ context run align:<type>:<source>:<collection> --stage --input <structure.yaml>
 
 Read source material only through these evidence views. `source-index` gives a
 compact refs-first map when run with `--compact`; use `span-detail` /
-`span-text` only for exact evidence. When validate returns
-`repair_confirmation_blockers`, follow its repair route without asking for
-preliminary approval. `--repair suggested-splits` mechanically handles
-non-contiguous source Sections. For oversized Views, use the returned child
-View and contains-edge suggestions while classifying child Nodes from evidence.
-Stage only after
-`confirmation_ready=true`; stage opens the final `structure-summary` report for
-the structure confirmation gate. Ask a separate structure-design question only
-when evidence supports multiple incompatible semantic choices, and make clear
-that it is not final review. Do not inspect `sources/` or `.tmp` directly.
+`span-text` only for exact evidence. Before introducing a new Node identity,
+use the targeted `existing-knowledge` View returned by the read plan to inspect
+approved stable refs; do not inspect `knowledge/**` directly. The CLI applies
+deterministic boundary repairs internally and returns only blockers that need
+Agent judgment. For oversized Views, use the returned structural diagnostics
+while classifying
+child Nodes from evidence. Stage only after validation state is `ready`; stage
+opens the final `structure-summary` report for the current Route's confirmation
+gate. Ask a separate structure-design question only when evidence supports
+multiple incompatible semantic choices. Do not inspect `sources/` or `.tmp`
+directly.
 
 Compile:
 
 ```bash
 context run compile:<type>:<source>:<collection> --view read-plan --format json
-context run compile:<type>:<source>:<collection> --view node-context --source <view-ref> --format json
-context run compile:<type>:<source>:<collection> --view schema --format json
-context run compile:<type>:<source>:<collection> --validate --input <compile-actions.yaml> --format json
-context run compile:<type>:<source>:<collection> --stage --input <compile-actions.yaml> --format json
+context run compile:<type>:<source>:<collection> --validate --format json
+context run compile:<type>:<source>:<collection> --stage --format json
+context run compile:<type>:<source>:<collection> --view diagnostics --format json
 ```
 
-Compile each confirmed View sequentially, but do not stop for Review after each
-write. Follow `continue_compile_batch` until no planned View remains; then open
-one collection-level Review, apply one Payload, and run close once.
+Compile derives every candidate mechanically from the confirmed section ids,
+kinds, ownership, and source spans. One stage command validates the complete
+source/collection slot before atomically writing its candidates. The Agent does
+not author compile actions or rewrite reader-visible body. Re-evaluate status
+after the batch, finish any other structure slots, then open one
+collection-level Review, apply one Payload, and run close once.
 
-Default compile actions should mirror source spans into `verbatim` body and
-attach summary/kind/source refs. Explicit reader-visible content is not part of
-the current compile action contract; split evidence or return to structure
-confirmation instead. Relationships and cross references are structure typed
-edges in current output; this workflow does not render relationship reference
-blocks. Never inject relation markers into verbatim body.
+Relationships and cross references remain structure typed edges; compile does
+not infer them or inject relation markers into verbatim body.
 
 ## Package Rules
 
-If `context status` says `needs-package-output`, treat it as a human gate.
+If `workflow.current.reason_code` is `route.package.output-required`, treat it
+as a human gate.
 First read [Package Outputs](./package-outputs.md). Then explain the package
 decision using concrete output trees, not unexplained labels.
 
@@ -402,13 +446,18 @@ dist/<name>-kb/
 ├── skills/knowledge-query/SKILL.md
 └── wikis/
     ├── index.md
-    ├── <group>/index.md
-    └── <group>/...
+    ├── <group-page>.md
+    └── <large-group>/index.md
 ```
 
 This is an agent knowledge-base package. It is the recommended first output for
 agent consumption; the internal `skills/` folder follows agent installation
 conventions.
+The package name already identifies the surrounding `dist/` directory. Its OKF
+roots stay flat (`wikis/`, `guides/`, `rules/`, and `feats/`), so do not ask for
+a second distribution namespace. Ask separately whether the author wants a
+short Skill prefix; if so, maintain the complete final Skill directory name in
+the template.
 The default `knowledge-query` skill teaches agents to query copied OKF root
 directories structure-first, starting with `wikis/`, cite
 page/section evidence, use structure/build metadata when present, and report
@@ -422,8 +471,9 @@ installation files; the OKF-compatible interchange surface is the selected OKF
 root directories. Tell the user they can customize
 `src/package-templates/kb/wikis/index.md` before build to describe package
 scope and query guidance. The default root index should list only next-level
-directories. `context build` generates child directory indexes such as
-`<okf-root>/<group>/index.md` for deeper navigation.
+entries. By default, `context build` links small directory contents directly
+and generates a child index only when that directory contains more than 50
+selected knowledge pages.
 
 Alternative:
 

package/docs/guides/lark-resources.md

@@ -0,0 +1,115 @@
+# 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.