@prismer/runtime 2.0.7 → 2.0.8

package/built-in-skills/human-approval/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: human-approval
+description: Request human approval before performing a SAFETY-CRITICAL, IRREVERSIBLE, or SCOPE-EXPANDING action — submit a structured context (action, scope, risk, consequence) plus options, then STOP the current turn. The platform redispatches the agent after the human decides. NEVER use for routine deliverables (writing docs / generating files / summarising chats / answering questions / explaining concepts / read-only tool calls) — those are pre-authorized; just produce the output. The 5-minute-rollback litmus test applies: if the wrong outcome can be undone in <5 minutes by editing or deleting, it is NOT approval-eligible. Routine misuse (intro/explain/summarise/file-generation) burns the user's attention budget and is a contract violation. Executes via `cloud approval` CLI.
+---
+
+# Human Approval
+
+Some actions need a human in the loop **before** they execute: production deploys, large credit spend, deleting data, scope-expanding decisions. This skill submits a structured request and **halts the current turn**. The platform stores the request, notifies the human, and **redispatches the agent** with the decision when the human responds — you don't poll, you don't re-ask in the same turn.
+
+## When to use
+
+- **Production-impacting** action: deploy, schema change, infra reconfig, payment send.
+- **Irreversible**: delete files, drop tables, revoke keys, close accounts.
+- **Scope-expanding**: the task as-stated implies more changes than the user originally agreed to.
+- **High credit cost**: any operation that would spend > expected budget.
+- **Authority-elevating**: granting access, changing roles, modifying ACLs.
+
+## Not when to use
+
+- Routine clarifying questions ("what column name do you want?") — just ask in chat.
+- Choosing between two equivalent options where the user clearly didn't care — pick one and proceed.
+- When the user already explicitly approved this action in the current conversation — proceed.
+
+## Skill scope guard (v2.0.8)
+
+The "Not when to use" list above is the **load-bearing rule**. As of
+release 2.0.8 we tightened it because routine deliverables (write a
+doc, summarise a chat, draft a slide deck, answer a question) were
+incorrectly triggering approval gates — the user got a yellow "等待
+人工确认" banner for a request as simple as "@ceo 给我介绍一下产品 PDF",
+which is a deliverable request, not a scope-expansion.
+
+The following 8 categories are **never** approval-eligible. Run them
+directly and report the result in the same turn:
+
+| Category | Why it's not approval-eligible | Use instead |
+|---|---|---|
+| Writing a document / generating a report / outputting PDF, DOCX, PPTX, XLSX, CSV | The user *asked for the deliverable*; gating it is anti-UX. | Call `office-artifacts` and ship. |
+| Summarising a conversation / writing meeting notes | Pure synthesis from data the user already has. | Reply in chat. |
+| Answering a question / explaining a concept | The user invited the answer by asking. | Reply in chat. |
+| Asking the user for a preference ("Chinese or English?") | A chat question is the correct affordance. | Ask in chat — `human-approval` is overkill. |
+| Choosing model parameters / temperature / sampling style | Internal agent decision; users don't have context to judge. | Decide and proceed; mention the choice in the reply. |
+| Naming files / picking output paths | Internal agent decision; reversible by renaming. | Pick sensible defaults; let user override if asked. |
+| Internal brainstorming / scoring multiple candidates | The user asked for the *winner*, not the deliberation. | Do the work, surface the winner. |
+| Calling read-only MCP tools (search, web fetch, file read) | No side effect; trivially reversible. | Call directly. |
+
+**The litmus test:** "**If this step turns out wrong, can I roll it
+back in under 5 minutes by editing or deleting something?**"
+  - If **yes** → not approval-eligible. Ship it.
+  - If **no** → safety-critical / irreversible / scope-expanding → approval-eligible.
+
+Mis-using `human-approval` for routine work burns the user's attention
+budget, breaks chat flow, and signals lack of agent confidence — all
+three are real costs. The role templates (CEO / engineer / marketer /
+researcher / verifier) carry an explicit `operatingPrinciples` line as
+of 2.0.8: "Never trigger human-approval for routine deliverables".
+
+## CLI Reference
+
+**Anchor required.** `POST /api/im/approvals` rejects requests with neither `taskId` nor `conversationId`, because the platform needs a target to deliver the human decision to. Every invocation MUST pass one of `--task-id` or `--conversation-id`.
+
+```bash
+# Linked to a task — the platform resumes the task on decision (preferred for marketplace / agent flows)
+cloud approval request-human \
+  --task-id <taskId> \
+  --action "approve marketplace task completion" \
+  --context "Result: scan-deps found 3 CVEs. Report attached." \
+  --risk "Releases 10-credit escrow to the assignee."
+
+# Linked to a conversation — the decision is posted back as a chat message
+cloud approval request-human \
+  --conversation-id <conversationId> \
+  --action "delete branch feat/old-experiment" \
+  --context "Last commit 2025-12-10. Merged into main. Local copy preserved." \
+  --risk "Irreversible. No remote backup; force-pushed commits would be lost."
+
+# With explicit options (multi-choice)
+cloud approval request-human \
+  --conversation-id <conversationId> \
+  --action "deploy v1.8.2 to prod" \
+  --context "All gates green, 9/9 webhook tests pass, test env stable 48h." \
+  --risk "Touches payment webhook. Rollback ETA 5min via git revert + redeploy." \
+  --options "deploy-now" "deploy-tomorrow-morning" "wait-for-manual-smoke-test"
+```
+
+## Workflow
+
+1. **Summarize the action** in one sentence — what will happen, on what resource, with what permission.
+2. **Provide context** — recent state, related artifacts, why this came up now.
+3. **Spell out risk and consequence** — what breaks if this is wrong, what's reversible, what's not, who else is affected.
+4. **Provide options** when binary approve/reject is insufficient. Options must be **mutually understandable** and **independently actionable** (each is a thing the agent can do without further clarification).
+5. **Submit the approval request.** Capture the returned `approvalId`.
+6. **Stop the current turn.** Don't ask follow-up questions, don't start the action, don't speculate about the answer. The platform will redispatch you when the human decides.
+
+## Operating Rules
+
+- **Do not proceed with the gated action in the same turn after requesting approval.** This is the load-bearing rule. The platform will redispatch the agent with the decision; running the action now defeats the gate.
+- **Do not hide material risks or irreversible effects** from the approval context. The human is approving based on what you wrote — incomplete framing is worse than no gate.
+- **Keep options mutually understandable and actionable.** "Approve" / "Approve with conditions" / "Reject" is fine. "Maybe" / "Let me think" is not — that's not a decision the human can choose.
+- **Use this for safety-critical decisions**, not routine clarification. Asking the user "what label do you prefer?" via human-approval is overkill and burns their attention budget.
+- **Link to a task** (`--task-id`) when the approval gates a task's progression. The platform resumes the task automatically when the human approves.
+- If the user already explicitly approved this exact action earlier in the conversation, **skip the gate**. Repeated approval-prompts for the same authorized action feel broken.
+
+## Output reporting
+
+After submitting:
+
+> Submitted approval request `<approvalId>` for "<action>". Stopping this turn. The platform will redispatch when the human decides.
+
+When the agent is redispatched with the decision, the next turn's input includes the approval result. Don't re-issue the request — read the decision and act on it (or report rejection back to the user).
+
+## Backing capabilities (D22 mapping)
+
+Replaces this v1.x built-in skill: `approval-request-human`.

package/built-in-skills/image-generate/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: image-generate
+description: Generate an image from a text prompt via the cloud LLM image proxy, persist it as a content-addressed workspace asset, and return a ContentBlock that downstream renderers can attach. Use whenever the user asks "draw / generate / make an image of …", an agent needs a diagram / illustration as a follow-up artifact, or a task description explicitly demands visual output. Do NOT use for editing or describing existing images — `assets` covers reads, and image editing is a separate skill.
+applies_to: [hermes, claude-code, openclaw, codex]
+requires:
+  - assets
+phaseModel:
+  defaultPhase: tool_use
+version: 1
+---
+
+# Image Generate
+
+Turn a **text prompt** into a **content-addressed image asset** plus a v2.0 §4.6
+ContentBlock that the chat renderer can surface inline. The skill is a thin
+orchestration over two existing surfaces:
+
+1. **LLM image gateway** — the cloud's NewAPI proxy at
+   `POST /api/v1/images/generations` (OpenAI-compatible — see §"Hand-off" if
+   the endpoint is not yet wired in your deployment).
+2. **Asset store** — `POST /api/im/assets` (multipart) on the cloud, returning
+   a stable `assetId` + `contentHash`. Generated bytes flow through the
+   content-addressed pipeline like any other asset — same de-dup, same audit
+   trail, same URI scheme (`prismer://assets/<assetId>`).
+
+The skill's **only** output contract is a ContentBlock referencing the asset.
+Raw bytes / `data:` URIs / pre-signed URLs MUST NOT be embedded in prose; doing
+so defeats caching and makes follow-up retrieval impossible (same rule as the
+`assets` skill).
+
+## When to use
+
+- The user says "draw", "generate an image of …", "make me a picture / poster /
+  diagram / illustration".
+- A task description includes a `produce_image:` field or a `kind: image`
+  artifact expectation.
+- You need to **fabricate** a visual that does not exist in any source — if
+  the visual already exists, use `assets` to read it, not this skill.
+- A downstream skill (`canvas-design`, `slack-gif-creator`,
+  `web-artifacts-builder`) requires a generated source image as input.
+
+## Not when to use
+
+- Editing / variation / inpainting an existing image — that's a separate
+  upcoming skill (`image-edit`). Don't fake it by reading + regenerating.
+- Describing what's in an image — use a vision-capable adapter, no generation
+  needed.
+- Pure ASCII / SVG / Mermaid graphics that the LLM can emit as text — those
+  belong in the chat body, not in an asset.
+- Privacy-sensitive renderings (faces, identifiable individuals) without
+  explicit user confirmation. The skill does not gate this; the agent must.
+
+## API Reference
+
+There is **no `cloud image generate` subcommand** in the runtime CLI today
+(release 201 audit, `sdk/prismer-cloud/runtime/src/cli/commands/`). Call the
+cloud HTTP endpoint directly from a small Python / Node script in the skill
+runtime, then hand the bytes to `cloud asset upload` for the content-addressed
+write. Adding a dedicated CLI verb is tracked as a future release; until then,
+do **not** invent the command — it will exit with "unknown command".
+
+HTTP shape:
+
+```http
+POST /api/v1/images/generations
+Authorization: Bearer <user JWT or sk-prismer-* key>
+Content-Type: application/json
+
+{
+  "prompt":  "<text prompt, 1..4000 chars>",
+  "model":   "gpt-image-1",                 // or "dall-e-3", deployment-dependent
+  "size":    "1024x1024",                   // 256x256 | 512x512 | 1024x1024 | 1792x1024 | 1024x1792
+  "n":       1,                             // skill always uses 1 (return single ContentBlock)
+  "response_format": "b64_json"             // skill requires bytes — never "url"
+}
+
+Successful response (OpenAI shape):
+{
+  "created": 1716345600,
+  "data": [{ "b64_json": "<base64 PNG bytes>" }]
+}
+```
+
+After receiving bytes the skill **MUST** upload to the cloud asset store
+(`POST /api/im/assets`, multipart) and use the returned `assetId` in the
+ContentBlock. Bytes never leak into chat.
+
+## Workflow
+
+1. **Validate inputs.** Prompt 1..4000 chars; size in the allow-list above;
+   workspaceId resolved (defaulting to the active workspace if none supplied).
+2. **Generate.** POST to `/api/v1/images/generations` with
+   `response_format: 'b64_json'`. Capture `b64_json` (single image).
+3. **Decode + hash.** Base64-decode to bytes, compute SHA-256 client-side, and
+   compare against the upload response's `contentHash` field (server validates
+   too — use `x-content-sha256` header).
+4. **Upload as asset.** Multipart POST to `/api/im/assets`:
+   - `file` — Blob with `image/png` MIME and filename
+     `generated-${shortHash}.png`
+   - `workspaceId`, `kind=image`, `description=<prompt[0..500]>`
+   - `sourceTaskId` / `sourceAgentImUserId` (if available from runtime context)
+   - `folderPath=/generated/images/${YYYY-MM}` (auto-organized, optional)
+5. **Emit ContentBlock.** Return — and only return — a ContentBlock pointing
+   at the new asset. Shape exactly as v2.0 §4.6 (Anthropic-shape, not OpenAI):
+
+   ```json
+   {
+     "kind":      "image",
+     "assetId":   "<returned assetId>",
+     "mediaType": "image/png",
+     "alt":       "<prompt truncated to 100 chars>"
+   }
+   ```
+
+## Operating Rules
+
+- **Always `response_format: b64_json`.** Never `url` — the OpenAI URL is
+  short-lived, doesn't survive the content-address round-trip, and tempts you
+  to leak it into chat (which defeats the asset model).
+- **One image per call.** `n=1` only. If the user wants variants, call the
+  skill multiple times — each variant gets its own assetId so the user can
+  pick + delete cleanly.
+- **Hash check is non-negotiable.** Server enforces `x-content-sha256`; if the
+  hashes disagree, abort and surface the mismatch — the bytes were corrupted
+  in flight.
+- **Never inline base64 / `data:<mime>;base64,...` in the reply body.** The
+  whole point of the skill is to avoid that anti-pattern. If you find yourself
+  about to do so, stop and check that the asset upload actually succeeded.
+- **Default size = 1024x1024** unless the user explicitly asks for portrait
+  (1024x1792) or landscape (1792x1024). 256/512 only when budget is tight.
+- **Cost-aware:** image gen is far more expensive than a chat completion.
+  Tell the user the model + size you picked before spending more than 1
+  credit's worth, and surface the actual cost from the response.
+
+## ContentBlock output (v2.0 §4.6 / Gap E-⑤)
+
+This skill produces a **single image ContentBlock** per successful generation.
+It MUST NOT also dump the base64 / pre-signed URL into the reply — that
+violates the §4.6 rule (asset-by-reference, not asset-by-value) and breaks the
+chat renderer's preview pipeline.
+
+```json
+{ "kind": "image", "assetId": "<assetId>", "mediaType": "image/png", "alt": "<prompt summary, ≤100 chars>" }
+```
+
+The reply envelope from this skill (when invoked via the agent runtime) looks
+like:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "assetId":     "<assetId>",
+    "contentHash": "<sha256 hex>",
+    "sizeBytes":   123456,
+    "cdnUrl":      "<optional, server may include>",
+    "model":       "gpt-image-1",
+    "size":        "1024x1024",
+    "promptHash":  "<sha256 of prompt for de-dup>"
+  },
+  "contentBlocks": [
+    { "kind": "image", "assetId": "<assetId>", "mediaType": "image/png", "alt": "<prompt[0..100]>" }
+  ]
+}
+```
+
+Legacy callers that only know how to parse `result.assetId` keep working
+(field preserved). Multimodal-aware callers prefer `contentBlocks[]` —
+adapters and the chat renderer both check `contentBlocks` first per the §4.6
+prefer-blocks rule.
+
+## Failure modes
+
+| Status | Where | Cause | What to surface |
+|---|---|---|---|
+| 400 | LLM proxy | prompt too long / disallowed content | Prompt rejected; surface the proxy's error message verbatim. Do NOT retry the same prompt. |
+| 402 | LLM proxy | not enough credits | Tell the user the cost + ask them to top up. Don't burn credits on retries. |
+| 415 | asset upload | server rejected MIME (not in allow-list) | Should not happen — `image/png` is allow-listed. If it does, this is a deployment bug; flag it. |
+| 422 | asset upload | `x-content-sha256` mismatch | Bytes corrupted in flight. Retry once; if it persists, fail the skill and tell the user. |
+| 5xx | either | upstream outage | Retry with exponential backoff up to 2 times, then fail loudly. Do NOT fabricate the assetId. |
+
+## Output reporting
+
+After successful generation:
+
+```
+[image-generate] generated assetId=<id> model=<model> size=<WxH> sha=<short>
+                 cost=<credits>c prompt="<first 60 chars>…"
+```
+
+Then in chat, return ONLY the ContentBlock (the renderer surfaces the image
+preview). One-line caption may accompany it if useful ("Here's the
+illustration you asked for.").
+
+After failure: report `status + proxy error code + message` verbatim. Do not
+silently retry on 4xx (those are the user's prompt / quota — they need to
+know).
+
+## Backing capabilities (Gap E-⑤ mapping)
+
+- **LLM image gateway:** `POST /api/v1/images/generations` (NewAPI proxy
+  wired in Wave 6 G1 at `src/app/api/images/generations/route.ts`; gateway
+  reuses `proxyToNewAPI` in `src/lib/llm-proxy.ts` with image-specific
+  billing via `calculateImageCredits`). Setting env `MOCK_LLM_IMAGES=true`
+  bypasses NewAPI and returns a fixture 1×1 PNG (for integration tests
+  that should not burn real image-gen credits).
+- **Asset store:** `POST /api/im/assets` (multipart) — `src/im/api/assets.ts`
+  line 2729+. Returns `IMAsset` with `id`, `contentHash`, `cdnUrl`,
+  `sizeBytes`.
+- **ContentBlock contract:** v2.0 §4.6 — `sdk/prismer-cloud/typescript/src/types.ts`
+  lines 278–296 (8-variant discriminated union, Anthropic-shape).
+- **Reply attachment plumbing:** `AgentDispatchReplyPayload.attachments` —
+  same path as the `assets` skill's image-resolve output. Chat renderer
+  surfaces previews from `attachments` / `contentBlocks` automatically.
+
+## Examples
+
+### Example 1 — User asks for an illustration
+
+```
+User: "Draw an isometric server room with glowing blue racks"
+
+Skill flow:
+  POST /api/v1/images/generations
+    { prompt: "An isometric...", model: "gpt-image-1",
+      size: "1024x1024", n: 1, response_format: "b64_json" }
+    ← 200 { data: [{ b64_json: "<bytes>" }] }
+
+  decode + sha256 → "8f4a..."
+
+  POST /api/im/assets (multipart)
+    file=generated-8f4a.png  kind=image  workspaceId=...
+    x-content-sha256: 8f4a...
+    ← 200 { data: { id: "asset_<...>", contentHash: "8f4a...",
+                    cdnUrl: "/api/im/assets/asset_<...>" } }
+
+Reply envelope:
+  { ok: true,
+    result: { assetId: "asset_<...>", contentHash: "8f4a...", ... },
+    contentBlocks: [
+      { kind: "image", assetId: "asset_<...>", mediaType: "image/png",
+        alt: "An isometric server room with glowing blue racks" }
+    ] }
+```
+
+### Example 2 — Task-pinned generation for kanban artifact
+
+```
+Task input: { produce_image: { prompt: "Logo: minimalist owl, monochrome",
+                                size: "1024x1024" } }
+
+Skill call: POST /api/v1/images/generations with the prompt, then
+`cloud asset upload generated.png --task-id "$PRISMER_TASK_ID"` so the
+kanban task review board surfaces the image inline (chat renderer reads
+contentBlocks from the asset attachment).
+```
+
+### Example 3 — Failure: prompt rejected
+
+```
+User: "<disallowed content>"
+LLM proxy: 400 { error: { code: "content_policy_violation", ... } }
+
+Skill response:
+  { ok: false,
+    error: { code: "content_policy_violation",
+             message: "<proxy's verbatim message>" } }
+
+Do NOT retry. Do NOT fabricate an assetId.
+```
+
+## Anti-patterns
+
+- ❌ Returning the raw base64 in `result.image_b64` for chat to render. The
+  chat renderer expects ContentBlock referencing an asset; raw bytes bypass
+  caching.
+- ❌ Using `response_format: 'url'` and pasting the OpenAI URL into the
+  reply. URL expires; user clicks later → 404.
+- ❌ Skipping the asset upload "to save time" when the generated image is
+  tiny. Tiny images still need stable IDs for follow-up retrieval and audit
+  trail.
+- ❌ Calling the skill in a loop to "generate variants" — call once per
+  variant with explicit prompt deltas. The de-dup hash will catch identical
+  prompts.
+- ❌ Setting `n > 1`. The ContentBlock output shape is single-image; multi
+  would force you to fabricate which one to attach.
+
+## Hand-off — endpoint provisioning
+
+**Cloud-side endpoint wired in Wave 6 G1.** `POST /api/v1/images/generations`
+is now provisioned at `src/app/api/images/generations/route.ts` and uses
+the same `proxyToNewAPI` helper that backs `/api/chat/completions` +
+`/api/embeddings`. Image-specific billing lives in
+`src/lib/llm-pricing.ts::calculateImageCredits` (per-image USD pricing,
+no token semantics). Setting `MOCK_LLM_IMAGES=true` returns a fixture PNG
+without hitting NewAPI — used by F6 integration tests.
+
+Historical handler template (matches the landed implementation):
+
+```ts
+// src/app/api/images/generations/route.ts (NEW)
+import { NextRequest, NextResponse } from 'next/server';
+import { apiGuard } from '@/lib/api-guard';
+import { checkRateLimit, rateLimitResponse } from '@/lib/rate-limit';
+import { FEATURE_FLAGS } from '@/lib/feature-flags';
+import { proxyToNewAPI } from '@/lib/llm-proxy';
+import { ensureNacosConfig } from '@/lib/nacos-config';
+
+export async function POST(request: NextRequest) {
+  await ensureNacosConfig();
+  if (!FEATURE_FLAGS.LLM_PROXY_ENABLED) {
+    return NextResponse.json(
+      { error: { message: 'LLM proxy is not enabled' } }, { status: 503 });
+  }
+  const guard = await apiGuard(request, { tier: 'tracked' });
+  if (!guard.ok) return guard.response;
+  const rl = checkRateLimit(guard.auth.userId, 'llm');
+  if (!rl.allowed) return rateLimitResponse(rl);
+  return proxyToNewAPI(request, guard, '/v1/images/generations');
+}
+```
+
+Until this lands, the skill operates in **mock mode** — see
+`scripts/test-image-generate-skill.ts` which proves the
+generate→upload→ContentBlock chain by stubbing the LLM bytes (a 1x1 PNG) and
+hitting the real `/api/im/assets` upload, so the asset half of the contract
+is fully validated against production code paths.

package/built-in-skills/ingest/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ingest
+description: Turn external URLs and documents into LLM-ready content — load + cache web pages (HQCC compression) and OCR PDFs/images to Markdown. Use whenever the user gives a URL, asks you to read a webpage, or attaches a PDF/scan that needs to be parsed before reasoning. Executes via the `cloud load`, `cloud search`, and `cloud parse` CLIs.
+---
+
+# Ingest
+
+Use this skill to **bring external content into the LLM context window** without copy-pasting raw HTML or burning tokens on uncompressed prose. Two paths:
+
+- **Web content** → `cloud load` / `cloud search` → returns HQCC (a compressed, LLM-optimized form). Cache hits are free.
+- **Documents (PDF, images)** → `cloud parse` → OCR to Markdown. Two modes: `fast` (digital PDFs, clean images) and `hires` (scans, handwriting).
+
+## When to use
+
+- The user pastes a URL or asks "what does this page say".
+- The user asks to research a topic ("AI agent frameworks 2025") — use `search` to fetch top-K relevant pages.
+- The user attaches a PDF or image and the next step requires reading its contents.
+- A task description contains URLs that need to be resolved into actual content before the assignee can act.
+
+## CLI Reference
+
+### Web content
+
+```bash
+# Single URL → HQCC
+cloud load https://example.com
+cloud load https://example.com --format raw     # exact wording / code / tables (more tokens)
+
+# Batch (up to 50 URLs)
+cloud load https://a.com https://b.com https://c.com
+
+# Search → load (fetch top-K relevant pages)
+cloud search "AI agent frameworks 2025"
+cloud search "topic" -k 10
+
+# Pre-save to cache (e.g. content you scraped elsewhere)
+cloud context save https://example.com "compressed content"
+```
+
+### Documents (OCR)
+
+```bash
+# Fast mode — digital PDFs, clean images
+cloud parse https://example.com/paper.pdf
+
+# Hi-res — scans, handwriting, complex layouts
+cloud parse https://example.com/scan.pdf -m hires
+
+# Async — long parses return a task id; poll until ready
+cloud parse <url> --async                       # → returns parseTaskId
+cloud parse-status <parseTaskId>                # check progress
+cloud parse-result <parseTaskId>                # fetch finished markdown
+```
+
+Supported parse formats: PDF, PNG, JPG, TIFF, BMP, GIF, WEBP.
+
+## Workflow
+
+### For web URLs
+
+1. Decide: single URL load? Batch? Or search query?
+2. Default to `--format hqcc` (compressed). Use `raw` only when **exact wording, code, or tables** are needed.
+3. Run `cloud load` / `cloud search` and capture: source URLs, titles, cache status, cost.
+4. Base downstream reasoning **only on the returned content**. If a load failed, say so; don't pretend you read it.
+
+### For documents
+
+1. Confirm the URL points to the **actual document** (PDF/image), not a landing page that hosts it. If unsure, try `cloud load` first to see what's at that URL.
+2. Start with `fast` mode for digital PDFs and clean images. Switch to `hires` when fidelity matters (scans, handwriting, dense tables).
+3. If parse returns asynchronously, record the **parseTaskId** and **don't invent** content while waiting.
+4. When the result returns, capture page count, cost, and any parse warnings.
+5. Use the parsed Markdown as the **source of truth** for subsequent extraction or summary.
+
+## Operating Rules
+
+### Load / Search
+
+- **Prefer cached context.** Don't re-process the same source — the service handles cache lookup automatically; just don't re-issue identical loads in tight loops.
+- Preserve **source URLs** in your notes and citations. The HQCC return retains origin pointers; use them.
+- Don't claim to have read a source until the load **succeeds**. If it fails (404, blocked, timeout), report the failed URL and continue only with clearly stated assumptions or ask for a better source.
+- `--format raw` costs more tokens. Only use when the user needs exact wording (legal text, code snippets, tables that compress badly).
+- For batch loads, the service runs them concurrently up to a limit; you don't need to throttle yourself.
+
+### Parse
+
+- Don't parse **private or access-controlled documents** unless the user explicitly intended to share that source.
+- Prefer `cloud load` for **normal web pages**. Use parse only when the source is a document / image / scan that load can't extract from.
+- For large or expensive parses (long PDFs in hi-res), explain the tradeoff before running if the user didn't explicitly ask for full fidelity.
+- If the result is **incomplete** (truncated, low confidence on key pages), ask for a clearer source or escalate to `hires` before drawing firm conclusions.
+- Async parse is the right call for documents >50 pages or hi-res scans. Sync mode will time out on these.
+
+## Output reporting
+
+After load/search:
+- One-line summary per source: `<title> · <url> · cache_hit | fresh · <cost>`
+- Then proceed with the user's actual question, citing the source by URL.
+
+After parse:
+- `Parsed <filename>: <pageCount> pages, <cost> credits, mode=<fast|hires>`
+- If async: `Parse queued as <parseTaskId>; poll with cloud parse-status`
+- Use the markdown body for the next step; don't dump the whole thing in chat unless the user asked.
+
+## Backing capabilities (D22 mapping)
+
+Replaces these v1.x built-in skills: `context-load`, `parse-document`.