@codemation/agent-skills 0.4.0 → 0.5.1

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

@@ -0,0 +1,191 @@
+---
+name: workspace-files
+description: Reads and writes files in the platform's shared workspace pool from inside a running workflow — listWorkspaceFilesNode, readWorkspaceFileNode, writeWorkspaceFileNode. Use this whenever an automation needs a file the platform manages (a lookup table, a config sheet, a concierge-derived JSON) or produces a file back into the pool.
+compatibility: Codemation core-nodes-workspace-files. Requires WORKSPACE_ID and BLOB_STORAGE_* env vars.
+tags: workspace, files, pool, binary, storage, read, write, list, csv, json, lookup
+uses: "@codemation/core-nodes-workspace-files"
+---
+
+# Codemation Workspace Files
+
+## The lifecycle — how an automation gets at a platform-managed file
+
+The workspace **file pool** is shared storage (S3-backed) that the platform manages. A user does not
+hand a file to a workflow directly. The real flow is:
+
+1. A user **uploads a heavy file** (e.g. an Excel product catalogue) through the platform.
+2. The **concierge** has the coding agent **transform** it into a workflow-friendly shape (e.g. a flat
+   JSON keyed by SKU) and **stores the result** in the pool under a known filename.
+3. A **running automation reads that stored file** by filename (or pinned id) via the nodes below — and
+   does its work with the data.
+
+The automation is **decoupled** from the upload: it reads whatever the current version of that filename
+is, every run. Two concrete use cases:
+
+- **Product database for lookups.** A nightly order workflow reads `products.json` from the pool to
+  enrich each line item with price and description — no external API call, the sheet is the source.
+- **Leads router.** An inbound-lead webhook reads a `zipcode-regions.json` table from the pool, maps the
+  lead's zipcode to a region, and routes it to the right regional manager.
+
+Workflows can also **write** files back into the pool (`writeWorkspaceFileNode`) when a step produces a
+derived artifact other runs or the concierge should pick up — but **read is the headline pattern**.
+
+**Bytes always flow through `item.binary`**, never as base64 on `item.json`. Read nodes stream a file's
+bytes into a binary slot; you parse them in the next step. Use `workflow-dsl` for the
+surrounding builder.
+
+## A complete read-and-use workflow
+
+The concierge stored `products.json` in the pool. This webhook-triggered workflow reads it (latest-wins),
+parses the JSON straight off the binary slot with `ctx.binary.getJson`, and looks a SKU up.
+
+```typescript
+import { createWorkflowBuilder, WebhookTrigger, Callback } from "@codemation/core-nodes";
+import type { NodeExecutionContext } from "@codemation/core";
+import { readWorkspaceFileNode } from "@codemation/core-nodes-workspace-files";
+
+type FileMeta = {
+  fileId: string;
+  filename: string;
+  contentType: string;
+  size: number;
+  lastModified: string;
+  binarySlot: string;
+};
+type Product = { sku: string; name: string; price: number };
+
+export default createWorkflowBuilder({ id: "wf.product-lookup", name: "Look up product from pool" })
+  .trigger(new WebhookTrigger("Order in", { endpointKey: "order", methods: ["POST"] }))
+  // Read the newest "products.json" — a fresher upload is picked up on the next run.
+  .then(
+    readWorkspaceFileNode.create(
+      { filename: "products.json", binarySlot: "data" },
+      "Read product DB",
+      "read-product-db",
+    ),
+  )
+  // Parse the bytes from the binary slot — never base64 on item.json.
+  .then(
+    new Callback<FileMeta, { count: number; first?: Product }>(
+      "Parse products",
+      async (items, ctx: NodeExecutionContext) => {
+        const results: Array<{ json: { count: number; first?: Product } }> = [];
+        for (const item of items) {
+          const attachment = item.binary?.["data"];
+          if (!attachment) throw new Error('No binary at slot "data"');
+          const products = await ctx.binary.getJson<Product[]>(attachment);
+          results.push({ json: { count: products.length, first: products[0] } });
+        }
+        return results;
+      },
+      { id: "parse-products" },
+    ),
+  )
+  .build();
+```
+
+## Resolution modes (read)
+
+| Mode                      | Config                      | Behaviour                                                                                                      |
+| ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **latest-wins** (default) | `filename: "products.json"` | Reads the **newest** file with that name. Next upload of the same name is what the next run reads.             |
+| **pinned fileId**         | `fileId: "abc123..."`       | Reads that exact, immutable version forever — a new upload never changes it. Takes precedence over `filename`. |
+
+Use **latest-wins** for "always use the current sheet". Use a **pinned fileId** for reproducible /
+auditable runs. Discover ids with `listWorkspaceFilesNode`.
+
+## Binary slot handoff
+
+`readWorkspaceFileNode` streams the file's bytes into `item.binary[binarySlot]` (default `"data"`) and
+emits this metadata on `item.json`:
+
+```text
+{
+  fileId: string;
+  filename: string;
+  contentType: string;
+  size: number;          // bytes
+  lastModified: string;  // ISO 8601
+  binarySlot: string;    // e.g. "data"
+}
+```
+
+Read the bytes downstream via `ctx.binary.getJson<T>(attachment)` (bounded read + decode + parse, the
+clean default for JSON), `ctx.binary.getBytes(attachment)` (raw `Uint8Array`), or
+`ctx.binary.openReadStream(attachment)` for streaming. The bytes are never on `item.json`.
+
+## Node reference
+
+Import every node from `@codemation/core-nodes-workspace-files`.
+
+### `listWorkspaceFilesNode` — discover what's in the pool
+
+```typescript
+import { listWorkspaceFilesNode } from "@codemation/core-nodes-workspace-files";
+
+const list = listWorkspaceFilesNode.create(
+  { filenameFilter: "products" }, // optional case-insensitive substring; omit to list all
+  "List product files",
+  "list-product-files",
+);
+```
+
+Emits one item per file (newest-first): `{ fileId, filename, contentType, size, lastModified }`. Useful
+to drive a fan-out (one item per file) or to resolve a fileId for pinned reads.
+
+### `readWorkspaceFileNode` — read a file's bytes
+
+```typescript
+import { readWorkspaceFileNode } from "@codemation/core-nodes-workspace-files";
+
+const read = readWorkspaceFileNode.create(
+  {
+    filename: "products.json", // latest-wins; or use fileId for a pinned version
+    binarySlot: "data", // where the bytes land on item.binary — default "data"
+    maxBytes: 5 * 1024 * 1024, // cap before streaming — default 100 MiB
+  },
+  "Read products",
+  "read-products",
+);
+```
+
+Either `filename` or `fileId` must be set (`fileId` wins). Output: the metadata JSON above + bytes in
+`item.binary[binarySlot]`.
+
+### `writeWorkspaceFileNode` — produce a file back into the pool
+
+```typescript
+import { writeWorkspaceFileNode } from "@codemation/core-nodes-workspace-files";
+
+const write = writeWorkspaceFileNode.create(
+  {
+    filename: "daily-summary.json", // required — the name in the pool / concierge view
+    binarySlot: "data", // slot holding the bytes to write — default "data"
+    contentType: "application/json", // stamped on the stored object — default application/octet-stream
+  },
+  "Write daily summary",
+  "write-daily-summary",
+);
+```
+
+Reads bytes from `item.binary[binarySlot]` and writes them under a new fileId. Output:
+`{ fileId, filename, contentType, size, key, registered }`. In managed (CP-paired) mode it also registers
+the file so the concierge can list/read it; until the CP register endpoint ships, `registered` is `false`
+while the bytes are always written.
+
+## Gotchas
+
+- **Bytes go through `item.binary`, never base64 on `item.json`.** Read nodes attach to a slot; write
+  nodes read from a slot. Attach bytes with `ctx.binary` (or an upstream node) before writing.
+- **Read the derived file, not the raw upload.** Point workflows at the concierge-produced JSON/CSV in
+  the pool — not at a user's raw PDF/Excel. The transform is the concierge's job.
+- **`WORKSPACE_ID` / `BLOB_STORAGE_*` must be set.** Outside a configured workspace (e.g. plain local dev
+  without CP integration) the storage adapter is unavailable and the node throws — guard if a workflow
+  may run in that mode.
+- **Stable node ids.** Set an explicit `nodeId`; the engine slugifies the label otherwise, so renaming
+  re-keys the node.
+
+## Read next when needed
+
+- `workflow-dsl` — builder, triggers, flow control, the per-item contract.
+- `document-ai` — scan a file's bytes (e.g. read a PDF, then scan it).

package/skills/concierge/credentials/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: credentials
+description: Explains how the concierge connects a credential — the slot/type/instance model and how it presents and binds API-key, OAuth2, and MCP credentials. Use whenever a workflow needs an external account connected (an API key, an OAuth login, an MCP server) before it can run.
+compatibility: Concierge planning skill — conversation + binding guidance, no code.
+tags: audience:concierge, credentials, oauth, mcp, api-key, binding
+---
+
+# Codemation Credentials
+
+## Mental model
+
+Four words run through everything here:
+
+- **Credential TYPE** — a schema for one kind of connection (e.g. "Odoo API", "Gmail").
+  It declares `publicFields` (config, e.g. base URL) and `secretFields` (secret material, e.g.
+  an API key or token).
+- **Credential INSTANCE** — one concrete connection the owner has set up against a type (their
+  actual Odoo, their actual mailbox). A type can have several instances (personal vs work Gmail).
+- **SLOT** — a credential requirement a node declares. The binding key is
+  `(workflowId, nodeId, slotKey)`.
+- **BIND** — pointing a slot at an instance, so the node authenticates with that connection at run time.
+
+The division of labour: **the builder DECLARES and USES** slots (a node says "I need an Odoo
+credential"); **the concierge BINDS** an instance into each slot. A workflow can't be activated while
+any required slot has no healthy bound instance — so binding is the concierge's job to close out.
+
+## Forms render themselves — you collect and bind
+
+You do **not** hand-build credential forms. The control-plane UI and the credential tools render the
+fields automatically from the type's `publicFields` / `secretFields` schema served by the host. Each
+field carries its own presentation: `type` (`string` / `password` / `textarea` / `json` / `boolean`),
+whether it's `required`, and `visibility: "advanced"` (renders in a collapsed section for power-user
+fields). You pick the right credential type, walk the owner through the rendered fields, and bind.
+
+**Secrets go straight to the host, never into the chat.** When the owner types an API key or password,
+it is submitted directly to the host as secret material — you never echo it, store it in the
+conversation, or pass it through a tool argument. Public config (a base URL, a database name) is fine
+in conversation; secret material is not.
+
+## The three presentation patterns
+
+These are three _shapes the form takes_, not three different credential systems. Only OAuth2 is a
+distinct auth flow under the hood — API-key and MCP both reduce to "render the schema, then bind".
+
+```text
+API-key / basic-auth credential
+  - the type declares plain publicFields + secretFields (e.g. baseUrl + apiKey, or username + password)
+  - you: surface the form → owner fills it → secrets go to the host → test → bind to the slot
+  - the host's test() probes the real service; a "failing" result blocks activation, so resolve it first
+
+OAuth2 credential (redirect flow)
+  - the type carries an oauth2 auth definition (provider, scopes, authorize/token URLs)
+  - there is NO secret field to type — the token comes from the redirect, not from chat
+  - you: surface the connection → owner clicks Connect → redirected to the provider → grants access
+    → the host stores the returned token as material → bind the resulting instance to the slot
+  - if a client id / secret field is part of publicFields, those are config, not the user's secret
+
+MCP server credential
+  - an MCP server (from the control-plane registry) declares acceptedCredentialTypes — usually an
+    OAuth connection (e.g. Gmail). MCP is NOT its own credential kind; you bind an instance of the
+    accepted type exactly as above
+  - one instance can serve both a node (e.g. a Gmail trigger) and the MCP server in the same workflow
+```
+
+## How a binding gets done
+
+```text
+1. find the workflow's open credential slots (the builder declared them on specific nodes)
+2. for each slot, identify the credential type it accepts
+3. is there already a healthy instance of that type? → reuse it; otherwise set one up:
+     - API-key/basic: present the form → collect → secrets to host → test
+     - OAuth2 (incl. most MCP): present Connect → owner completes the redirect
+4. bind the instance to the slot
+5. confirm every required slot is bound and healthy → only then can the workflow activate
+```
+
+## The things owners forget — surface them
+
+- **Connect before they expect to.** A workflow that "looks built" still won't run until its slots are
+  bound. Drive the owner through connecting accounts as part of finishing, not after they hit an error.
+- **Reuse, don't re-ask.** If a healthy instance of the right type already exists, bind it rather than
+  making the owner reconnect.
+- **A failing test is a blocker, not a warning.** The host tests a credential on Connect and before
+  activation. Treat a "failing" status as work to resolve (wrong key, bad URL), not something to skip.
+- **One real test before live.** After binding, run the workflow once on real input so the owner sees
+  the connection actually working end to end.
+
+## Read next when needed
+
+- `credential-development` — the builder side: declaring a credential type and node slots.
+- `mcp-capabilities` — discover MCP server ids and their accepted credential types.

package/skills/concierge/intake-automation-playbook/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: intake-automation-playbook
+description: Scopes an INTAKE automation (something arrives → gets understood → an action happens) and proactively surfaces the dimensions owners forget — traceability, duplicate-handling, human-review, testing on real data. Use whenever an owner wants to automate handling of incoming emails, messages, orders, leads, or form submissions.
+compatibility: Concierge planning skill — plain-language conversation guidance, no code.
+tags: audience:concierge, audience:concierge-only, intake, automation, planning
+---
+
+# Intake automation playbook
+
+## Mental model
+
+Most automations a business owner asks for are the same shape: an **intake automation**. Something
+arrives → it gets understood → an action happens → the loop is closed. "Process my order emails", "new
+leads into my CRM", "contact-form submissions into a spreadsheet" are all this one pattern.
+
+Your job is not to transcribe what the owner asks — it's to recognise the pattern and **proactively fill
+in the parts they don't know to ask for**. A non-technical owner describes the happy path; they rarely
+mention what happens when the same email arrives twice, when the AI misreads a total, or how they'll
+know it works on _their_ data. You supply that missing input.
+
+## When to use
+
+The moment a request looks like intake: an incoming thing (email / message / order / lead / form /
+document) that should be processed into an action. Walk the owner through the dimensions below,
+**suggesting** the ones they didn't raise — as recommendations, not a checklist. Don't use this for
+one-off tasks, reports with no incoming trigger, or pure data lookups.
+
+## The nine dimensions
+
+The owner usually volunteers 1, 2, and 7. **You** raise the rest.
+
+1. **Trigger — what starts it.** Confirm the exact source (which inbox / label / endpoint).
+2. **Ingest / understand — turn messy input into clean data.** Read PDFs and free text, pull out the fields.
+3. **Match + link + report.** The one most underestimated: each company / contact / product must be
+   matched to the record in their system and linked — and whatever can't be matched is reported, not
+   silently dropped.
+4. **Human-review — a person checks before it commits, when it matters.** Pause on low-confidence or
+   unusual cases for the owner's OK.
+5. **Traceability / audit trail — keep the original** so a human can reconstruct what happened. This is
+   what makes them trust it.
+6. **Idempotency — don't process the same thing twice.** A re-sent or forwarded item must not double-enter.
+7. **Act — the actual output.** Be concrete: create the sale order, print the ticket, add the contact.
+8. **Notify / close the loop.** Reply to confirm or send a summary; mark the item handled.
+9. **Testability — the owner verifies on THEIR real data, no code.** Let them drop ~5 real items into a
+   test path and see exactly what it would do before switching it on. For a mailbox workflow this means a
+   **designated test folder** — ask for the folder/label name, resolve its id (via MCP), and pass it to
+   the builder. Fabricating fixtures defeats the point: the test must exercise the real processing on the
+   real input shape. See the `testing` skill for the principle and the integration skill (e.g. `gmail`)
+   for the concrete mechanism.
+
+## Per-vertical extensions
+
+The nine are the universal core; each vertical adds its own concerns. Pull the matching scenario skill
+if one exists (e.g. `scenario-procurement-intake`,
+`scenario-invoice-to-accounting`), or reason from the same shape: what's the domain's
+system-of-record (3), what's domain-specific to verify before committing (4), what counts as a
+duplicate (6)? If no scenario skill exists, the nine still apply.
+
+## Using it in conversation — not an interrogation
+
+- Lead with the owner's goal; weave the forgotten dimensions in as **suggestions you recommend**. Two or
+  three well-placed "I'd also set it up to…" beats nine blunt questions.
+- Prioritise the high-value forgotten ones — **traceability, duplicate-handling, human-review, and a way
+  to test on real data**. These are what owners are most grateful you raised.
+- Fold them into the plan you present, so it visibly covers them — that plan becomes the brief the
+  builder works from.
+
+## Anti-patterns
+
+- **Mirroring the naive input** — building exactly the happy path, omitting traceability / dedup /
+  review / testing. That's the failure this skill exists to prevent.
+- **Interrogating** — firing all nine as questions. Suggest and recommend instead.
+- **Recognise-without-link** — "the AI read the order" isn't done. If matched entities aren't linked into
+  the system of record and the unmatched aren't reported, a human has to redo it.
+- **Silent skips on the hard cases** — low-confidence or unmatched items must surface, never be quietly
+  guessed or dropped.
+- **Leaking how it's built** — keep it plain-language outcomes; never mention nodes, tools, or code to
+  the owner.

package/skills/concierge/scenario-invoice-to-accounting/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: scenario-invoice-to-accounting
+description: Plans an invoice-to-accounting automation — an incoming invoice is scanned, its vendor/amount/line-items extracted, and posted to an accounting system, with low-confidence ones held for review. Use when an owner wants supplier invoices read off and pushed into their accounting system automatically.
+tags: scenario, invoice, accounting, ocr, document, confidence, audience:concierge
+---
+
+# Invoice → accounting — scenario guidance
+
+A business receives supplier invoices and wants the key fields read off and pushed into their
+accounting system automatically — with the uncertain ones held back for a person to check. This is the
+shape to plan from; build each step from the skills listed below.
+
+## The flow
+
+```text
+on invoice arriving (webhook / upload / email)
+  → scan the document (invoice analyzer, per-field confidence)
+  → normalise the fields (vendor, invoice number, date, total, tax, line items)
+  → if any key field's confidence is below threshold → human review, else continue
+  → post the structured invoice to the accounting API
+  → keep the original document + the posted result audited
+```
+
+## What to ask the owner first
+
+- How do invoices arrive — a webhook/upload, an email attachment, a watched folder?
+- Which accounting system, and what's its API for creating a bill/expense? Which fields does it need?
+- What confidence is "safe to auto-post" vs "send to a human"? (the scanner returns per-field confidence)
+- Which fields matter — vendor, invoice number, date, total, tax, line items?
+- How will they test it before going live — which ~5 real invoices?
+
+## Build it from these skills
+
+- `workflow-dsl` — the builder, trigger, and flow-control spine. Start here.
+- `workflow-dsl` — receive the invoice by webhook/upload; or `gmail` if it arrives by email.
+- `document-ai` — the invoice analyzer with `includeConfidence` for per-field confidence.
+- `workflow-dsl` — normalise the extracted fields into the shape the accounting API wants.
+- `human-in-the-loop` — the confidence gate that routes uncertain invoices to review.
+- `workflow-dsl` — post to the accounting API.
+- `credentials` — connect the accounting API and bind it to the slot the builder declared.
+- `testing` — let them dry-run on real invoices before it goes live.
+
+## The things owners forget — surface them
+
+- **Gate on confidence** — don't auto-post a low-confidence amount; route it to review.
+- **Idempotency** — the same invoice arriving twice must not post twice (dedupe on invoice number).
+- **Traceability** — keep the original document and a record of what was posted.
+- **Testability is part of done** — let them dry-run on a handful of real invoices before going live.

package/skills/concierge/scenario-procurement-intake/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: scenario-procurement-intake
+description: Plans an order-intake automation — order emails are read, matched into the customer's ERP, and turned into sales orders, with a human in the loop for the uncertain ones. Use when an owner wants incoming purchase orders processed into their ERP (Odoo, AFAS, Salesforce, …) automatically.
+tags: scenario, procurement, order-intake, erp, gmail, ocr, audience:concierge
+---
+
+# Procurement order-intake — scenario guidance
+
+A dealer or distributor receives purchase orders by email — usually a PDF — and wants them turned into
+sales orders in their ERP automatically and safely, with a human checking the uncertain ones. The ERP
+is **whatever the owner uses** (Odoo, AFAS, Salesforce, …) — ask, don't assume. This is the shape to
+plan from; build each step from the skills listed below.
+
+## The flow
+
+```text
+on new mail @ "orders" label
+  → OCR the attachment + read the body
+  → [agent] router    : is this really an order?  (order / not-order / needs-human)
+  → [agent] extractor : company, buyer, PO number, line items (description, code, qty) as structured output
+  → erp-sync          : MATCH company + contacts + products in the customer's ERP, LINK them into a new
+                        sales order, REPORT anything unmatched — never silently drop it
+  → if low-confidence or unusual → human review gate, else continue
+  → create the sales order (header + lines for the matched items)
+  → reply to confirm + label the mail processed
+  → keep the original email + PDF audited throughout
+```
+
+## What to ask the owner first
+
+- Which Gmail label do order emails land on? Are orders a PDF attachment, inline text, or both?
+- **Which ERP / business system do they use** (Odoo, AFAS, Salesforce, …)? products matched by code/SKU?
+  existing customers to match? which company owns the order?
+- The buyer: is it the sender, or a buyer address inside the mail? any company to exclude (their own)?
+  default country / currency?
+- How will they test it before going live — which ~5 real order emails?
+
+## Build it from these skills
+
+- `workflow-dsl` — the builder, trigger, and flow-control spine. Start here.
+- `gmail` — trigger on the label; reply and label the mail processed.
+- `document-ai` — OCR the attachment (managed, no Azure key).
+- `ai-agent` — the router and the extractor (with an output schema). The agents classify and extract;
+  the ERP sync itself is deterministic integration work, not an agent.
+- `connect-external-systems` — **how to reach the ERP**: once you know which ERP the owner uses, follow
+  the routing rule — a specialized node if one exists (e.g. `odoo`), else an MCP-backed agent, else
+  `defineRestNode`. Never hand-roll the ERP's HTTP/JSON-RPC in a Callback.
+- `human-in-the-loop` — the review gate, on the live path, not beside a NoOp.
+- `testing` — TestTrigger reads a label, IsTestRun guards live writes, assertions.
+- `credential-development` — author or bind the ERP credential the integration nodes declare.
+
+## The things owners forget — surface them
+
+- **Match → link → report** every entity (company, contacts, products): recognise it, match the ERP
+  record, link it, and report what didn't match for review. Recognise-only isn't enough.
+- **Traceability** — keep the original email + PDF attached and audited.
+- **Idempotency** — the same mail processed twice must not create a duplicate sales order.
+- **Testability is part of done** — the workflow is tested on **real order emails from a designated test folder**, not fabricated data. Ask the owner for the test-folder name, resolve its Gmail label id (via MCP), and pass it to the builder in the build task. The builder will `report_flag` a gap if it's missing. See the `testing` and `gmail` skills for the mechanism.

package/skills/codemation-ai-agent-node/SKILL.md

@@ -1,66 +0,0 @@
----
-name: codemation-ai-agent-node
-description: AIAgent constructor, message shape, managed and BYOK chatModel configs, outputSchema, mcpServers. Read before writing any workflow step that calls an LLM.
-compatibility: Codemation core-nodes. Requires @codemation/core-nodes import.
-tags: agent, llm, ai
-uses: "@codemation/core-nodes"
----
-
-# Codemation AI Agent Node
-
-## Mental model
-
-`AIAgent` is the single building block for any LLM step in a workflow. It receives items, runs a chat completion per item using the configured model and messages, and emits `{ output: string }` (or a parsed object when `outputSchema` is set) on its `main` port. The `chatModel` field determines whether the run consumes Codemation-managed quota (no credential needed) or a BYOK key the operator supplies. Every AIAgent emits exactly one output item per input item — it never fans out or filters.
-
-## When to use / when NOT
-
-Use `AIAgent` when a workflow step needs an LLM call: classification, extraction, summarisation, drafting, or decision.
-Use a plain `Callback` instead when the logic is deterministic code — no LLM needed.
-Use `mcpServers` (see `codemation-mcp-capabilities`) when the agent needs tool access to external services.
-Read `codemation-workflow-dsl` for the surrounding workflow structure.
-
-## Quickstart
-
-```ts
-import { AIAgent, CodemationChatModelConfig } from "@codemation/core-nodes";
-
-new AIAgent({
-  name: "Classify email",
-  messages: [
-    { role: "system", content: "Classify the email as spam or not-spam." },
-    { role: "user", content: (args) => args.item.json.body as string },
-  ],
-  chatModel: new CodemationChatModelConfig("Claude Haiku", "anthropic/claude-haiku-4-5-20251001"),
-});
-```
-
-For full patterns — BYOK (`OpenAIChatModelConfig`), `outputSchema`, tools, multi-step pipelines, and gmail classification — use your harness's example-discovery tool: `find_examples({ query: "AIAgent" })`.
-
-## Decision branches & gotchas
-
-**Managed mode (default — no API key needed):** use `CodemationChatModelConfig(label, modelId)`. In managed mode the LLM broker **auto-authenticates via the workspace HMAC pairing** — no API key, no credential slot, no user setup required. This is the correct default for all managed-mode workflows. Do NOT tell managed users to "get an API key" — the broker handles authentication transparently.
-
-```ts
-chatModel: new CodemationChatModelConfig("Claude Haiku", "anthropic/claude-haiku-4-5-20251001");
-// No credential slot created. Discover live model ids:
-// GET <CONTROL_PLANE_URL>/api/llm/managed-models
-```
-
-**BYOK (self-hosted / non-managed only):** use `OpenAIChatModelConfig(label, modelId, slotKey)` — it creates a credential slot the operator must bind with an API key. Only use this in self-hosted deployments where no managed broker is available.
-
-**Messages:** `content` is a plain string or a function `(args: { item, itemIndex, items, ctx }) => string`. Put instructions in the `system` message, per-item data in the `user` message. Use `"assistant"` role only for few-shot examples.
-
-**Structured output:** add `outputSchema: z.object({...})` to validate and parse the response. Without it, `item.json.output` is always a plain string.
-
-**Stable node id:** if the node has a credential binding (BYOK), set an explicit `id:` on the constructor. Without it the id derives from the `name` label — renaming the label orphans the binding. See `codemation-workflow-dsl` for the full id-stability rule.
-
-**Downstream access:** the next node sees `item.json.output` as the agent's text response. Cast it via a typed `Callback<{ output: string }>`.
-
-## Anti-patterns
-
-- Do not tell managed users to get an API key — use `CodemationChatModelConfig`; the broker authenticates automatically.
-- Do not use `OpenAIChatModelConfig` in managed mode — it creates an unnecessary credential slot and will prompt the user to bind a key they don't need.
-- Do not use `AIAgent` for deterministic logic; use `Callback` instead (cheaper, faster, no LLM billing).
-- Do not attempt to return multiple items from a single `AIAgent` step — it emits exactly one output per input.
-
-See `references/anti-patterns.md` for version-specific gotchas (managed model id churn, chatModel string shorthand trap).

package/skills/codemation-ai-agent-node/references/anti-patterns.md

@@ -1,11 +0,0 @@
-# AIAgent anti-patterns (version-specific)
-
-## Managed model ids change between releases
-
-Do NOT hard-code managed model ids sourced from training data. The allowlisted set changes with each release.
-Always discover the live list via `GET <CONTROL_PLANE_URL>/api/llm/managed-models` before committing a model id.
-
-## `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-credential-development/SKILL.md

@@ -1,57 +0,0 @@
----
-name: codemation-credential-development
-description: Guides Codemation custom credential development with `defineCredential(...)`, typed sessions, credential testing, and node credential slots. Use when creating or updating custom credentials, credential registrations, or credential-aware custom nodes.
-compatibility: Designed for Codemation apps and plugins that register typed credentials.
-tags: credential, oauth, plugin
----
-
-# Codemation Credential Development
-
-## Mental model
-
-A credential type is a schema + runtime adapter: it declares `public` config (e.g. OAuth client id), `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)`.
-
-## When to use / when NOT
-
-Use this skill for defining new credential types, wiring them into apps or plugins, and teaching nodes to request typed credential sessions.
-Do not use for general workflow authoring unless credential slots or runtime sessions are the core problem.
-
-## Quickstart
-
-No standalone snippet — the full `defineCredential(...)` shape is in `references/credential-patterns.md`. Use your harness's example-discovery tool for runnable examples: `find_examples({ query: "defineCredential api-key test" })` or `find_examples({ query: "credential slot" })`.
-
-## 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.
-
-See the `define-credential-api-key` example for a concrete `test()` implementation: `find_examples({ query: "defineCredential api-key test" })`.
-
-## 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.