@codemation/agent-skills 0.4.0 → 0.5.1

package/skills/builder/odoo/SKILL.md

@@ -0,0 +1,498 @@
+---
+name: odoo
+description: Builds Odoo steps with the @codemation/core-nodes-odoo plugin — search/MATCH records (odooQueryNode), CREATE records like a sale.order (odooCreateNode), plus read/update/delete and a generic call_kw. Every node declares the "odoo" credential slot for you. Use whenever a workflow looks up, links, or writes Odoo records (partners, products, sale orders).
+compatibility: Requires @codemation/core-nodes-odoo. An Odoo credential (URL + database + API key) binds on slot "odoo".
+tags: odoo, erp, sale-order, partner, product, match, link, crud, call_kw, credential, integration
+uses: "@codemation/core-nodes-odoo, @codemation/core-nodes, @codemation/core"
+---
+
+# Odoo nodes
+
+The `@codemation/core-nodes-odoo` plugin talks to Odoo over JSON-RPC. Each node **declares the `odoo`
+credential slot itself** (`credentials: { odoo }`) — so the moment you use one, the platform knows the
+workflow needs an Odoo connection and prompts the operator to bind it before activation. You do **not**
+hand-roll `fetch`/JSON-RPC and you do **not** declare the slot separately.
+
+**Discipline:** author straight from this file, then run `verify_workflow` and fix only what it flags.
+Use `workflow-dsl` for the surrounding builder, trigger, and flow-control surface.
+
+## The nodes
+
+| Node             | Odoo op       | Use for                                                         |
+| ---------------- | ------------- | --------------------------------------------------------------- |
+| `odooQueryNode`  | `search_read` | MATCH records — find a partner by email, products by code       |
+| `odooCreateNode` | `create`      | CREATE a record — a `sale.order` header, a partner              |
+| `odooReadNode`   | `read`        | read one record's fields by id                                  |
+| `odooUpdateNode` | `write`       | update a record by id                                           |
+| `odooDeleteNode` | `unlink`      | delete a record by id                                           |
+| `odooCallKwNode` | any `call_kw` | anything the CRUD nodes don't cover (e.g. `sale.order` + lines) |
+
+## MATCH → LINK → REPORT (the order-intake shape)
+
+`odooQueryNode` runs `search_read(model, domain, fields)` and **fans out one item per matched row** —
+this is the generic node fan-out behaviour (a node returning an array emits one item per element; see
+`workflow-dsl` → **Fan-out & fan-in**). Zero rows ⇒ zero items downstream, so branch on that to REPORT
+what didn't match, never silently drop it. Each downstream item's `item.json` is one `OdooQueryOutputRow`.
+`odooCreateNode` writes a record (e.g. a `sale.order`) and emits its new `id`; LINK the matched partner
+into it with `itemExpr`.
+
+**For every entity in an order-intake workflow (company, contacts, products), apply the same three-step
+discipline:**
+
+1. **MATCH** — run `odooQueryNode` to search for the ERP record. Fan-out: zero rows = unmatched.
+2. **LINK** — wire the matched record's `id` into the downstream create/update via `itemExpr`.
+3. **REPORT** — when a record CANNOT be matched, do NOT drop it silently and do NOT fabricate an id.
+   Instead, report it: write an audit note / human-review flag / `unmatchedItems` field on `item.json`
+   so the concierge can surface it and the user can act. Keep the original email + any PDF attachment
+   on `item.binary` throughout so the audit trail is complete.
+
+```typescript
+import { createWorkflowBuilder, ManualTrigger, Callback } from "@codemation/core-nodes";
+import { itemExpr } from "@codemation/core";
+import type { Items } from "@codemation/core";
+import { odooQueryNode, odooCreateNode, type OdooQueryOutputRow } from "@codemation/core-nodes-odoo";
+
+type OrderCanonical = { companyName: string; poNumber: string; buyerEmail: string };
+type WithPartner = OrderCanonical & { partnerId: number };
+type UnmatchedReport = OrderCanonical & { unmatchedReason: string };
+
+export default createWorkflowBuilder({ id: "wf.odoo.order-sync", name: "Odoo order sync" })
+  .trigger(
+    new ManualTrigger<OrderCanonical>("Start", [
+      { companyName: "ACME", poNumber: "PO-001", buyerEmail: "buyer@acme.example" },
+    ]),
+  )
+  // MATCH: search_read res.partner by email — fans out one item per match (none ⇒ none downstream).
+  .then(
+    odooQueryNode.create<OrderCanonical>(
+      {
+        model: "res.partner",
+        fields: ["id", "name", "email"],
+        query: [{ field: "email", operator: "=", value: "buyer@acme.example" }],
+        mode: "and",
+        pagination: { limit: 1 },
+      },
+      "Match customer",
+      "match-partner",
+    ),
+  )
+  // LINK + CREATE: each item is now one matched partner row — wire its id into a new sale.order.
+  .then(
+    odooCreateNode.create(
+      {
+        model: "sale.order",
+        values: itemExpr<Record<string, unknown>, OdooQueryOutputRow>(({ item }) => ({
+          partner_id: Number(item.json["id"]),
+          origin: "order-intake",
+        })),
+      },
+      "Create sale order",
+      "create-order",
+    ),
+  )
+  .build();
+```
+
+**REPORT the unmatched (the missing stage agents often skip):** when the match query returns
+zero rows, branch on that and produce an explicit unmatched record — not silence:
+
+```typescript
+import { Callback } from "@codemation/core-nodes";
+import type { Items } from "@codemation/core";
+
+type OrderCanonical = { companyName: string; poNumber: string; buyerEmail: string };
+type UnmatchedReport = OrderCanonical & { unmatchedReason: string };
+
+// In the zero-match branch: preserve the full order payload + record WHY it didn't match.
+// Surface this as an audit note or a human-review item — never drop the unmatched entity.
+const reportUnmatched = new Callback<OrderCanonical, UnmatchedReport>(
+  "Flag unmatched company",
+  (items: Items<OrderCanonical>) =>
+    items.map((i) => ({
+      json: {
+        ...i.json, // ← preserve the entire canonical payload
+        unmatchedReason: `No Odoo partner found for email "${i.json.buyerEmail}" (company: "${i.json.companyName}") — needs manual review`,
+      },
+    })),
+  { id: "flag-unmatched-company" },
+);
+export {};
+```
+
+## Fuzzy matching? Use an Odoo AGENT, not a deterministic chain
+
+When you need to match real-world text (company names, product descriptions, buyer contacts) against Odoo records, a deterministic `odooQueryNode` chain **fails**:
+
+- `odooQueryNode` **fans out** — one item per matched row. On a multi-entity canonical payload (company + contacts + line items) this collapses the original item structure, forcing unsafe casts to retrieve the order payload again.
+- On **no match** the chain emits zero items — making it trivial to accidentally silently drop the record or, worse, fall back to a fabricated `partner_id: 1`.
+- Fuzzy matching (a company name that's slightly different, a product code vs. description) requires multiple strategies and reasoning, which a deterministic query can't express.
+
+**The solution: author an `AIAgent` whose tools are the Odoo nodes.** The agent calls one search tool per entity, reasons over the candidates, links matched ids into the final create, and explicitly reports everything it could not resolve. No fan-out, no fabrication, no silent drops.
+
+### The pattern: `AgentToolFactory.asTool(odooNode, { mapInput, mapOutput })` for each entity
+
+Wrap each Odoo operation as an agent tool. The key discipline:
+
+- **`mapInput`**: translate the agent's tool-call args to the node's item-level config (`{ query: [...] }`). Static parts (`model`, `fields`, `pagination`) live in the node's `.create(...)` config.
+- **`mapOutput`**: always write a custom handler that reads `outputs.main?.[0]?.json` and returns `{ found: false, id: null }` on empty — never let the default throw on a no-match.
+- **`onRejected: "halt"`** on `request_human_review` so the workflow halts when a human rejects a critical gap.
+
+### MATCH → LINK → REPORT system prompt
+
+The agent's system prompt enforces three phases:
+
+1. **MATCH**: for each entity, call the corresponding search tool. Accept the result; never invent an id.
+2. **LINK**: once all searches are done, call `odoo_create_sale_order` with the matched ids. For unmatched products, pass `productId: null` and include the line description.
+3. **REPORT**: call `odoo_post_audit_comment` with a structured summary of matched and unmatched entities. If a critical entity (company, key product) could not be matched, call `request_human_review` BEFORE creating the order.
+
+### Compilable example
+
+```typescript
+import { AIAgent, CodemationChatModelConfig, inboxApproval } from "@codemation/core-nodes";
+import { AgentToolFactory } from "@codemation/core";
+import { odooQueryNode, odooCreateNode, odooCallKwNode, type OdooQueryOutputRow } from "@codemation/core-nodes-odoo";
+import { z } from "zod";
+import type { Item } from "@codemation/core";
+
+// --- Tool 1: search res.partner by email (node-backed) ---
+// Static config on .create(): model + fields + pagination (the "outer shape").
+// mapInput supplies the dynamic per-call query from the agent's args.
+// mapOutput handles zero-match safely — never throws, never fabricates an id.
+const odoo_search_partner = AgentToolFactory.asTool(
+  odooQueryNode.create(
+    { model: "res.partner", fields: ["id", "name", "email"], mode: "and", pagination: { limit: 1 } },
+    "Search partner",
+    "odoo-search-partner",
+  ),
+  {
+    name: "odoo_search_partner",
+    description: "Search res.partner by email. Returns { found: false, id: null } on no match — NEVER fabricate an id.",
+    inputSchema: z.object({
+      email: z.string().describe("Email address to search for"),
+    }),
+    outputSchema: z.object({
+      found: z.boolean(),
+      id: z.number().nullable(),
+      name: z.string().nullable(),
+    }),
+    mapInput: ({ input }) => ({ json: { query: [{ field: "email", operator: "=", value: input.email }] } }),
+    mapOutput: ({ outputs }: { outputs: { main?: ReadonlyArray<{ json: unknown }> } }) => {
+      const row = outputs.main?.[0]?.json as OdooQueryOutputRow | undefined;
+      return row
+        ? { found: true, id: Number(row["id"]), name: String(row["name"] ?? "") }
+        : { found: false, id: null, name: null };
+    },
+  },
+);
+
+// --- Tool 2: search product.template by description or code (node-backed) ---
+const odoo_search_product = AgentToolFactory.asTool(
+  odooQueryNode.create(
+    { model: "product.template", fields: ["id", "name", "default_code"], mode: "or", pagination: { limit: 3 } },
+    "Search product",
+    "odoo-search-product",
+  ),
+  {
+    name: "odoo_search_product",
+    description:
+      "Search product.template by description (ilike) or exact product code. " +
+      "Returns the best match or { found: false } on no match.",
+    inputSchema: z.object({
+      description: z.string().describe("Product description to fuzzy-match"),
+      code: z.string().optional().describe("Exact product code to try first"),
+    }),
+    outputSchema: z.object({ found: z.boolean(), id: z.number().nullable(), name: z.string().nullable() }),
+    mapInput: ({ input }) => ({
+      json: {
+        query: [
+          ...(input.code ? [{ field: "default_code", operator: "=", value: input.code }] : []),
+          { field: "name", operator: "ilike", value: input.description },
+        ],
+      },
+    }),
+    mapOutput: ({ outputs }: { outputs: { main?: ReadonlyArray<{ json: unknown }> } }) => {
+      const row = outputs.main?.[0]?.json as OdooQueryOutputRow | undefined;
+      return row
+        ? { found: true, id: Number(row["id"]), name: String(row["name"] ?? "") }
+        : { found: false, id: null, name: null };
+    },
+  },
+);
+
+// --- Tool 3: create sale.order (node-backed) ---
+const odoo_create_sale_order = AgentToolFactory.asTool(
+  odooCreateNode.create({ model: "sale.order" }, "Create sale order", "odoo-create-sale-order"),
+  {
+    name: "odoo_create_sale_order",
+    description: "Create a sale.order with matched partner and order lines.",
+    inputSchema: z.object({
+      partnerId: z.number().describe("res.partner id (billing contact or company)"),
+      clientOrderRef: z.string().nullable().describe("Customer PO or reference number"),
+      orderLines: z.array(
+        z.object({
+          productId: z.number().nullable().describe("product.template id; null for unmatched lines"),
+          name: z.string().describe("Line description (required when productId is null)"),
+          productUomQty: z.number().default(1),
+        }),
+      ),
+    }),
+    outputSchema: z.object({ saleOrderId: z.number().nullable() }),
+    mapInput: ({ input }) => ({
+      json: {
+        values: {
+          partner_id: input.partnerId,
+          client_order_ref: input.clientOrderRef,
+          order_line: input.orderLines.map((l) => [
+            0,
+            0,
+            { product_id: l.productId ?? false, name: l.name, product_uom_qty: l.productUomQty },
+          ]),
+        },
+      },
+    }),
+    mapOutput: ({ outputs }: { outputs: { main?: ReadonlyArray<{ json: unknown }> } }) => {
+      const row = outputs.main?.[0]?.json as Record<string, unknown> | undefined;
+      return { saleOrderId: row?.id != null ? Number(row["id"]) : null };
+    },
+  },
+);
+
+// --- Tool 4: HITL escalation (node-backed) ---
+const request_human_review = AgentToolFactory.asTool(
+  inboxApproval.create(
+    {
+      title: ({ item }: { item: Item }) => String((item.json as { title?: unknown }).title ?? "Review needed"),
+      body: ({ item }: { item: Item }) => String((item.json as { body?: unknown }).body ?? ""),
+      priority: "high",
+      timeout: "8h",
+      onTimeout: "halt",
+    },
+    "Human review request",
+  ),
+  {
+    name: "request_human_review",
+    description:
+      "Escalate to a human when a critical entity (company, key product) cannot be matched. " +
+      "Call BEFORE creating the order. Halt if the reviewer rejects.",
+    onRejected: "halt",
+    inputSchema: z.object({
+      title: z.string(),
+      reason: z.string(),
+      missingEntities: z.array(z.string()),
+    }),
+    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}\n\nCould not match: ${input.missingEntities.join(", ")}`,
+      },
+    }),
+    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 };
+    },
+  },
+);
+
+// --- Tool 4b: post audit comment — node-backed via odooCallKwNode message_post ---
+// Post audit notes via a node-backed `asTool(odooCallKwNode … message_post)` tool — NOT a stubbed callableTool; the real node does the RPC.
+const odoo_post_audit_comment = AgentToolFactory.asTool(
+  odooCallKwNode.create({ model: "sale.order", method: "message_post" }, "Post audit comment", "post-audit"),
+  {
+    name: "odoo_post_audit_comment",
+    description: "Post an audit chatter note on the sale.order summarising matched/unmatched entities.",
+    inputSchema: z.object({ saleOrderId: z.number(), body: z.string() }),
+    outputSchema: z.object({ posted: z.boolean() }),
+    mapInput: ({ input }) => ({ json: { args: [[input.saleOrderId]], kwargs: { body: input.body } } }),
+    mapOutput: () => ({ posted: true }),
+  },
+);
+
+// --- Shared types ---
+const OdooSyncOutput = z.object({
+  saleOrderId: z.number().nullable(),
+  matched: z.object({
+    partnerId: z.number().nullable(),
+    productIds: z.array(z.number()),
+  }),
+  unmatched: z.object({
+    products: z.array(z.string()),
+    contacts: z.array(z.string()),
+  }),
+});
+type OdooSyncOutputT = z.infer<typeof OdooSyncOutput>;
+type OrderT = { company: string; buyerEmail: string; lines: Array<{ desc: string; code?: string; qty: number }> };
+
+// --- The Odoo sync agent ---
+new AIAgent<OrderT, OdooSyncOutputT>({
+  name: "Odoo sync agent",
+  id: "odoo-sync-agent",
+  messages: [
+    {
+      role: "system",
+      content:
+        "You are an Odoo integration agent. Follow MATCH → LINK → REPORT strictly:\n" +
+        "\n" +
+        "1. MATCH each entity:\n" +
+        "   - Company/partner: odoo_search_partner(email)\n" +
+        "   - Each line item: odoo_search_product(description, code?) — try code first, then description\n" +
+        "\n" +
+        "2. LINK: call odoo_create_sale_order with the matched partnerId and orderLines.\n" +
+        "   - For unmatched products, set productId: null and include the original line description.\n" +
+        "   - NEVER invent a partnerId. If company is not found AND order has >2 lines: call request_human_review FIRST.\n" +
+        "\n" +
+        "3. REPORT: call odoo_post_audit_comment with a summary of matched ids and unmatched entities.\n" +
+        "\n" +
+        "Return {saleOrderId, matched:{partnerId, productIds:[]}, unmatched:{products:[], contacts:[]}}.",
+    },
+    { role: "user", content: ({ item }) => JSON.stringify(item.json, null, 2) },
+  ],
+  chatModel: new CodemationChatModelConfig("Managed AI", "medium"),
+  tools: [
+    odoo_search_partner,
+    odoo_search_product,
+    odoo_create_sale_order,
+    odoo_post_audit_comment,
+    request_human_review,
+  ],
+  outputSchema: OdooSyncOutput,
+  guardrails: { maxTurns: 20 },
+});
+export {};
+```
+
+### Why this beats a deterministic node chain
+
+| Concern                                 | Deterministic chain                                                              | Odoo agent                                                                                   |
+| --------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Fan-out loses canonical payload         | Yes — `odooQueryNode` emits one item per row; multi-entity payload is gone       | No — agent holds the full order in context across all tool calls                             |
+| Zero-match → silent drop or fabrication | Yes — easy to miss the zero-items branch; agents have fabricated `partner_id: 1` | No — `mapOutput` returns `{ found: false, id: null }`; agent reads it and reports explicitly |
+| Fuzzy matching (typos, partial names)   | Hard — requires multiple `odooQueryNode` branches                                | Natural — agent reasons over candidates, tries code then description                         |
+| Escalate unresolvable gaps              | Requires extra HITL node wired correctly outside the chain                       | Built-in — agent calls `request_human_review` tool                                           |
+
+**Use a deterministic chain only when the match is guaranteed exact** (e.g. a webhook that already includes an Odoo record id). For anything fuzzy, incomplete, or multi-entity: use the agent pattern above.
+
+## Querying — the `query` domain
+
+`query` is a list of `{ field, operator, value }` leaves combined with `mode: "and" | "or"`; it compiles
+to an Odoo domain. Common operators: `"="`, `"!="`, `"ilike"` (fuzzy, case-insensitive — use it for
+product-name matching), `"in"`. `pagination` takes `{ limit, offset, order }`. Set `includeTotalCount: true`
+to add a `totalCount` to each row when you need the full match count.
+
+```typescript
+import { odooQueryNode } from "@codemation/core-nodes-odoo";
+
+// Fuzzy product match by code OR name — fans out every candidate so a Callback can rank/report.
+const findProducts = odooQueryNode.create(
+  {
+    model: "product.product",
+    fields: ["id", "default_code", "name"],
+    query: [
+      { field: "default_code", operator: "=", value: "PUMP-100" },
+      { field: "name", operator: "ilike", value: "centrifugal pump" },
+    ],
+    mode: "or",
+    pagination: { limit: 5 },
+    includeTotalCount: true,
+  },
+  "Find products",
+  "find-products",
+);
+```
+
+## Per-item values with `itemExpr`
+
+Static config is the default. When a field must come from the current item (the matched id, an
+extracted value), wrap it with `itemExpr(...)` — the engine resolves it per item before `execute`.
+
+```typescript
+import { itemExpr } from "@codemation/core";
+import { odooReadNode } from "@codemation/core-nodes-odoo";
+
+const readMatched = odooReadNode.create(
+  {
+    model: "res.partner",
+    fields: ["id", "name", "email"],
+    id: itemExpr<number, { id: number }>(({ item }) => item.json.id),
+  },
+  "Read matched partner",
+  "read-partner",
+);
+```
+
+## Chaining after any upstream (humanApproval, transforms, triggers)
+
+Every Odoo node's input brand is `any`, so `.then(odooXxxNode.create(...))` compiles after **any**
+upstream — a trigger, a transform, a `humanApproval` step, or another Odoo node. Type-safe `itemExpr`
+access to the upstream item shape comes from the `create<TUpstreamJson>()` generic, not from the
+node's brand.
+
+```typescript
+import { createWorkflowBuilder, ManualTrigger, inboxApproval } from "@codemation/core-nodes";
+import { itemExpr } from "@codemation/core";
+import { odooCallKwNode } from "@codemation/core-nodes-odoo";
+
+type OrderJson = Record<string, unknown> & { orderId: string; vendor: string };
+
+export default createWorkflowBuilder({ id: "wf.odoo.approval-chain", name: "Approval → Odoo" })
+  .trigger(new ManualTrigger<OrderJson>("Start", [{ orderId: "42", vendor: "ACME" }]))
+  // humanApproval emits OrderJson & { decision: HumanApprovalDecisionResult }
+  .humanApproval(inboxApproval, {
+    title: "Approve order?",
+    body: "Review the order.",
+    priority: "normal",
+    timeout: "24h",
+    onTimeout: "halt",
+  })
+  // create<UpstreamType>() gives typed item.json inside itemExpr; the node chains regardless of upstream shape
+  .then(
+    odooCallKwNode.create<OrderJson & { decision: unknown }>({
+      model: "sale.order",
+      method: "create",
+      args: itemExpr<unknown[], OrderJson & { decision: unknown }>(({ item }) => [
+        { partner_id: 1, origin: item.json.orderId },
+      ]),
+    }),
+  )
+  .build();
+```
+
+## Beyond CRUD — `odooCallKwNode`
+
+A `sale.order` with its `order_line` is one `create` with nested commands, which is cleaner via the
+generic node. `args`/`kwargs` map straight onto Odoo's `call_kw(model, method, args, kwargs)`.
+
+```typescript
+import { odooCallKwNode } from "@codemation/core-nodes-odoo";
+
+const createOrderWithLines = odooCallKwNode.create(
+  {
+    model: "sale.order",
+    method: "create",
+    args: [
+      {
+        partner_id: 1,
+        order_line: [
+          // Odoo command 0 = "create a new line"
+          [0, 0, { product_id: 42, product_uom_qty: 3 }],
+        ],
+      },
+    ],
+  },
+  "Create order + lines",
+  "create-order-lines",
+);
+```
+
+## Credential
+
+The `odoo` slot is declared by the nodes — bind an Odoo credential (instance URL + database + API key)
+to it in the canvas before activating. See `credential-development` to author a new Odoo credential
+type, or bind an existing one. Nothing to declare in the workflow beyond using the nodes.
+
+## Related
+
+- `workflow-dsl` — the builder, trigger, and flow-control spine. Start here.
+- `ai-agent` — extract structured order fields (company, line items) before the Odoo match.
+- `document-ai` — OCR an order PDF into `{ markdown, fields }` upstream of the match.

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

@@ -1,15 +1,12 @@
 ---
-name: codemation-plugin-development
-description: Guides Codemation plugin package development, including `definePlugin(...)`, plugin sandboxes, custom nodes, custom credentials, and publishable plugin package structure. Use when building or updating a Codemation plugin package or the plugin starter template.
-compatibility: Designed for Codemation plugin packages and the Codemation plugin starter template.
+name: plugin-development
+description: Packages reusable Codemation nodes and credential types as a publishable plugin with definePlugin(...), including the composition root, sandbox app, and optional MCP server declarations. Use when building or updating a Codemation plugin package.
 tags: plugin, node, package
 ---
 
 # Codemation Plugin Development
 
-## Mental model
-
-A Codemation plugin is an npm package with a `codemation.plugin.ts` composition root that calls `definePlugin(...)`. It registers custom nodes and credential types, optionally declares MCP servers, and ships a sandbox app so the plugin is immediately testable. Consumers load the built JavaScript entry (`package.json#codemation.plugin`) — not TypeScript source. Plugin code follows the same `defineNode` / `defineCredential` patterns as app-level code; the plugin boundary is purely about packaging and distribution.
+A Codemation plugin is an npm package with a `codemation.plugin.ts` composition root that calls `definePlugin(...)` (from `@codemation/host/authoring`). It registers custom nodes and credential types, optionally declares MCP servers, and ships a sandbox app so the plugin is immediately testable. Consumers load the built JavaScript entry (`package.json#codemation.plugin`) — not TypeScript source. Plugin code follows the same `defineNode` / `defineCredential` patterns as app-level code; the plugin boundary is purely about packaging and distribution.
 
 ## When to use / when NOT
 
@@ -19,7 +16,7 @@ Use this skill for published plugin packages, plugin starter work, and sandbox-d
 
 ## Decision branches & gotchas
 
-**MCP servers in plugins:** Plugin-declared `mcpServers` is a non-managed pattern for self-hosted / framework-author scenarios. In managed mode, MCP servers are loaded from the control plane — see `codemation-mcp-capabilities` for the managed path.
+**MCP servers in plugins:** Plugin-declared `mcpServers` is a non-managed pattern for self-hosted / framework-author scenarios. In managed mode, MCP servers are loaded from the control plane — see `mcp-capabilities` for the managed path.
 
 **Publishing guardrail:** `package.json#codemation.plugin` must point at runnable JavaScript (`./dist/codemation.plugin.js`). Do not rely on consumers TypeScript-loading plugin files from `node_modules`.
 

package/skills/{codemation-plugin-development → builder/plugin-development}/references/plugin-anatomy.md

@@ -6,6 +6,29 @@ Plugin authoring is a **framework-author / non-managed task**. Managed-mode agen
 
 ```ts
 import { definePlugin } from "@codemation/host/authoring";
+import { defineCredential, defineNode } from "@codemation/core";
+
+const myCredentialType = defineCredential({
+  key: "my-provider.api-key",
+  label: "My Provider API Key",
+  public: { baseUrl: "string" },
+  secret: { apiKey: "password" },
+  createSession(args) {
+    return { baseUrl: String(args.publicConfig.baseUrl ?? ""), apiKey: String(args.material.apiKey ?? "") };
+  },
+  test() {
+    return { status: "healthy", testedAt: new Date().toISOString() };
+  },
+});
+
+const myNode = defineNode({
+  key: "my-provider.ping",
+  title: "Ping",
+  credentials: { api: myCredentialType },
+  async execute() {
+    return { ok: true };
+  },
+});
 
 export default definePlugin({
   nodes: [myNode],
@@ -47,25 +70,28 @@ Consumers discover the plugin through `package.json#codemation.plugin`, which mu
 - 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", authorizeUrl, tokenUrl, scopes }`).
-- See the `codemation-credential-development` skill for detailed credential patterns.
+- See the `credential-development` skill for detailed credential patterns.
 
 ## Declaring MCP servers in a plugin
 
-> **Non-managed pattern.** In managed mode, MCP servers are loaded from the control plane — see `codemation-mcp-capabilities`. Plugin-declared MCP servers are for self-hosted / framework-author scenarios.
+> **Non-managed pattern.** In managed mode, MCP servers are loaded from the control plane — see `mcp-capabilities`. Plugin-declared MCP servers are for self-hosted / framework-author scenarios.
 
 ```ts
-import { definePlugin } from "@codemation/host/authoring";
-import type { McpServerDeclaration } from "@codemation/host/authoring";
+import type { McpServerDeclaration } from "@codemation/core";
 
-const myMcpServer: McpServerDeclaration = {
+export const myMcpServer: McpServerDeclaration = {
   id: "my-provider-mcp", // globally unique slug /^[a-z0-9-]+$/
   displayName: "My Provider",
   description: "Exposes My Provider tools to AIAgent.",
-  transport: "streamable-http",
+  transport: "http",
   url: "https://my-provider.example.com/mcp",
   acceptedCredentialTypes: ["my-provider.api-key"],
 };
+```
+
+Pass the declaration to `definePlugin` alongside the plugin's nodes and credentials:
 
+```text
 export default definePlugin({
   nodes: [myNode],
   credentials: [myCredentialType],
@@ -79,18 +105,13 @@ Use plugin-declared MCP servers only when the provider has non-standard auth or
 
 ## WorkflowTestKit
 
-```ts
-import { WorkflowTestKit } from "@codemation/core/testing";
-// For defineNode packages:
-import { registerDefinedNodes } from "@codemation/core/testing";
-registerDefinedNodes([myNode]);
-// Then use runNode(...) or run(...) for fuller graph tests.
-```
+Use `WorkflowTestKit` from `@codemation/core/testing`: construct it, register the plugin's defined nodes through its registration context, then run a workflow that wires them via `.create(...)` and assert on the emitted items.
 
 ## Binary payloads — never put bytes on item.json
 
-```ts
-// Inside execute(items, ctx) when a node fetches binary content:
+Inside `execute`, attach via `ctx.binary` (on the first arg) — never base64 on `item.json`:
+
+```text
 const stored = await ctx.binary.attach({
   name: "report.pdf",
   body: Buffer.from(bytes),

package/skills/{codemation-plugin-development → builder/plugin-development}/references/plugin-structure.md

@@ -41,8 +41,8 @@ That file is the plugin repository's source composition root. Consumers should d
 
 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:
+```text
+// Inside execute on a node that has fetched a file (ctx is on the first arg):
 const stored = await ctx.binary.attach({
   name: "report.pdf", // slot name (also the key under item.binary)
   body: Buffer.from(bytes), // Buffer / Uint8Array / Readable