@c4a/context-cli 0.7.29 → 0.7.34

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

@@ -23,6 +23,14 @@ refresh, or capture preview before permission is clear. A request that
 explicitly says to ingest, fetch, capture, or read the named documents grants
 that scope; merely mentioning a possible source does not.
 
+The image preflight in the document-capture procedure is an Agent self-check,
+not an additional user question. Before capture, briefly report the task-wide
+document count and applied policy. Reference-only images keep source references
+but are not downloaded or interpreted. Do not wait for confirmation or infer an
+all-image override from managed execution. Unknown scope requires authorized
+metadata or body-and-reference-only discovery first. Existing source-read
+permission requirements remain unchanged.
+
 If deterministic inspection detects `.mdx`, route metadata, sidebars, or a docs
 configuration, explain that the boundary looks like a documentation site and
 ask whether to use the Context document-site processor. Do not infer that

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

@@ -18,7 +18,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. |
@@ -34,21 +35,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
 
@@ -133,8 +135,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.
@@ -168,3 +186,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/providers/context/resources/procedures/document-capture.md

@@ -13,14 +13,16 @@ 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.
+3. perform the Agent's task-wide image acquisition preflight below before capture;
+4. 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
+When that permission is already present and the Agent's image acquisition
+preflight is complete, 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
@@ -48,12 +50,33 @@ 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.
 
-For Lark reads, Context prefers the authenticated user identity. If that
-identity is unavailable because its credential is missing, expired, or cannot
-be refreshed, Context may retry the same registered source with the bot
-identity. It does not switch identity after a permission or missing-scope
-response. Once selected, the same identity is used for the document body and
-all embedded resources. If `docs +fetch` lacks the required `--doc-format`
+For Lark reads, set `CONTEXT_LARK_IDENTITY=user|bot` in the environment of every
+Context invocation that may read Lark; the default is `user`. A host/Bot prompt
+setting alone is not an exported environment variable. User mode reads only
+as the current user. Bot mode may fall back once to the current user only when
+reading the document body fails with a credential, scope or access denial.
+The fallback restarts the entire body, including pagination; never combine body
+pages from different identities. Once the body is available, its identity is
+fixed for all media, synced references, Sheets, Base and whiteboard reads.
+Resource failures do not request user authorization or restart the article.
+Network, rate-limit and format errors do not switch identity.
+
+An image download denied by permissions may use the official preview endpoint
+once with the same identity. A captured preview is explicitly marked as such.
+Unavailable resources retain their location and failure reason; continue with
+other resources and usable body text. Never infer missing image contents or
+present a partial snapshot as a complete original. Assess any evidence gaps
+before approving conclusions that depend on those resources.
+
+This setting does not grant source access or change the intended audience of
+the resulting knowledge. Do not use another person's credentials. For direct
+host reads, explicitly pass the article's selected identity on every read.
+Only an article-level fallback may request the current user's authorization;
+use the managed runtime's authorization flow once when needed.
+Local help and embedded skill discovery require no document authorization;
+do not request user OAuth just to read a CLI guide.
+
+If `docs +fetch` lacks the required `--doc-format`
 capability, follow the returned `lark-cli update` recovery and rerun the same
 Route command; do not replace the capture with a hand-written export.
 
@@ -63,9 +86,67 @@ are available while another capture remains pending. Keep unresolved sources in
 pending capture after the active production/review work, before delivery completes.
 This does not mark failed captures as complete or waive source-read authorization.
 
-For image-heavy tasks, reuse the image choice in the work-start report. When
-source descriptors already show more than 30 distinct images across the task,
-resolve that question before bulk media acquisition. If counts emerge only from
-capture, stop further image processing to confirm the choice during planning.
-Use explicit image/GIF reference-only policies for exclusions; never substitute
-temporary signed media URLs as permanent public image links.
+## Image acquisition before capture
+
+The workflow instruction setting `DOCUMENT_IMAGE_CAPTURE` accepts `ON`, `OFF`,
+or a positive integer document threshold; when absent it defaults to **10**.
+Read it from the current task instructions or workspace guidance; a current
+conversation instruction takes precedence. This is an Agent-interpreted setting,
+not a CLI flag, environment variable, or SDK field. Hosts need not add a setting.
+
+| Setting | Acquisition policy |
+| --- | --- |
+| `ON` | Include images without a document-count cutoff, subject to existing resource limits and explicit exclusions. |
+| `OFF` | Capture bodies and image references only, regardless of document count. |
+| positive integer `N` | Include images under the existing policy for at most `N` documents; above `N`, use references only. |
+| absent | Use `10`. |
+
+For an invalid value, report it and use `10` rather than silently enabling all
+images or blocking the task. An explicit current-conversation request to include
+all images selects `ON` for this task; an explicit request to skip images selects
+`OFF`. If neither is present, use the configured setting. Do not write a temporary
+conversation override back into permanent workspace guidance.
+
+Count distinct documents
+selected for this task, including Wiki descendants and in-scope linked documents,
+not all historical workspace sources, API pages, retries, or output articles.
+Deduplicate shortcuts and repeated links. Splitting the task into batches or
+resuming it does not reset the count. Exactly 10 documents is within the default.
+
+Before starting capture, the Agent separately checks the document count (or known
+lower bound), setting, and effective image policy. This is an Agent self-check,
+not a user confirmation gate: do not ask a question or wait for a reply. Above the
+numeric threshold, automatically capture bodies with image references only; at or
+below it, retain the existing image policy. `ON` and `OFF` apply regardless of count.
+A generic
+"capture everything", source-read permission, managed mode, or an old bundle setting
+does not. Briefly report the count and applied policy in the work-start update and
+retain the decision in task notes; do not repeat the update for every document.
+
+If the count is unknown, first perform only authorized directory/metadata discovery
+without image downloads. If body reads are needed to discover linked documents,
+use a body-and-reference-only discovery pass within existing read authorization.
+With a numeric setting, unknown totals do not authorize image acquisition; `ON`
+does not require counting to enable images, and `OFF` never enables them.
+Recalculate the task total before enabling images under a numeric setting.
+If later expansion crosses the numeric threshold, apply the
+reference-only policy before further acquisition and report the change without
+waiting for a reply; retain any explicit all-image override and existing evidence.
+
+For `OFF` or above-threshold tasks without an `ON` override, apply
+`resources: { images: "reference-only", gifs: "reference-only" }` to the selected
+Lark capture declarations before executing the Route. Preserve unrelated sources,
+resource settings and existing stricter exclusions; inspect generated/dynamic
+configuration rather than assuming registration applied the policy. Host prefetch
+and import paths must honor the same choice, not download images before import.
+Other resource types retain their existing policies. Do not edit snapshots or
+invent unsupported flags; when a capture adapter cannot exclude images, explain
+that limitation and resolve the acquisition method before downloading.
+
+Preserve source links/placeholders and report skipped images as not acquired or
+interpreted. This is a workflow instruction using existing resource policies, not
+a new CLI hard gate or automatic document counter. For tasks that still include
+images, retain the existing handling workflow for more than 30 distinct images
+and reuse an explicit choice; do not invoke it for images skipped by this
+preflight. Never substitute temporary signed media URLs as permanent
+public image links.

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

@@ -71,6 +71,12 @@ settled scope, not a new confirmation step.
 
 ## Workflow
 
+Before any capture or host prefetch, follow the task-wide image threshold and
+Agent self-check in [Document capture](document-capture.md#image-acquisition-before-capture).
+Do not ask the user to confirm this default or infer an all-image override from
+source-read permission. Apply the effective resource policy before a managed batch;
+registration defaults must not silently re-enable excluded images.
+
 Capture is entirely CLI-driven — your role is to register the right source,
 declare the matching capture phase, run the current `context run capture:*`
 command, and preserve its machine fields while summarizing the outcome in the