@codemation/agent-skills 0.2.0 → 0.4.0

package/skills/codemation-workflow-dsl/SKILL.md

@@ -2,277 +2,77 @@
 name: codemation-workflow-dsl
 description: Guides Codemation workflow authoring. Use when creating or updating workflow definitions in `src/workflows` — manual-trigger flows via `workflow("...").manualTrigger(...)`, or cron/webhook/other triggers via `createWorkflowBuilder({id, name}).trigger(...)`.
 compatibility: Designed for Codemation apps and plugins that author workflows.
+tags: workflow, dsl, authoring
+uses: "@codemation/core-nodes, @codemation/host"
 ---
 
 # Codemation Workflow DSL
 
-## Use this skill when
+## Mental model
 
-Authoring or reviewing workflow definitions under `src/workflows/`.
+A workflow definition describes how items move from a trigger through downstream node steps. Items carry data in `item.json`; earlier outputs are available through `ctx.data`. Activations are batch-shaped but most node steps execute per-item. Every workflow definition finishes with `.build()`, which validates node ids and emits a `WorkflowDefinitionError` on collision or empty id.
 
-Do not use this skill for CLI-only troubleshooting or deep host architecture questions unless they directly affect workflow authoring.
+## When to use / when NOT
 
-## Discovering nodes and patterns
+Use this skill when authoring or reviewing workflow definitions under `src/workflows/`.
+Do not use for CLI-only troubleshooting or deep host architecture questions unless they directly affect workflow authoring.
 
-**Always call `find_examples` first** when you need to learn how to use a node or build a workflow pattern.
-
-### Why examples are the canonical reference
-
-Examples in the catalog typecheck, lint, and are verified by CI. They show the exact import paths, constructor signatures, and DSL shape that work in a real project — more efficiently than reading schema definitions or grepping framework source.
-
-### When to call `find_examples` first
-
-- Before writing any workflow that uses an unfamiliar node.
-- When you need a pattern (polling, branching, sub-workflow, agent with tools, etc.) and aren't sure of the exact API.
-- As your first step — before `read_skill`, before `search_capabilities`, before reading any file.
-
-### Query patterns
-
-Call `find_examples` in two ways:
-
-```ts
-// By node name:
-find_examples({ query: "HttpRequest" });
-find_examples({ query: "AIAgent" });
-find_examples({ query: "CronTrigger" });
-
-// By use case / intent:
-find_examples({ query: "poll API and write to database" });
-find_examples({ query: "AIAgent multi-step pipeline" });
-find_examples({ query: "gmail trigger classify email" });
-```
-
-Mix both: `find_examples({ query: "AIAgent gmail classify" })` works too.
-
-### Install state in results
-
-Every search result includes `installed: boolean` and `requiresInstall: string[]`. Use these to plan installs (`install_package`) before adapting an example. If `installed` is `false` or `requiresInstall` is non-empty, call `install_package` for each missing package before writing any workflow code that imports them.
-
-### When find_examples returns zero hits
-
-Stop. Do not improvise from memory. Do one of:
-
-1. **Ask the user**: "I don't have an example for `<query>`. Would you like me to adapt the closest match (`<nearest>`) or should a proper example be added first?"
-2. **Adapt the closest near-miss** — only with the user's explicit confirmation that the approach is reasonable.
-
-Do not attempt to infer node behavior by grepping framework source code (e.g. `node_modules/@codemation/*`). Examples convey the same information more efficiently and are authoritative.
-
-## When no example matches — the self-solving fallback chain
-
-If `find_examples` returns no good match for your query, **do not ask the user**. The user is non-technical and can't help you pick between framework primitives. Solve it using this fixed chain:
-
-### Tier 1 — Retry with intent variations
-
-Re-query with the underlying intent: a different verb, a more generic term, the closest standard pattern. Example: no hit for `"google sheets append row"` → retry `"http POST bearer credential"` or `"REST API call with credential"`.
-
-### Tier 2 — Custom REST node (preferred for HTTP APIs)
-
-If the task is "call an external HTTP API," use `defineRestNode`. Always works.
-
-`find_examples({ query: "defineRestNode" })` → returns the canonical templates:
-
-- `custom-rest-node-simple.example.ts` — basic shape
-- `custom-rest-node-with-credential.example.ts` — with bearer/OAuth credential slot
-
-Adapt these to the specific endpoint + payload shape needed.
-
-### Tier 3 — Raw HttpRequest (inline, one-off)
-
-If the call is one-shot inline in a workflow and you don't need to define a reusable node, use the `HttpRequest` config class.
-
-`find_examples({ query: "HttpRequest" })` → `node-httprequest.example.ts`
-
-### Tier 4 — defineNode (non-HTTP custom logic)
-
-If the task isn't an HTTP call (data transformation, business logic, anything stateful), use `defineNode`.
-
-`find_examples({ query: "defineNode template" })` → `custom-node-template.example.ts`
-
-### What NOT to do
-
-- Do NOT ask the user "should I use HttpRequest or defineRestNode?" — they can't help; pick using the chain.
-- Do NOT grep `node_modules/@codemation/*` for node implementations — the templates above are the canonical reference.
-- Do NOT invent a custom solution outside this chain.
-
-### Surfacing what you did
-
-After building, your final message to the concierge should state the technique used, e.g.:
-
-> "Built using `defineRestNode` for the Google Sheets append call (no first-class Sheets node yet)."
-
-This is informational, not a request for approval.
-
-## There are TWO authoring APIs — pick by trigger type
-
-| Trigger                                                     | API to use                                                         | Import                                                                                        | Available chain helpers                                                                      |
-| ----------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| **Manual** (one-shot, optionally seeded with default items) | `workflow("id").manualTrigger(...)`                                | `import { workflow } from "@codemation/host"`                                                 | Full fluent sugar: `.map`, `.if`, `.switch`, `.split`, `.agent`, `.node`, `.then`, `.build`  |
-| **Cron, Webhook, Test, or any non-manual trigger**          | `createWorkflowBuilder({ id, name }).trigger(new XxxTrigger(...))` | `import { createWorkflowBuilder, CronTrigger, WebhookTrigger } from "@codemation/core-nodes"` | Low-level `.then(new SomeNodeConfig(...))` only — **no** `.map`/`.if`/`.agent`/`.node` sugar |
-
-**Why two APIs?** `workflow("...")` returns a `WorkflowAuthoringBuilder` that _only_ exposes `.name()` and `.manualTrigger(...)`. Once you call `.manualTrigger(...)`, you get a `WorkflowChain` that has all the fluent helpers. For any other trigger, you must use the lower-level `createWorkflowBuilder({id, name}).trigger(new Trigger(...))` path — the result is a `ChainCursor` whose only chain method is `.then(new NodeConfig(...))`. You compose by passing node config classes directly: `new Callback(...)`, `new HttpRequest(...)`, `new AIAgent(...)`, `new If(...)`, `new Split(...)`, etc.
-
-If you find yourself wanting `.map` or `.if` on a cron workflow, you have two options: (a) accept the verbose `.then(new Callback(...))` style, or (b) wrap the cron-trigger cursor explicitly: `new WorkflowChain(builder.trigger(new CronTrigger(...)))` — but this is rare in practice; production cron workflows use plain `.then(new ConfigClass(...))`.
-
-## Core mental model
-
-1. A workflow definition describes how items move from a trigger through downstream steps.
-2. Activations are **batch-shaped** (`Items`); many steps use **per-item** execution (`execute`, including helper **`defineNode`**) with optional **`inputSchema`** and **`itemExpr`** on config fields. Batch reshape steps (split/filter/aggregate, **`defineBatchNode`**) work on the whole batch.
-3. Fluent callback helpers (manual-trigger only) follow the runtime item contract: `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` receive `(item, ctx)`. Row fields live under `item.json`; earlier completed outputs are available through `ctx.data`.
-4. Finish every workflow definition with `.build()`.
-
-## Authoring rules
-
-1. **Pick the API by trigger type** (see table above). Don't try to call `.trigger(...)` on the `workflow(...)` builder — it doesn't exist there.
-2. Keep workflow files focused on orchestration and named steps.
-3. Use custom nodes when a callback grows into reusable product logic.
-4. Distinguish **batch activations** from **per-item node bodies**: custom nodes from **`defineNode`** implement **`execute`** per item unless you chose **`defineBatchNode`** for batch **`run`**.
-5. **Collection nodes (`collectionInsertNode`, `collectionGetNode`, `collectionListNode`, etc.) use `.then(node.create(...))` instead of `.node(label, node, opts)`.** TypeScript's inference can't bridge the recursive `ParamDeep` constraint when the node config contains `z.record(...)` fields. See `node-collection-crud.example.ts` for the canonical pattern.
-
-## Node ids and stability
-
-Every node in a workflow definition has an `id`. When no explicit `id:` is given, `WorkflowBuilder` derives one by slugifying the node's `name` label: lowercase, non-alphanumeric runs replaced with `-`, trimmed. `"Send Email"` becomes `"send-email"`.
-
-`.build()` throws `WorkflowDefinitionError` if any node ends up with an empty id (blank label and no explicit `id`) or if two nodes share the same id. The check covers agent connection children (model + tools) as well.
-
-For nodes that hold credential bindings, the binding is keyed by `(workflowId, nodeId, slotKey)`. Renaming a node's label changes its slug-derived id and orphans the binding — the operator must re-attach the credential in the UI. Prefer stable labels or set an explicit `id:` on credential-using nodes:
+## Quickstart — pick API by trigger type
 
 ```ts
-.node("Send notification", SendEmailNodeConfig, {
-  id: "send-notification", // stable even if the label is later renamed
-  // ...
-})
-```
-
-### Collision gotcha — set explicit ids on every node
-
-Auto-derived ids can also **collide** when a trigger and a downstream node share a label. Example:
-
-```ts
-// ❌ Auto-derived ids collide: both slugify to "classify-feedback"
-workflow("wf.feedback")
-  .manualTrigger("Classify feedback", {
-    /* ... */
-  })
-  .agent("Classify feedback", {
-    /* ... */
+// Manual trigger — full fluent sugar (.map, .if, .switch, .agent, .node, .then)
+import { workflow } from "@codemation/host";
+export default workflow("wf.example")
+  .manualTrigger("Start", {
+    /* seed items */
   })
-  .build(); // throws WorkflowDefinitionError: duplicate nodeId "classify-feedback"
+  .map(/* ... */)
+  .build();
 
-// ✅ Explicit id on the AIAgent disambiguates
-workflow("wf.feedback")
-  .manualTrigger("Classify feedback", {
-    /* ... */
-  })
-  .agent("Classify feedback", { id: "classify-feedback-agent" /* ... */ })
+// Cron / webhook / any other trigger — low-level .then(new NodeConfig(...)) only
+import { createWorkflowBuilder, CronTrigger } from "@codemation/core-nodes";
+export default createWorkflowBuilder({ id: "wf.example", name: "Example" })
+  .trigger(new CronTrigger("Daily", { schedule: "0 9 * * *", timezone: "UTC" }))
+  .then(/* new SomeNodeConfig(...) */)
   .build();
 ```
 
-**Recommendation: always set an explicit `id:` on every node.** It's a few extra characters that buys you:
-
-1. Stable credential bindings across label renames (above)
-2. No collision build errors when refactoring labels
-3. Stable references for any downstream code that addresses nodes by id (e.g. pinned-output state, test-suite assertions, audit-log entries)
-
-The slug-derived default exists for quick prototyping; production workflows should declare ids.
-
-## Typical flow
+For full patterns — multi-step pipelines, branching, SubWorkflow, binary, agent tools, TestTrigger, and complete working examples — use your harness's example-discovery tool: `find_examples({ query: "..." })`. Useful queries: `"CronTrigger"`, `"if branch"`, `"AIAgent multi-step"`, `"SubWorkflow binary"`, `"TestTrigger assertion"`.
 
-**Manual trigger (fluent):**
+## Decision branches & gotchas
 
-1. `workflow("wf.example.id")`.
-2. `.name("Display name")` (optional — defaults to the id).
-3. `.manualTrigger("Start", { /* default item json */ })`.
-4. Chain transformations: `.map(...)`, `.if(...)`, `.switch(...)`, `.split(...)`, `.agent(...)`, `.node(...)`, `.then(...)`.
-5. `.build()`.
+**Two authoring APIs — pick by trigger type.** `workflow("id").manualTrigger(...)` returns a `WorkflowChain` with full fluent helpers (`.map`, `.if`, `.switch`, `.split`, `.agent`, `.node`). `createWorkflowBuilder({id, name}).trigger(new XxxTrigger(...))` returns a `ChainCursor` whose only chain method is `.then(new NodeConfig(...))`. Do NOT call `.trigger(...)` on the `workflow(...)` builder — it doesn't exist there.
 
-**Cron / webhook (low-level):**
+**Node ids and stability.** When no explicit `id:` is given, the engine slugifies the node's `name` label (lowercase, non-alphanumeric → `-`). `"Send Email"` → `"send-email"`. Nodes sharing credential bindings use `(workflowId, nodeId, slotKey)` as the binding key — renaming a label orphans the binding. **Set explicit `id:` on every credential-using node.** `.build()` throws `WorkflowDefinitionError` on empty or duplicate ids.
 
-1. `createWorkflowBuilder({ id: "wf.example.id", name: "Display name" })`.
-2. `.trigger(new CronTrigger("Label", { schedule, timezone }))` or `.trigger(new WebhookTrigger("Label", { endpointKey, methods }))`.
-3. Chain with `.then(new SomeNodeConfig(...))` repeatedly. Common configs: `Callback`, `HttpRequest`, `AIAgent`, `If`, `Split`, `Merge`, `SubWorkflow`.
-4. `.build()`.
+**Id collision pitfall.** A manual-trigger label and a downstream agent label that share the same string both slugify to the same id — `.build()` throws. Fix: add `id: "...-agent"` to disambiguate.
 
-## Built-in triggers
+**Collection nodes** use `.then(node.create(...))` instead of `.node(label, node, opts)` — TypeScript can't infer the `ParamDeep` constraint via the fluent helper. See `find_examples({ query: "collection crud" })`.
 
-- **`ManualTrigger`** — one-shot manual run, optionally seeded with default items. Use the fluent shortcut: `workflow("id").manualTrigger(name, items?)`. The shortcut internally wires up `createWorkflowBuilder(...).trigger(new ManualTrigger(...))` and wraps the result in `WorkflowChain` so you get the full fluent sugar.
-- **`WebhookTrigger`** — fires on an incoming HTTP request. Construct with `new WebhookTrigger(name, { endpointKey, methods })`. Attach via `createWorkflowBuilder({id, name}).trigger(new WebhookTrigger(...))`.
-- **`CronTrigger`** — fires on a cron schedule. Construct with `new CronTrigger(name, { schedule, timezone? })`. Attach via `createWorkflowBuilder({id, name}).trigger(new CronTrigger(...))`. The expression is validated at workflow build time. Each tick emits one item: `{ firedAt: string, scheduledFor: string }` (both ISO-8601). Defaults to UTC — always supply `timezone` for DST-sensitive schedules.
+**Install state in example results.** Every `find_examples` result includes `installed: boolean` and `requiresInstall: string[]`. If `installed` is `false` or `requiresInstall` is non-empty, call `install_package` for each missing package before writing any workflow code that imports them.
 
-## Agent tools (callable helpers)
+**When no example matches — self-solving fallback chain.**
 
-- For **inline** agent tools in workflow files (no separate `@tool()` class), use **`callableTool(...)`** from `@codemation/core`: supply `name`, Zod `inputSchema` / `outputSchema`, and `execute({ input, item, ctx, ... })`. **`CallableToolFactory.callableTool(...)`** is the same implementation if you prefer the factory style.
-- Prefer **plugin `Tool` classes** when the tool is reusable across packages; use **`AgentToolFactory.asTool(...)`** when exposing an existing runnable node to the agent.
+1. Retry with intent variations (different verb, more generic term).
+2. For HTTP APIs: `find_examples({ query: "defineRestNode" })` — covers basic and credential-slotted REST.
+3. For one-shot inline HTTP: `find_examples({ query: "HttpRequest" })`.
+4. For non-HTTP custom logic: `find_examples({ query: "defineNode template" })`.
+   Do NOT ask the user to pick between primitives — they can't help; use the chain. Do NOT grep `node_modules/@codemation/*` for node implementations — examples are authoritative. Surface the technique used in your reply.
 
-## Workflow agent authoring
+**Workflow testing.** Three built-in nodes from `@codemation/core-nodes`: `TestTrigger` (yields one item per test case), `IsTestRun` (routes `true`/`false` by `ctx.testContext`), `Assertion` (emits `AssertionResult[]`, sets `emitsAssertions: true`). See `references/workflow-testing.md` for authoring details.
 
-- Use `.agent(...)` for fluent workflow-defined agent steps.
-- Define agent messages with `messages`, not a workflow-specific prompt shortcut.
-- Use a static `messages` array for fixed prompts.
-- Use `itemExpr(...)` when agent messages depend on the current item.
-- Use fluent `.map((item, ctx) => ...)` when workflow data itself needs reshaping before the agent step.
-- `model` may be a provider string such as `"openai:gpt-4o-mini"` or a `ChatModelConfig`.
+**SubWorkflow binary.** `item.binary` slots pass transparently through SubWorkflow boundaries in both directions — no special config needed. Both runs share the same `BinaryStorage` singleton.
 
-## Workflow testing nodes
+**Verify your workflow.** Call `verify_workflow({ path: "src/workflows/my-workflow.ts" })` instead of running `pnpm typecheck` yourself. Returns `{ ok, data: { typecheck, lint, build, structure }, hint? }`.
 
-Codemation ships first-class **workflow tests**: each test case is one full workflow run, persisted with assertion records. Three nodes from `@codemation/core-nodes`:
+## Anti-patterns
 
-1. **`TestTrigger`** — drop alongside live triggers. Author callback `generateItems(ctx)` returns an `AsyncIterable<Item>`; the orchestrator dispatches one workflow run per yielded item with `executionOptions.testContext` set. `triggerKind: "test"` is set automatically — live activation skips it.
-2. **`IsTestRun`** — per-item router with `true` / `false` ports. Routes `true` iff `ctx.testContext` is set. Use it to skip side-effects in tests (don't actually send a real reply).
-3. **`Assertion`** — generic callback emitter; returns `AssertionResult[]`. Each result is `{ name, score: 0..1, passThreshold?, errored?, expected?, actual?, message?, details? }` — pass/fail derives from `score >= (passThreshold ?? 0.5)` (use `score: 1`/`0` for boolean checks, set `passThreshold` for continuous metrics, `errored: true` for assertion-code crashes). Each result becomes one emitted item on `main` and one persisted `TestAssertion` row when running inside a test. Sets `emitsAssertions: true` so the host persister identifies it.
-
-Authors invoke a TestSuiteRun from the canvas **Tests tab** or via `POST /api/workflows/:id/test-suite-runs`. The orchestrator caps concurrency (default 4, configurable per trigger) and aggregates results into `succeeded | failed | partial | cancelled | errored`.
-
-Custom nodes can also read `ctx.testContext?.{testSuiteRunId, testCaseIndex}` directly — useful for synthetic outputs in test mode without `IsTestRun` branching.
-
-## Binary slots across SubWorkflow boundaries
-
-`item.binary` (the map of named `BinaryAttachment` records) is carried transparently through SubWorkflow boundaries in both directions:
-
-- **Parent → child**: binary slots attached before the SubWorkflow node are visible inside the child run. `ctx.binary.openReadStream(attachment)` works in the child because both runs share the same `BinaryStorage`.
-- **Child → parent**: slots attached inside the child are returned with the item and visible in the parent's continuation nodes.
-
-This requires no special configuration in production — the shared `BinaryStorage` DI singleton is what makes cross-run byte reads possible.
-
-### SubWorkflow + binary example (manual trigger)
-
-```ts
-import { workflow } from "@codemation/host";
-import { Callback, SubWorkflow } from "@codemation/core-nodes";
-
-// Manual-trigger flow — uses the fluent `.map`/`.then` sugar.
-export default workflow("wf.parent")
-  .manualTrigger<{ url: string }>("Start", { url: "" })
-  // Attach a binary slot before the sub-workflow:
-  .map(async (item, ctx) => {
-    const att = await ctx.binary.attach({
-      name: "doc",
-      body: Buffer.from("..."),
-      mimeType: "application/pdf",
-      filename: "doc.pdf",
-    });
-    return ctx.binary.withAttachment(item, "doc", att);
-  })
-  // Sub-workflow receives item with binary["doc"] populated:
-  .then(new SubWorkflow("ParseDoc", { workflowId: "wf.child" }))
-  // Continuation: both parent "doc" slot and any child-added slots are visible here.
-  .map((item) => item)
-  .build();
-```
+- Do not call `.trigger(...)` on the `workflow(...)` manual builder — use `createWorkflowBuilder(...)` for non-manual triggers.
+- Do not rely on slug-derived node ids for production workflows with credential bindings — always set an explicit `id:`.
+- Do not improvise from memory when `find_examples` returns zero hits — use the fallback chain above.
 
 ## Read next when needed
 
-- Read `references/builder-patterns.md` for item-flow rules and fluent authoring patterns.
-- Read `references/workflow-testing.md` for TestTrigger / IsTestRun / Assertion authoring with full examples.
-- Read `references/complete-example.md` for a single dense end-to-end workflow example that exercises most authoring features (CronTrigger, map, if, agent, callableTool, itemExpr, ctx.data, ctx.binary, node with explicit id, build).
-
-## Verifying your workflow
-
-After writing or modifying a workflow file, call `verify_workflow({ path })` instead of running `pnpm typecheck` yourself. The tool runs typecheck + lint + DSL build + structure dump in one round-trip and returns a structured envelope:
-
-```ts
-verify_workflow({ path: "src/workflows/my-workflow.ts" });
-// → { ok: true, data: { typecheck: "ok", lint: "ok", build: "ok", structure: { id, name, trigger, nodes, edges, activation } } }
-// → { ok: false, error: "...", data: { typecheck: {...}, lint: {...}, build: {...}, structure: null }, hint: "..." }
-```
-
-A failed `ok: false` result includes a `hint` field that points at the specific fix needed. Fix the reported errors and call `verify_workflow` again — do not report done until `ok: true`.
+- `references/builder-patterns.md` — item-flow rules and fluent authoring patterns.
+- `references/workflow-testing.md` — TestTrigger / IsTestRun / Assertion with full examples.
+- `references/complete-example.md` — dense end-to-end example covering most authoring features.

package/skills/codemation-workspace-files/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: codemation-workspace-files
+description: ListWorkspaceFiles + ReadWorkspaceFile nodes — read files from the shared workspace pool. Covers read-by-filename (latest-wins), pinned fileId, binary slot handoff, and the raw-upload → concierge-digests → workflow-reads-derived-file pattern. Read before building any workflow that reads workspace files.
+compatibility: Codemation core-nodes-workspace-files. Requires WORKSPACE_ID and BLOB_STORAGE_* env vars.
+tags: workspace, files, binary, storage, read, csv, json
+uses: "@codemation/core-nodes-workspace-files"
+---
+
+# Codemation Workspace Files
+
+## Mental model
+
+Workflows **read** the shared workspace file pool; they do **not** write to it. Files are
+created and managed on the control-plane side (the Files UI, the concierge, the
+DocumentScanner). The framework's role is to provide `ListWorkspaceFiles` and
+`ReadWorkspaceFile` as pure read nodes.
+
+The **headline scenario** is: a user uploads a raw PDF; the concierge digests it into a
+structured JSON; the workflow reads the _derived JSON_, not the raw bytes. Workflows
+never touch raw uploads directly.
+
+## When to use / when NOT
+
+Use `ReadWorkspaceFile` when a workflow needs data that lives in the workspace pool
+(pricing sheets, config JSON, concierge-derived documents, CSV exports).
+
+Use `ListWorkspaceFiles` to discover what files exist or to drive a fan-out (one item per file).
+
+Do NOT use these nodes to write files — writing is CP-mediated and deferred to v2.
+
+Do NOT base64-encode bytes onto `item.json`. Binary payloads always flow through
+`item.binary` via `ctx.binary`.
+
+## Quickstart
+
+```ts
+import { readWorkspaceFileNode } from "@codemation/core-nodes-workspace-files";
+
+// Read the latest "pricing.csv" by name — picks up the newest upload automatically.
+readWorkspaceFileNode.create({ filename: "pricing.csv", binarySlot: "data" }, "Read pricing CSV", "read-pricing-csv");
+```
+
+```ts
+// Pin to an exact version — a later upload never changes what this reads.
+readWorkspaceFileNode.create(
+  { fileId: "abc123def456", binarySlot: "data" },
+  "Read pinned pricing CSV",
+  "read-pricing-pinned",
+);
+```
+
+For full patterns (parse the bytes, scenario walkthrough, list + filter), use your
+harness's example-discovery tool: `find_examples({ query: "workspace files" })`.
+
+## Resolution modes
+
+| Mode                      | Config                    | Behaviour                                                                                          |
+| ------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
+| **latest-wins** (default) | `filename: "pricing.csv"` | Reads the **newest** file with that name. Next upload of the same name is what the next run reads. |
+| **pinned fileId**         | `fileId: "abc123..."`     | Reads that exact, immutable version forever. A new upload never changes this ref.                  |
+
+Use **latest-wins** for "always use the current sheet" patterns.
+Use **pinned fileId** for reproducible/auditable runs (e.g., regression tests, compliance audits).
+
+## Binary slot handoff
+
+`ReadWorkspaceFile` streams the file's bytes into `item.binary[binarySlot]` (default `"data"`).
+The node emits:
+
+```ts
+{
+  fileId: string;
+  filename: string;
+  contentType: string;
+  size: number; // bytes
+  lastModified: string; // ISO 8601
+  binarySlot: string; // e.g. "data"
+}
+```
+
+Downstream nodes read the bytes via `ctx.binary.openReadStream(item.binary["data"])`.
+The bytes are **never** base64-encoded on `item.json`.
+
+## Concierge → digest → workflow pattern
+
+This is the intended headline flow:
+
+```
+User uploads PDF  →  CP Files UI stores it in the workspace pool
+Concierge sees upload  →  DocumentScanner digests it  →  writes "report-digested.json" back
+Workflow runs (schedule/webhook)  →  ReadWorkspaceFile("report-digested.json")  →  acts
+```
+
+The workflow is **decoupled** from the upload event. It reads the _derived_ file that the
+concierge produced, not the raw upload. The concierge's job is to bridge the raw-upload world
+and the structured-data world.
+
+Key boundaries:
+
+- **CP side (write)**: raw file ingest, concierge digest, derived file write, Files UI.
+- **Workflow side (read)**: `ReadWorkspaceFile` + `ListWorkspaceFiles` only.
+
+## Anti-patterns
+
+- Do NOT tell users to read the raw PDF upload in a workflow — point at the concierge-derived JSON.
+- Do NOT base64-encode file bytes onto `item.json` — use `item.binary[slot]` + `ctx.binary`.
+- Do NOT attempt to write a file from a workflow node — there is no write surface in v1.
+- Do NOT assume `WORKSPACE_ID` is always set — in local dev without CP integration, the storage
+  token resolves to `undefined`. Add a guard if your workflow runs in dev mode.
+
+## Node reference
+
+### `listWorkspaceFilesNode`
+
+```ts
+listWorkspaceFilesNode.create(
+  {
+    filenameFilter?: string; // optional substring match (case-insensitive)
+  },
+  "List files",
+  "list-files",
+)
+```
+
+Output per item: `{ fileId, filename, contentType, size, lastModified }`. Sorted newest-first.
+
+### `readWorkspaceFileNode`
+
+```ts
+readWorkspaceFileNode.create(
+  {
+    filename?: string;    // latest-wins resolution
+    fileId?: string;      // pinned resolution (takes precedence over filename)
+    binarySlot?: string;  // default: "data"
+    maxBytes?: number;    // default: 100 MiB — raise for large files
+  },
+  "Read file",
+  "read-file",
+)
+```
+
+Either `filename` or `fileId` must be set. Output: metadata JSON + bytes in `item.binary[binarySlot]`.