@codemation/agent-skills 0.1.10 → 0.3.0

package/skills/codemation-custom-node-development/references/define-batch-node.md

@@ -0,0 +1,38 @@
+# Define Batch Node
+
+Load this when you need to author a `defineBatchNode(...)` node that processes all items in one call.
+
+## When to use `defineBatchNode` instead of `defineNode`
+
+- The node must see the **entire activation batch** at once (e.g. an aggregation, a bulk API call, or a node that correlates items against each other).
+- Legacy batch semantics are required by the calling workflow.
+- You need the same contract as built-in batch-shaped nodes such as `Aggregate`.
+
+For the common case (one-item-at-a-time logic), prefer `defineNode` — the engine handles iteration for you.
+
+## Minimal skeleton
+
+```ts
+import { defineBatchNode } from "@codemation/core";
+import { z } from "zod";
+
+export const sumNode = defineBatchNode({
+  key: "example.sum",
+  title: "Sum numeric field",
+  inputSchema: z.object({ value: z.number() }),
+  async run(items, { config }) {
+    const total = items.reduce((acc, item) => acc + (item.json as { value: number }).value, 0);
+    return [{ json: { total } }];
+  },
+});
+```
+
+## Contract
+
+- `run(items, context)` receives the **full array** of activation items.
+- Return an array of output items (same length as input is not required — you can fan-in to one, or fan-out to many).
+- The context object exposes `config`, `credentials`, and `execution` (same as `defineNode`).
+
+## Advanced fallback
+
+Reach for class-based node APIs when constructor-injected collaborators are required, plugin packaging needs the lower-level runtime contract, or decorators/persisted metadata need tighter control.

package/skills/codemation-custom-node-development/references/define-node-per-item.md

@@ -0,0 +1,61 @@
+# Define Node (Per-Item)
+
+Load this when you need to author a `defineNode(...)` node that processes one item at a time.
+
+## When to use `defineNode`
+
+- Node logic is straightforward.
+- The node belongs to one app or plugin package.
+- Helper-based credential slots are sufficient.
+- You do not need to inspect the entire batch in one call.
+
+## Minimal skeleton
+
+```ts
+import { defineNode } from "@codemation/core";
+import { z } from "zod";
+
+export const uppercaseNode = defineNode({
+  key: "example.uppercase",
+  title: "Uppercase field",
+  icon: "lucide:languages", // optional — Lucide, builtin:, si:, or image URL
+  inputSchema: z.object({ field: z.string() }),
+  async execute({ input, item }, { config }) {
+    return { ...input, [config.field]: String(input.field).toUpperCase() };
+  },
+});
+```
+
+## Contract
+
+- `execute(args, context)` is called **once per item** by the engine.
+- Return a plain JSON object → one output item on `main`.
+- Return a top-level array → **fan-out** (one item per element).
+- Return `emitPorts({ portName: [...] })` for multi-port routing.
+- Return an item-shaped `{ json, binary?, meta?, paired? }` when you need explicit binary/meta control.
+
+## Config fields with `itemExpr`
+
+Place **static** options (credentials, retry policy, labels) on `config`; place **per-item** values in `inputs` using `itemExpr` on config fields — consistent with built-in nodes.
+
+## Input schema and `inputSchema`
+
+Supply `inputSchema` (Zod) to get typed `input` in `execute` and to drive the canvas form. The engine validates items against it before calling `execute`.
+
+## Testing with `WorkflowTestKit`
+
+```ts
+import { createEngineTestKit, registerDefinedNodes } from "@codemation/core/testing";
+
+const kit = createEngineTestKit();
+registerDefinedNodes([uppercaseNode]);
+const result = await kit.runNode(uppercaseNode, { json: { field: "hello" } });
+```
+
+Use `WorkflowTestKit` from `@codemation/core/testing` for engine-backed tests without the host.
+
+## Custom assertion nodes
+
+Set `emitsAssertions: true` on the node config to record results into `TestSuiteRun` infrastructure. The host's `TestSuiteRunTracker` listens for `nodeCompleted` events on runs with `ctx.testContext` set and persists each emitted item (matching `AssertionResult`) as a `TestAssertion` row.
+
+Per-item nodes can also read `ctx.testContext?.{testSuiteRunId, testCaseIndex}` to branch on test mode — useful for synthetic outputs or skipping irreversible side effects.

package/skills/codemation-custom-node-development/references/node-patterns.md

@@ -1,5 +1,7 @@
 # Node Patterns
 
+Load this when working with file data, binary payloads, HTTP binaries, MS Graph attachments, or when you need reference on fan-out return shapes and polling-trigger binary patterns.
+
 ## Start here
 
 Use `defineNode(...)` when:
@@ -78,3 +80,142 @@ Reach for class-based node APIs when:
   1. In `runCycle` (the polling step), fetch only the **metadata** (id, name, contentType, size). The result is persisted into the trigger's setup state and into emitted item JSON, so it must stay small.
   2. In `execute(items, ctx)`, when the cfg opts into downloads, fetch each blob's bytes from the source API and register them via `ctx.binary.attach(...)`. Then return items via `ctx.binary.withAttachment(item, slot, stored)`.
 - **Do not** request the full payload in the polling fetch (e.g. Microsoft Graph `$expand=attachments` returns base64 `contentBytes` inline; use `$expand=attachments($select=id,name,contentType,size)` to keep the response light). Large polling responses bloat the run state on every cycle, even when no item is emitted.
+
+## Binary payloads in sub-workflow chains
+
+Binary slots attached inside a node survive SubWorkflow boundaries with no extra work. The shared `BinaryStorage` DI singleton means `ctx.binary.openReadStream` works regardless of which run originally stored the bytes.
+
+### Pattern: attach in a node, read in the parent after SubWorkflow
+
+```ts
+// Child node — attaches a slot and returns the modified item.
+export const parseAndStoreNode = defineNode({
+  key: "example.parse-store",
+  title: "Parse and Store",
+  inputSchema: z.object({ filename: z.string() }),
+  async execute({ input, item }, { binary }) {
+    const bytes = Buffer.from("...parsed content...");
+    const att = await binary.attach({
+      name: "parsed",
+      body: bytes,
+      mimeType: "text/plain",
+      filename: `${input.filename}.txt`,
+    });
+    return binary.withAttachment(item, "parsed", att);
+  },
+});
+```
+
+After `SubWorkflowNode` returns, the parent's continuation nodes see `item.binary["parsed"]` and can call `ctx.binary.openReadStream(item.binary["parsed"])` to read the bytes.
+
+### Testing binary across SubWorkflow with `WorkflowTestKit`
+
+```ts
+import { DefaultExecutionContextFactory, InMemoryBinaryStorage } from "@codemation/core";
+import { createEngineTestKit } from "@codemation/core/testing";
+import { ItemHarnessNodeConfig } from "@codemation/core/testing";
+
+const storage = new InMemoryBinaryStorage();
+const kit = createEngineTestKit({
+  executionContextFactory: new DefaultExecutionContextFactory(storage),
+});
+
+// Use ItemHarnessNodeConfig (NOT CallbackNodeConfig) for nodes that must modify items:
+const attachNode = new ItemHarnessNodeConfig(
+  "Attach",
+  z.unknown(),
+  async ({ item, ctx }) => {
+    const att = await ctx.binary.attach({
+      name: "doc",
+      body: Buffer.from("content"),
+      mimeType: "application/pdf",
+      filename: "doc.pdf",
+    });
+    return ctx.binary.withAttachment(item as Item, "doc", att);
+  },
+  { id: "attach" },
+);
+// CallbackNodeConfig is fine for assertion-only (observe) nodes — it echoes input unchanged.
+```
+
+Important: `CallbackNodeConfig` discards its callback return value and always echoes input items. Never use it for nodes that must attach binary or transform items.
+
+## MS Graph: selective attachment download
+
+Use `OutlookAttachmentDownload` from `@codemation/core-nodes-msgraph` when you have already obtained attachment metadata (filename, contentType, id) and want to download only specific attachments.
+
+```ts
+import { onNewMsGraphMailTrigger, outlookAttachmentDownloadNode } from "@codemation/core-nodes-msgraph";
+
+workflow("wf.download-resumes")
+  .trigger(onNewMsGraphMailTrigger, { mailbox: "me", folderId: "inbox" })
+  .then(
+    outlookAttachmentDownloadNode.create(
+      {
+        messageId: "", // falls back to item.json when empty
+        attachmentId: "", // falls back to item.json when empty
+        binarySlot: "resume",
+        sizeCapBytes: 10 * 1024 * 1024,
+      },
+      "DownloadResume",
+    ),
+  )
+  .build();
+```
+
+Key constraints:
+
+- Only `#microsoft.graph.fileAttachment` is supported — `itemAttachment` / `referenceAttachment` throw immediately.
+- Set `keepBinaries: true` on any downstream node that needs to pass the binary slot forward.
+- The credential is `msGraphMailOAuthCredentialType`; `Mail.Read` scope is sufficient.
+
+## HTTP + binary: download to a slot, then upload from a slot
+
+`HttpRequest` (from `@codemation/core-nodes`) natively handles binary response and request bodies.
+
+### Download a file to a binary slot
+
+```ts
+import { HttpRequest } from "@codemation/core-nodes";
+import { workflow } from "@codemation/host";
+
+export default workflow("wf.download-pdf")
+  .manualTrigger<{ url: string }>("Start", { url: "" })
+  .then(
+    new HttpRequest("DownloadResume", {
+      responseFormat: "binary",
+      responseBinarySlot: "resume", // default is "response"
+      responseSizeCapBytes: 10 * 1024 * 1024, // 10 MiB cap (default 100 MiB)
+    }),
+  )
+  .build();
+// item.json gets: { status, headers, binarySlot, contentType, size, filename? }
+// item.binary["resume"] holds the BinaryAttachment reference — never base64.
+```
+
+### Upload binary bytes from a slot
+
+```ts
+new HttpRequest("UploadResume", {
+  method: "POST",
+  url: "https://api.example.com/files",
+  body: { kind: "binary", slot: "resume" },
+  // Content-Type defaults to the attachment's mimeType.
+});
+```
+
+### Download then upload (full round-trip)
+
+```ts
+export default workflow("wf.mirror-pdf")
+  .manualTrigger<{ sourceUrl: string; targetUrl: string }>("Start", { sourceUrl: "", targetUrl: "" })
+  .then(new HttpRequest("Download", { urlField: "sourceUrl", responseFormat: "binary", responseBinarySlot: "file" }))
+  .then(new HttpRequest("Upload", { urlField: "targetUrl", method: "PUT", body: { kind: "binary", slot: "file" } }))
+  .build();
+```
+
+Key rules:
+
+- Never put bytes or base64 in `item.json` — always use `ctx.binary`.
+- `responseSizeCapBytes` is checked against `Content-Length` before reading the body; set it for untrusted sources.
+- Use `keepBinaries: true` on downstream nodes that must forward the slot.

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

@@ -1,45 +1,41 @@
 ---
 name: codemation-framework-concepts
-description: Explains Codemation package boundaries, runtime concepts, observability shape, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, telemetry, or runtime modes.
+description: Explains Codemation package boundaries, runtime concepts, observability shape, and the normal consumer mental model. Use when the user asks where code belongs across `@codemation/core`, `@codemation/host`, `@codemation/next-host`, `@codemation/cli`, workflows, plugins, credentials, activation, telemetry, or runtime modes. Read this first when starting any Codemation task — it points at the right skill for the work.
 compatibility: Designed for Codemation apps, plugins, and framework contributors.
+tags: concepts, architecture
 ---
 
 # Codemation Framework Concepts
 
-## Use this skill when
+## Mental model
 
-Use this skill to explain package ownership, runtime shape, observability boundaries, and the boundary between consumer code and framework code.
+Codemation is a workflow engine with a layered package structure. `@codemation/core` owns the engine and runtime contracts (must stay pure — no HTTP, UI, or vendor SDKs). `@codemation/host` adds persistence, credentials, APIs, and scheduler wiring. `@codemation/next-host` is the framework UI shell. `@codemation/cli` runs local development, build, and serve. Consumer apps define behavior in `codemation.config.ts` and `src/workflows/` — they never touch core internals.
 
-Do not use this skill as a substitute for detailed CLI, workflow DSL, or plugin implementation guidance when the user already knows the concept they need.
+## When to use / when NOT
 
-## Core map
+Use this skill to orient on package ownership, runtime shape, observability boundaries, and the consumer/framework divide.
+Do not use as a substitute for detailed CLI, workflow DSL, or plugin implementation guidance when you already know which skill you need.
 
-1. `@codemation/core` owns the engine, runtime contracts, and workflow DSL foundations.
-2. `@codemation/host` adds config loading, persistence, credentials, APIs, and scheduler wiring.
-3. `@codemation/next-host` owns the framework UI.
-4. `@codemation/cli` runs local development, build, serve, and user commands.
-5. Consumer apps define `codemation.config.ts` and workflow files.
+## Core concepts
 
-## Important concepts
+- **workflows** define behavior; **triggers** start runs; **nodes** process items; **items** carry `item.json` data.
+- **credentials** provide typed runtime resources (bound per operator instance, not per workflow code).
+- **activation** is framework-managed and happens in the UI — consumer code does not call it directly.
+- **telemetry** is observability-first: traces, spans, artifacts, and metric points are framework-owned runtime data.
+- **workflow testing** is a first-class primitive: `TestTrigger` yields one item per test case; `Assertion` nodes record per-run results into `TestAssertion` rows; the canvas exposes a Tests tab.
+- **run retention** and **telemetry retention** can differ — trend data can outlive raw run state.
 
-- workflows define behavior
-- triggers start runs
-- nodes process items
-- items carry workflow data
-- credentials provide typed runtime resources
-- activation is framework-managed and happens in the UI
-- telemetry is observability-first: traces, spans, artifacts, and metric points are framework-owned runtime data
-- run retention and telemetry retention can differ, so trend data can outlive raw run state
-- **workflow testing** is a first-class primitive: a `TestTrigger` node yields one item per test case, the orchestrator dispatches a workflow run per case with `executionOptions.testContext` set, and `Assertion` nodes (`emitsAssertions: true`) record per-run results into `TestAssertion` rows; the canvas exposes a Tests tab parallel to Live and Executions
+## Where to go next
 
-## Runtime rule of thumb
-
-1. Start with the minimum setup.
-2. Move to shared PostgreSQL and Redis when execution needs separate worker infrastructure.
-3. Keep workflow code stable while the runtime shape grows around it.
-4. Treat telemetry as part of the runtime contract, not as ad-hoc node-local logging.
+| Task                                  | Skill                                |
+| ------------------------------------- | ------------------------------------ |
+| Authoring workflows                   | `codemation-workflow-dsl`            |
+| Building a reusable node              | `codemation-custom-node-development` |
+| Building a credential type            | `codemation-credential-development`  |
+| Packaging as a plugin                 | `codemation-plugin-development`      |
+| Calling an MCP server from a workflow | `codemation-mcp-capabilities`        |
+| CLI commands / dev loop               | `codemation-cli`                     |
 
 ## Read next when needed
 
 - Read `references/architecture-map.md` for package ownership and runtime-mode guidance.
-- Use the `codemation-workflow-dsl` skill (and its `references/workflow-testing.md`) for hands-on test authoring with TestTrigger / IsTestRun / Assertion.

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

@@ -0,0 +1,53 @@
+---
+name: codemation-mcp-capabilities
+description: Discover MCP servers registered on the Codemation control plane. Use before authoring agent workflows that reference mcpServers to find available server ids and their credential requirements.
+compatibility: Requires an installation paired with a connected control plane (Sprint 2+).
+tags: mcp, agent, tool
+---
+
+# Codemation MCP Capabilities
+
+## Mental model
+
+MCP servers extend `AIAgent` with tool access to external services (Gmail, Sheets, etc.). Server ids and credential requirements come from the control-plane registry — they are not hard-coded in framework code. The agent's `mcpServers` array contains stable server id slugs; each declared server surfaces a credential slot the operator must bind in the canvas before activation.
+
+## When to use / when NOT
+
+Use this skill before writing `agent({ mcpServers: ["..."] })` to discover available server ids and their credential types.
+Do not use for general AIAgent authoring — read `codemation-ai-agent-node` for that.
+
+## Managed mode: CP-loaded MCP servers (default path)
+
+In **managed mode**, MCP servers are loaded from the **control plane (CP)** — not declared in plugin code. Discover available servers by querying the CP registry:
+
+```
+GET /api/registry/capabilities?query=gmail
+```
+
+Response contains objects with `{ kind, id, displayName, description, acceptedCredentialTypes }`. Use `id` in the workflow's `mcpServers` array. An empty `query` string returns all registered servers.
+
+For a full wired example — cron workflow + AIAgent + mcpServers — use your harness's example-discovery tool: `find_examples({ query: "AIAgent gmail mcpServers" })` or `find_examples({ query: "mcp server" })`.
+
+## Non-managed: plugin-declared MCP servers
+
+In self-hosted / non-managed deployments, MCP servers can also be declared via `mcpServers: [...]` in a `definePlugin(...)` call. This is a framework-author pattern — do not use it in managed-mode workflows. See `references/plugin-anatomy.md` in the `codemation-plugin-development` skill for the plugin declaration syntax.
+
+## Decision branches & gotchas
+
+**Credential types:** `"oauth.google.gmail"` requires the user to connect a Google account via the credential dialog before the workflow runs. The same instance can be shared between a `GmailTrigger` and the Gmail MCP server. An empty `acceptedCredentialTypes` array means no credential is needed.
+
+**Multiple instances:** a user may have multiple instances of the same credential type (personal vs work Gmail). The canvas credential dropdown surfaces all matching instances — the operator picks the one to bind.
+
+**Bind via UI only:** there is no inline credential field on the workflow definition. The operator binds the credential instance via the canvas credential dropdown before activation.
+
+**Typical flow (managed):**
+
+1. `GET /api/registry/capabilities?query=<term>` → find `id` and `acceptedCredentialTypes`.
+2. Add `id` to `mcpServers` in the `AIAgent` config.
+3. Report: "The user will need to bind a `<type>` credential instance via the canvas before activating."
+
+## Anti-patterns
+
+- Do not guess server ids — always query the registry first.
+- Do not add `acceptedCredentialTypes` to the workflow definition — credential binding is UI-driven, not code-driven.
+- Do not declare MCP servers inside plugin code for managed-mode workflows — use the CP registry instead.

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

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

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

@@ -2,49 +2,28 @@
 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.
+tags: plugin, node, package
 ---
 
 # Codemation Plugin Development
 
-## Use this skill when
+## Mental model
 
-Use this skill for published plugin packages, plugin starter work, and sandbox-driven plugin development.
+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.
 
-Do not use this skill for ordinary consumer workflow-only changes unless the work needs plugin packaging or reusable extension boundaries.
+## When to use / when NOT
 
-## Default approach
+**Plugin authoring is a framework-author / non-managed task.** Managed-mode agents work with credential slots and workflow DSL — they do not author or modify plugin packages.
 
-1. Treat `codemation.plugin.ts` as the plugin composition root.
-2. Register custom credentials and custom nodes from explicit modules.
-3. Keep the sandbox app small and useful so plugin behavior is testable immediately.
-4. Prefer helper-based node and credential definitions first, then drop to class-based APIs only when needed.
+Use this skill for published plugin packages, plugin starter work, and sandbox-driven plugin development. Do not use for ordinary consumer workflow-only changes.
 
-## Plugin rules
+## Decision branches & gotchas
 
-1. Export a plugin with `definePlugin(...)`.
-2. Keep plugin registration separate from node and credential implementation modules.
-3. Use the sandbox app to exercise the plugin right away.
-4. Keep the package publishable like a normal npm package.
-5. Treat `codemation.plugin.ts` as the plugin repo's source composition root; consumer projects should load the built JavaScript entry declared in `package.json#codemation.plugin`.
+**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.
 
-## Common plugin pieces
-
-- `codemation.plugin.ts`: plugin registration and sandbox app source, compiled to the published plugin entry in `dist/`
-- `src/nodes/*`: custom node definitions (`defineNode` → **`execute`**; `defineBatchNode` → batch **`run`**)
-- `src/credentialTypes/*`: custom credential definitions
-- `src/index.ts`: package exports
-- `test/*.test.ts` (optional): Vitest + `WorkflowTestKit` from `@codemation/core/testing` for engine-backed unit tests without starting the full host (`pnpm test`)
-
-## Packaging guardrail
-
-- `package.json#codemation.plugin` should point at runnable JavaScript such as `./dist/codemation.plugin.js`.
-- Do not rely on consumers TypeScript-loading plugin files from `node_modules`.
-- Prefer publishing `dist/**` plus package metadata/docs rather than shipping source-only plugin entry files as runtime dependencies.
-
-## Unit tests (`WorkflowTestKit`)
-
-Import **`WorkflowTestKit`** from **`@codemation/core/testing`**. Use **`registerDefinedNodes([...])`** for `defineNode` packages, then **`runNode({ node: yourNode.create(...), items })`** or **`run({ workflow, items })`** for fuller graphs. Prefer this for fast node tests; use **`codemation dev:plugin`** when you need the UI and persistence.
+**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`.
 
 ## Read next when needed
 
-- Read `references/plugin-structure.md` for package layout and node-versus-credential guidance.
+- Read `references/plugin-anatomy.md` for the full `definePlugin(...)` code, package layout, sandbox setup, MCP server declaration, binary payload rules, and publishing guidance.
+- Read `references/plugin-structure.md` for a concise package layout reference.

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

@@ -0,0 +1,115 @@
+# Plugin Anatomy
+
+Plugin authoring is a **framework-author / non-managed task**. Managed-mode agents almost never need to create or modify plugin packages — they work with credential slots and workflow DSL. This reference is for developers building and publishing reusable Codemation plugin packages.
+
+## Quickstart
+
+```ts
+import { definePlugin } from "@codemation/host/authoring";
+
+export default definePlugin({
+  nodes: [myNode],
+  credentials: [myCredentialType],
+  // mcpServers: [...],  // optional — see MCP section below
+});
+```
+
+## Plugin package layout
+
+```text
+codemation.plugin.ts  ← composition root; calls definePlugin(...)
+src/
+  nodes/              ← defineNode / defineBatchNode / defineRestNode files
+  credentialTypes/    ← defineCredential files
+  index.ts            ← public package exports (types, session shapes)
+test/
+  *.test.ts           ← Vitest + WorkflowTestKit tests
+```
+
+## Composition root (`codemation.plugin.ts`)
+
+The single file that:
+
+- calls `definePlugin(...)` and registers nodes + credentials
+- optionally defines a sandbox app via `defineCodemationApp(...)`
+
+Consumers discover the plugin through `package.json#codemation.plugin`, which must point at built JavaScript in `dist/` — NOT TypeScript source.
+
+## Node guidance
+
+- Start with `defineNode(...)` and `execute(...)` for per-item nodes (most common).
+- Use `defineBatchNode(...)` only when the node must process the whole activation batch in one `run(items, ...)`.
+- Keep runtime logic close to the node definition; use class-based APIs only when you need constructor-injected collaborators.
+
+## Credential guidance
+
+- Start with `defineCredential(...)`.
+- Build typed sessions in `createSession(...)`.
+- Implement `test(...)` so operators can validate configuration before activation.
+- For OAuth2 redirect flows, use the URL-template variant (`auth: { kind: "oauth2", authorizeUrl, tokenUrl, scopes }`).
+- See the `codemation-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.
+
+```ts
+import { definePlugin } from "@codemation/host/authoring";
+import type { McpServerDeclaration } from "@codemation/host/authoring";
+
+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",
+  url: "https://my-provider.example.com/mcp",
+  acceptedCredentialTypes: ["my-provider.api-key"],
+};
+
+export default definePlugin({
+  nodes: [myNode],
+  credentials: [myCredentialType],
+  mcpServers: [myMcpServer],
+});
+```
+
+**Merge precedence:** plugin declarations < `codemation.config.ts` < control-plane registry. A warning is logged when a higher-priority source shadows a plugin declaration.
+
+Use plugin-declared MCP servers only when the provider has non-standard auth or when co-locating with custom nodes for the same provider. For standard OAuth/API-key providers, prefer the control-plane registry.
+
+## 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.
+```
+
+## Binary payloads — never put bytes on item.json
+
+```ts
+// Inside execute(items, ctx) when a node fetches binary content:
+const stored = await ctx.binary.attach({
+  name: "report.pdf",
+  body: Buffer.from(bytes),
+  mimeType: "application/pdf",
+  filename: "report.pdf",
+});
+const enriched = ctx.binary.withAttachment(item, "report.pdf", stored);
+```
+
+Only the `BinaryAttachment` reference (id, storageKey, mimeType, size) belongs on the item — not the bytes.
+
+## Publishing
+
+- `package.json#codemation.plugin` must point at `./dist/codemation.plugin.js`.
+- Do not rely on consumers TypeScript-loading plugin files from `node_modules`.
+- Treat the plugin as a normal npm package: install it in a Codemation app for auto-discovery.
+
+## Anti-patterns
+
+- Do not put plugin registration logic inside workflow files — use `codemation.plugin.ts`.
+- Do not ship source-only plugin entries as runtime dependencies — publish `dist/**`.
+- Do not declare an MCP server in a plugin for standard OAuth/API-key providers already in the control-plane registry.