@noodleseed/agent-kit 0.14.0 → 0.16.0

package/skills/codex/examples/food-ordering/vitest.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@noodleseed/one': new URL('../../packages/authoring/src/index.ts', import.meta.url).pathname,
+      '@noodle-borg/capabilities': new URL(
+        '../../packages/capabilities/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/compiler': new URL('../../packages/compiler/src/index.ts', import.meta.url)
+        .pathname,
+      '@noodle-borg/compute': new URL('../../packages/compute/src/index.ts', import.meta.url)
+        .pathname,
+      '@noodle-borg/connector-defs': new URL(
+        '../../packages/connector-defs/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/connector-http': new URL(
+        '../../packages/connector-http/src/index.ts',
+        import.meta.url,
+      ).pathname,
+      '@noodle-borg/runtime': new URL('../../packages/runtime/src/index.ts', import.meta.url)
+        .pathname,
+    },
+  },
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+});

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

@@ -0,0 +1,13 @@
+# hello — minimal TypeScript quickstart
+
+The smallest deployable Noodle app: a single `greet` tool authored in TypeScript with no
+connectors, secrets, flows, widgets, or handoff policy. It still uses the current server options form
+so new authors see where server-level branding belongs. Use it to smoke the author loop
+(`noodle validate` / `noodle dev`) or a first deploy.
+
+```sh
+noodle dev examples/hello/src/server.ts --app hello
+noodle deploy examples/hello/src/server.ts --org acme --app hello
+```
+
+It is also the fixture for `pnpm smoke:dev` and the e2e harness, so keep its tool surface stable.

package/skills/codex/examples/hello/noodle.json

@@ -0,0 +1,5 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "hello",
+  "template": "hello"
+}

package/skills/codex/examples/hello/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "hello",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@noodleseed/one": "latest",
+    "vitest": "latest"
+  }
+}

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

@@ -0,0 +1,29 @@
+import { server, tool, z } from '@noodleseed/one';
+
+export default server(
+  'hello',
+  {
+    title: 'Hello',
+    version: '1.0.0',
+    branding: {
+      name: 'Hello',
+      accent: '#1D9E75',
+      radius: 'md',
+      density: 'comfortable',
+    },
+  },
+  [
+    tool('greet', {
+      description: 'Greet someone by name.',
+      input: z.object({
+        name: z.string(),
+      }),
+      output: z.object({
+        message: z.string(),
+      }),
+      fulfil: ({ input }) => {
+        return { message: `Hello, ${input.name}!` };
+      },
+    }),
+  ],
+);

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

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('hello example', () => {
+  it('exports a Noodle server definition', () => {
+    expect(typeof app.toManifest).toBe('function');
+  });
+});

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

@@ -0,0 +1,85 @@
+# Weather Briefing
+
+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,
+**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
+  app surface.
+- **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 — 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.
+
+## Run it locally
+
+From the repo root, with the workspace built (`pnpm build`):
+
+```bash
+: # 1. boot the local loopback dev server
+node packages/cli/dist/cli.js dev examples/weather/src/server.ts --app weather
+
+: # 2. in another shell, call the printed local endpoint
+URL=http://127.0.0.1:<port>/o/local/weather/dev/mcp
+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":1,"method":"tools/call","params":{"name":"weather_briefing","arguments":{"city":"Paris"}}}'
+```
+
+Example result (live data, abbreviated):
+
+```json
+{
+  "place": "Paris", "country": "France",
+  "temperature_c": 25.1, "windspeed_kmh": 8.3,
+  "conditions": "overcast",
+  "headline": "Paris, France: 25°C, overcast.",
+  "advice": "Comfortable conditions — no special prep needed."
+}
+```
+
+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/noodle.json

@@ -0,0 +1,4 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "weather"
+}

package/skills/codex/examples/weather/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "weather",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@noodleseed/one": "latest",
+    "vitest": "latest"
+  }
+}

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

@@ -0,0 +1,261 @@
+import { connector, server, tool, z } from '@noodleseed/one';
+
+// The same Weather Briefing server, authored in TypeScript with the Noodle authoring SDK.
+//
+// The SDK owns the *manifest*: the tool, its Zod-typed input/output schemas, and the flow — which you
+// write as ordinary code in `fulfil` and the SDK records symbolically into ordered steps.
+//
+// HTTP and compute connectors are authored here too, so the public developer entrypoint is one
+// self-contained server.ts. The SDK still compiles this to internal manifest/catalog data for the runtime.
+
+const geocoding = connector('open_meteo_geocoding')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://geocoding-api.open-meteo.com',
+    allowedOrigins: ['https://geocoding-api.open-meteo.com'],
+    operations: {
+      search: {
+        type: 'read',
+        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' },
+        },
+        response: {
+          latitude: '${response.results[0].latitude}',
+          longitude: '${response.results[0].longitude}',
+          place: '${response.results[0].name}',
+          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}',
+        },
+      },
+    },
+  });
+
+const forecast = connector('open_meteo_forecast')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://api.open-meteo.com',
+    allowedOrigins: ['https://api.open-meteo.com'],
+    operations: {
+      current: {
+        type: 'read',
+        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' },
+        },
+        response: {
+          temperature: '${response.current_weather.temperature}',
+          windspeed: '${response.current_weather.windspeed}',
+          weathercode: '${response.current_weather.weathercode}',
+        },
+      },
+    },
+  });
+
+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 },
+    },
+    // 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) => {
+      const codes: Record<number, string> = {
+        0: 'clear sky',
+        1: 'mainly clear',
+        2: 'partly cloudy',
+        3: 'overcast',
+        45: 'fog',
+        48: 'depositing rime fog',
+        51: 'light drizzle',
+        53: 'moderate drizzle',
+        55: 'dense drizzle',
+        61: 'slight rain',
+        63: 'moderate rain',
+        65: 'heavy rain',
+        71: 'slight snow',
+        73: 'moderate snow',
+        75: 'heavy snow',
+        77: 'snow grains',
+        80: 'slight rain showers',
+        81: 'moderate rain showers',
+        82: 'violent rain showers',
+        85: 'slight snow showers',
+        86: 'heavy snow showers',
+        95: 'thunderstorm',
+        96: 'thunderstorm with hail',
+        99: 'thunderstorm with heavy hail',
+      };
+      const code = Number(input.weathercode);
+      const conditions = codes[code] || 'unknown conditions';
+      const temp = Math.round(Number(input.temperature));
+      const wind = Math.round(Number(input.windspeed));
+      const where = input.country ? `${input.place}, ${input.country}` : input.place;
+      const headline = `${where}: ${temp}°C, ${conditions}.`;
+      const tips: string[] = [];
+      if (temp <= 0) tips.push("bundle up, it's freezing");
+      else if (temp <= 10) tips.push('wear a warm coat');
+      else if (temp >= 28) tips.push("stay hydrated, it's hot");
+      if (code >= 95) tips.push('thunderstorms expected — seek shelter');
+      else if (code >= 71 && code <= 86 && code !== 80 && code !== 81 && code !== 82)
+        tips.push('snow — dress warm and tread carefully');
+      else if (code >= 51 && code <= 82) tips.push('bring an umbrella');
+      if (wind >= 30) tips.push('expect strong winds');
+      const advice = tips.length
+        ? `${tips.join('; ')}.`
+        : 'Comfortable conditions — no special prep needed.';
+      return { conditions, headline, advice };
+    },
+  });
+
+// 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, places: placeNarrow },
+    branding: {
+      name: 'Weather Briefing',
+      accent: '#0284C7',
+      radius: 'md',
+      density: 'comfortable',
+    },
+  },
+  [
+    tool('weather_briefing', {
+      description:
+        'Look up a city, fetch its current weather, and return a human-readable briefing. Runs a ' +
+        'three-step flow: geocode the city, fetch the forecast, then derive the briefing in a sandboxed compute step.',
+      input: z.object({
+        city: z.string(),
+      }),
+      output: z.object({
+        place: z.string(),
+        country: z.string(),
+        temperature_c: z.number(),
+        windspeed_kmh: z.number(),
+        conditions: z.string(),
+        headline: z.string(),
+        advice: z.string(),
+      }),
+      fulfil: ({ input, connectors }) => {
+        const located = connectors.geo.search({ name: input.city });
+        const weather = connectors.forecast.current({
+          latitude: located.latitude,
+          longitude: located.longitude,
+        });
+        const briefing = connectors.brief.summarize({
+          place: located.place,
+          country: located.country,
+          temperature: weather.temperature,
+          windspeed: weather.windspeed,
+          weathercode: weather.weathercode,
+        });
+        return {
+          place: located.place,
+          country: located.country,
+          temperature_c: weather.temperature,
+          windspeed_kmh: weather.windspeed,
+          conditions: briefing.conditions,
+          headline: briefing.headline,
+          advice: briefing.advice,
+        };
+      },
+    }),
+    // 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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+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

@@ -1,15 +1,24 @@
 # Examples
 
-Flagship examples (one per capability). Each lives in the Noodle Seed repository under `examples/<name>/` (`server.ts`, `src/views/*.tsx`, `README.md`, and a `design/` folder for the design-first flagships). Read the matching example for the pattern you need; extend an existing flagship rather than inventing a new shape.
+Flagship examples, one per capability. The **bundled** rows ship inside this skill under `examples/<name>/` (the real `server.ts`, `src/views/*.tsx`, and — for the design-first flagships — a `design/` set); read them locally at the paths shown. The rest live only in the Noodle Seed repository under `examples/<name>/` on GitHub. Extend an existing flagship rather than inventing a new shape.
+
+## Bundled in this skill — read locally
+
+Paths are relative to this skill directory. Assets (images/fonts) are omitted from the bundle; fetch the full runnable example from the repository if you need them. Verify any edit with `noodle validate --json` then `noodle test --json`.
+
+| 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, 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/` |
+| `acme-bistro` | End-to-end ordering with a payment-only handoff; ships a gold-standard `design/` set (UX doc, wireframe with compliance audit, API contract). | `examples/acme-bistro/src/server.ts` + `design/` |
+
+## In the repository only — `examples/<name>/` on GitHub
 
 | Example | Use when |
 | :-- | :-- |
-| `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. |
-| `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. |
-| `food-ordering` | Consumer ordering MCP App widgets, app-only helpers, cart state, assets, branding, and handoff. |
-| `acme-discovery` | Top-of-funnel discovery→handoff: a discovery carousel, a `create_handoff` deep link, and a design-first UX spec + wireframe. |
-| `acme-tasks` | A two-way productivity app designed around its top-3 prioritized flows (capture/prioritize/complete), with a design-first flow spec + wireframe. |
-| `acme-bistro` | End-to-end ordering with a payment-only handoff; ships a gold-standard `design/` set (UX doc, wireframe with compliance audit, API contract). |
 | `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
 | `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
 | `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |

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` |