@noodleseed/agent-kit 0.11.0 → 0.12.0

package/manifest.json

@@ -1,14 +1,14 @@
 {
-  "packageVersion": "0.11.0",
+  "packageVersion": "0.12.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "54f2a9d84455361127f40fe079715ec69c1ef737b491fc2ace896cb754ff4fe3",
+      "sha256": "0b986b87d14e9eed8add2c3d294a9c3df319847f410340815d9f4690af126c11",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/sdk-surface.md",
-      "sha256": "d5da0c1ec33aa8d2770e145293174e99cff0c73264756dafe121e818ade14abf",
+      "sha256": "410fe309a6091b469892edc55c8083b0643cae7706b3769e9b836546a6ad1235",
       "agentTarget": "codex"
     },
     {
@@ -28,7 +28,7 @@
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "ad5866ad739885592eb729fdd0bf18d602b886021309e28565a090d66f7c2e9a",
+      "sha256": "aba1853b5709cc40f341f827bae739e11142b2a6996872757b1db68e0cb35015",
       "agentTarget": "codex"
     },
     {
@@ -43,7 +43,7 @@
     },
     {
       "path": "skills/codex/references/troubleshooting.md",
-      "sha256": "4e0446d67d4ab037ecb6c9ffdf28494b42ed410f5c94ad7c498c3545f746eefb",
+      "sha256": "fe13045fab55fc660c50482540e89654bac6a925c3d189fa3e9650d7e656b7ba",
       "agentTarget": "codex"
     },
     {
@@ -63,12 +63,12 @@
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "fa975102477cd02ecdb083b4b8f747fc3fee3a7bcb5b725fe63ca9504258ba39",
+      "sha256": "909001bcf63868d51228d2c55da471c12f770b83f15958bbb9eefedb6afd0ec9",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/sdk-surface.md",
-      "sha256": "d5da0c1ec33aa8d2770e145293174e99cff0c73264756dafe121e818ade14abf",
+      "sha256": "410fe309a6091b469892edc55c8083b0643cae7706b3769e9b836546a6ad1235",
       "agentTarget": "claude-code"
     },
     {
@@ -88,7 +88,7 @@
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "ad5866ad739885592eb729fdd0bf18d602b886021309e28565a090d66f7c2e9a",
+      "sha256": "aba1853b5709cc40f341f827bae739e11142b2a6996872757b1db68e0cb35015",
       "agentTarget": "claude-code"
     },
     {
@@ -103,7 +103,7 @@
     },
     {
       "path": "skills/claude-code/references/troubleshooting.md",
-      "sha256": "4e0446d67d4ab037ecb6c9ffdf28494b42ed410f5c94ad7c498c3545f746eefb",
+      "sha256": "fe13045fab55fc660c50482540e89654bac6a925c3d189fa3e9650d7e656b7ba",
       "agentTarget": "claude-code"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: noodle-seed
 description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
-version: 0.11.0
-hash: 5aa15e5bf381543c
+version: 0.12.0
+hash: dd621716fbd94dab
 ---
 
 # Noodle Seed
@@ -20,10 +20,11 @@ This CLI is agent-native: the cold-agent-path commands speak the `--json` envelo
 3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
 4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
 5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
-6. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
-7. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
-8. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
-9. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
+6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret locally (`noodle secrets set <NAME> --from-env <ENV>`), then run a live read — `noodle tools call <read_tool> --args '{...}'` executes the connector against the real API in-process — and confirm the mapped fields are populated, not `undefined`, before trusting it. Only run a live write if it is safe/approved.
+7. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
+8. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
+9. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
+10. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
 
 ## References
 

package/skills/claude-code/references/authoring-workflow.md

@@ -36,7 +36,7 @@ Declare connectors as data, not imperative code:
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
-HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `oauth2ClientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 ## HTTP connector example
 
@@ -72,7 +72,7 @@ const crm = connector('crm').version('1.0.0').http({
 });
 ```
 
-Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "oauth2ClientCredentials", tokenUrl, clientId, clientSecret, scopes? }`; for per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
+Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
 
 ## Worked example (full server)
 
@@ -112,7 +112,7 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
 ]);
 ```
 
-More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `oauth2ClientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
 
 ## Compute connector example
 
@@ -129,7 +129,7 @@ const scoring = connector('scoring').version('1.0.0').compute('normalize', {
 });
 ```
 
-Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
+Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in acyclic `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
 
 ## Tests
 

package/skills/claude-code/references/sdk-surface.md

@@ -68,7 +68,7 @@ Minimal, complete, compiling recipes — author in `src/server.ts`, then `noodle
 
 ### Resource
 
-`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns `{ contents: [{ uri, mimeType, text }] }`. Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
+`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns the resource body itself — a plain string, or a bare content entry `{ uri, mimeType, text }` — and the runtime maps it into MCP `contents` for you. Do **not** return a `{ contents: [...] }` wrapper: the runtime already wraps it, so that double-wraps (the whole JSON ends up inside `contents[0].text`). Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
 
 ```ts
 import { resource } from '@noodleseed/one';
@@ -78,11 +78,8 @@ resource('changelog', {
   uri: 'docs://changelog',
   title: 'Changelog',
   mimeType: 'text/markdown',
-  fulfil: () => ({
-    contents: [
-      { uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' },
-    ],
-  }),
+  // Return the bare content entry (or just a string); never a { contents: [...] } wrapper.
+  fulfil: () => ({ uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' }),
 });
 
 // {var} URI-template resource: the URI variable arrives on ctx.input (a symbolic ref).
@@ -91,9 +88,9 @@ resource('ticket', {
   title: 'Support ticket',
   mimeType: 'text/markdown',
   fulfil: (ctx) => ({
-    contents: [
-      { uri: `tickets://${ctx.input.id}`, mimeType: 'text/markdown', text: `Ticket ${ctx.input.id}` },
-    ],
+    uri: `tickets://${ctx.input.id}`,
+    mimeType: 'text/markdown',
+    text: `Ticket ${ctx.input.id}`,
   }),
 });
 ```
@@ -177,4 +174,65 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
     fulfil: async ({ input }) => ({ echo: input.text }),
   }),
 ]);
+```
+
+### Conditional flow with when()
+
+`when(condition, () => record)` records the inner step(s) guarded by a condition instead of a native `if`. `when` is a **free function** (import it), the condition is `ref.equals(scalar)` (equality only — no `<`/`>`/`&&`), and the recorded step is skipped at runtime unless the condition holds. Never write a native `if` on a symbolic ref, and never call a method on one (e.g. `input.name.trim()`) — both silently mis-record or throw; compose strings with a template literal and branch with `when(...)`.
+
+```ts
+import { connector, server, tool, when, z } from '@noodleseed/one';
+
+// Two read operations; the tracking lookup only runs when the order came back shipped.
+const orders = connector('orders')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://orders.example.com',
+    allowedOrigins: ['https://orders.example.com'],
+    operations: {
+      get_order: {
+        type: 'read',
+        method: 'GET',
+        path: '/orders',
+        query: ['id'],
+        input: { id: { type: 'string', required: true } },
+        output: { id: { type: 'string' }, status: { type: 'string' } },
+        response: { id: '${response.id}', status: '${response.status}' },
+      },
+      get_tracking: {
+        type: 'read',
+        method: 'GET',
+        path: '/tracking',
+        query: ['order_id'],
+        input: { order_id: { type: 'string', required: true } },
+        output: { url: { type: 'string' } },
+        response: { url: '${response.url}' },
+      },
+    },
+  });
+
+export default server('orders_app', { title: 'Orders', version: '1.0.0', use: { orders } }, [
+  tool('track_order', {
+    description: 'Find shipment tracking for an order.',
+    input: z.object({ orderId: z.string() }),
+    output: z.object({
+      orderId: z.string(),
+      status: z.string(),
+      trackingUrl: z.string().optional(),
+    }),
+    fulfil: ({ input, connectors }) => {
+      const order = connectors.orders.get_order({ id: input.orderId });
+      // Record the tracking step only when order.status === "shipped" (equality-only condition).
+      const tracking = when(order.status.equals('shipped'), () =>
+        connectors.orders.get_tracking({ order_id: order.id }),
+      );
+      return {
+        orderId: order.id,
+        status: order.status,
+        // `.optional()` marks a ref that may be absent when its guarding step did not run.
+        trackingUrl: tracking.url.optional(),
+      };
+    },
+  }),
+]);
 ```

package/skills/claude-code/references/troubleshooting.md

@@ -25,5 +25,6 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
-| Need to invoke a deployed tool from the terminal | The `noodle` CLI is not a general MCP client and has no `call` verb | Use `noodle test` for the local smoke, `noodle tools`/`resources`/`prompts` for local listing, MCP Inspector, or `npx @mcpjam/cli@latest tools call --url <url> ...` for headless MCP probing |
+| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (`${response.body...}` when the parsed body is bound to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
+| Need to invoke a tool from the terminal | Local tools run in-process; the `noodle` CLI is not a general MCP client for **deployed** URLs (there is no `call <url>` verb) | Locally, `noodle tools call <name> --args <json>` (also `noodle resources read` / `noodle prompts get`) runs the tool against the in-process runtime — with the secret set it executes the connector against the real API, so use it to prove mapped output. For a **deployed** URL use MCP Inspector or `npx @mcpjam/cli@latest tools call --url <url> ...` |
 | One customer/session reports a bad answer or protocol error | The failure may be a model/tool error, host protocol error, or connector/runtime error | Run `noodle metrics --agent-output`, then `noodle events --tool <name> --status tool_error --json`; copy the `sessionId` into `noodle events --session <id> --json`, then match timestamps with `noodle logs` |

package/skills/codex/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: noodle-seed
 description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
-version: 0.11.0
-hash: 7cae1fbf5bdf6a0d
+version: 0.12.0
+hash: 68c2cc25462f5be7
 ---
 
 # Noodle Seed
@@ -20,10 +20,11 @@ This CLI is agent-native: the cold-agent-path commands speak the `--json` envelo
 3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
 4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
 5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
-6. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
-7. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
-8. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
-9. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
+6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret locally (`noodle secrets set <NAME> --from-env <ENV>`), then run a live read — `noodle tools call <read_tool> --args '{...}'` executes the connector against the real API in-process — and confirm the mapped fields are populated, not `undefined`, before trusting it. Only run a live write if it is safe/approved.
+7. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
+8. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
+9. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
+10. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
 
 ## References
 

package/skills/codex/references/authoring-workflow.md

@@ -36,7 +36,7 @@ Declare connectors as data, not imperative code:
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
-HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `oauth2ClientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
 ## HTTP connector example
 
@@ -72,7 +72,7 @@ const crm = connector('crm').version('1.0.0').http({
 });
 ```
 
-Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "oauth2ClientCredentials", tokenUrl, clientId, clientSecret, scopes? }`; for per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
+Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
 
 ## Worked example (full server)
 
@@ -112,7 +112,7 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
 ]);
 ```
 
-More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `oauth2ClientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
 
 ## Compute connector example
 
@@ -129,7 +129,7 @@ const scoring = connector('scoring').version('1.0.0').compute('normalize', {
 });
 ```
 
-Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
+Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in acyclic `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
 
 ## Tests
 

package/skills/codex/references/sdk-surface.md

@@ -68,7 +68,7 @@ Minimal, complete, compiling recipes — author in `src/server.ts`, then `noodle
 
 ### Resource
 
-`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns `{ contents: [{ uri, mimeType, text }] }`. Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
+`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns the resource body itself — a plain string, or a bare content entry `{ uri, mimeType, text }` — and the runtime maps it into MCP `contents` for you. Do **not** return a `{ contents: [...] }` wrapper: the runtime already wraps it, so that double-wraps (the whole JSON ends up inside `contents[0].text`). Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
 
 ```ts
 import { resource } from '@noodleseed/one';
@@ -78,11 +78,8 @@ resource('changelog', {
   uri: 'docs://changelog',
   title: 'Changelog',
   mimeType: 'text/markdown',
-  fulfil: () => ({
-    contents: [
-      { uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' },
-    ],
-  }),
+  // Return the bare content entry (or just a string); never a { contents: [...] } wrapper.
+  fulfil: () => ({ uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' }),
 });
 
 // {var} URI-template resource: the URI variable arrives on ctx.input (a symbolic ref).
@@ -91,9 +88,9 @@ resource('ticket', {
   title: 'Support ticket',
   mimeType: 'text/markdown',
   fulfil: (ctx) => ({
-    contents: [
-      { uri: `tickets://${ctx.input.id}`, mimeType: 'text/markdown', text: `Ticket ${ctx.input.id}` },
-    ],
+    uri: `tickets://${ctx.input.id}`,
+    mimeType: 'text/markdown',
+    text: `Ticket ${ctx.input.id}`,
   }),
 });
 ```
@@ -177,4 +174,65 @@ export default server('support', { title: 'Support', version: '1.0.0', use: { cr
     fulfil: async ({ input }) => ({ echo: input.text }),
   }),
 ]);
+```
+
+### Conditional flow with when()
+
+`when(condition, () => record)` records the inner step(s) guarded by a condition instead of a native `if`. `when` is a **free function** (import it), the condition is `ref.equals(scalar)` (equality only — no `<`/`>`/`&&`), and the recorded step is skipped at runtime unless the condition holds. Never write a native `if` on a symbolic ref, and never call a method on one (e.g. `input.name.trim()`) — both silently mis-record or throw; compose strings with a template literal and branch with `when(...)`.
+
+```ts
+import { connector, server, tool, when, z } from '@noodleseed/one';
+
+// Two read operations; the tracking lookup only runs when the order came back shipped.
+const orders = connector('orders')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://orders.example.com',
+    allowedOrigins: ['https://orders.example.com'],
+    operations: {
+      get_order: {
+        type: 'read',
+        method: 'GET',
+        path: '/orders',
+        query: ['id'],
+        input: { id: { type: 'string', required: true } },
+        output: { id: { type: 'string' }, status: { type: 'string' } },
+        response: { id: '${response.id}', status: '${response.status}' },
+      },
+      get_tracking: {
+        type: 'read',
+        method: 'GET',
+        path: '/tracking',
+        query: ['order_id'],
+        input: { order_id: { type: 'string', required: true } },
+        output: { url: { type: 'string' } },
+        response: { url: '${response.url}' },
+      },
+    },
+  });
+
+export default server('orders_app', { title: 'Orders', version: '1.0.0', use: { orders } }, [
+  tool('track_order', {
+    description: 'Find shipment tracking for an order.',
+    input: z.object({ orderId: z.string() }),
+    output: z.object({
+      orderId: z.string(),
+      status: z.string(),
+      trackingUrl: z.string().optional(),
+    }),
+    fulfil: ({ input, connectors }) => {
+      const order = connectors.orders.get_order({ id: input.orderId });
+      // Record the tracking step only when order.status === "shipped" (equality-only condition).
+      const tracking = when(order.status.equals('shipped'), () =>
+        connectors.orders.get_tracking({ order_id: order.id }),
+      );
+      return {
+        orderId: order.id,
+        status: order.status,
+        // `.optional()` marks a ref that may be absent when its guarding step did not run.
+        trackingUrl: tracking.url.optional(),
+      };
+    },
+  }),
+]);
 ```

package/skills/codex/references/troubleshooting.md

@@ -25,5 +25,6 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
-| Need to invoke a deployed tool from the terminal | The `noodle` CLI is not a general MCP client and has no `call` verb | Use `noodle test` for the local smoke, `noodle tools`/`resources`/`prompts` for local listing, MCP Inspector, or `npx @mcpjam/cli@latest tools call --url <url> ...` for headless MCP probing |
+| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (`${response.body...}` when the parsed body is bound to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
+| Need to invoke a tool from the terminal | Local tools run in-process; the `noodle` CLI is not a general MCP client for **deployed** URLs (there is no `call <url>` verb) | Locally, `noodle tools call <name> --args <json>` (also `noodle resources read` / `noodle prompts get`) runs the tool against the in-process runtime — with the secret set it executes the connector against the real API, so use it to prove mapped output. For a **deployed** URL use MCP Inspector or `npx @mcpjam/cli@latest tools call --url <url> ...` |
 | One customer/session reports a bad answer or protocol error | The failure may be a model/tool error, host protocol error, or connector/runtime error | Run `noodle metrics --agent-output`, then `noodle events --tool <name> --status tool_error --json`; copy the `sessionId` into `noodle events --session <id> --json`, then match timestamps with `noodle logs` |