@noodleseed/agent-kit 0.15.0 → 0.17.0

package/manifest.json

@@ -1,14 +1,14 @@
 {
-  "packageVersion": "0.15.0",
+  "packageVersion": "0.17.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "3dfbb3af5b9176302b787da3118896d4cc4b4382c674b68f956ef2d52f5adbf6",
+      "sha256": "5f24dd83ca00ad0b078de17f0a978b28ee17b17678ab103a0151f550444e1c47",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/sdk-surface.md",
-      "sha256": "410fe309a6091b469892edc55c8083b0643cae7706b3769e9b836546a6ad1235",
+      "sha256": "7275aedfb2338040f1b9f989765179ce970d1b25c77066b3d3f4f4e2fe39f7cc",
       "agentTarget": "codex"
     },
     {
@@ -28,12 +28,12 @@
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "eca8d1f2b98ee64f6beda4d983f0f0df9023ceed8bd00ffb9dd6b5025dcaa4e4",
+      "sha256": "bf59d1550ce72fa188e50e74b7d586be49a0e5473501ee3b83a5f41687ac5163",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/connect-an-api.md",
-      "sha256": "5c7d763ad57e6d6b67e3e115da48acd5bef3687acd050b776416906076cec440",
+      "sha256": "497221256ebb78300b5e4055daff3f222052a7b78fb829fd24171668dd7fc0fa",
       "agentTarget": "codex"
     },
     {
@@ -53,7 +53,7 @@
     },
     {
       "path": "skills/codex/references/troubleshooting.md",
-      "sha256": "834d2c6626dc90c009aebac3ee7ff8977a1f97dfb66cf5b955fd6414e6e2a897",
+      "sha256": "b08dc48e72fa186fc953cf7052bfb7500b4586a772a1f4c54ff1e53a29f21eb2",
       "agentTarget": "codex"
     },
     {
@@ -73,7 +73,7 @@
     },
     {
       "path": "skills/codex/references/examples.md",
-      "sha256": "7bef744d11a33f445d316e145d268035a29d108e5159c7de62899e6364840106",
+      "sha256": "bd19dead1f7b1b6610a53694a06569d3c71d149bd6c72c4a1c94c83ded13a34f",
       "agentTarget": "codex"
     },
     {
@@ -268,7 +268,7 @@
     },
     {
       "path": "skills/codex/examples/food-ordering/src/server.ts",
-      "sha256": "760817a7c1731cf0f5d721fc2fb9adcaa7c2cfe0cbaae5d97e7673a535de26b8",
+      "sha256": "491e7e7e8289d4295d09ca2a5f7035f00a06e1d9f3349c406397f90a966269df",
       "agentTarget": "codex"
     },
     {
@@ -323,7 +323,7 @@
     },
     {
       "path": "skills/codex/examples/weather/README.md",
-      "sha256": "cdad82399028f275e5ac5fabd35d373f5673839171302128ed066e3adacd6ed6",
+      "sha256": "59dd103ae387b4ef0f32e155dbe9a11d79e260310a07c0f266a16add2e8e31bd",
       "agentTarget": "codex"
     },
     {
@@ -338,22 +338,22 @@
     },
     {
       "path": "skills/codex/examples/weather/src/server.ts",
-      "sha256": "ba1ef62597885a2ec89e8c02d593bfa277763fd3a3af2154e9d1b72b06eb58f1",
+      "sha256": "95cd3a2ef47be898469d40d109f3fb89ac6e59a34fd8ad600c80dfe2908d4598",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/examples/weather/test/server.test.ts",
-      "sha256": "25047bd0c8d00c33ed485eb62b2893a7374074e9a793ca855c20a93a5fbb82d5",
+      "sha256": "6753e4db274b00d2e92405040a27609a15087227de7b13f9e9f9e19c12d3a255",
       "agentTarget": "codex"
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "b2ca82b392a9a03841db8249d5fabde456c08209c6bc3ac29679fbf5cc9dbeaa",
+      "sha256": "24cdedbf4db8484b6e06823037b5b8fd0ef7ee39a57eb0fd135d167196fea3ff",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/sdk-surface.md",
-      "sha256": "410fe309a6091b469892edc55c8083b0643cae7706b3769e9b836546a6ad1235",
+      "sha256": "7275aedfb2338040f1b9f989765179ce970d1b25c77066b3d3f4f4e2fe39f7cc",
       "agentTarget": "claude-code"
     },
     {
@@ -373,12 +373,12 @@
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "eca8d1f2b98ee64f6beda4d983f0f0df9023ceed8bd00ffb9dd6b5025dcaa4e4",
+      "sha256": "bf59d1550ce72fa188e50e74b7d586be49a0e5473501ee3b83a5f41687ac5163",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/connect-an-api.md",
-      "sha256": "5c7d763ad57e6d6b67e3e115da48acd5bef3687acd050b776416906076cec440",
+      "sha256": "497221256ebb78300b5e4055daff3f222052a7b78fb829fd24171668dd7fc0fa",
       "agentTarget": "claude-code"
     },
     {
@@ -398,7 +398,7 @@
     },
     {
       "path": "skills/claude-code/references/troubleshooting.md",
-      "sha256": "834d2c6626dc90c009aebac3ee7ff8977a1f97dfb66cf5b955fd6414e6e2a897",
+      "sha256": "b08dc48e72fa186fc953cf7052bfb7500b4586a772a1f4c54ff1e53a29f21eb2",
       "agentTarget": "claude-code"
     },
     {
@@ -418,7 +418,7 @@
     },
     {
       "path": "skills/claude-code/references/examples.md",
-      "sha256": "7bef744d11a33f445d316e145d268035a29d108e5159c7de62899e6364840106",
+      "sha256": "bd19dead1f7b1b6610a53694a06569d3c71d149bd6c72c4a1c94c83ded13a34f",
       "agentTarget": "claude-code"
     },
     {
@@ -613,7 +613,7 @@
     },
     {
       "path": "skills/claude-code/examples/food-ordering/src/server.ts",
-      "sha256": "760817a7c1731cf0f5d721fc2fb9adcaa7c2cfe0cbaae5d97e7673a535de26b8",
+      "sha256": "491e7e7e8289d4295d09ca2a5f7035f00a06e1d9f3349c406397f90a966269df",
       "agentTarget": "claude-code"
     },
     {
@@ -668,7 +668,7 @@
     },
     {
       "path": "skills/claude-code/examples/weather/README.md",
-      "sha256": "cdad82399028f275e5ac5fabd35d373f5673839171302128ed066e3adacd6ed6",
+      "sha256": "59dd103ae387b4ef0f32e155dbe9a11d79e260310a07c0f266a16add2e8e31bd",
       "agentTarget": "claude-code"
     },
     {
@@ -683,12 +683,12 @@
     },
     {
       "path": "skills/claude-code/examples/weather/src/server.ts",
-      "sha256": "ba1ef62597885a2ec89e8c02d593bfa277763fd3a3af2154e9d1b72b06eb58f1",
+      "sha256": "95cd3a2ef47be898469d40d109f3fb89ac6e59a34fd8ad600c80dfe2908d4598",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/examples/weather/test/server.test.ts",
-      "sha256": "25047bd0c8d00c33ed485eb62b2893a7374074e9a793ca855c20a93a5fbb82d5",
+      "sha256": "6753e4db274b00d2e92405040a27609a15087227de7b13f9e9f9e19c12d3a255",
       "agentTarget": "claude-code"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.15.0",
+  "version": "0.17.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.15.0
-hash: dc338e17bb0de722
+version: 0.17.0
+hash: b4952708b1c38f55
 ---
 
 # Noodle Seed
@@ -15,6 +15,8 @@ Use this skill for project-local Noodle Seed authoring in Claude Code; preserve
 
 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/claude-code/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/claude-code/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/claude-code/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/claude-code/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/claude-code/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/claude-code/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