@codemation/agent-skills 0.1.9 → 0.2.0

package/skills/codemation-framework-concepts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codemation-framework-concepts
-description: Explains Codemation package boundaries, runtime concepts, observability shape, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, telemetry, or runtime modes.
+description: Explains Codemation package boundaries, runtime concepts, observability shape, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, telemetry, or runtime modes. Read this first when starting any Codemation task — it points at the right skill for the work.
 compatibility: Designed for Codemation apps, plugins, and framework contributors.
 ---
 
@@ -30,6 +30,7 @@ Do not use this skill as a substitute for detailed CLI, workflow DSL, or plugin
 - activation is framework-managed and happens in the UI
 - telemetry is observability-first: traces, spans, artifacts, and metric points are framework-owned runtime data
 - run retention and telemetry retention can differ, so trend data can outlive raw run state
+- **workflow testing** is a first-class primitive: a `TestTrigger` node yields one item per test case, the orchestrator dispatches a workflow run per case with `executionOptions.testContext` set, and `Assertion` nodes (`emitsAssertions: true`) record per-run results into `TestAssertion` rows; the canvas exposes a Tests tab parallel to Live and Executions
 
 ## Runtime rule of thumb
 
@@ -38,6 +39,16 @@ Do not use this skill as a substitute for detailed CLI, workflow DSL, or plugin
 3. Keep workflow code stable while the runtime shape grows around it.
 4. Treat telemetry as part of the runtime contract, not as ad-hoc node-local logging.
 
+## Where to go next
+
+- Authoring workflows → `codemation-workflow-dsl`
+- Building a reusable node → `codemation-custom-node-development`
+- Building a credential type → `codemation-credential-development`
+- Packaging as a plugin → `codemation-plugin-development`
+- Calling an MCP server from a workflow → `codemation-mcp-capabilities`
+- CLI commands / dev loop → `codemation-cli`
+
 ## Read next when needed
 
 - Read `references/architecture-map.md` for package ownership and runtime-mode guidance.
+- Use the `codemation-workflow-dsl` skill (and its `references/workflow-testing.md`) for hands-on test authoring with TestTrigger / IsTestRun / Assertion.

package/skills/codemation-mcp-capabilities/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: codemation-mcp-capabilities
+description: Discover MCP servers registered on the Codemation control plane. Use before authoring agent workflows that reference mcpServers to find available server ids and their credential requirements.
+compatibility: Requires an installation paired with a connected control plane (Sprint 2+).
+---
+
+# Codemation MCP Capabilities
+
+## Use this skill when
+
+Use this skill before writing `agent({ mcpServers: ["..."] })` to discover what server ids are
+available and what credential types they require. Without it, you'd have to guess server ids or
+ask the user.
+
+## How to search
+
+Call `GET /api/registry/capabilities?query=<search term>` on the control-plane API.
+The endpoint is session-authenticated (the control-plane session cookie is forwarded automatically
+when called from within the workspace's paired context).
+
+```
+GET /api/registry/capabilities?query=gmail
+```
+
+Response shape (array of capability objects):
+
+```json
+[
+  {
+    "kind": "mcp-server",
+    "id": "gmail",
+    "displayName": "Gmail",
+    "description": "Read, send, and manage Gmail messages and labels.",
+    "acceptedCredentialTypes": ["oauth.google.gmail"]
+  }
+]
+```
+
+An empty query string returns all registered servers.
+
+## Response fields
+
+| Field                    | Type     | Notes                                                                 |
+| ------------------------ | -------- | --------------------------------------------------------------------- |
+| `kind`                   | string   | Always `"mcp-server"` for now. Future: `"node"`, `"credential-type"` |
+| `id`                     | string   | Stable slug — add this string to the agent's mcpServers array         |
+| `displayName`            | string   | Human-readable name for UI or explanations                            |
+| `description`            | string   | What the server does                                                  |
+| `acceptedCredentialTypes`| string[] | Credential type ids accepted by this server (empty = no credential)   |
+
+## Credential types
+
+- **`"oauth.google.gmail"`** — user must connect a Google account credential instance via the
+  credential dialog before the workflow runs. The same credential instance can be shared between
+  a `GmailTrigger` node and the Gmail MCP server.
+- **`"bearer_token"`** etc. — user configures a static credential via the credential dialog.
+- **empty array** — no credential required. The server is usable immediately.
+
+## Using results in workflow config
+
+The `id` field from the response is added to the agent's `mcpServers` array. Each entry
+surfaces a credential slot on the materialized MCP connection node (same shape as
+ChatModel and Tool connection nodes); the user picks a specific credential instance via
+the canvas credential dropdown — same flow as a trigger credential. A user may have
+multiple instances of the same type (personal vs work Gmail); the dropdown surfaces all
+matching instances.
+
+```ts
+new AIAgent({
+  name: "Gmail reader",
+  mcpServers: ["gmail"],
+  // ...
+});
+```
+
+Bind the credential instance via the UI before activation; there is no inline credential
+field on the workflow definition.
+
+## Example flow
+
+1. User asks: "Build a workflow that reads Gmail and summarises unread messages."
+2. Call `GET /api/registry/capabilities?query=gmail` → find `id: "gmail"`, `acceptedCredentialTypes: ["oauth.google.gmail"]`.
+3. Report back: "Gmail MCP is available. The user will need to bind a `oauth.google.gmail` credential instance."
+4. In the workflow, use `mcpServers: ["gmail"]`.
+5. The user binds their credential instance via the canvas credential dropdown before activating.

package/skills/codemation-mcp-capabilities/references/agent-with-mcp.ts

@@ -0,0 +1,44 @@
+/**
+ * Reference: using an MCP server in a workflow agent node.
+ *
+ * Before writing this, call GET /api/registry/capabilities?query=<name> to confirm
+ * the server id and credential type. Then list the server id under `mcpServers`.
+ *
+ * Cron / webhook workflows use createWorkflowBuilder({id, name}).trigger(new XxxTrigger(...))
+ * and chain with .then(new SomeNodeConfig(...)). The fluent .map/.if/.agent helpers are
+ * only available via workflow("id").manualTrigger(...). See codemation-workflow-dsl skill.
+ *
+ * `mcpServers` is a plain array of server ids. Each declared server surfaces a credential
+ * slot on the materialized MCP connection node (same shape as ChatModel/Tool connection
+ * nodes). The user binds a credential instance via the canvas credential dropdown before
+ * activation — same flow as trigger credentials.
+ */
+
+import { AIAgent, CronTrigger, createWorkflowBuilder } from "@codemation/core-nodes";
+
+// Example: cron-triggered agent that uses the Gmail MCP server.
+// The "gmail" id comes from the registry (acceptedCredentialTypes: ["oauth.google.gmail"]).
+// The user must have connected their Google account and bound the credential before this runs.
+
+export const summariseEmailsWorkflow = createWorkflowBuilder({
+  id: "wf.summarise-emails",
+  name: "Summarise unread emails",
+})
+  .trigger(new CronTrigger("Weekdays at 09:00", { schedule: "0 9 * * 1-5", timezone: "UTC" }))
+  .then(
+    new AIAgent({
+      name: "Summarise",
+      mcpServers: ["gmail"],
+      messages: [
+        {
+          role: "system",
+          content: [
+            "You are an email assistant. Read the user's unread Gmail messages from the last 24 hours.",
+            "Summarise each one in one sentence. Output as a bullet list.",
+            "Do not draft or send any replies.",
+          ].join("\n"),
+        },
+      ],
+    }),
+  )
+  .build();

package/skills/codemation-plugin-development/SKILL.md

@@ -45,6 +45,49 @@ Do not use this skill for ordinary consumer workflow-only changes unless the wor
 
 Import **`WorkflowTestKit`** from **`@codemation/core/testing`**. Use **`registerDefinedNodes([...])`** for `defineNode` packages, then **`runNode({ node: yourNode.create(...), items })`** or **`run({ workflow, items })`** for fuller graphs. Prefer this for fast node tests; use **`codemation dev:plugin`** when you need the UI and persistence.
 
+## Declaring MCP servers from a plugin (`mcpServers?`)
+
+A plugin can declare MCP servers that the framework merges into its in-memory catalog at startup. Use this for providers that need non-standard auth, custom adapter logic, or are shipping alongside custom nodes. For standard SaaS providers (OAuth via broker, plain bearer/API key), prefer the control-plane registry instead — no plugin code required.
+
+### When to use plugin-declared MCP servers
+
+- The provider's MCP server has non-standard auth the generic credential types cannot express.
+- The plugin already ships custom nodes for the same provider and wants to co-locate the MCP declaration.
+- Self-hosted deployments where no control-plane registry is available.
+
+### Required fields
+
+```ts
+import { definePlugin } from "@codemation/host/authoring";
+import type { McpServerDeclaration } from "@codemation/core";
+
+const myServer: McpServerDeclaration = {
+  id: "my-service", // globally unique slug: /^[a-z0-9-]+$/
+  displayName: "My Service",
+  description: "Provides MCP tools for My Service.",
+  transport: "http",
+  url: "https://mcp.my-service.com",
+  // Credential types this server accepts. Users bind a credential instance
+  // per slot via the UI. Omit (or set to []) for servers requiring no auth.
+  acceptedCredentialTypes: ["my-service.bearer-token"],
+};
+
+export default definePlugin({
+  mcpServers: [myServer],
+  // credentials, nodes, register, etc.
+});
+```
+
+### Merge precedence
+
+The framework merges from three sources in this order (last-write-wins on `id` collisions):
+
+1. **Plugin** (lowest) — code in `codemation.plugin.ts`
+2. **`codemation.config.ts`** — dev/self-host declarations
+3. **Control-plane registry** (highest) — managed-mode fast lane; shadows plugin declarations to fix descriptions without a plugin release
+
+A warning is logged when a higher-priority source shadows a plugin declaration. This is intentional.
+
 ## Read next when needed
 
 - Read `references/plugin-structure.md` for package layout and node-versus-credential guidance.

package/skills/codemation-plugin-development/references/plugin-structure.md

@@ -33,6 +33,37 @@ That file is the plugin repository's source composition root. Consumers should d
 - start with `defineCredential(...)`
 - build typed sessions in `createSession(...)`
 - implement `test(...)` so operators can validate configuration before activation
+- for OAuth2 redirect flows, use the URL-template variant (`auth: { kind: "oauth2", providerId, authorizeUrl, tokenUrl, scopes }`) with `{publicFieldKey}` placeholders — no core or host edits needed per provider. See the credential-development skill for details.
+
+## Binary payloads — never put bytes on the item JSON
+
+**Rule:** if a node produces or fetches binary content (file attachments, image bytes, audio, PDFs, downloads, etc.), the bytes go through the framework's binary storage via `ctx.binary.attach(...)`. They MUST NOT be placed on the item's JSON payload.
+
+The runtime persists each item's JSON into the runs table for telemetry, replay, and debugging. Putting megabyte-scale base64 strings in there bloats the database, slows queries, and makes telemetry unreadable. The binary system exists exactly for this: blobs live in object storage; the item JSON only carries a `BinaryAttachment` reference (`{ id, storageKey, mimeType, size, ... }`) under `item.binary[<slot-name>]`.
+
+```ts
+// Inside execute(items, ctx) on a node that has fetched a file:
+const stored = await ctx.binary.attach({
+  name: "report.pdf", // slot name (also the key under item.binary)
+  body: Buffer.from(bytes), // Buffer / Uint8Array / Readable
+  mimeType: "application/pdf",
+  filename: "report.pdf", // hint for downloads
+});
+const enriched = ctx.binary.withAttachment(item, "report.pdf", stored);
+```
+
+Notes:
+
+- Attachment **metadata** (id, name, contentType, size) belongs on the item JSON — it is small and useful for branching. Only the **bytes** must go through `ctx.binary`.
+- For triggers, fetch metadata cheaply in `runCycle` (e.g. Graph's `$expand=attachments($select=id,name,contentType,size)`) and defer the byte download to `execute()` so persisted run state stays tiny on every poll.
+- Two attachments with the same filename within one item collide on `item.binary[name]`; suffix the slot name (`report-2.pdf`) to keep both.
+
+## Polling-trigger guidance
+
+- the engine ships a generic polling-trigger runtime in `@codemation/core` exposed via `ctx.polling` on the trigger setup context
+- call `ctx.polling.start({ intervalMs, runCycle })` from your trigger node's `setup()` — the runtime handles the loop, overlap guard, dedup window (`ctx.polling.dedup.merge(...)`), state persistence, and cleanup
+- on the first cycle, baseline-skip (record current ids, emit nothing) so the workflow does not flood with the existing backlog when the trigger is first set up
+- implement `TestableTriggerNode.getTestItems(ctx)` to power the workflow UI's **Test** button — return the most recent N items without consulting or mutating polling state, so users can preview live data without waiting
 
 ## Publishability
 

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

@@ -1,39 +1,202 @@
 ---
 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.
 ---
 
 # Codemation Workflow DSL
 
 ## Use this skill when
 
-Use this skill for authoring or reviewing workflow definitions built with `workflow("...")`.
+Authoring or reviewing workflow definitions under `src/workflows/`.
 
 Do not use this skill for CLI-only troubleshooting or deep host architecture questions unless they directly affect workflow authoring.
 
+## Discovering nodes and patterns
+
+**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. 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`.
+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. Prefer the fluent `workflow(...)` chain for app-local workflow files.
+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:
+
+```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", {
+    /* ... */
+  })
+  .build(); // throws WorkflowDefinitionError: duplicate nodeId "classify-feedback"
+
+// ✅ Explicit id on the AIAgent disambiguates
+workflow("wf.feedback")
+  .manualTrigger("Classify feedback", {
+    /* ... */
+  })
+  .agent("Classify feedback", { id: "classify-feedback-agent" /* ... */ })
+  .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
 
-1. Start with `workflow("wf.example.id")`.
-2. Name the workflow with `.name(...)`.
-3. Add a trigger such as `.manualTrigger(...)`.
-4. Add transformations or nodes in execution order.
-5. End with `.build()`.
+**Manual trigger (fluent):**
+
+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()`.
+
+**Cron / webhook (low-level):**
+
+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()`.
+
+## Built-in triggers
+
+- **`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.
 
 ## Agent tools (callable helpers)
 
@@ -49,6 +212,67 @@ Do not use this skill for CLI-only troubleshooting or deep host architecture que
 - 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`.
 
+## Workflow testing nodes
+
+Codemation ships first-class **workflow tests**: each test case is one full workflow run, persisted with assertion records. Three nodes from `@codemation/core-nodes`:
+
+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();
+```
+
 ## 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`.

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,21 +17,80 @@ export default workflow("wf.example.id")
   .build();
 ```
 
-## Use the fluent DSL by default
+The `.map`, `.if`, `.switch`, `.split`, `.agent`, `.node`, `.then` helpers are available because `manualTrigger(...)` returns a `WorkflowChain`.
 
-- import `workflow` from `@codemation/host`
-- keep the file under `src/workflows`
-- export the built workflow definition as the default export when following starter patterns
+## Cron-triggered workflow (low-level — `.then(new NodeConfig(...))` only)
+
+```ts
+import { Callback, CronTrigger, createWorkflowBuilder } from "@codemation/core-nodes";
+
+export default createWorkflowBuilder({
+  id: "wf.nightly.id",
+  name: "Nightly job",
+})
+  .trigger(new CronTrigger("Nightly", { schedule: "0 3 * * *", timezone: "Europe/Amsterdam" }))
+  .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.
+
+**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
+
+- `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
 
 - workflow data flows as items
-- items usually carry `json` data and optional `binary` data
+- items usually carry `json` data and optional `binary` data (**storage-backed attachments** via node **`ctx.binary.attach`**, not huge base64 strings in **`json`** — base64 in **`json`** inflates the persisted run payload in the DB; binaries stay as **references**)
 - runtime nodes receive batches of items, not just one record
 - author workflow steps with batching in mind
 - fluent `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` callbacks receive `(item, ctx)`
 - read row fields from `item.json` and earlier completed outputs from `ctx.data`
 
+## Node id assignment
+
+When no `id:` is provided, the builder slugifies the node's `name` label: lowercase, non-alphanumeric runs replaced with `-`, leading/trailing `-` stripped. Two nodes with the same effective label produce the same slug and `.build()` throws `WorkflowDefinitionError`. Fix: provide a unique `id:` on the colliding node configs.
+
+Credential bindings are stored as `(workflowId, nodeId, slotKey)`. Changing a node's label changes its slug-derived id and the binding appears unbound. For credential-using nodes, either keep the label stable or set an explicit `id:`:
+
+```ts
+.node("Send email", SendEmailNodeConfig, {
+  id: "send-email", // stable even after a label rename
+  credentials: { smtp: mySmtpCredential },
+})
+```
+
 ## When to move beyond callbacks
 
 Promote inline callbacks into custom nodes when: