@noodleseed/agent-kit 0.15.0 → 0.16.0

package/manifest.json

@@ -1,9 +1,9 @@
 {
-  "packageVersion": "0.15.0",
+  "packageVersion": "0.16.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "3dfbb3af5b9176302b787da3118896d4cc4b4382c674b68f956ef2d52f5adbf6",
+      "sha256": "5a709e078dbc9e5ab9194e35e1cef93936c62f2c4e826877028ec269162d9b7c",
       "agentTarget": "codex"
     },
     {
@@ -33,7 +33,7 @@
     },
     {
       "path": "skills/codex/references/connect-an-api.md",
-      "sha256": "5c7d763ad57e6d6b67e3e115da48acd5bef3687acd050b776416906076cec440",
+      "sha256": "890dd3a73a73e29f0cad88d1fb1b4ebc24791b791cfffb130143b26f714e9da0",
       "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"
     },
     {
@@ -323,7 +323,7 @@
     },
     {
       "path": "skills/codex/examples/weather/README.md",
-      "sha256": "cdad82399028f275e5ac5fabd35d373f5673839171302128ed066e3adacd6ed6",
+      "sha256": "59dd103ae387b4ef0f32e155dbe9a11d79e260310a07c0f266a16add2e8e31bd",
       "agentTarget": "codex"
     },
     {
@@ -338,17 +338,17 @@
     },
     {
       "path": "skills/codex/examples/weather/src/server.ts",
-      "sha256": "ba1ef62597885a2ec89e8c02d593bfa277763fd3a3af2154e9d1b72b06eb58f1",
+      "sha256": "4af1ea8c9ed5d41456bfa52b4b0245a3d482f4a95ef4e994b2758dd32c1c52ce",
       "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": "0a3e1998439a89d14887c9e533a225e7f83dbfdedffd278eb773213d3758e469",
       "agentTarget": "claude-code"
     },
     {
@@ -378,7 +378,7 @@
     },
     {
       "path": "skills/claude-code/references/connect-an-api.md",
-      "sha256": "5c7d763ad57e6d6b67e3e115da48acd5bef3687acd050b776416906076cec440",
+      "sha256": "890dd3a73a73e29f0cad88d1fb1b4ebc24791b791cfffb130143b26f714e9da0",
       "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"
     },
     {
@@ -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": "4af1ea8c9ed5d41456bfa52b4b0245a3d482f4a95ef4e994b2758dd32c1c52ce",
       "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.16.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.16.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/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

@@ -33,6 +33,28 @@ 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: {
+          name: { type: 'string', required: true },
+          count: { type: 'number' },
+        },
+        output: {
+          results: { type: 'array' },
+        },
+        response: {
+          results: '${response.results}',
+        },
+      },
     },
   });
 
@@ -132,12 +154,44 @@ 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: {
+      results: { type: 'unknown' },
+    },
+    output: {
+      places: { type: 'array', required: true },
+    },
+    // 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 +240,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/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: { places: { type: 'array' } },
+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: { id: { type: 'string', required: true } },
+  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/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/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.16.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/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

@@ -33,6 +33,28 @@ 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: {
+          name: { type: 'string', required: true },
+          count: { type: 'number' },
+        },
+        output: {
+          results: { type: 'array' },
+        },
+        response: {
+          results: '${response.results}',
+        },
+      },
     },
   });
 
@@ -132,12 +154,44 @@ 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: {
+      results: { type: 'unknown' },
+    },
+    output: {
+      places: { type: 'array', required: true },
+    },
+    // 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 +240,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/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: { places: { type: 'array' } },
+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: { id: { type: 'string', required: true } },
+  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/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` |