@codemation/agent-skills 0.3.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/agent-skills",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "Reusable agent skills for Codemation projects and plugin development.",
   "publishConfig": {
     "access": "public"
@@ -51,6 +51,8 @@
     "changeset:verify": "pnpm --workspace-root run changeset:verify",
     "build": "pnpm build:metadata",
     "build:metadata": "tsx ../../tooling/discovery/scripts/extract-metadata.ts",
+    "typecheck": "node scripts/verify-skill-code.mjs",
+    "verify-skills": "node scripts/verify-skill-code.mjs",
     "test": "vitest run",
     "test:unit": "vitest run"
   }

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

@@ -0,0 +1,314 @@
+---
+name: ai-agent
+description: Add an LLM step to a workflow with the AIAgent node — classification, extraction, drafting, or tool-using reasoning. It runs one chat completion per item and emits the model's reply on its port. Read this when a step needs an LLM (and prefer a plain Callback when the logic is deterministic).
+compatibility: Designed for Codemation workflows authored with @codemation/core-nodes.
+tags: agent, llm, ai, aiagent, classification, extraction
+uses: "@codemation/core-nodes, @codemation/core"
+---
+
+# Codemation AI Agent Node
+
+`AIAgent` is the single building block for any LLM step in a workflow. It receives items, runs one chat completion **per item** using the configured `chatModel` and `messages`, and emits the result on its `main` port — always exactly one output item per input item (it never fans out or filters). Reach for it when a step needs an LLM: classification, extraction, summarisation, drafting, or a decision. For deterministic logic use a plain `Callback` instead (cheaper, faster, no LLM billing). See `workflow-dsl` for the surrounding workflow chain.
+
+## The node — one-liner
+
+`AIAgent<TInput, TOutput>` takes an options object. `messages` are `{ role, content }` lines; `content` is a string or a function `({ item, itemIndex, items, ctx }) => string`. Parameterise the generics so `item.json` is typed inside the content callbacks.
+
+```typescript
+import { AIAgent, CodemationChatModelConfig } from "@codemation/core-nodes";
+
+type Mail = { body: string };
+
+// No outputSchema → output shape is NON-DETERMINISTIC: JSON.parse succeeds → the parsed object;
+// JSON.parse fails → { output: string }. Always set outputSchema (see below).
+const classify = new AIAgent<Mail>({
+  name: "Classify email",
+  id: "classify-email",
+  messages: [
+    { role: "system", content: "Classify the email as spam or not-spam. Reply with one word." },
+    { role: "user", content: ({ item }) => item.json.body },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "low"),
+});
+```
+
+## chatModel — managed is the default
+
+**Managed (default — no API key needed):** `CodemationChatModelConfig(label, complexity)`. The LLM broker auto-authenticates via the workspace HMAC pairing — no API key, no credential slot, no user setup. Do **not** tell managed users to "get an API key". The first argument is just a **neutral display label** for the node (e.g. `"Managed AI"`) — never put a provider or model name (`"Claude"`, `"GPT"`, …) in it, because the framework does **not** choose the provider: the broker does, from the complexity token. The second argument is that **complexity token** (`"low" | "medium" | "high" | "xhigh"`), **not** a model id — the broker maps the token to a concrete provider model and thinking effort. Never hard-code a model id; there is no live list to discover and no endpoint to call.
+
+```typescript
+import { CodemationChatModelConfig } from "@codemation/core-nodes";
+
+const cheap = new CodemationChatModelConfig("Managed AI", "low");
+```
+
+**BYOK (self-hosted / non-managed only):** `OpenAIChatModelConfig(label, modelId, slotKey)` — it creates a credential slot the operator must bind with an API key. Only use this where no managed broker is available; in managed mode it prompts the user to bind a key they don't need.
+
+```typescript
+import { OpenAIChatModelConfig } from "@codemation/core-nodes";
+
+const gpt = new OpenAIChatModelConfig("OpenAI", "gpt-4.1-mini", "openai"); // creates a bindable "openai" slot
+```
+
+`chatModel` does **not** accept a plain string — pass a config instance.
+
+## Structured output and the downstream shape
+
+Without `outputSchema` the output shape is **non-deterministic**: internally `AgentOutputFactory.fromAgentContent` does `JSON.parse(content)` — if that succeeds the output json is the parsed object; if it throws (plain-text reply) the fallback is `{ output: content }`. This means you can't reliably read `item.json.output` unless you also own the prompt.
+
+**Prefer `outputSchema` — read typed fields directly; do NOT hand-parse `output`.** With `outputSchema` (a Zod object) the model is instructed to reply with structured JSON, the response is validated and parsed, and the output json **is the parsed object** — read its fields directly (`item.json.sentiment`, not `item.json.output`). Match the `AIAgent<TInput, TOutput>` second generic to the schema so the downstream node is correctly typed.
+
+```typescript
+import { z } from "zod";
+import { AIAgent, CodemationChatModelConfig } from "@codemation/core-nodes";
+
+type Feedback = { text: string };
+const VerdictSchema = z.object({
+  sentiment: z.enum(["positive", "neutral", "negative"]),
+  topic: z.string(),
+});
+type Verdict = z.infer<typeof VerdictSchema>;
+
+// outputSchema → output json IS the parsed object; read item.json.sentiment / item.json.topic directly.
+new AIAgent<Feedback, Verdict>({
+  name: "Classify feedback",
+  id: "classify-feedback",
+  messages: [
+    { role: "system", content: 'Reply with strict JSON {"sentiment","topic"}.' },
+    { role: "user", content: ({ item }) => item.json.text },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "low"),
+  outputSchema: VerdictSchema,
+  guardrails: { maxTurns: 2 },
+});
+// Downstream reads item.json.sentiment / item.json.topic — `output` does not exist when a schema is set.
+```
+
+## Tools and MCP servers
+
+An `AIAgent` becomes a reasoning loop when it has **tools**. The model calls tools mid-turn; `guardrails.maxTurns` caps the loop. Three tool kinds, in priority order:
+
+### (a) Node-backed tools — `AgentToolFactory.asTool` (preferred for Codemation integrations)
+
+Wrap any Codemation node as an agent tool so the real node does the ERP/service RPC — not a hand-rolled `execute` body. The node config carries the static parts (model, fields); `mapInput` maps the agent's tool-call args to the node's item input; `mapOutput` maps the node's output back to the tool result. Use `onRejected: "halt"` for HITL nodes (e.g. `inboxApproval`).
+
+```typescript
+import { AIAgent, CodemationChatModelConfig, inboxApproval } from "@codemation/core-nodes";
+import { AgentToolFactory, callableTool } from "@codemation/core";
+import { z } from "zod";
+
+type AnalysisInput = { text: string };
+
+// (a) Node-backed: wrap inboxApproval so the agent can escalate to a human.
+const escalateToHuman = AgentToolFactory.asTool(
+  inboxApproval.create(
+    {
+      title: ({ item }: { item: { json: unknown } }) => String((item.json as { title?: unknown }).title ?? "Review"),
+      body: ({ item }: { item: { json: unknown } }) => String((item.json as { body?: unknown }).body ?? ""),
+      priority: "normal",
+      timeout: "8h",
+      onTimeout: "halt",
+    },
+    "Human escalation",
+  ),
+  {
+    name: "escalate_to_human",
+    description: "Pause and ask a human reviewer to approve or reject. Halt if rejected.",
+    onRejected: "halt",
+    inputSchema: z.object({
+      title: z.string().describe("Short summary for the reviewer"),
+      reason: z.string().describe("Why this needs human review"),
+    }),
+    outputSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
+    mapInput: ({ input, item }) => ({
+      json: {
+        ...((item.json as Record<string, unknown>) ?? {}),
+        title: input.title,
+        body: input.reason,
+      },
+    }),
+    mapOutput: ({ outputs }: { outputs: { main?: ReadonlyArray<{ json: unknown }> } }) => {
+      const first = outputs.main?.[0]?.json as { decision?: { status?: string; note?: string } } | undefined;
+      return { approved: first?.decision?.status === "approved", note: first?.decision?.note };
+    },
+  },
+);
+
+// (b) Inline callable: custom logic without a Codemation node.
+const lookup_rate = callableTool({
+  name: "lookup_rate",
+  description: "Look up the current EUR/USD exchange rate.",
+  inputSchema: z.object({ pair: z.string() }),
+  outputSchema: z.object({ rate: z.number() }),
+  execute: async () => ({ rate: 1.08 }),
+});
+
+const SyncOutput = z.object({ decision: z.string(), note: z.string().optional() });
+type SyncOutputT = z.infer<typeof SyncOutput>;
+
+// Agent with both tool kinds — model reasons, calls tools as needed, emits structured output.
+new AIAgent<AnalysisInput, SyncOutputT>({
+  name: "Analysis agent",
+  id: "analysis-agent",
+  messages: [
+    {
+      role: "system",
+      content:
+        "Analyse the text. If you need current exchange rates call lookup_rate. " +
+        "If the text describes a critical unresolvable issue, call escalate_to_human. " +
+        "Reply with { decision, note }.",
+    },
+    { role: "user", content: ({ item }) => item.json.text },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "medium"),
+  tools: [escalateToHuman, lookup_rate],
+  outputSchema: SyncOutput,
+  guardrails: { maxTurns: 10 },
+});
+export {};
+```
+
+Key constraints:
+
+- `mapInput` returns `{ json: <node-input> }` (an `Item`) or a bare `<node-input>` object. Use the `{ json: {} }` form when you need to merge additional fields.
+- `mapOutput` receives `{ outputs }` where `outputs.main` is the node's output items. Always handle the empty-array case (`outputs.main?.[0]?.json`) — some nodes (e.g. `odooQueryNode`) emit zero items on no-match, which throws without a custom `mapOutput`.
+- `outputSchema` of `asTool` is the **tool result** schema (what the agent sees back), not the node's own output type.
+
+### (b) Inline callable tools — `callableTool`
+
+For custom logic with no Codemation node behind it. Declare a credential slot if the execute body needs auth:
+
+```typescript
+import { callableTool } from "@codemation/core";
+import { z } from "zod";
+
+const ping = callableTool({
+  name: "ping",
+  description: "Check that a URL is reachable.",
+  inputSchema: z.object({ url: z.string().url() }),
+  outputSchema: z.object({ ok: z.boolean() }),
+  execute: async ({ input }) => {
+    const res = await fetch(input.url, { method: "HEAD" });
+    return { ok: res.ok };
+  },
+});
+export {};
+```
+
+### (c) MCP servers — `mcpServers`
+
+For tool access to services registered on the control plane, pass `mcpServers: ["<server-id>"]`. The agent gets `find_tools` auto-injected when `mcpServers` is set — but **the agent will not use it unless you tell it to** in the system `messages`. Add this line to the system prompt:
+
+```text
+Use find_tools(query) to discover available tools before calling them. Never call a tool name you have not seen returned by find_tools.
+```
+
+Node-backed and `callableTool` tools in `tools: [...]` are always present — no `find_tools` needed for them. Soft limit: 8 pinned MCP tools (`pinnedMcpTools`); hard limit: 16.
+
+## One realistic complete example
+
+Manual trigger → classify each feedback item with a managed model → tag the result downstream. Uses `outputSchema` so the downstream `MapData` reads `item.json.sentiment` directly — no hand-parsing, no non-determinism.
+
+```typescript
+import { z } from "zod";
+import {
+  createWorkflowBuilder,
+  ManualTrigger,
+  AIAgent,
+  MapData,
+  CodemationChatModelConfig,
+} from "@codemation/core-nodes";
+
+type Feedback = { text: string };
+const SentimentSchema = z.object({ sentiment: z.enum(["positive", "neutral", "negative"]) });
+type SentimentOutput = z.infer<typeof SentimentSchema>;
+
+export default createWorkflowBuilder({ id: "wf.classify-feedback", name: "Classify customer feedback" })
+  .trigger(
+    new ManualTrigger<Feedback>("Classify feedback", [
+      { text: "The new onboarding flow is really intuitive — great job!" },
+      { text: "Couldn't find the export button anywhere, very confusing." },
+    ]),
+  )
+  .then(
+    new AIAgent<Feedback, SentimentOutput>({
+      name: "Classify feedback",
+      id: "classify-feedback-agent",
+      messages: [
+        { role: "system", content: 'Reply with strict JSON {"sentiment":"positive"|"neutral"|"negative"}.' },
+        { role: "user", content: ({ item }) => `Feedback: ${item.json.text}` },
+      ],
+      chatModel: new CodemationChatModelConfig("Managed AI", "low"),
+      outputSchema: SentimentSchema,
+      guardrails: { maxTurns: 1 },
+    }),
+  )
+  .then(
+    new MapData<SentimentOutput, { label: string }>("Tag sentiment", (item) => ({ label: item.json.sentiment }), {
+      id: "tag-sentiment",
+    }),
+  )
+  .build();
+```
+
+## Choosing the model
+
+Pick by the complexity and size of the content being processed — not by habit. The second arg to `CodemationChatModelConfig` is a **complexity token**; the broker maps it to a concrete model and thinking effort.
+
+| Tier            | Use when                                                                                                                                                                                    | Complexity token |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| **Small/cheap** | Short, simple text: classification, triage, single-field extraction from a clean snippet.                                                                                                   | `"low"`          |
+| **Mid**         | Long or complex content: order PDFs, multi-page invoices, multi-field extraction, documents that would tax a smaller context. A `"low"` model may truncate or underperform on large inputs. | `"medium"`       |
+| **Heavy**       | Multi-step reasoning loops, tricky multi-tool decisions, demanding extraction where `"medium"` is unreliable.                                                                               | `"high"`         |
+| **Frontier**    | The hardest problems where you need the most capable model regardless of cost.                                                                                                              | `"xhigh"`        |
+
+Rule of thumb: if the prompt payload exceeds a paragraph or the output schema has more than two or three fields, step up to `"medium"`. Never hard-code a model id — the token IS the API; the broker picks the concrete model.
+
+```typescript
+import { AIAgent, CodemationChatModelConfig } from "@codemation/core-nodes";
+import { z } from "zod";
+
+// Small/cheap: one-field classification of a short text snippet.
+const triage = new AIAgent<{ subject: string }>({
+  name: "Triage email",
+  id: "triage-email",
+  messages: [
+    { role: "system", content: "Reply with one word: order, complaint, or other." },
+    { role: "user", content: ({ item }) => item.json.subject },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "low"),
+  outputSchema: z.object({ category: z.enum(["order", "complaint", "other"]) }),
+});
+
+// Larger: multi-field extraction from a full order document (PDF → markdown from OCR node upstream).
+// Step up the complexity token instead of hard-coding a model id.
+const extract = new AIAgent<{ markdown: string }>({
+  name: "Extract order",
+  id: "extract-order",
+  messages: [
+    { role: "system", content: "Extract vendor, total, and line items from the order document." },
+    { role: "user", content: ({ item }) => item.json.markdown },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "medium"),
+  outputSchema: z.object({
+    vendor: z.string(),
+    total: z.number(),
+    lines: z.array(z.object({ description: z.string(), amount: z.number() })),
+  }),
+  guardrails: { maxTurns: 1 },
+});
+export {};
+```
+
+## Gotchas
+
+- **Set an explicit `id`.** Without one the id derives from `name`; renaming the label re-keys any credential binding (BYOK / MCP). See the id-stability rule in `workflow-dsl`.
+- **Always set `outputSchema`.** Without it the output shape is non-deterministic (parsed JSON object or `{ output: string }` depending on whether the reply parses). With it, read parsed fields directly (`item.json.field`). Never read `item.json.output` when a schema is set, and avoid relying on `output` without a schema.
+- **One output per input.** `AIAgent` never fans out or filters — use `Split`/`Filter` for that.
+- **Don't use `AIAgent` for deterministic logic** — a `Callback` is cheaper and not billed.
+- **Managed = no key.** Never use `OpenAIChatModelConfig` (or "get an API key" guidance) in managed mode; the broker authenticates transparently.
+- **Binaries pass natively — never hand-roll the encoding.** Every attachment on the incoming item's `binary` is sent to the chat model AUTOMATICALLY as an inline multimodal block — images as `image` blocks, every other type (PDF, xlsx, pptx, docx, CSV, JSON, …) as `file`/`document` blocks — so the agent reads the file's actual bytes directly. You prepare nothing: the agent attaches whatever is on `item.binary` for you.
+  - **DON'T** add a "convert/encode to base64" node, stringify the bytes into a prompt/message, or OCR-to-text upstream just to feed an agent. Putting a base64 string into a text prompt is the #1 binary mistake — the model gets unreadable text, not a real image/document, and the extra hand-rolled node fails at runtime when the binary isn't where its code looked (`"No binary attachment found on item"`). There is no `Encode`/`Base64` node and you never need one here.
+  - **DO (binary from the direct upstream node):** keep the file on `item.binary` and feed that item straight into the `AIAgent` — a Gmail attachment, a file-pool read, or an HTTP download just flows in; the passdown is automatic. (To make an `HttpRequest` node hand you the raw bytes, set `responseFormat: "binary"` on it — it writes the response to `ctx.binary` under `binaryName` (default `"body"`) instead of parsing JSON/text. There is no `responseType` option.)
+  - **DO (binary from a NON-adjacent earlier node):** when the bytes were produced several nodes back, not by the direct upstream one, don't thread them through every node by hand — forward them explicitly with the agent's `binaries` option, e.g. `binaries: ({ item }) => item.binary ? Object.values(item.binary) : []` (a `BinaryAttachment[]`, or a `({ item }) => BinaryAttachment[]` selector that pulls the bytes from wherever they live on the item).
+  - Binaries are not filtered by type; an unsupported type surfaces a runtime error you can filter out upstream. Set `passBinariesToModel: false` only to deliberately turn the passdown off.

package/skills/builder/ai-agent/references/anti-patterns.md

@@ -0,0 +1,24 @@
+# AIAgent anti-patterns (version-specific)
+
+## Do NOT hard-code concrete model ids
+
+Do NOT pass a concrete model id (e.g. `"anthropic/claude-..."`, `"gpt-4o"`) to `CodemationChatModelConfig`.
+The second argument is a **complexity token**: `"low" | "medium" | "high" | "xhigh"`.
+The broker maps that token to a concrete provider model. Hard-coded ids will be rejected.
+
+```ts no-check
+// WRONG — concrete model id
+new CodemationChatModelConfig("Managed AI", "anthropic/claude-haiku-4-5-20251001");
+
+// CORRECT — complexity token
+new CodemationChatModelConfig("Managed AI", "medium");
+```
+
+## Do NOT call GET /api/llm/managed-models
+
+The model-discovery endpoint has been removed. The complexity token IS the API — no discovery step is needed or available.
+
+## `chatModel` string shorthand is not supported on AIAgent
+
+`AIAgent` does not accept a plain string for `chatModel` — only `CodemationChatModelConfig` or `OpenAIChatModelConfig` instances.
+(The string shorthand `model: "openai:gpt-4o-mini"` works on the `.agent(...)` fluent DSL helper only.)

package/skills/{codemation-cli → builder/cli}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: codemation-cli
+name: cli
 description: Guides Codemation CLI work for consumer apps and framework-author development. Use when the user asks about `codemation dev`, `build`, `serve web`, `serve worker`, `user create`, `user list`, `--consumer-root`, `.codemation/output`, or consumer versus framework-author mode.
 compatibility: Designed for Codemation repositories and projects that use the Codemation CLI.
 tags: cli, dev
@@ -7,15 +7,8 @@ tags: cli, dev
 
 # Codemation CLI
 
-## Mental model
-
 The CLI is a thin orchestrator: it loads `codemation.config.ts`, delegates to `@codemation/host` (web server) and worker packages, and manages build artifacts in `.codemation/output/`. It owns no workflow logic. There are two modes: **consumer mode** (`codemation dev`) runs a stable packaged UI against the consumer's workflows; **framework-author mode** (`codemation dev --watch-framework`) enables `next-host` HMR for monorepo development.
 
-## When to use / when NOT
-
-Use this skill for command selection, local development flow, and CLI troubleshooting.
-Do not use for workflow graph design, custom node implementation, or credential modeling unless the CLI command is the core question.
-
 ## Quickstart
 
 ```

package/skills/builder/connect-external-systems/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: connect-external-systems
+description: The decision guide for connecting a workflow step to ANY external system — an ERP, CRM, mailbox, or any HTTP/REST API. Follow this EVERY time a step talks to a service outside the workflow: pick the least-code route in strict priority order (specialized node → MCP server → defineRestNode → hand-rolled Callback). Read this before authoring any integration step.
+compatibility: Cross-vertical guidance for Codemation workflows. No specific package required.
+tags: integration, external, api, http, rest, mcp, connect, erp, crm, credential, routing
+uses: "@codemation/core-nodes, @codemation/core"
+---
+
+# Connecting to external systems — the routing hierarchy
+
+Whenever a workflow step must talk to a system outside the workflow (an ERP, CRM, mailbox, payment
+provider, any HTTP/REST or JSON-RPC API), pick the **least-code route** that works, in this **strict
+priority order**. Always start at route 1 and only descend when the route above genuinely doesn't apply.
+
+> **The rule, plainly: never hand-roll an external API in a `Callback` when a specialized node, an MCP
+> server, or `defineRestNode` can do it.** A hand-rolled `fetch`/JSON-RPC call is the last resort only —
+> it is considered non-production-grade whenever any route above it is available (no declared credential
+> slot, no shared session, no inspector surface, easy to get auth/retries wrong).
+
+**Discipline:** run this decision tree for **every** external step before you write code. Then author
+the step from the route's deeper skill, run `verify_workflow`, and fix only what it flags.
+
+## The decision tree
+
+```text
+Step talks to an external system?
+│
+├─ 1. Is there a SPECIALIZED NODE for this service?
+│      discover: search_skills("<service>")  →  e.g. odoo / gmail / msgraph
+│      yes → use that package's nodes (they declare the credential slot for you). DONE.
+│
+├─ 2. Is there an MCP SERVER for this service on the control plane?
+│      discover: list_mcp_servers (or GET /api/registry/capabilities?query=<service>)
+│      yes → drive it from an AIAgent:  new AIAgent({ ..., mcpServers: ["<id>"] }). DONE.
+│
+├─ 3. Is it a plain REST/HTTP JSON API (no node, no MCP)?
+│      yes → wrap one endpoint with defineRestNode({ api, credentials, request, response }). DONE.
+│
+└─ 4. None of the above fits (multi-step JSON-RPC, streaming, an SDK with no REST surface)?
+       LAST RESORT → hand-roll fetch / JSON-RPC inside a Callback, resolving auth via
+       ctx.getCredential(...). Justify why routes 1–3 didn't apply.
+```
+
+## Route 1 — specialized node (preferred)
+
+If a node package exists for the service, use it. It ships typed nodes, declares the credential slot for
+you, and encodes the service's quirks. **Discover it before assuming it doesn't exist:**
+
+```text
+search_skills("odoo")     → odoo skill: odooQueryNode / odooCreateNode / call_kw, slot "odoo"
+search_skills("gmail")    → gmail skill: OnNewGmailTrigger / ReplyToGmailMessage, slot "auth"
+search_skills("msgraph")  → Microsoft Graph (Outlook / Teams / SharePoint) nodes
+```
+
+When `search_skills` returns a matching integration skill, open it and author from its nodes. Deeper
+skills: **`odoo`** (ERP — match/create sale orders, partners, products), **`gmail`** (mailbox),
+**`msgraph`** (Microsoft 365). This is always the least-code, most-correct option — never reach past a
+specialized node to a hand-rolled call.
+
+## Route 2 — MCP server on the control plane
+
+No specialized node, but the service may be reachable as an **MCP server** registered on the control
+plane. An `AIAgent` step can then call its tools. **Discover the server id first — never guess it:**
+
+```text
+list_mcp_servers
+GET /api/registry/capabilities?query=<service>   → { id, displayName, acceptedCredentialTypes }
+```
+
+Pass the discovered `id` into the agent's `mcpServers` array. The credential binds on the materialized
+MCP connection node via the canvas dropdown (the operator binds; you only declare):
+
+```typescript
+import { AIAgent, CodemationChatModelConfig } from "@codemation/core-nodes";
+
+type Ticket = { summary: string };
+
+// Drive a CP-registered MCP server's tools from an LLM step. "<server-id>" comes from
+// list_mcp_servers / the capabilities registry — do not invent it.
+const triage = new AIAgent<Ticket>({
+  name: "Triage via MCP",
+  id: "triage-via-mcp",
+  messages: [
+    { role: "system", content: "Use the available tools to look up and update the ticket." },
+    { role: "user", content: ({ item }) => item.json.summary },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "low"),
+  mcpServers: ["<server-id>"],
+});
+```
+
+Deeper skills: **`mcp-capabilities`** (discovery + credential rules) and **`ai-agent`** (the `AIAgent`
+node, `mcpServers`, tools, and structured output).
+
+## Route 3 — `defineRestNode` for a plain REST API
+
+No specialized node and no MCP server, but the service is a plain REST/HTTP JSON API. Wrap the endpoint
+with **`defineRestNode`** — declare `api` (base URL, path, method), a `credentials` slot, and the
+`request`/`response` mappers, then use `node.create(...)` in the builder. This is strongly preferred over
+a raw `fetch`: you get a typed node, a declared credential slot, a shared HTTP session, and SSRF guards
+for free. Deeper skill: **`rest-node`** (full API + a complete example).
+
+## Route 4 — hand-rolled `Callback` (last resort)
+
+Only when none of routes 1–3 can express the call — e.g. a multi-step JSON-RPC handshake, a streaming
+protocol, or an SDK with no REST surface — hand-roll the call inside a `Callback`, resolving auth via
+`ctx.getCredential<T>(slotKey)` for a slot a credentialed node owns. State why routes 1–3 didn't apply.
+A plain `Callback` slot is not itself bindable — see `workflow-dsl` (Credentials) for the pattern.
+
+## Iterative / fuzzy matching: prefer an AIAgent with that integration's nodes as tools
+
+When a step must **match real-world text against integration records** (fuzzy company names, partial product codes, contacts that may or may not exist), a deterministic node chain fans out, loses the canonical payload, and fabricates ids on no-match. Instead, author an `AIAgent` whose `tools` are that integration's nodes wrapped via `AgentToolFactory.asTool(node.create(...), { mapInput, mapOutput })` — the agent calls one search per entity, reasons over the results, links matched ids, and explicitly reports what it cannot resolve. See the `odoo` skill for the full node-backed tool pattern (and the `ai-agent` skill for `AgentToolFactory.asTool` mechanics).
+
+## Anti-patterns
+
+- **Don't hand-roll `fetch`/JSON-RPC when a route above works.** A specialized node, MCP server, or
+  `defineRestNode` is always preferred — the raw `Callback` is the last resort, not the default.
+- **Don't skip discovery.** Run `search_skills` and `list_mcp_servers` _before_ concluding "there's no
+  node/server for this" — guessing leads straight to an unnecessary hand-rolled call.
+- **Don't put credentials in code.** Every route declares a bindable slot; the operator binds the
+  instance via the canvas. Never inline secrets or hard-code tokens.
+- **Never wire to fabricated external resource IDs.** Gmail label IDs, Drive folder IDs, ERP record IDs,
+  and any other external-system identifiers must come from config, a credential, or a prior lookup node.
+  If the ID isn't guaranteed to exist at runtime, **omit the feature or flag it for human setup** —
+  shipping a workflow wired to a hard-coded ID not guaranteed to exist is worse than a missing feature.
+  Use a placeholder comment (`// TODO: bind real label id from config`) or a config field instead.
+
+## Build what works; report what's missing — and never claim what you didn't wire
+
+**If you don't have all the required information at build time, do NOT invent it.** Build everything
+that DOES work with what you know, and explicitly surface every gap so the concierge can ask the user
+for the missing detail.
+
+**Don't claim/comment functionality you didn't wire.** If a comment says "includes order_line
+commands" but the code doesn't actually build them, remove the comment. A misleading comment is
+worse than silence: it tells the next agent (and the operator) the step works when it doesn't.
+The rule: every claim in a comment must be true of the code immediately below it. If you INTEND
+to wire something but haven't, either wire it now OR omit it and call `record_decision` to surface
+the gap — never write a claim that the code doesn't back.
+
+**A `callableTool` whose `execute` is a stub is the same defect as claiming unwired functionality.**
+A `callableTool` with `execute: async () => ({ ok: true })`, a `// TODO` for the real call, or
+any `execute` body that doesn't perform the intended external operation is a runtime lie — it builds
+and typechecks but does nothing. For any real external or ERP operation, use a NODE-BACKED tool
+(`AgentToolFactory.asTool(theNode.create(...), { mapInput, mapOutput })`) so the specialized node
+performs the call. If you genuinely cannot wire the operation (missing credential, unreachable
+endpoint), omit the tool entirely and call `record_decision` to surface the gap — never ship a
+stubbed `callableTool` standing in for a real integration call.
+
+**What counts as "invented":** a Gmail label ID that doesn't come from the user, an ERP record ID you
+don't know, a folder path you assume, a queue name you guessed. Any identifier that will fail at
+runtime if the real account/system is different.
+
+**What to do instead:**
+
+1. **Use runtime-resolved references when the node supports it.** Gmail's `addLabels`/`removeLabels`
+   (on `ModifyGmailLabels`) and `labelIds` (on `OnNewGmailTrigger`) accept display names — the
+   plugin resolves them at runtime. Prefer those over guessed IDs. Check the target node's type
+   definition before assuming you need a raw ID.
+
+2. **If no runtime-resolved reference exists,** build the surrounding workflow but declare the missing
+   value as a named required constant at the top of the file with a `// TODO(setup): <what's needed>`
+   comment, so the gap is unmissable:
+
+   ```text
+   // TODO(setup): replace with the real Jira project key from the customer's account
+   const JIRA_PROJECT_KEY = "TODO_REPLACE";
+   ```
+
+3. **Call `record_decision` to surface the gap** to the concierge and the build report:
+
+   ```text
+   record_decision({
+     choice: "Left JIRA_PROJECT_KEY as TODO_REPLACE — user must supply their Jira project key",
+     why: "No project key was provided; inventing one would break every run on the real account.",
+   })
+   ```
+
+4. **Do NOT omit the entire feature.** Build the node/step with the placeholder; the concierge can
+   bind or configure the real value once the user provides it. An incomplete-but-correct skeleton is
+   always better than a fully wired but runtime-broken workflow.
+
+The eval scoring criteria: a workflow that builds AND explicitly reports missing info is CORRECT. A
+workflow that fabricates values that will fail at runtime is WRONG regardless of how "complete" it looks.
+
+## Read next when needed
+
+- `odoo` / `gmail` / `msgraph` — route 1 specialized-node skills.
+- `mcp-capabilities` + `ai-agent` — route 2: discover MCP servers and drive them from `AIAgent`.
+- `rest-node` — route 3: wrap a plain REST endpoint with `defineRestNode`.
+- `workflow-dsl` — the surrounding builder, and the `Callback` + `ctx.getCredential` pattern for route 4.

package/skills/builder/credential-development/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: credential-development
+description: Authors a Codemation credential type with defineCredential(...) — public config, secret material, a typed createSession(...), and a test(...) probe — plus how nodes request it via named slots. Use when creating or updating custom credentials or credential-aware nodes.
+tags: credential, oauth, plugin
+---
+
+# Codemation Credential Development
+
+A credential type is a schema + runtime adapter: it declares `public` config (e.g. base URL), `secret` material (e.g. tokens), a `createSession(...)` factory that returns the typed object nodes consume, and a `test(...)` function for pre-activation validation. Nodes declare named credential slots; operators bind concrete instances to those slots in the UI. The binding key is `(workflowId, nodeId, slotKey)`.
+
+## Quickstart
+
+`defineCredential` takes a `public`/`secret` field map (or a Zod object), `createSession(args)` returning the runtime session, and `test(args)` returning a `CredentialHealth`. `args` is `{ publicConfig, material }`. This API-key type injects the key as a header and probes the endpoint in `test`:
+
+```ts
+import { defineCredential } from "@codemation/core";
+import type { CredentialSession, HttpCredentialDelta } from "@codemation/core-nodes";
+
+export const weatherApiKeyCredentialType = defineCredential({
+  key: "example.weather-api-key",
+  label: "Weather API Key",
+  public: {
+    keyHeader: { label: "Header name", type: "string" as const, placeholder: "X-Api-Key" },
+  },
+  secret: {
+    apiKey: { label: "API Key", type: "password" as const, required: true },
+  },
+  createSession(args): CredentialSession {
+    const apiKey = String(args.material.apiKey ?? "");
+    const headerName = String(args.publicConfig.keyHeader ?? "X-Api-Key").trim() || "X-Api-Key";
+    return {
+      applyToRequest: (): HttpCredentialDelta => ({ headers: { [headerName]: apiKey } }),
+    };
+  },
+  async test(args) {
+    const apiKey = String(args.material.apiKey ?? "").trim();
+    if (!apiKey) {
+      return { status: "failing", message: "API key is empty.", testedAt: new Date().toISOString() };
+    }
+    const resp = await fetch("https://api.example.com/me", { headers: { "X-Api-Key": apiKey } });
+    return resp.status === 401 || resp.status === 403
+      ? {
+          status: "failing",
+          message: `API returned ${resp.status} — key is invalid.`,
+          testedAt: new Date().toISOString(),
+        }
+      : { status: "healthy", message: "API key accepted.", testedAt: new Date().toISOString() };
+  },
+});
+```
+
+Register it with `defineCodemationApp({ credentials: [...] })` or `definePlugin({ credentials: [...] })`, then wire it onto a node — for `HttpRequest`, `credentialSlot: { name: "apiKey", acceptedTypes: [weatherApiKeyCredentialType] }`.
+
+## What `test()` does and why it matters
+
+Every credential type must implement `test(args)`. It is called:
+
+- When the operator clicks **Connect** in the credential dialog (validates before saving).
+- Before a workflow activates (blocks activation on failing credentials).
+
+`test()` receives the same `{ publicConfig, material }` args as `createSession()`. It must return `{ status: "healthy" | "failing", message, testedAt }`. A "failing" result blocks workflow activation and surfaces the `message` to the operator — use it to give actionable guidance ("API key is empty", "Endpoint returned 401 — key is invalid").
+
+Implement `test()` as a cheap probe against the real service when possible (e.g. a `/health` or `/me` call). At minimum, validate that required secret fields are non-empty. Do NOT call `createSession()` from inside `test()` — test independently so credential issues are caught before runtime.
+
+## Authoring rules
+
+1. Start with `defineCredential(...)`.
+2. Keep `public` versus `secret` fields intentional.
+3. Make `createSession(...)` return the typed runtime object the node actually needs.
+4. Implement `test(...)` so failure states are explicit before workflow activation.
+5. Register credential types at the app or plugin boundary, not inside random workflow files.
+
+## Decision branches & gotchas
+
+**Node integration:** helper-defined nodes declare credentials directly in the `credentials` field; class-based nodes use lower-level credential requirement APIs when needed.
+
+**Binding stability:** the `nodeId` defaults to a slug of the node's `name` label. Renaming a credential-using node's label silently changes its id and orphans the binding in the UI. To prevent this, set an explicit `id:` on credential-using node configs so the id is decoupled from the label.
+
+## Anti-patterns
+
+- Do not hard-code secrets in node implementation — use credential slots.
+- Do not register credential types inside workflow files — use the app or plugin composition root.
+
+## Read next when needed
+
+- Read `references/credential-patterns.md` for schema, registration, and slot guidance.