@c4a/context 0.7.29 → 0.7.34

package/docs/guides/lark-resources.md

@@ -12,7 +12,8 @@ resource checks; it does not fetch that supplied body again. See
 
 | Resource | Default capture behavior |
 |---|---|
-| Image and attachment | Download the original file and link it from the Markdown projection. |
+| Image | Download the original; on explicit download permission denial, try a same-identity preview once and mark it as a preview. |
+| 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. |
@@ -28,21 +29,22 @@ 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
+an explicit permission denial (including HTTP 403) 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
+with a warning. Explicit missing-scope and access-denied resource responses are
+likewise recorded without changing identity. Transient network errors, malformed
+payloads, and unclassified 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.
 
-Document and resource reads share one access identity. Context first uses the
-user identity; it falls back to the bot identity only when user credentials
-are unavailable, never when the source denies permission or reports missing
-scopes. This prevents a capture from mixing document text read by one identity
-with attachments read by another. A bot fallback is reported in the capture
-result and remains subject to the bot's own access boundary.
+Document and resource reads share one access identity. The configured default is
+user. Bot mode permits one whole-document user fallback for a body authorization
+failure, restarting all pages. After the body is read, resources remain under
+that identity. A resource failure never requests another identity's credentials.
+Legacy explicit auto mode may select Bot when user credentials are unavailable;
+all resources still use the identity that supplied the complete body.
 
 ## Storage lifecycle
 
@@ -127,8 +129,24 @@ assess the page with its non-text evidence.
 
 ## Image choices for a production task
 
+Before capture, the Agent follows the document-capture Route procedure's task-wide
+document threshold and image self-check, without asking for user confirmation.
+Set `DOCUMENT_IMAGE_CAPTURE` in task instructions or workspace guidance to `ON`
+(include images), `OFF` (references only), or a positive integer document threshold.
+Omitting it uses `10`; exactly the threshold remains within normal acquisition.
+Current-conversation instructions override workspace guidance for that task only.
+For example, `DOCUMENT_IMAGE_CAPTURE: 20` skips image downloads when the task
+contains more than 20 distinct documents. This is an Agent instruction, not an
+environment variable, CLI flag or SDK field; no Bot configuration is required.
+Above a numeric threshold, the default is body capture with image references,
+unless the effective setting is overridden to `ON`. This workflow
+choice uses the existing resource fields; it does not change SDK defaults or add
+a CLI hard gate. Apply it before bulk capture or host prefetch, not after images
+have already been downloaded.
+
 The work-start report asks once when a task contains more than 30 distinct images
-and has no explicit image policy. The choices are intelligent conversion and
+that will be acquired and has no explicit image handling policy. Reuse the
+current-conversation image instruction when it already settles this choice. The choices are intelligent conversion and
 inclusion (recommended), include all as images with compression, or include none
 with placeholders. Count the whole task, not each capture or writing batch.
 Review reports show the resulting image handling and any fallbacks.
@@ -162,3 +180,13 @@ limits. The reading meaning of an image is handled in writing and Review.
 Source document links can be retained for viewing under the reader's permissions.
 Temporary signed media links are not durable image hosting. Do not embed access
 tokens in generated pages or claim that excluded images have been interpreted.
+
+### Capture identity and unavailable media
+
+The selected document identity remains fixed for resource reads. In Bot mode,
+only an authorization failure while reading the body can restart the article
+as the current user. Resource failures never trigger that identity fallback.
+Images may use the official same-identity preview endpoint after download
+permission is denied. Previews are marked explicitly; unavailable resources
+retain references and diagnostics. Use available body evidence without inferring
+missing resource contents, and review evidence gaps before approving conclusions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.7.29",
+  "version": "0.7.34",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",