@codemation/agent-skills 0.4.0 → 0.5.2

package/skills/{codemation-credential-development → builder/credential-development}/references/credential-patterns.md

@@ -6,7 +6,7 @@ A credential binding is stored as `(workflowId, nodeId, slotKey)`. The `nodeId`
 
 For production workflows with credential-using nodes, prefer an explicit `id:` on the node config:
 
-```ts
+```text
 .node("Fetch from API", MyApiNodeConfig, {
   id: "fetch-from-api", // stable across label renames
   credentials: { apiKey: myApiCredential },
@@ -38,7 +38,7 @@ Register the credential type from the app or plugin boundary:
 
 Helper-defined nodes can request credentials directly:
 
-```ts
+```text
 credentials: {
   myService: myServiceCredential,
 }
@@ -59,7 +59,7 @@ See **`packages/core/docs/credential-ui-fields.md`** in the repository root layo
 
 For credentials that go through the OAuth2 redirect flow (Microsoft Graph, Slack, GitHub, Notion, etc.), declare the authorize and token URLs directly on the credential's `auth` definition. The host's `OAuth2ProviderRegistry` substitutes `{publicFieldKey}` placeholders from the credential's public config at connect time (URL-encoded).
 
-```ts
+```text
 auth: {
   kind: "oauth2",
   // providerId is a free-form label for telemetry / DB rows / Better Auth provider naming.

package/skills/builder/custom-node-development/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: custom-node-development
+description: Authors a reusable Codemation node with defineNode(...) (per-item execute) or defineBatchNode(...) (batch run), including credential slots, binary payloads, and the class-based fallback. Use when creating or updating custom nodes in an app or plugin package.
+tags: node, custom, plugin
+uses: "@codemation/core"
+---
+
+# Codemation Custom Node Development
+
+Custom nodes are the extension point for reusable business logic that doesn't belong inline in a workflow callback. `defineNode(...)` wraps a per-item `execute` function with a typed contract (config, credential slots, output shape); the engine calls it once per item. `defineBatchNode(...)` is the batch variant for logic that must see all items at once. A node definition exposes `.create(config, name?, id?)` to wire it into a workflow.
+
+## Per-item vs batch
+
+**`defineNode(...)` (per-item)** — the engine calls `execute(args, context)` once per item. This is the right default for the vast majority of nodes: straightforward logic, credential slots, input schema, optional fan-out.
+
+**`defineBatchNode(...)` (batch)** — the engine calls `run(items, context)` with the full activation batch. Use only when the node genuinely needs to see all items at once (aggregation, bulk API calls, cross-item correlation).
+
+When in doubt, start with `defineNode`.
+
+## Node rules
+
+1. Keep nodes deterministic and focused.
+2. Request credentials through named slots — never hard-code secrets.
+3. Put **static** options (credentials, retry policy, labels) on `input` (the config defaults); read them in `execute` via the second arg's `config`.
+4. **Emit files with `ctx.binary`, not base64 in `json`** — base64 in `item.json` bloats persisted run data. See `references/node-patterns.md`.
+5. Drop to class-based node APIs only when you need constructor-injected collaborators, decorators, or deeper runtime metadata.
+
+## Minimal `defineNode` example
+
+`execute(args, context)` receives `args = { input, item, itemIndex, items, ctx }` and `context = { config, credentials, execution }`. `input` is the per-item `item.json`; `config` is the resolved static config declared in `input:`.
+
+```ts
+import { defineNode } from "@codemation/core";
+
+export const normalizeTextField = defineNode({
+  key: "example.normalize-text-field",
+  title: "Normalize text field",
+  icon: "lucide:case-lower",
+  input: {
+    field: "text",
+    trim: true as boolean,
+    lowercase: true as boolean,
+  },
+  execute({ input }, { config }) {
+    const rawValue = String((input as Record<string, unknown>)[config.field as string] ?? "");
+    let normalized = rawValue;
+    if (config.trim) normalized = normalized.trim();
+    if (config.lowercase) normalized = normalized.toLowerCase();
+    return { ...(input as Record<string, unknown>), [config.field as string]: normalized };
+  },
+});
+```
+
+Wire it into a workflow with `normalizeTextField.create({ field: "text" }, "Normalize text", "normalize-text")`.
+
+## Read next
+
+- `references/define-node-per-item.md` — `defineNode(...)` contract, `inputSchema`, fan-out, and assertion nodes.
+- `references/define-batch-node.md` — `defineBatchNode(...)` contract and when to choose batch over per-item.
+- `references/credential-aware-nodes.md` — credential slots and typed sessions.
+- `references/node-patterns.md` — binary payloads (`ctx.binary`, `attach`, `withAttachment`), fan-out shapes, polling-trigger binary patterns, and HTTP binary round-trips.

package/skills/builder/custom-node-development/references/credential-aware-nodes.md

@@ -0,0 +1,52 @@
+# Credential-Aware Nodes
+
+Load this when your node needs a typed credential (OAuth token, API key, or any `defineCredential(...)` type) injected at runtime.
+
+## Core rule
+
+Request credentials through **named slots** on the node config instead of hard-coding secrets. The framework resolves the slot to a live typed session at execution time.
+
+## Adding a credential slot to `defineNode`
+
+Declare slots in `credentials:` (slot name → credential type). Each slot becomes an accessor `credentials.<slot>()` that resolves a live, typed session at execution time:
+
+```ts
+import { defineCredential, defineNode } from "@codemation/core";
+
+const myApiCredentialType = defineCredential({
+  key: "example.my-api",
+  label: "My API",
+  public: { baseUrl: "string" },
+  secret: { accessToken: "password" },
+  createSession(args) {
+    return {
+      baseUrl: String(args.publicConfig.baseUrl ?? ""),
+      accessToken: String(args.material.accessToken ?? ""),
+    };
+  },
+  test() {
+    return { status: "healthy", testedAt: new Date().toISOString() };
+  },
+});
+
+export const callApiNode = defineNode({
+  key: "example.call-api",
+  title: "Call My API",
+  credentials: { api: myApiCredentialType }, // slot name → credential type
+  async execute(_args, { credentials }) {
+    const session = (await credentials.api()) as { baseUrl: string; accessToken: string };
+    const response = await fetch(`${session.baseUrl}/data`, {
+      headers: { Authorization: `Bearer ${session.accessToken}` },
+    });
+    return await response.json();
+  },
+});
+```
+
+## Typed sessions
+
+`credentials.<slot>()` returns exactly what the credential type's `createSession(...)` returns. The framework handles binding, storage, and error propagation — your node only consumes the session.
+
+## Testing credential-aware nodes
+
+Inject a fake credential session through `WorkflowTestKit` rather than live credentials. See `credential-development` for the full `defineCredential(...)` story.

package/skills/builder/custom-node-development/references/define-batch-node.md

@@ -0,0 +1,54 @@
+# Define Batch Node
+
+Load this when you need to author a `defineBatchNode(...)` node that processes all items in one call.
+
+## When to use `defineBatchNode` instead of `defineNode`
+
+- The node must see the **entire activation batch** at once (e.g. an aggregation, a bulk API call, or a node that correlates items against each other).
+- Legacy batch semantics are required by the calling workflow.
+- You need the same contract as built-in batch-shaped nodes such as `Aggregate`.
+
+For the common case (one-item-at-a-time logic), prefer `defineNode` — the engine handles iteration for you.
+
+## Minimal skeleton
+
+`run(items, context)` receives plain JSON values (`TInputJson[]`), not `Item` wrappers, and returns one output per row. The example below ranks rows against the full batch — impossible per-item:
+
+```ts
+import { defineBatchNode } from "@codemation/core";
+
+type SaleRow = Readonly<{ salesRepId: string; revenueUsd: number }>;
+type RankedSaleRow = SaleRow & Readonly<{ rank: number; pctOfTotal: number }>;
+
+export const rankSalesByRevenue = defineBatchNode<
+  "example.rank-sales-by-revenue",
+  Record<string, never>,
+  SaleRow,
+  RankedSaleRow
+>({
+  key: "example.rank-sales-by-revenue",
+  title: "Rank sales by revenue",
+  icon: "lucide:bar-chart-2",
+  run(items) {
+    const total = items.reduce((sum, row) => sum + row.revenueUsd, 0);
+    const sorted = [...items].sort((a, b) => b.revenueUsd - a.revenueUsd);
+    const rankMap = new Map(sorted.map((row, index) => [row.salesRepId, index + 1]));
+    return items.map((row) => ({
+      ...row,
+      rank: rankMap.get(row.salesRepId) ?? items.length,
+      pctOfTotal: total > 0 ? Math.round((row.revenueUsd / total) * 10000) / 100 : 0,
+    }));
+  },
+});
+```
+
+## Contract
+
+- `run(items, context)` is called **once**, on the last item in the activation; intermediate items return `[]` internally.
+- `items` is plain `TInputJson[]`; return an array of output JSON values.
+- The context object exposes `config`, `credentials`, and `execution` (same as `defineNode`).
+- Batch nodes have no `inputSchema` — type the rows through the generic parameters.
+
+## Advanced fallback
+
+Reach for class-based node APIs when constructor-injected collaborators are required, plugin packaging needs the lower-level runtime contract, or decorators/persisted metadata need tighter control.

package/skills/{codemation-custom-node-development → builder/custom-node-development}/references/define-node-per-item.md

@@ -13,19 +13,27 @@ Load this when you need to author a `defineNode(...)` node that processes one it
 
 ```ts
 import { defineNode } from "@codemation/core";
-import { z } from "zod";
 
 export const uppercaseNode = defineNode({
   key: "example.uppercase",
   title: "Uppercase field",
   icon: "lucide:languages", // optional — Lucide, builtin:, si:, or image URL
-  inputSchema: z.object({ field: z.string() }),
-  async execute({ input, item }, { config }) {
-    return { ...input, [config.field]: String(input.field).toUpperCase() };
+  input: { field: "text" },
+  execute({ input }, { config }) {
+    const value = String((input as Record<string, unknown>)[config.field as string] ?? "");
+    return { ...(input as Record<string, unknown>), [config.field as string]: value.toUpperCase() };
   },
 });
 ```
 
+To validate and type the per-item payload, pass a Zod `inputSchema`:
+
+```text
+import { z } from "zod";
+inputSchema: z.object({ field: z.string() }),
+// → `input` is typed; the engine validates each item before calling execute.
+```
+
 ## Contract
 
 - `execute(args, context)` is called **once per item** by the engine.
@@ -42,17 +50,9 @@ Place **static** options (credentials, retry policy, labels) on `config`; place
 
 Supply `inputSchema` (Zod) to get typed `input` in `execute` and to drive the canvas form. The engine validates items against it before calling `execute`.
 
-## Testing with `WorkflowTestKit`
-
-```ts
-import { createEngineTestKit, registerDefinedNodes } from "@codemation/core/testing";
-
-const kit = createEngineTestKit();
-registerDefinedNodes([uppercaseNode]);
-const result = await kit.runNode(uppercaseNode, { json: { field: "hello" } });
-```
+## Testing
 
-Use `WorkflowTestKit` from `@codemation/core/testing` for engine-backed tests without the host.
+Use `WorkflowTestKit` from `@codemation/core/testing` for engine-backed tests without the host: construct it, register your defined nodes through its registration context, then run a workflow that wires the node via `.create(...)` and assert on the emitted items.
 
 ## Custom assertion nodes
 

package/skills/{codemation-custom-node-development → builder/custom-node-development}/references/node-patterns.md

@@ -13,23 +13,21 @@ Use `defineNode(...)` when:
 ## Standard helper shape (`execute`)
 
 ```ts
+import { defineNode } from "@codemation/core";
+
 export const uppercaseNode = defineNode({
   key: "example.uppercase",
   title: "Uppercase field",
   icon: "lucide:languages",
-  input: {
-    field: "string",
-  },
+  input: { field: "text" },
   execute({ input }, { config }) {
-    return {
-      ...input,
-      [config.field]: String(input[config.field as keyof typeof input] ?? "").toUpperCase(),
-    };
+    const value = String((input as Record<string, unknown>)[config.field as string] ?? "");
+    return { ...(input as Record<string, unknown>), [config.field as string]: value.toUpperCase() };
   },
 });
 ```
 
-Optional **`icon`** is forwarded to the generated node config for the canvas (Lucide `lucide:…`, **`builtin:…`** / **`si:…`**, or image URLs). See `packages/core-nodes/src/canvasIconName.ts` and the Next host `WorkflowCanvasNodeIcon` resolver.
+Optional **`icon`** is forwarded to the generated node config for the canvas (Lucide `lucide:…`, **`builtin:…`** / **`si:…`**, or image URLs).
 
 ## Batch helper shape (`defineBatchNode`)
 
@@ -88,20 +86,23 @@ Binary slots attached inside a node survive SubWorkflow boundaries with no extra
 ### Pattern: attach in a node, read in the parent after SubWorkflow
 
 ```ts
+import { defineNode } from "@codemation/core";
+
 // Child node — attaches a slot and returns the modified item.
+// Binary lives on `ctx` (the first arg), not the second context param.
 export const parseAndStoreNode = defineNode({
   key: "example.parse-store",
   title: "Parse and Store",
-  inputSchema: z.object({ filename: z.string() }),
-  async execute({ input, item }, { binary }) {
+  input: { filename: "out" },
+  async execute({ item, ctx }, { config }) {
     const bytes = Buffer.from("...parsed content...");
-    const att = await binary.attach({
+    const att = await ctx.binary.attach({
       name: "parsed",
       body: bytes,
       mimeType: "text/plain",
-      filename: `${input.filename}.txt`,
+      filename: `${config.filename}.txt`,
     });
-    return binary.withAttachment(item, "parsed", att);
+    return ctx.binary.withAttachment(item, "parsed", att);
   },
 });
 ```
@@ -110,32 +111,18 @@ After `SubWorkflowNode` returns, the parent's continuation nodes see `item.binar
 
 ### Testing binary across SubWorkflow with `WorkflowTestKit`
 
-```ts
-import { DefaultExecutionContextFactory, InMemoryBinaryStorage } from "@codemation/core";
-import { createEngineTestKit } from "@codemation/core/testing";
-import { ItemHarnessNodeConfig } from "@codemation/core/testing";
-
-const storage = new InMemoryBinaryStorage();
-const kit = createEngineTestKit({
-  executionContextFactory: new DefaultExecutionContextFactory(storage),
-});
+`@codemation/core/testing` exposes `WorkflowTestKit` and `ItemHarnessNodeConfig`. Use `ItemHarnessNodeConfig` (NOT `CallbackNodeConfig`) for harness nodes that must modify items — its callback receives `{ item, ctx }`, calls `ctx.binary.attach(...)`, and returns `ctx.binary.withAttachment(item, slot, att)`:
 
-// Use ItemHarnessNodeConfig (NOT CallbackNodeConfig) for nodes that must modify items:
+```text
 const attachNode = new ItemHarnessNodeConfig(
   "Attach",
   z.unknown(),
   async ({ item, ctx }) => {
-    const att = await ctx.binary.attach({
-      name: "doc",
-      body: Buffer.from("content"),
-      mimeType: "application/pdf",
-      filename: "doc.pdf",
-    });
-    return ctx.binary.withAttachment(item as Item, "doc", att);
+    const att = await ctx.binary.attach({ name: "doc", body: Buffer.from("content"), mimeType: "application/pdf", filename: "doc.pdf" });
+    return ctx.binary.withAttachment(item, "doc", att);
   },
   { id: "attach" },
 );
-// CallbackNodeConfig is fine for assertion-only (observe) nodes — it echoes input unchanged.
 ```
 
 Important: `CallbackNodeConfig` discards its callback return value and always echoes input items. Never use it for nodes that must attach binary or transform items.
@@ -144,23 +131,17 @@ Important: `CallbackNodeConfig` discards its callback return value and always ec
 
 Use `OutlookAttachmentDownload` from `@codemation/core-nodes-msgraph` when you have already obtained attachment metadata (filename, contentType, id) and want to download only specific attachments.
 
-```ts
-import { onNewMsGraphMailTrigger, outlookAttachmentDownloadNode } from "@codemation/core-nodes-msgraph";
-
-workflow("wf.download-resumes")
-  .trigger(onNewMsGraphMailTrigger, { mailbox: "me", folderId: "inbox" })
-  .then(
-    outlookAttachmentDownloadNode.create(
-      {
-        messageId: "", // falls back to item.json when empty
-        attachmentId: "", // falls back to item.json when empty
-        binarySlot: "resume",
-        sizeCapBytes: 10 * 1024 * 1024,
-      },
-      "DownloadResume",
-    ),
-  )
-  .build();
+```text
+// from @codemation/core-nodes-msgraph
+outlookAttachmentDownloadNode.create(
+  {
+    messageId: "",   // falls back to item.json when empty
+    attachmentId: "", // falls back to item.json when empty
+    binarySlot: "resume",
+    sizeCapBytes: 10 * 1024 * 1024,
+  },
+  "DownloadResume",
+)
 ```
 
 Key constraints:
@@ -195,7 +176,7 @@ export default workflow("wf.download-pdf")
 
 ### Upload binary bytes from a slot
 
-```ts
+```text
 new HttpRequest("UploadResume", {
   method: "POST",
   url: "https://api.example.com/files",
@@ -207,6 +188,9 @@ new HttpRequest("UploadResume", {
 ### Download then upload (full round-trip)
 
 ```ts
+import { HttpRequest } from "@codemation/core-nodes";
+import { workflow } from "@codemation/host";
+
 export default workflow("wf.mirror-pdf")
   .manualTrigger<{ sourceUrl: string; targetUrl: string }>("Start", { sourceUrl: "", targetUrl: "" })
   .then(new HttpRequest("Download", { urlField: "sourceUrl", responseFormat: "binary", responseBinarySlot: "file" }))

package/skills/builder/document-ai/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: document-ai
+description: Extracts markdown text and structured fields from a document, invoice, or image with the managed codemationDocumentScannerNode — no Azure or BYOK credential needed. Use this whenever a workflow scans an attachment (PDF, receipt, photo) and reads back markdown or per-field values.
+compatibility: Codemation core-nodes. Requires @codemation/core-nodes import.
+tags: ocr, document, invoice, image, scan, extract, markdown, fields, confidence, managed, binary
+uses: "@codemation/core-nodes"
+---
+
+# Codemation Document Scanner
+
+`codemationDocumentScannerNode` reads the bytes of a binary attachment off `item.binary` and returns
+`{ markdown, fields }` from the **managed** Codemation doc-scanner service. It signs each call with the
+workspace pairing secret over HMAC — the workspace holds **no Azure key**. This is the default for any
+scanning step on the managed platform.
+
+**Discipline:** author straight from this file, then run `verify_workflow` and fix only what it flags.
+Use `workflow-dsl` for the surrounding builder, trigger, and flow-control surface.
+
+## A complete scanning workflow
+
+A webhook receives a file upload; the framework places the bytes at `item.binary["data"]`; the node
+analyzes them and replaces the item payload with `{ markdown, fields }`.
+
+```typescript
+import { createWorkflowBuilder, WebhookTrigger, codemationDocumentScannerNode } from "@codemation/core-nodes";
+
+export default createWorkflowBuilder({
+  id: "wf.scan-document",
+  name: "Scan an uploaded document",
+})
+  .trigger(
+    new WebhookTrigger("Receive upload", { endpointKey: "doc-upload", methods: ["POST"] }, undefined, {
+      id: "receive-upload",
+      description: "Accepts an uploaded file and starts the scan.",
+    }),
+  )
+  .then(
+    codemationDocumentScannerNode.create(
+      {
+        binaryField: "data", // key on item.binary holding the bytes — default "data"
+        analyzerType: "auto", // routes on Content-Type; set explicitly when you know the class
+      },
+      "Scan document",
+      { id: "scan-document", description: "Reads the uploaded file and pulls out its text and key fields." },
+    ),
+  )
+  .build();
+```
+
+`.create(config, label, idOrOptions)` is the `defineNode` call shape — same for every built-in node here.
+The third argument takes either a bare `"nodeId"` string OR an options object `{ id, description }` — **always
+pass the object so the scan step carries a plain-language `description`** (it is a node like any other; a
+document/OCR step with no description is the most-forgotten gap). Set an explicit `id` whenever a downstream
+node references this output or the label may change later.
+
+## Choosing `analyzerType`
+
+Default is `"auto"`. Set an explicit type whenever you know the content class — it avoids re-routing
+and self-documents the workflow.
+
+| `analyzerType` | When                                                 | Field extraction   |
+| -------------- | ---------------------------------------------------- | ------------------ |
+| `"document"`   | General PDFs, Word, HTML, text-heavy files           | Yes                |
+| `"invoice"`    | Invoices and receipts                                | Yes                |
+| `"image"`      | Photos, screenshots, diagrams                        | No (markdown only) |
+| `"auto"`       | Unknown mime type — `image/*` → image, else document | Depends on routing |
+
+## Output shape
+
+The node replaces the item payload with this shape (`DocScannerOutput`):
+
+```text
+{
+  markdown: string;                 // full text rendering of the document
+  fields: Record<string, {
+    value: unknown;                 // scalar, ISO date string, nested object, or array
+    confidence: number | null;      // 0–1 when includeConfidence:true; otherwise null
+  }>;
+}
+```
+
+`item.json.markdown` is the Markdown rendering. `item.json.fields` is a flat-or-nested map of
+structured fields the analyzer found — sparse or empty for generic documents (best-effort), and
+always `{}` for `analyzerType: "image"`.
+
+## Per-field confidence (opt-in)
+
+By default `confidence` is `null` on every field — this keeps token cost low for the common case that
+only needs `value`. Set `includeConfidence: true` to populate it:
+
+```typescript
+import { createWorkflowBuilder, WebhookTrigger, codemationDocumentScannerNode } from "@codemation/core-nodes";
+
+export default createWorkflowBuilder({ id: "wf.scan-invoice", name: "Scan invoice with confidence" })
+  .trigger(new WebhookTrigger("Receive invoice", { endpointKey: "invoice-upload", methods: ["POST"] }))
+  .then(
+    codemationDocumentScannerNode.create(
+      {
+        analyzerType: "invoice",
+        includeConfidence: true, // fields now carry confidence 0–1
+      },
+      "Scan invoice",
+      "scan-invoice",
+    ),
+  )
+  .build();
+```
+
+**Cost:** enabling confidence routes to a confidence-enabled analyzer variant, roughly doubling the
+contextualization token count for `document`/`invoice`. Only enable it when downstream logic reads
+`field.confidence`. `image` (and auto-routed-to-image) requests ignore the flag silently — confidence
+stays `null`, never a 400.
+
+## Consuming fields downstream
+
+Read named fields off `item.json.fields` in a following step. Type the `Callback` input with
+`DocScannerOutput` so the field map is inferred:
+
+```typescript
+import { Callback } from "@codemation/core-nodes";
+import type { DocScannerOutput } from "@codemation/core-nodes";
+
+const useFields = new Callback<DocScannerOutput, { vendorName?: string; vendorConfidence: number | null }>(
+  "Use invoice fields",
+  (items) =>
+    items.map((item) => {
+      const vendorName = item.json.fields["VendorName"]?.value as string | undefined;
+      const vendorConfidence = item.json.fields["VendorName"]?.confidence ?? null;
+      return { ...item, json: { vendorName, vendorConfidence } };
+    }),
+  { id: "use-invoice-fields" },
+);
+```
+
+## Config reference
+
+```text
+codemationDocumentScannerNode.create(
+  {
+    binaryField?: string;          // key on item.binary — default "data"
+    analyzerType?: "document" | "invoice" | "image" | "auto";  // default "auto"
+    contentType?: string;          // MIME override — falls back to the attachment's mimeType
+    includeConfidence?: boolean;   // default false — see the cost note above
+    maxBytes?: number;             // size cap before reading — default 50 MiB
+  },
+  label?: string,                  // node label on the canvas
+  nodeId?: string,                 // explicit stable id — set when output is used downstream
+)
+```
+
+## Gotchas
+
+- **Bytes come from `item.binary`, never base64 on `item.json`.** The node reads
+  `item.binary[binaryField]`; a webhook, Gmail, or `readWorkspaceFileNode` must have attached the bytes
+  to that slot upstream. Missing attachment → the node throws.
+- **The output replaces the item payload.** After scanning, `item.json` is `{ markdown, fields }` — the
+  original payload is gone. Carry forward anything you still need before this step, or read it from a
+  retained binary slot.
+- **`fields` is best-effort.** Guard every `fields["Name"]?.value` access; the analyzer may not find it.
+- **Managed only.** The node needs `DOC_SCANNER_GATEWAY_URL` + workspace pairing in the env; it throws a
+  clear error when run outside a paired workspace.
+
+## Read next when needed
+
+- `workflow-dsl` — builder, triggers, flow control, the per-item contract.
+- `workspace-files` — read a stored file's bytes into `item.binary` before scanning.
+- `ai-agent` — pass `item.json.markdown` to an LLM for summarization or extraction.