@codemation/agent-skills 0.1.10 → 0.3.0

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

@@ -1,88 +1,78 @@
 ---
 name: codemation-workflow-dsl
-description: Guides Codemation workflow authoring with the fluent Workflow DSL. Use when creating or updating `workflow("...")` definitions, triggers, `.map(...)`, `.node(...)`, branch flow, item handling, or `.build()` chains in `src/workflows`.
-compatibility: Designed for Codemation apps and plugins that author workflows with the fluent 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
 
-Use this skill for authoring or reviewing workflow definitions built with `workflow("...")`.
+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
 
-## Core mental model
+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.
 
-1. A workflow definition describes how items move from a trigger through downstream steps.
-2. The fluent authoring chain is the normal starting point for Codemation apps.
-3. Finish fluent workflow definitions with `.build()`.
-4. 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.
-5. Fluent callback helpers follow the runtime item contract: `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` receive `(item, ctx)`, so row fields live under `item.json` and earlier completed outputs are available through `ctx.data`.
-
-## Authoring rules
-
-1. Prefer the fluent `workflow(...)` chain for app-local workflow files.
-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`**.
-
-## 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
-  // ...
-})
+// 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 */
+  })
+  .map(/* ... */)
+  .build();
+
+// 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();
 ```
 
-## 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"`.
+
+## Decision branches & gotchas
 
-1. Start with `workflow("wf.example.id")`.
-2. Name the workflow with `.name(...)`.
-3. Add a trigger such as `.manualTrigger(...)` or `builder.trigger(new CronTrigger(...))`.
-4. Add transformations or nodes in execution order.
-5. End with `.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.
 
-## Built-in triggers
+**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.
 
-- **`ManualTrigger`** — one-shot manual run, optionally seeded with default items. Use `.manualTrigger(name, items?)` on the fluent builder.
-- **`WebhookTrigger`** — fires on an incoming HTTP request. Construct with `new WebhookTrigger(name, { endpointKey, methods })` and attach with `builder.trigger(...)`.
-- **`CronTrigger`** — fires on a cron schedule. Construct with `new CronTrigger(name, { schedule, timezone? })` and attach with `builder.trigger(...)`. 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.
+**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.
 
-## Agent tools (callable helpers)
+**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" })`.
 
-- 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.
+**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.
 
-## Workflow agent authoring
+**When no example matches — self-solving fallback chain.**
 
-- 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`.
+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 testing nodes
+**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.
 
-Codemation ships first-class **workflow tests**: each test case is one full workflow run, persisted with assertion records. Three nodes from `@codemation/core-nodes`:
+**SubWorkflow binary.** `item.binary` slots pass transparently through SubWorkflow boundaries in both directions — no special config needed. Both runs share the same `BinaryStorage` singleton.
 
-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.
+**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? }`.
 
-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`.
+## Anti-patterns
 
-Custom nodes can also read `ctx.testContext?.{testSuiteRunId, testCaseIndex}` directly — useful for synthetic outputs in test mode without `IsTestRun` branching.
+- 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.
+- `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-workflow-dsl/references/builder-patterns.md

@@ -1,13 +1,15 @@
+Load this when you need item-flow rules, the two-API decision, and fluent authoring patterns.
+
 # Builder Patterns
 
-## Standard workflow shape
+## Manual-trigger workflow (fluent — full sugar available)
 
 ```ts
+import { workflow } from "@codemation/host";
+
 export default workflow("wf.example.id")
   .name("Example")
-  .manualTrigger("Start", {
-    step: "start",
-  })
+  .manualTrigger("Start", { step: "start" })
   .map("Transform", (item, _ctx) => ({
     ...item.json,
     transformed: true,
@@ -15,27 +17,57 @@ export default workflow("wf.example.id")
   .build();
 ```
 
-## Cron-triggered workflow
+The `.map`, `.if`, `.switch`, `.split`, `.agent`, `.node`, `.then` helpers are available because `manualTrigger(...)` returns a `WorkflowChain`.
+
+## Cron-triggered workflow (low-level — `.then(new NodeConfig(...))` only)
 
 ```ts
-import { CronTrigger } from "@codemation/core-nodes";
+import { Callback, CronTrigger, createWorkflowBuilder } from "@codemation/core-nodes";
 
-export default workflow("wf.nightly.id")
-  .name("Nightly job")
+export default createWorkflowBuilder({
+  id: "wf.nightly.id",
+  name: "Nightly job",
+})
   .trigger(new CronTrigger("Nightly", { schedule: "0 3 * * *", timezone: "Europe/Amsterdam" }))
-  .map("Process tick", (item, _ctx) => ({
-    firedAt: (item.json as { firedAt: string }).firedAt,
-  }))
+  .then(
+    new Callback("Process tick", (items, _ctx) => {
+      // Callback receives the whole batch (Items), not a single item.
+      // For a cron trigger the batch is always one item: { firedAt, scheduledFor }.
+      return items.map((item) => ({ firedAt: (item.json as { firedAt: string }).firedAt }));
+    }),
+  )
   .build();
 ```
 
 The cron expression is validated at workflow build time. Each tick emits one item with `{ firedAt, scheduledFor }` ISO-8601 strings. Always supply `timezone` for DST-sensitive schedules — defaults to UTC.
 
-## Use the fluent DSL by default
+**Note:** non-manual triggers do NOT give you `.map(...)` / `.if(...)` / `.agent(...)` sugar. Compose with `.then(new Callback(...))`, `.then(new If(...))`, `.then(new AIAgent({...}))`, etc.
+
+## Webhook-triggered workflow
+
+```ts
+import { WebhookTrigger, createWorkflowBuilder, Callback } from "@codemation/core-nodes";
+
+export default createWorkflowBuilder({
+  id: "wf.webhook.example",
+  name: "Webhook example",
+})
+  .trigger(new WebhookTrigger("Incoming", { endpointKey: "inbound", methods: ["POST"] }))
+  .then(new Callback("Handle payload", (items) => items.map((it) => ({ received: it.json }))))
+  .build();
+```
+
+## Decision rule
+
+- **Manual one-shot trigger?** Use `workflow("id").manualTrigger(...)` — short, fluent, full sugar.
+- **Anything else?** Use `createWorkflowBuilder({ id, name }).trigger(new Trigger(...))` — verbose, node-config style.
+
+## Imports cheat sheet
 
-- import `workflow` from `@codemation/host`
-- keep the file under `src/workflows`
-- export the built workflow definition as the default export when following starter patterns
+- `workflow` → `@codemation/host` (re-exports from `@codemation/core-nodes`)
+- `createWorkflowBuilder`, `CronTrigger`, `WebhookTrigger`, `Callback`, `HttpRequest`, `AIAgent`, `If`, `Split`, `Merge`, `SubWorkflow` → `@codemation/core-nodes`
+- `callableTool`, `itemExpr` → `@codemation/core`
+- Workflow file location: `src/workflows/`. Export the built definition as the default export.
 
 ## Item rules
 

package/skills/codemation-workflow-dsl/references/complete-example.md

@@ -0,0 +1,263 @@
+Load this when you need to see a complete workflow that exercises most authoring features end-to-end.
+
+## The dense example (manual trigger — full fluent sugar)
+
+The fluent `.map`/`.if`/`.switch`/`.split`/`.agent`/`.node` helpers are only available after `.manualTrigger(...)`. The example below is a manual-trigger workflow so it can demonstrate all of them. For cron / webhook variants, see the snippet at the bottom.
+
+```ts
+// src/workflows/dailyCsvDigest.ts
+//
+// Theme: a manual-triggered "daily CSV digest". Caller passes { date: "YYYY-MM-DD" }.
+// The flow fetches that day's sales CSV from a reporting API, parses each row,
+// classifies rows with an LLM agent, and sends a per-row digest email.
+//
+// Register in codemation.config.ts:
+//   import dailyCsvDigest from "./src/workflows/dailyCsvDigest";
+//   workflows: [dailyCsvDigest]
+
+import { z } from "zod";
+import { callableTool, itemExpr } from "@codemation/core";
+import { HttpRequest } from "@codemation/core-nodes";
+import { workflow } from "@codemation/host";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type TriggerInput = { date: string }; // e.g. "2025-05-14"
+
+type FetchMeta = {
+  url: string;
+  ok: boolean;
+  status: number;
+  binarySlot: string;
+};
+
+type CsvRow = {
+  region: string;
+  product: string;
+  revenue: number;
+  anomaly: boolean;
+};
+
+type ClassifiedRow = CsvRow & {
+  classification: "normal" | "warning" | "critical";
+  rationale: string;
+};
+
+// ---------------------------------------------------------------------------
+// Inline callable tool — classify a single row
+// ---------------------------------------------------------------------------
+
+const classifyRowTool = callableTool({
+  name: "classify_row",
+  description: "Classify a revenue row as normal, warning, or critical.",
+  inputSchema: z.object({
+    region: z.string(),
+    product: z.string(),
+    revenue: z.number(),
+    anomaly: z.boolean(),
+  }),
+  outputSchema: z.object({
+    classification: z.enum(["normal", "warning", "critical"]),
+    rationale: z.string(),
+  }),
+  execute: async ({ input }) => {
+    // Fallback executor if the agent doesn't call the tool — keeps the workflow deterministic in tests.
+    const classification =
+      input.anomaly || input.revenue < 0 ? "critical" : input.revenue < 1000 ? "warning" : "normal";
+    return { classification, rationale: `Revenue ${input.revenue}, anomaly=${input.anomaly}` };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Workflow
+// ---------------------------------------------------------------------------
+
+export default workflow("wf.daily-csv-digest")
+  .name("Daily CSV Digest")
+  // Manual trigger seeded with a default date — callers can override at run time.
+  .manualTrigger<TriggerInput>("Start", { date: "2025-05-14" })
+
+  // ── Step 1: build the fetch URL ────────────────────────────────────────────
+  // async .map — use when you need await (date math here is sync, but the API call below is async).
+  .map("Build fetch URL", async (item, _ctx) => ({
+    date: item.json.date,
+    reportUrl: `https://reports.internal/sales/${item.json.date}.csv`,
+  }))
+
+  // HttpRequest with responseFormat:"binary" stores the body in ctx.binary automatically.
+  // Explicit id "fetch-report" keeps the credential binding stable across label renames.
+  .then(
+    new HttpRequest("Fetch report CSV", {
+      id: "fetch-report",
+      urlField: "reportUrl",
+      responseFormat: "binary",
+      responseBinarySlot: "csvFile",
+      credentialSlot: "reportApi",
+    }),
+  )
+
+  // ── Step 2: gate on HTTP success ───────────────────────────────────────────
+  // .if predicate receives (item, ctx). Use for fast boolean branches; .switch is overkill for two outcomes.
+  .if((item: { json: FetchMeta }, _ctx) => item.json.ok, {
+    true: (branch) =>
+      branch
+        // ── Step 3: parse CSV from binary ──────────────────────────────────────
+        // async .map — needs await to read from binary storage.
+        .map("Parse CSV rows", async (item: { json: FetchMeta }, ctx) => {
+          const stream = await ctx.binary.openReadStream(item.json.binarySlot);
+          const text = await streamToText(stream);
+          const rows = parseCsv(text);
+          return { rows, fetchedAt: item.json.url };
+        })
+
+        // .split emits one item per CSV row so downstream steps run per-row.
+        .split("Split rows", (item: { json: { rows: CsvRow[] } }) => item.json.rows)
+
+        // ── Step 4: classify each row with an agent ──────────────────────────
+        // itemExpr defers message construction to per-item runtime — required when content depends on the current item.
+        .agent("Classify row", {
+          model: "openai:gpt-4o-mini",
+          messages: itemExpr(({ item }: { item: { json: CsvRow } }) => [
+            { role: "system" as const, content: "You are a revenue analyst. Use classify_row." },
+            { role: "user" as const, content: JSON.stringify(item.json) },
+          ]),
+          tools: [classifyRowTool],
+          outputSchema: z.object({
+            classification: z.enum(["normal", "warning", "critical"]),
+            rationale: z.string(),
+          }),
+        })
+
+        // ── Step 5: merge agent output with the original row via ctx.data ──────
+        // ctx.data is keyed by node id (the slug of the node label).
+        // "Split rows" slugs to "split-rows"; we read its emitted item back here.
+        // sync .map — pure object merge, no I/O.
+        .map("Enrich classification", (item: { json: { classification: string; rationale: string } }, ctx) => {
+          const originalRow = ctx.data["split-rows"]?.items?.[0]?.json as CsvRow | undefined;
+          return {
+            ...originalRow,
+            classification: item.json.classification as ClassifiedRow["classification"],
+            rationale: item.json.rationale,
+          } satisfies Partial<ClassifiedRow>;
+        })
+
+        // ── Step 6: send digest email via a registered node ───────────────────
+        // .node(name, config, options) — explicit id keeps credential binding stable.
+        // SendEmailNodeConfig is illustrative; replace with the email node available in your project.
+        .node(
+          "Send digest email",
+          new SendEmailNodeConfig({
+            // itemExpr on a config field — engine resolves once per item at execution time.
+            subject: itemExpr(
+              ({ item }: { item: { json: Partial<ClassifiedRow> } }) =>
+                `[${item.json.classification?.toUpperCase()}] ${item.json.region} – ${item.json.product}`,
+            ),
+            to: "ops-team@example.com",
+            body: itemExpr(
+              ({ item }: { item: { json: Partial<ClassifiedRow> } }) =>
+                `Region: ${item.json.region}\nRevenue: ${item.json.revenue}\nRationale: ${item.json.rationale}`,
+            ),
+          }),
+          { id: "send-digest-email" },
+        ),
+
+    false: (branch) =>
+      branch.map("Log fetch failure", (item: { json: FetchMeta }, _ctx) => ({
+        error: `Fetch failed: HTTP ${item.json.status}`,
+        url: item.json.url,
+      })),
+  })
+
+  // .build() validates non-empty + unique node ids (including agent connection children).
+  // Throws WorkflowDefinitionError on violation.
+  .build();
+
+// ---------------------------------------------------------------------------
+// Helpers (inline for brevity — promote to lib/ if reused)
+// ---------------------------------------------------------------------------
+
+async function streamToText(stream: AsyncIterable<Uint8Array>): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+function parseCsv(text: string): CsvRow[] {
+  const [header, ...lines] = text.trim().split("\n");
+  const cols = header!.split(",");
+  return lines.map((line) => {
+    const vals = line.split(",");
+    return {
+      region: vals[cols.indexOf("region")] ?? "",
+      product: vals[cols.indexOf("product")] ?? "",
+      revenue: Number(vals[cols.indexOf("revenue")] ?? 0),
+      anomaly: vals[cols.indexOf("anomaly")] === "true",
+    };
+  });
+}
+```
+
+## What this exercises
+
+- **Manual trigger with typed default item** → `workflow("...").manualTrigger<TriggerInput>("Start", {...})`
+- **sync `.map`** → "Enrich classification" — pure object merge, no `await`
+- **async `.map`** → "Build fetch URL" and "Parse CSV rows" — uses `await` for binary read
+- **`.if` per-item predicate** → `(item, _ctx) => item.json.ok` with branch factories
+- **`HttpRequest` with explicit `id:`** → `id: "fetch-report"` (credential binding stability)
+- **`.split`** → fan-out one batch into many items
+- **`.agent(...)` with `messages`, `model`, `tools`, `outputSchema`** → typed structured output
+- **`callableTool` with Zod schemas and `execute({ input })`** → inline tool definition
+- **`itemExpr(...)`** → on agent messages (per-item content) and on `.node` config fields (per-item subject/body)
+- **`.node(name, config, options)` with explicit id** → stable credential binding
+- **`ctx.data["<slug>"]`** → reading earlier node output without threading it through every step
+- **`ctx.binary.openReadStream(slot)`** → reading bytes from a binary slot attached upstream
+- **`.build()`** → final validation pass
+
+## Cron / webhook variant (alternative trigger)
+
+When the trigger isn't manual, the fluent `.map`/`.if`/`.agent` sugar isn't available — you use the lower-level builder and `.then(new SomeNodeConfig(...))`. Shape:
+
+```ts
+import { Callback, CronTrigger, createWorkflowBuilder, HttpRequest } from "@codemation/core-nodes";
+
+export default createWorkflowBuilder({
+  id: "wf.daily-csv-digest.cron",
+  name: "Daily CSV Digest (cron)",
+})
+  .trigger(new CronTrigger("Daily 06:00", { schedule: "0 6 * * *", timezone: "UTC" }))
+  // Cron fires one item per tick: { firedAt, scheduledFor }. Wrap downstream logic in Callback configs:
+  .then(
+    new Callback("Build fetch URL", (items, _ctx) => {
+      return items.map((item) => {
+        const date = new Date((item.json as { scheduledFor: string }).scheduledFor).toISOString().slice(0, 10);
+        return { date, reportUrl: `https://reports.internal/sales/${date}.csv` };
+      });
+    }),
+  )
+  .then(
+    new HttpRequest("Fetch report CSV", {
+      id: "fetch-report",
+      urlField: "reportUrl",
+      responseFormat: "binary",
+      responseBinarySlot: "csvFile",
+      credentialSlot: "reportApi",
+    }),
+  )
+  // For branching, use `new If(...)`. For per-item agent calls, use `new AIAgent({...})`.
+  // For row fan-out, use `new Split(...)`. The execution semantics match the fluent helpers
+  // — only the surface syntax differs.
+  .build();
+```
+
+If you need both cron + the fluent sugar in the same workflow, you can wrap the cursor manually:
+
+```ts
+import { WorkflowChain } from "@codemation/core-nodes";
+
+const cursor = createWorkflowBuilder({ id, name }).trigger(new CronTrigger("Tick", { schedule: "..." }));
+export default new WorkflowChain(cursor).map("First step", (item) => ({ ...item.json })).build();
+```
+
+This is uncommon in production code; reach for it only when the fluent helpers genuinely help readability.