@noodleseed/agent-kit 0.15.0 → 0.17.0

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

@@ -9,7 +9,7 @@ Paths are relative to this skill directory. Assets (images/fonts) are omitted fr
 | Example | Use when | Read |
 | :-- | :-- | :-- |
 | `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. | `examples/hello/src/server.ts` |
-| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. | `examples/weather/src/server.ts` |
+| `weather` | HTTP connectors, multi-step flows, a list-returning connector op (whole-array bind + compute narrowing), and the sandboxed compute connector. | `examples/weather/src/server.ts` |
 | `food-ordering` | Consumer ordering MCP App widgets, app-only helpers, cart state, assets, branding, and handoff. | `examples/food-ordering/src/server.ts` |
 | `acme-discovery` | Top-of-funnel discovery→handoff: a discovery carousel, a `create_handoff` deep link, and a design-first UX spec + wireframe. | `examples/acme-discovery/src/server.ts` + `design/` |
 | `acme-tasks` | A two-way productivity app designed around its top-3 prioritized flows (capture/prioritize/complete), with a design-first flow spec + wireframe. | `examples/acme-tasks/src/server.ts` + `design/` |

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

@@ -144,8 +144,8 @@ const crm = connector('crm')
         method: 'GET',
         path: '/tickets',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ subject: z.string().optional(), status: z.string().optional() }),
         response: { subject: '${response.subject}', status: '${response.status}' },
       },
     },
@@ -195,8 +195,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/orders',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { id: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ id: z.string().optional(), status: z.string().optional() }),
         response: { id: '${response.id}', status: '${response.status}' },
       },
       get_tracking: {
@@ -204,8 +204,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/tracking',
         query: ['order_id'],
-        input: { order_id: { type: 'string', required: true } },
-        output: { url: { type: 'string' } },
+        input: z.object({ order_id: z.string() }),
+        output: z.object({ url: z.string().optional() }),
         response: { url: '${response.url}' },
       },
     },

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

@@ -26,5 +26,7 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | 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 |
 | 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 (a `.body` segment, when the parsed body is bound directly 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}`) |
+| A connector should return a list but returns one item, `undefined`, or the whole raw objects | A `${response.arr[0]…}` mapping picks ONE element; a response mapping cannot reshape array items and a tool’s Zod output does not strip them at runtime | Bind the whole array with `${response.<arr>}`, then narrow each element in a compute connector (`references/connect-an-api.md` → “Return a list”) |
+| `noodle dev` boots but the loopback returns `-32600 "not found"` (or 404) for a valid server | A required `secret(...)` is unresolved — a missing secret fails compile *closed* at boot so nothing is served; the local secret was set at a scope `noodle dev` does not read | Set the secret at the scope your local `noodle dev` resolves — `noodle secrets set NAME --runtime local --scope org --org local --from-env NAME`; the clear `missing_secret` line is in the `noodle dev` boot log, not the HTTP response (`references/connect-an-api.md` → “Set the secret for local runs”) |
 | 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.15.0
-hash: e623fd6ca7caad0f
+version: 0.17.0
+hash: 39c6a606c728d164
 ---
 
 # Noodle Seed
@@ -15,6 +15,8 @@ Use this skill for local Noodle Seed project work in Codex.
 
 This CLI is agent-native: the cold-agent-path commands speak the `--json` envelope (hosted admin/ops commands are still being normalized). Drive the loop by parsing machine state, not human prose. The full envelope, exit codes, and output modes are in `references/agent-contract.md`.
 
+**Discover the skill first.** Before authoring anything, read this whole `SKILL.md` and scan the `## References` index below (including `references/examples.md`) so you build from the shipped patterns — connectors that return live lists, secret scoping, widgets, testing — instead of rediscovering them. Open the references your task touches in full.
+
 Before authoring, design the experience — the funnel/handoff boundary, tools, widgets, display modes, and grounding — see `references/experience-design.md`. Then run the loop:
 
 1. **Discover** — `noodle commands --json`: every command, subcommand, flag, and exit code (don't read source).
@@ -22,7 +24,7 @@ Before authoring, design the experience — the funnel/handoff boundary, tools,
 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. **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.
+6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret at the scope your local `noodle dev` resolves (`noodle secrets set <NAME> --runtime local --scope org --org local --from-env <ENV>`; a secret set at the wrong scope leaves the loopback returning `-32600 "not found"` — see `references/connect-an-api.md`), 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`).
@@ -30,7 +32,7 @@ Before authoring, design the experience — the funnel/handoff boundary, tools,
 
 ## References
 
-Load these on demand:
+Scan all of these during discovery; open in full the ones your task touches:
 
 - `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.
 - `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.

package/skills/codex/examples/food-ordering/src/server.ts

@@ -17,28 +17,28 @@ const state = connector('noodle_state')
   .version('1.0.0')
   .operation('read_state', {
     type: 'read',
-    input: {
-      handle: { type: 'string', required: true },
-      key: { type: 'string' },
-    },
-    output: {
-      value: { type: 'object', required: true },
-      revision: { type: 'integer', required: true },
-      status: { type: 'string', required: true },
-    },
+    input: z.object({
+      handle: z.string(),
+      key: z.string().optional(),
+    }),
+    output: z.object({
+      value: z.record(z.string(), z.unknown()),
+      revision: z.number().int(),
+      status: z.string(),
+    }),
   })
   .operation('patch_state', {
     type: 'action',
-    input: {
-      handle: { type: 'string', required: true },
-      expectedRevision: { type: 'integer', required: true },
-      value: { type: 'object', required: true },
-    },
-    output: {
-      value: { type: 'object', required: true },
-      revision: { type: 'integer', required: true },
-      status: { type: 'string', required: true },
-    },
+    input: z.object({
+      handle: z.string(),
+      expectedRevision: z.number().int(),
+      value: z.record(z.string(), z.unknown()),
+    }),
+    output: z.object({
+      value: z.record(z.string(), z.unknown()),
+      revision: z.number().int(),
+      status: z.string(),
+    }),
   });
 
 const stores = [

package/skills/codex/examples/weather/README.md

@@ -1,15 +1,22 @@
 # Weather Briefing
 
-A single declarative tool that shows the runtime's breadth working together, with **no auth and no API
+Two declarative tools that show the runtime's breadth working together, with **no auth and no API
 keys**. The `weather_briefing` tool takes a city name and runs a **three-step flow**:
 
-Capability slots: HTTP connector authoring, ordered fulfilment flows, query/response mapping, and sandboxed
-compute.
+Capability slots: HTTP connector authoring, ordered fulfilment flows, query/response mapping,
+**list-returning connector output** (a connector that returns a live, variable-length array), and
+sandboxed compute.
 
 1. **`geo.search`** → geocode the city to coordinates (Open-Meteo Geocoding API)
 2. **`forecast.current`** → fetch current weather for those coordinates (Open-Meteo Forecast API)
 3. **`brief.summarize`** → derive a human-readable briefing in a **WASM/QuickJS compute sandbox**
 
+The second tool, `search_places`, shows a connector returning a **live, variable-length list**: it binds
+the whole Open-Meteo geocoding `results` array with `${response.results}`, then narrows each match to
+`{ id, label }` in a compute connector — the "search → a list of options the model can pick from"
+pattern. Narrowing lives in compute because a `${...}` response mapping cannot iterate an array and a
+tool's Zod output does not strip fields at runtime.
+
 It exercises, in one TypeScript-authored app:
 
 - **Server-level branding** with semantic tokens carried through the runtime artifact for any generated
@@ -17,8 +24,12 @@ It exercises, in one TypeScript-authored app:
 - **Ordered flow execution** with outputs threaded between steps (`${steps.geo.latitude}` → next step).
 - **Two HTTP connectors on two different hosts**, each with its own egress allowlist.
 - **Query parameters** (`query: [...]`) and a constant query baked into the path (`?current_weather=true`).
-- **Deep response mapping** with the `${...}` language (`${response.results[0].latitude}`,
-  `${response.current_weather.temperature}`).
+- **Deep response mapping** with the `${...}` language — single-element indexing
+  (`${response.results[0].latitude}`, `${response.current_weather.temperature}`) **and** whole-array
+  binding (`${response.results}` returns the entire list verbatim).
+- **A list-returning connector + compute narrowing** — `geo.search_list` binds the whole `results`
+  array; `places.narrow` reduces each element to `{ id, label }` and normalizes the no-results case
+  to `[]`.
 - **Sandboxed compute** (no network/fs/env/clock) turning raw numbers into conditions + advice.
 - **Typed input/output schemas** emitted as JSON Schema 2020-12.
 
@@ -52,3 +63,23 @@ Example result (live data, abbreviated):
 ```
 
 Try other cities (`Reykjavik`, `Singapore`, `Denver`) to see the conditions and advice change.
+
+Call `search_places` to see the **list-returning** tool — one query, many matches:
+
+```bash
+curl -s "$URL" \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -H 'mcp-protocol-version: 2025-11-25' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_places","arguments":{"query":"Springfield"}}}'
+```
+
+```json
+{
+  "places": [
+    { "id": "4951788", "label": "Springfield, Massachusetts, United States" },
+    { "id": "4250542", "label": "Springfield, Illinois, United States" },
+    { "id": "4508722", "label": "Springfield, Ohio, United States" }
+  ]
+}
+```

package/skills/codex/examples/weather/src/server.ts

@@ -19,13 +19,13 @@ const geocoding = connector('open_meteo_geocoding')
         method: 'GET',
         path: '/v1/search',
         query: ['name'],
-        input: { name: { type: 'string', required: true } },
-        output: {
-          latitude: { type: 'number', required: true },
-          longitude: { type: 'number', required: true },
-          place: { type: 'string' },
-          country: { type: 'string' },
-        },
+        input: z.object({ name: z.string() }),
+        output: z.object({
+          latitude: z.number(),
+          longitude: z.number(),
+          place: z.string().optional(),
+          country: z.string().optional(),
+        }),
         response: {
           latitude: '${response.results[0].latitude}',
           longitude: '${response.results[0].longitude}',
@@ -33,6 +33,23 @@ const geocoding = connector('open_meteo_geocoding')
           country: '${response.results[0].country}',
         },
       },
+      // A LIST-returning read. `${response.results}` binds the WHOLE array verbatim — a
+      // variable-length list of place objects — with no pagination (Open-Meteo returns every match in
+      // one page). Contrast the `search` op above, which indexes a single element (`results[0]`). To
+      // reduce each element to a few fields, narrow it in the `geo_places` compute connector below: a
+      // response mapping cannot iterate an array, and a tool's Zod output does not strip fields at
+      // runtime.
+      search_list: {
+        type: 'read',
+        method: 'GET',
+        path: '/v1/search',
+        query: ['name', 'count'],
+        input: z.object({ name: z.string(), count: z.number().optional() }),
+        output: z.object({ results: z.array(z.unknown()).optional() }),
+        response: {
+          results: '${response.results}',
+        },
+      },
     },
   });
 
@@ -47,15 +64,12 @@ const forecast = connector('open_meteo_forecast')
         method: 'GET',
         path: '/v1/forecast?current_weather=true',
         query: ['latitude', 'longitude'],
-        input: {
-          latitude: { type: 'number', required: true },
-          longitude: { type: 'number', required: true },
-        },
-        output: {
-          temperature: { type: 'number' },
-          windspeed: { type: 'number' },
-          weathercode: { type: 'number' },
-        },
+        input: z.object({ latitude: z.number(), longitude: z.number() }),
+        output: z.object({
+          temperature: z.number().optional(),
+          windspeed: z.number().optional(),
+          weathercode: z.number().optional(),
+        }),
         response: {
           temperature: '${response.current_weather.temperature}',
           windspeed: '${response.current_weather.windspeed}',
@@ -69,18 +83,18 @@ const brief = connector('weather_brief')
   .version('1.0.0')
   .compute('summarize', {
     type: 'read',
-    input: {
-      place: { type: 'string', required: true },
-      country: { type: 'string' },
-      temperature: { type: 'number', required: true },
-      windspeed: { type: 'number', required: true },
-      weathercode: { type: 'number', required: true },
-    },
-    output: {
-      conditions: { type: 'string', required: true },
-      headline: { type: 'string', required: true },
-      advice: { type: 'string', required: true },
-    },
+    input: z.object({
+      place: z.string(),
+      country: z.string().optional(),
+      temperature: z.number(),
+      windspeed: z.number(),
+      weathercode: z.number(),
+    }),
+    output: z.object({
+      conditions: z.string(),
+      headline: z.string(),
+      advice: z.string(),
+    }),
     // A real function — type-checked here, serialized to source and run in the sandbox. It must be
     // self-contained: no imports, no closure over outer variables, synchronous.
     run: (input) => {
@@ -132,12 +146,40 @@ const brief = connector('weather_brief')
     },
   });
 
+// Narrowing a live list to `{ id, label }` summaries is the ONE reshape a response mapping cannot do
+// (the `${...}` language has no per-item iteration) and a tool's Zod output does not enforce at runtime
+// — so it happens here, in a sandboxed compute connector (a connector is HTTP or compute, not both).
+// This also normalizes the no-results case (Open-Meteo omits `results` when nothing matches) to `[]`.
+const placeNarrow = connector('geo_places')
+  .version('1.0.0')
+  .compute('narrow', {
+    type: 'read',
+    input: z.object({ results: z.unknown().optional() }),
+    output: z.object({ places: z.array(z.unknown()) }),
+    // Self-contained: no imports, no closure over outer variables, synchronous.
+    run: (input) => {
+      const raw = input.results;
+      const list = Array.isArray(raw) ? raw : [];
+      const places = list.map((entry) => {
+        const parts = [entry.name, entry.admin1, entry.country].filter(
+          (part) => typeof part === 'string' && part.length > 0,
+        );
+        const id =
+          entry.id !== undefined && entry.id !== null
+            ? String(entry.id)
+            : `${entry.latitude},${entry.longitude}`;
+        return { id, label: parts.join(', ') };
+      });
+      return { places };
+    },
+  });
+
 export default server(
   'weather_briefing',
   {
     title: 'Weather Briefing',
     version: '1.0.0',
-    use: { geo: geocoding, forecast, brief },
+    use: { geo: geocoding, forecast, brief, places: placeNarrow },
     branding: {
       name: 'Weather Briefing',
       accent: '#0284C7',
@@ -186,5 +228,22 @@ export default server(
         };
       },
     }),
+    // A connector that returns a live, variable-length LIST: search a place name, get back the
+    // matching locations as `{ id, label }` options the model can resolve against. The HTTP op binds
+    // the whole array; the compute connector narrows each element to the two fields the model speaks
+    // from. Append new tools AFTER existing ones so `tools[0]` stays stable for host harnesses.
+    tool('search_places', {
+      description:
+        'Search a place name and return the matching locations as a list of { id, label } options.',
+      input: z.object({ query: z.string() }),
+      output: z.object({
+        places: z.array(z.object({ id: z.string(), label: z.string() })),
+      }),
+      fulfil: ({ input, connectors }) => {
+        const found = connectors.geo.search_list({ name: input.query });
+        const narrowed = connectors.places.narrow({ results: found.results });
+        return { places: narrowed.places };
+      },
+    }),
   ],
 );

package/skills/codex/examples/weather/test/server.test.ts

@@ -5,4 +5,25 @@ describe('weather example', () => {
   it('exports a Noodle server definition', () => {
     expect(typeof app.toManifest).toBe('function');
   });
+
+  it('adds a list-returning search_places tool without disturbing tool order', async () => {
+    const manifest = (await app.toManifest()) as {
+      tools: ReadonlyArray<{ name: string }>;
+      connectors?: Record<string, { id: string; version: string }>;
+    };
+    const toolNames = manifest.tools.map((t) => t.name);
+    // The original briefing tool stays first — host harnesses (the online e2e) read `tools[0]`,
+    // so new tools are appended, never prepended.
+    expect(toolNames[0]).toBe('weather_briefing');
+    expect(toolNames).toContain('search_places');
+    expect(toolNames.indexOf('search_places')).toBeGreaterThan(
+      toolNames.indexOf('weather_briefing'),
+    );
+    // The list is produced by a whole-array-bind HTTP op (`search_list`) narrowed to {id,label}
+    // through a separate compute connector (`geo_places`).
+    expect(manifest.connectors?.places).toEqual({ id: 'geo_places', version: '1.0.0' });
+    const wire = JSON.stringify(manifest);
+    expect(wire).toContain('search_list');
+    expect(wire).toContain('narrow');
+  });
 });

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

@@ -55,16 +55,16 @@ const crm = connector('crm').version('1.0.0').http({
       method: 'GET',
       path: '/customers',
       query: ['email'],
-      input: { email: { type: 'string', required: true } },
-      output: { id: { type: 'string', required: true }, name: { type: 'string' } },
+      input: z.object({ email: z.string() }),
+      output: z.object({ id: z.string(), name: z.string().optional() }),
       response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
     },
     create_ticket: {
       type: 'action',
       method: 'POST',
       path: '/tickets',
-      input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
-      output: { ticket_id: { type: 'string', required: true } },
+      input: z.object({ customer_id: z.string(), body: z.string() }),
+      output: z.object({ ticket_id: z.string() }),
       request: { customer_id: '${args.customer_id}', body: '${args.body}' },
       response: { ticket_id: '${response.id}' },
     },
@@ -120,16 +120,16 @@ const tasks = connector('tasks').version('1.0.0').http({
       method: 'GET',
       path: '/tasks',
       query: ['query'],
-      input: { query: { type: 'string', required: true } },
-      output: { matches: { type: 'array', required: true } },
+      input: z.object({ query: z.string() }),
+      output: z.object({ matches: z.array(z.unknown()) }),
       response: { matches: '${response.results}' },
     },
     close_task: {
       type: 'action',
       method: 'POST',
       path: '/tasks/{id}/close',
-      input: { id: { type: 'string', required: true } },
-      output: { ok: { type: 'boolean', required: true } },
+      input: z.object({ id: z.string() }),
+      output: z.object({ ok: z.boolean() }),
       response: { ok: '${response.ok}' },
     },
   },
@@ -163,8 +163,8 @@ The model never sees a task id from the user; `find_tasks` returns `{ id, title
 
 ```ts
 const scoring = connector('scoring').version('1.0.0').compute('normalize', {
-  input: { email: { type: "string", required: true }, priority: { type: "string" } },
-  output: { score: { type: "number", required: true } },
+  input: z.object({ email: z.string(), priority: z.string().optional() }),
+  output: z.object({ score: z.number() }),
   calls: { find_customer: 'crm.find_customer' },
   limits: { timeoutMs: 1000, maxHostCalls: 2 },
   run(input, { callOperation }) {

package/skills/codex/references/connect-an-api.md

@@ -8,7 +8,10 @@ drift. Probe the live API, learn the real shape, then encode it as a `connector`
 - Secure the key first
 - Probe the live API
 - Model the connector from the observed shape
+- Return a list
+- Create, update, delete
 - Design intent tools
+- Set the secret for local runs
 - Prove real output
 - Then build the app
 
@@ -19,7 +22,7 @@ managed secret and reference it only as `secret(...)`:
 
 ```sh
 export SOME_API_KEY=…            # the user sets this; it never appears in a file or prompt
-noodle secrets set SOME_API_KEY --from-env SOME_API_KEY
+noodle secrets set SOME_API_KEY --runtime local --scope org --org local --from-env SOME_API_KEY   # local-run scope — see "Set the secret for local runs"
 ```
 
 In `server.ts` the key is only ever `secret("SOME_API_KEY")` — keep the raw value out of code, tests,
@@ -53,6 +56,51 @@ Encode the API as an HTTP connector, mapping only the fields you actually saw in
 The full connector shape, every `auth.kind`, and compute connectors are in
 `references/authoring-workflow.md`.
 
+## Return a list
+
+Most real tools return a variable-length list (search results, a user’s tasks). Bind the **whole array** — a single `${response.path}` returns the referenced value verbatim, arrays included:
+
+```ts
+// The API returns { results: [ { id, name, country, … }, … ] }
+output: z.object({ places: z.array(z.unknown()) }),
+response: { places: '${response.results}' },
+```
+
+Three things that are easy to get subtly wrong:
+
+- **A response mapping cannot iterate.** There is no per-item / `map` / `item` construct, so you cannot reshape `[{…30 fields}]` into `[{ id, label }]` inside a `response:` block — bind the whole array.
+- **A tool's Zod `output` does not strip at runtime.** It only advertises the JSON Schema; the runtime returns your `fulfil` output verbatim, so `z.array(z.object({ id, label }))` will NOT drop extra element fields.
+- **So narrow in a compute connector.** To reshape each element, synthesize a `label`, or normalize a missing array to `[]`, pass the whole array to a `.compute(...)` op whose `run` maps it (a connector is HTTP **or** compute, not both — use a second connector). To only *drop* known fields without reshaping, `projection: { hiddenFields: [...] }` deletes them from each element. Worked example: `examples/weather` — `search_list` binds the array, then `geo_places.narrow` reshapes to `{ id, label }` and normalizes no-results to `[]`; `examples/sharepoint-lists` shows the same pattern against a real API.
+
+For a **paginated** API, collect across pages with a `pagination` config; the collected list is then `${response.items}`:
+
+```ts
+pagination: {
+  kind: 'cursor',                       // or 'pageNumber'
+  items: '${response.results}',         // the array on ONE page
+  nextCursor: '${response.next_cursor}', // 'pageNumber' uses hasMore + pageParam instead
+  cursorParam: 'cursor',
+  maxPages: 5, maxItems: 100,
+},
+// items / nextCursor / hasMore run over ONE raw page; your response mapping runs over the
+// collected aggregate, so the full list is:
+response: { tasks: '${response.items}' },
+```
+
+## Create, update, delete
+
+Pair the read/list with the mutations your intent tools need:
+- **Create / update** — `method: 'POST'` / `'PATCH'`; the request body is authored as `request: { field: '${input.x}' }` — the `request` object **is** the JSON body (do not nest it under `body`), and URL query params are the operation-level `query: [...]` array.
+- **Delete / close** — many endpoints return `204 No Content`. Set `responseType: 'empty'`, which enforces the status and binds `{}` (there is no body to map).
+
+```ts
+close_task: {
+  type: 'action', method: 'POST', path: '/tasks/{id}/close',
+  input: z.object({ id: z.string() }),
+  responseType: 'empty',
+},
+```
+
 ## Design intent tools
 
 Shape tools around what the user says, not 1:1 around endpoints. Pair an id-taking action with a
@@ -60,6 +108,20 @@ find/search operation that returns `{ id, label }` summaries so the model resolv
 and map each response to a few labelled fields the model can speak from. See the "Design tools for the
 model" section of `references/authoring-workflow.md`.
 
+## Set the secret for local runs
+
+`noodle secrets set NAME --from-env NAME` **without a scope** writes to your global target (or errors) — which a local `noodle dev` never reads. Local `dev` resolves secrets under `org=local`, `app=<project-dir-slug>`, `env=dev` (the `…/o/local/<app>/dev/mcp` URL it prints). Set the secret at a matching local scope:
+
+```sh
+# Simplest — org scope is visible to every local app. Pin --runtime local so a cloud login
+# (a non-local default runtime) does not send it to the hosted control plane:
+noodle secrets set SOME_API_KEY --runtime local --scope org --org local --from-env SOME_API_KEY
+# Or the exact env scope, using the app slug from the printed dev URL:
+noodle secrets set SOME_API_KEY --runtime local --scope env --org local --app <app-slug> --env dev --from-env SOME_API_KEY
+```
+
+Local secrets live in `./.env.noodle` (never commit it). **Symptom to recognize:** a required `secret(...)` that can’t resolve fails compile *closed*, so nothing is served. `noodle tools call` / `noodle test` / `noodle dev` name this directly as `connector_secret_unresolved` with the exact scoped-secret fix; an external MCP client (Inspector/mcpjam) hitting the loopback still sees an opaque `-32600 "not found"`. Either way, fix the secret’s scope, not the connector.
+
 ## Prove real output
 
 `noodle validate` / `noodle test` prove a connector tool *compiles and registers* — not that its

package/skills/codex/references/examples.md

@@ -9,7 +9,7 @@ Paths are relative to this skill directory. Assets (images/fonts) are omitted fr
 | Example | Use when | Read |
 | :-- | :-- | :-- |
 | `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. | `examples/hello/src/server.ts` |
-| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. | `examples/weather/src/server.ts` |
+| `weather` | HTTP connectors, multi-step flows, a list-returning connector op (whole-array bind + compute narrowing), and the sandboxed compute connector. | `examples/weather/src/server.ts` |
 | `food-ordering` | Consumer ordering MCP App widgets, app-only helpers, cart state, assets, branding, and handoff. | `examples/food-ordering/src/server.ts` |
 | `acme-discovery` | Top-of-funnel discovery→handoff: a discovery carousel, a `create_handoff` deep link, and a design-first UX spec + wireframe. | `examples/acme-discovery/src/server.ts` + `design/` |
 | `acme-tasks` | A two-way productivity app designed around its top-3 prioritized flows (capture/prioritize/complete), with a design-first flow spec + wireframe. | `examples/acme-tasks/src/server.ts` + `design/` |

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

@@ -144,8 +144,8 @@ const crm = connector('crm')
         method: 'GET',
         path: '/tickets',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ subject: z.string().optional(), status: z.string().optional() }),
         response: { subject: '${response.subject}', status: '${response.status}' },
       },
     },
@@ -195,8 +195,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/orders',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { id: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ id: z.string().optional(), status: z.string().optional() }),
         response: { id: '${response.id}', status: '${response.status}' },
       },
       get_tracking: {
@@ -204,8 +204,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/tracking',
         query: ['order_id'],
-        input: { order_id: { type: 'string', required: true } },
-        output: { url: { type: 'string' } },
+        input: z.object({ order_id: z.string() }),
+        output: z.object({ url: z.string().optional() }),
         response: { url: '${response.url}' },
       },
     },

package/skills/codex/references/troubleshooting.md

@@ -26,5 +26,7 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | 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 |
 | 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 (a `.body` segment, when the parsed body is bound directly 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}`) |
+| A connector should return a list but returns one item, `undefined`, or the whole raw objects | A `${response.arr[0]…}` mapping picks ONE element; a response mapping cannot reshape array items and a tool’s Zod output does not strip them at runtime | Bind the whole array with `${response.<arr>}`, then narrow each element in a compute connector (`references/connect-an-api.md` → “Return a list”) |
+| `noodle dev` boots but the loopback returns `-32600 "not found"` (or 404) for a valid server | A required `secret(...)` is unresolved — a missing secret fails compile *closed* at boot so nothing is served; the local secret was set at a scope `noodle dev` does not read | Set the secret at the scope your local `noodle dev` resolves — `noodle secrets set NAME --runtime local --scope org --org local --from-env NAME`; the clear `missing_secret` line is in the `noodle dev` boot log, not the HTTP response (`references/connect-an-api.md` → “Set the secret for local runs”) |
 | 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` |