@noodleseed/agent-kit 0.12.0 → 0.14.0

package/README.md

@@ -8,10 +8,10 @@ into a project's `.agents/` and `.claude/` skill directories via `noodle agents
 
 ## Contents
 
-- `skills/codex/` — the Codex (Codex CLI / AGENTS.md) skill: a `SKILL.md` router plus eleven
+- `skills/codex/` — the Codex (Codex CLI / AGENTS.md) skill: a `SKILL.md` router plus fourteen
   `references/*.md` files (sdk-surface, cli-commands, agent-contract, compile-errors,
-  authoring-workflow, widgets-and-apps, test-in-hosts, troubleshooting, deploy-and-ops, publishing,
-  examples).
+  authoring-workflow, connect-an-api, experience-design, widgets-and-apps, test-in-hosts,
+  troubleshooting, deploy-and-ops, publishing, chatgpt-compliance, examples).
 - `skills/claude-code/` — the Claude Code skill, same hierarchical tree.
 - `manifest.json` — `{ packageVersion, files: [{ path, sha256, agentTarget }] }`. The CLI verifies every
   file's sha256 against this manifest before writing it into a user's project; a mismatch refuses the

package/manifest.json

@@ -1,9 +1,9 @@
 {
-  "packageVersion": "0.12.0",
+  "packageVersion": "0.14.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "0b986b87d14e9eed8add2c3d294a9c3df319847f410340815d9f4690af126c11",
+      "sha256": "430e32c03fd13e62cc285280ed846178ae941821516445ba210e5a77fb9e49cd",
       "agentTarget": "codex"
     },
     {
@@ -28,7 +28,17 @@
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "aba1853b5709cc40f341f827bae739e11142b2a6996872757b1db68e0cb35015",
+      "sha256": "eca8d1f2b98ee64f6beda4d983f0f0df9023ceed8bd00ffb9dd6b5025dcaa4e4",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/connect-an-api.md",
+      "sha256": "5c7d763ad57e6d6b67e3e115da48acd5bef3687acd050b776416906076cec440",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/experience-design.md",
+      "sha256": "f07ed621eb1e8cdfa08abd10d5a6331c7e9d8198da422b8b4ad54d23475b2d4d",
       "agentTarget": "codex"
     },
     {
@@ -43,7 +53,7 @@
     },
     {
       "path": "skills/codex/references/troubleshooting.md",
-      "sha256": "fe13045fab55fc660c50482540e89654bac6a925c3d189fa3e9650d7e656b7ba",
+      "sha256": "834d2c6626dc90c009aebac3ee7ff8977a1f97dfb66cf5b955fd6414e6e2a897",
       "agentTarget": "codex"
     },
     {
@@ -56,14 +66,19 @@
       "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
       "agentTarget": "codex"
     },
+    {
+      "path": "skills/codex/references/chatgpt-compliance.md",
+      "sha256": "b0d70446be90a3e76396207ff32e7dc9561f25f43fc313d80cc9d9afc12e9b99",
+      "agentTarget": "codex"
+    },
     {
       "path": "skills/codex/references/examples.md",
-      "sha256": "9f3ce479669040f0c58c9876b2bbca90821c69a760d0b020a56072bd6e549d73",
+      "sha256": "776fc09103f1a0eacb8f0efc9fdc527bc478f5897d226dd340e6676e67b27632",
       "agentTarget": "codex"
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "909001bcf63868d51228d2c55da471c12f770b83f15958bbb9eefedb6afd0ec9",
+      "sha256": "859218a6d7b97bc9a2b7da698550c5505b2ffab8370aecd3a21814ab3f4dd05f",
       "agentTarget": "claude-code"
     },
     {
@@ -88,7 +103,17 @@
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "aba1853b5709cc40f341f827bae739e11142b2a6996872757b1db68e0cb35015",
+      "sha256": "eca8d1f2b98ee64f6beda4d983f0f0df9023ceed8bd00ffb9dd6b5025dcaa4e4",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/connect-an-api.md",
+      "sha256": "5c7d763ad57e6d6b67e3e115da48acd5bef3687acd050b776416906076cec440",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/experience-design.md",
+      "sha256": "f07ed621eb1e8cdfa08abd10d5a6331c7e9d8198da422b8b4ad54d23475b2d4d",
       "agentTarget": "claude-code"
     },
     {
@@ -103,7 +128,7 @@
     },
     {
       "path": "skills/claude-code/references/troubleshooting.md",
-      "sha256": "fe13045fab55fc660c50482540e89654bac6a925c3d189fa3e9650d7e656b7ba",
+      "sha256": "834d2c6626dc90c009aebac3ee7ff8977a1f97dfb66cf5b955fd6414e6e2a897",
       "agentTarget": "claude-code"
     },
     {
@@ -116,9 +141,14 @@
       "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
       "agentTarget": "claude-code"
     },
+    {
+      "path": "skills/claude-code/references/chatgpt-compliance.md",
+      "sha256": "b0d70446be90a3e76396207ff32e7dc9561f25f43fc313d80cc9d9afc12e9b99",
+      "agentTarget": "claude-code"
+    },
     {
       "path": "skills/claude-code/references/examples.md",
-      "sha256": "9f3ce479669040f0c58c9876b2bbca90821c69a760d0b020a56072bd6e549d73",
+      "sha256": "776fc09103f1a0eacb8f0efc9fdc527bc478f5897d226dd340e6676e67b27632",
       "agentTarget": "claude-code"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.12.0",
+  "version": "0.14.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.12.0
-hash: dd621716fbd94dab
+version: 0.14.0
+hash: dc338e17bb0de722
 ---
 
 # 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`.
 
+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).
 2. **Author** — edit `src/server.ts` (the configured entrypoint); follow the capability recipe in `references/sdk-surface.md` and `references/examples.md`.
 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[]`.
@@ -35,11 +37,14 @@ Load these on demand:
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.
 - `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the fit check, the validate→test→dev repair loop, connectors, and secrets/variables.
+- `references/connect-an-api.md` — given an API key: secure it, probe the live API to learn the real shape, model the connector, and prove real output before building.
+- `references/experience-design.md` — design the app experience before authoring: funnel/handoff boundary, grounding, two-users, display modes, and the wireframe/UX spec.
 - `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, the widget hook surface, output shaping, and CSP.
 - `references/test-in-hosts.md` — connect and test in ChatGPT (developer mode), Claude, agent hosts, and MCP Inspector.
 - `references/troubleshooting.md` — runtime symptom → cause → fix, in-host and hosted.
 - `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
 - `references/publishing.md` — submit to the ChatGPT apps directory and Claude connectors directory.
+- `references/chatgpt-compliance.md` — the OpenAI Apps SDK pre-submission checklist (beyond the metadata gate): conversational value, helpful-UI-only, in-chat completion, UI guidelines, domain guardrails, privacy.
 - `references/examples.md` — flagship example index and a canonical `server.ts`.
 
 ## Safety

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

@@ -6,8 +6,8 @@
 - Fit check
 - Repair loop
 - Connectors
-- HTTP connector example
-- Worked example (full server)
+- HTTP connector example (full server)
+- Design tools for the model
 - Compute connector example
 - Tests
 - Secrets and variables
@@ -38,81 +38,126 @@ Tools record connector calls into a flow; recording is not execution. Do not bra
 
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
-## HTTP connector example
+## HTTP connector example (full server)
 
-The operation mapping in detail: `request` templates the outbound call, `response` maps the HTTP body into your typed `output`.
+Declare the API as data, bind it with `use`, then record calls in tools. The operation mapping in detail: `request` builds the JSON request body, `query: [...]` names the input args sent as URL query parameters, and `response` maps the parsed HTTP body (bound to `${response}`) into your typed `output`. `auth` reads a managed `secret(...)` — never inline a key. This whole example is compile-verified on every `pnpm test`.
 
 ```ts
-import { connector, secret, variable } from '@noodleseed/one';
+import { connector, secret, variable, server, tool, z } from '@noodleseed/one';
 
 const crm = connector('crm').version('1.0.0').http({
   baseUrl: variable('CRM_BASE_URL'),
-  allowedOrigins: [variable('CRM_BASE_URL')],
+  allowedOrigins: ['https://api.crm.example'],
   auth: { kind: 'bearer', secret: secret('CRM_TOKEN') },
   operations: {
-    findCustomer: {
+    find_customer: {
       type: 'read',
-      input: { email: { type: "string", required: true } },
-      output: { id: { type: "string", required: true }, name: { type: "string" } },
-      method: "GET",
-      path: "/customers",
-      request: { query: { email: "${args.email}" } },
-      response: { id: "${response.body.data.0.id}", name: "${response.body.data.0.name}" },
+      method: 'GET',
+      path: '/customers',
+      query: ['email'],
+      input: { email: { type: 'string', required: true } },
+      output: { id: { type: 'string', required: true }, name: { type: 'string' } },
+      response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
     },
-    createTicket: {
+    create_ticket: {
       type: 'action',
-      input: { customerId: { type: "string", required: true }, body: { type: "string", required: true } },
-      output: { ticketId: { type: "string", required: true } },
-      method: "POST",
-      path: "/tickets",
-      request: { body: { customer_id: "${args.customerId}", body: "${args.body}" } },
-      response: { ticketId: "${response.body.id}" },
+      method: 'POST',
+      path: '/tickets',
+      input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
+      output: { ticket_id: { type: 'string', required: true } },
+      request: { customer_id: '${args.customer_id}', body: '${args.body}' },
+      response: { ticket_id: '${response.id}' },
     },
   },
 });
+
+export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
+  tool('find_customer', {
+    description: 'Find a customer by email address.',
+    input: z.object({ email: z.string() }),
+    output: z.object({ id: z.string(), name: z.string().optional() }),
+    fulfil: ({ input, connectors }) => {
+      const customer = connectors.crm.find_customer({ email: input.email });
+      return { id: customer.id, name: customer.name };
+    },
+  }),
+  tool('open_ticket', {
+    description: 'Open a support ticket for a customer.',
+    input: z.object({ customer_id: z.string(), body: z.string() }),
+    output: z.object({ ticket_id: z.string() }),
+    fulfil: ({ input, connectors }) => {
+      const ticket = connectors.crm.create_ticket({ customer_id: input.customer_id, body: input.body });
+      return { ticket_id: ticket.ticket_id };
+    },
+  }),
+]);
 ```
 
-Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
+Naming: connector operation names and tool names are lowercase-with-underscores. Map with `${args.field}` for tool/operation inputs and `${response.path}` for the response — the parsed JSON body is bound directly to `${response}`, so there is **no `.body` envelope**; use bracket syntax for array indices (`${response.data[0].id}`) — a dotted numeric index like `.0.` is invalid. Declare URL query parameters with the operation-level `query: ["arg"]` array, **not** inside `request` (which builds only the JSON body). `allowedOrigins` must be literal origin URLs (the SSRF allowlist); `baseUrl` may be a `variable(...)` that differs by env.
+
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+
+## Design tools for the model
+
+Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
 
-## Worked example (full server)
+- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
+- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
+- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
 
-Declare the API as data, bind it with `use`, then record a call in a tool. `auth` reads a managed `secret(...)` — never inline a key. Map the HTTP body into your typed `output` with `${response...}`.
+This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
 
 ```ts
 import { connector, secret, server, tool, z } from '@noodleseed/one';
 
-const crm = connector('acme_crm')
-  .version('1.0.0')
-  .http({
-    baseUrl: 'https://api.acme.example',
-    allowedOrigins: ['https://api.acme.example'],
-    auth: { kind: 'apiKey', header: 'X-Api-Key', secret: secret('ACME_CRM_TOKEN') },
-    operations: {
-      get_ticket: {
-        type: 'read',
-        method: 'GET',
-        path: '/v1/tickets/{id}',
-        input: { id: { type: 'string', required: true } },
-        output: { subject: { type: 'string' }, status: { type: 'string' } },
-        response: { subject: '${response.data.subject}', status: '${response.data.state}' },
-      },
+const tasks = connector('tasks').version('1.0.0').http({
+  baseUrl: 'https://api.tasks.example',
+  allowedOrigins: ['https://api.tasks.example'],
+  auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
+  operations: {
+    search_tasks: {
+      type: 'read',
+      method: 'GET',
+      path: '/tasks',
+      query: ['query'],
+      input: { query: { type: 'string', required: true } },
+      output: { matches: { type: 'array', required: true } },
+      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 } },
+      response: { ok: '${response.ok}' },
+    },
+  },
+});
 
-export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
-  tool('ticket_status', {
-    description: 'Look up a support ticket by id.',
-    input: z.object({ ticket_id: z.string() }),
-    output: z.object({ subject: z.string(), status: z.string() }),
+export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
+  tool('find_tasks', {
+    description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
+    input: z.object({ query: z.string() }),
+    output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
+    fulfil: ({ input, connectors }) => {
+      const found = connectors.tasks.search_tasks({ query: input.query });
+      return { matches: found.matches };
+    },
+  }),
+  tool('complete_task', {
+    description: 'Mark a task complete by its id (get the id from find_tasks).',
+    input: z.object({ id: z.string() }),
+    output: z.object({ ok: z.boolean() }),
     fulfil: ({ input, connectors }) => {
-      const ticket = connectors.crm.get_ticket({ id: input.ticket_id });
-      return { subject: ticket.subject, status: ticket.status };
+      const result = connectors.tasks.close_task({ id: input.id });
+      return { ok: result.ok };
     },
   }),
 ]);
 ```
 
-More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
 
 ## Compute connector example
 
@@ -120,10 +165,10 @@ More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials`
 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 } },
-  calls: { findCustomer: 'crm.findCustomer' },
+  calls: { find_customer: 'crm.find_customer' },
   limits: { timeoutMs: 1000, maxHostCalls: 2 },
   run(input, { callOperation }) {
-    const customer = callOperation("findCustomer", { email: input.email }) as { id?: string };
+    const customer = callOperation("find_customer", { email: input.email }) as { id?: string };
     return { score: customer.id && input.priority === "high" ? 100 : 50 };
   },
 });

package/skills/claude-code/references/chatgpt-compliance.md

@@ -0,0 +1,63 @@
+# ChatGPT App compliance (pre-submission)
+
+`noodle check --target chatgpt` verifies the *metadata* prerequisites; app-store submission also faces a
+human review against OpenAI’s Apps SDK UX principles. Run this checklist against the built app before
+submitting, and render it as an audit table in the design wireframe (`design/wireframe.html` in the
+`acme-*` examples) so partners and reviewers see it up front.
+
+## Contents
+
+- Metadata gate vs review
+- Pre-submission checklist
+- UI guidelines
+- Domain guardrails
+- Privacy and data
+
+## Metadata gate vs review
+
+`noodle check --target chatgpt --json` returning `ok:true` means the widget is *metadata-ready* (widget
+`domain`, `openai/outputTemplate`, CSP, tool annotations, and `invoking`/`invoked` invocation copy are
+present) — it does NOT prove host rendering, conversation UX, or submission acceptance. Validate real
+rendering in ChatGPT Developer Mode / MCP Inspector, then run the checklist below.
+
+## Pre-submission checklist (what review looks for)
+
+1. **Conversational value** — at least one capability relies on ChatGPT’s strengths: natural-language
+   actions no tap-driven app can do (e.g. "two margheritas and a lemon tart" parses into a cart). Cite
+   concrete app behavior, not aspirations.
+2. **Beyond base ChatGPT** — new knowledge, actions, or presentation (grounded partner data, live
+   inventory, signed handoffs, real-world routing).
+3. **Atomic, model-friendly actions** — self-contained tools with explicit input/output schemas, and an
+   annotation on every tool (`annotations.readOnly()` / `.action()` / `.openAction()`).
+4. **Helpful UI only** — justify each widget (would plain text degrade UX?), and note what you
+   deliberately did NOT build a widget for (payment is off-app → no payment widget).
+5. **In-chat task completion** — the user finishes a meaningful task in chat. For a top-of-funnel app,
+   the task is the discovery/config loop completed in-chat with an intentional handoff.
+6. **Performance** — tool calls scoped per step; response-time targets stated.
+7. **Discoverability** — broad, natural trigger prompts listed; description keywords planned. Golden
+   prompt sets and metadata optimization are a launch workstream, not polish.
+8. **Platform fit** — multi-turn dialogue, conversation memory, and multimodality where genuinely useful.
+
+## UI guidelines
+
+System fonts, monochrome outlined icons, WCAG AA contrast, at most two actions on inline cards, no nested
+scroll, and the right display mode per intent (inline by default; fullscreen only where browsing needs
+it; picture-in-picture only for live state). Brand only through `server` `branding` tokens — accent on
+the primary CTA, logo, and badges, nothing else; the compiler derives the palette. Never inject raw
+global CSS.
+
+## Domain guardrails
+
+For regulated-adjacent apps, add app-specific trust behaviors and **show them in the rendered pixels**:
+cite the source and its revision for consequential lookups; frame regulated content as "considerations,
+not a ruling"; never invent compatibility, availability, or pricing; and always show the relevant
+caution/disclaimer. These are what make a regulated-adjacent app approvable.
+
+## Privacy and data
+
+Data flows through OpenAI; tool payloads and whatever the server stores must match the partner’s privacy
+policy. No payment happens in chat (PCI stays off-app). Avoid per-user OAuth in a top-of-funnel v1 (use
+service credentials via a `connector`); add end-user auth only for two-way apps (`customerAuth`). Keep
+secrets out of tool output, widgets, and logs. If the partner’s published policy predates the app, flag a
+privacy gap for their counsel before submission. Re-run this checklist against the *built* app before
+every submission — not just the wireframe.

package/skills/claude-code/references/connect-an-api.md

@@ -0,0 +1,76 @@
+# Connect a live API (you were given a key)
+
+When the user hands you an API key or credentials, don't infer the data from documentation — docs
+drift. Probe the live API, learn the real shape, then encode it as a `connector`. The loop:
+
+## Contents
+
+- Secure the key first
+- Probe the live API
+- Model the connector from the observed shape
+- Design intent tools
+- Prove real output
+- Then build the app
+
+## Secure the key first
+
+Never inline or log the key. Have the user put it in an environment variable, then store it as a
+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
+```
+
+In `server.ts` the key is only ever `secret("SOME_API_KEY")` — keep the raw value out of code, tests,
+prompts, logs, and generated files.
+
+## Probe the live API
+
+Learn the actual response shape empirically. Two ways — capture one real example response per endpoint
+you will use, and read its field names, nesting, array shapes, pagination, and id-vs-label fields:
+
+- **With your own HTTP/shell tool** — call a representative read endpoint using the key **from the env
+  var**, never the literal (so it stays out of logs): `curl -H "Authorization: Bearer $SOME_API_KEY"
+  https://api.example.com/things`. Inspect the returned JSON.
+- **Noodle-native** — author a minimal read operation that maps the whole body (`response: { raw:
+  '${response}' }`), `noodle secrets set` the key, then `noodle tools call` it to see the real payload
+  in-process.
+
+## Model the connector from the observed shape
+
+Encode the API as an HTTP connector, mapping only the fields you actually saw into a small typed
+`output`:
+
+- `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`.
+- `auth: { kind: 'bearer', secret: secret('SOME_API_KEY') }` — or `{ kind: 'apiKey', header: 'X-API-Key',
+  secret: secret('SOME_API_KEY') }`. Never put the credential in operation `headers`.
+- Per operation: `method`, `path` (with `{id}` templates), `query: ["arg"]` for URL params, `input`,
+  `output`, and a `response` mapping whose `${response.path}` matches the real JSON — the parsed body is
+  bound directly to `${response}` (no `.body` envelope); use bracket indices for arrays
+  (`${response.results[0].id}`).
+
+The full connector shape, every `auth.kind`, and compute connectors are in
+`references/authoring-workflow.md`.
+
+## Design intent tools
+
+Shape tools around what the user says, not 1:1 around endpoints. Pair an id-taking action with a
+find/search operation that returns `{ id, label }` summaries so the model resolves text → id itself,
+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`.
+
+## Prove real output
+
+`noodle validate` / `noodle test` prove a connector tool *compiles and registers* — not that its
+mapping returns data. With the secret set, run a live read: `noodle tools call <read_tool> --args
+'{…}'` executes the connector against the real API in-process. Confirm the mapped fields are populated,
+not `undefined`; if they are empty, fix the `${response…}` paths against the real payload and re-run.
+Only run a live write if it is safe or the user approved it.
+
+## Then build the app
+
+With real data flowing, design the experience (`references/experience-design.md`), add widgets where a
+UI genuinely helps (`references/widgets-and-apps.md`), and verify with `noodle check`. Deploy per
+`references/deploy-and-ops.md`, and set the same secret in the hosted environment with `noodle secrets
+set` before the first hosted call.

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

@@ -1,12 +1,15 @@
 # Examples
 
-Flagship examples (one per capability). Read the matching example for the pattern you need; extend an existing flagship rather than inventing a new shape.
+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.
 
 | 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/claude-code/references/experience-design.md

@@ -0,0 +1,142 @@
+# Experience design
+
+Design the app experience before you author it. A ChatGPT app is a conversation with tools and
+widgets, not a website — decide the funnel, the tools, the widgets, and the handoff first, then
+build with the SDK (`references/authoring-workflow.md`, `references/widgets-and-apps.md`). This
+reference is the design discipline; the build references are the mechanics.
+
+## Contents
+
+- Design first
+- The handoff is the product
+- Grounded, never guessing
+- Two users: the human and the model
+- ChatGPT-native surface
+- Scope discipline and auth stance
+- Wireframe and UX-spec anatomy
+- The deliverables
+- From design to build
+
+## Design first
+
+Write a short design spec before you author `server.ts` — a `SPEC.md`-style note you keep updated as
+the app evolves. It has required fields:
+
+- **Funnel boundary** — one sentence stating exactly what happens in ChatGPT and what happens off-app.
+- **Tools** — each model-visible tool, snake_case, with what it takes and returns.
+- **Widgets and display modes** — each widget, PascalCase, and the display mode it renders in
+  (inline card / carousel / fullscreen / picture-in-picture). State the modes you deliberately do
+  *not* use, and why.
+- **Grounding sources** — where each fact comes from (a `connector` operation, a provided dataset).
+- **Handoff domains** — the external origins the app links out to (these become server
+  `handoff.allowedDomains`).
+- **Exceptions** — any deliberate departure from the defaults below, each with its reason.
+
+Then author, preview with `noodle dev` / `noodle devtools`, and iterate. The spec is the contract the
+tools, widgets, and handoff all trace back to.
+
+## The handoff is the product
+
+Default scope is **top-of-funnel**: ChatGPT owns discovery, intent-shaping, and configuration; the
+partner's own platform owns the transaction, the account, and everything after. The app hands off with
+a deep link that carries the configured state (a pre-filled cart, a chosen configuration), and the
+external target is declared in the server-level `handoff.allowedDomains`. This is a feature: it keeps
+payment and account burden off the app and keeps the partner's platform central.
+
+Deliberate exceptions exist — an app that completes the transaction in-chat (handing off for payment
+only), or a two-way app that reads and writes a connected account. When you break the top-of-funnel
+default, write down why in the design spec.
+
+## Grounded, never guessing
+
+The app's credibility is that it answers from the partner's own data, reached through a `connector`,
+never invented. Never fabricate compatibility, availability, pricing, or eligibility. For
+consequential lookups, **cite the source and its revision in the widget** (e.g. a spec-sheet name and
+revision date) and route unknowns to a human path rather than improvising. Guardrails belong in the
+rendered pixels, not just in prose.
+
+## Two users: the human and the model
+
+Every tool and widget serves two users at once — the human who interacts and the model that reads the
+result. Keep tools atomic with inputs the model can fill from natural language, and return enough
+structure that the model can speak confidently in one round-trip. Build a widget only where plain text
+would genuinely degrade the experience (photos, comparisons, carts, configuration). If text would do,
+don't build the widget.
+
+## ChatGPT-native surface
+
+Widgets should read as native to the host. Brand through the `server` `branding` tokens only — the
+compiler derives the palette — and reserve the accent for the primary CTA, the logo, and badges. No
+brand gradients, no app-shoved-into-chat. Keep inline cards to at most two actions and avoid nested
+scroll. Pick each display mode deliberately (fullscreen only where browsing genuinely needs it;
+picture-in-picture only for live ongoing state). See `references/widgets-and-apps.md` for the widget
+mechanics — do not restyle with raw global CSS.
+
+## Scope discipline and auth stance
+
+Lock the funnel boundary in writing before designing, and keep a "future enhancements" list as the
+pressure valve. No payment happens in chat. Avoid per-user auth in a top-of-funnel v1 — use the
+partner's service credentials via a `connector`; add end-user auth only when the app is two-way by
+nature (see the `customer-auth` example in `references/examples.md`).
+
+## Wireframe and UX-spec anatomy
+
+For anything non-trivial, sketch the experience as a wireframe before authoring — a walk through the
+conversation, screen by screen. Each screen shows a real user message, the **tool call that precedes
+the widget**, and the widget filled with plausible, internally consistent data (never lorem ipsum).
+Label each widget with its component name so the wireframe, the spec, and the code share one
+vocabulary; put the funnel boundary at the top; and render off-app destinations distinctly (they are
+reached only after the handoff). Each wireframe screen maps directly to noodle: a screen with a widget
+is a `toolWithWidget` + a React `view`; a plain answer is a `tool`; an off-app destination is a
+`handoff.allowedDomains` entry. A compact single screen, anonymized to a fictional "Acme" business:
+
+```html
+<div class="phone">
+  <div class="chatgpt-header">ChatGPT · Acme</div>
+  <div class="msg user">14kW array, ~40kWh battery — what pairs with the Acme X?</div>
+  <!-- tool call precedes every widget; the model fills inputs from the message -->
+  <div class="tool-call">check_compatibility { model: "Acme X", battery_kwh: 40 }</div>
+  <div class="wcard">
+    <div class="wcard-head">CompatibilityCard</div>       <!-- component name = code + spec -->
+    <div class="wcard-body">
+      <div class="kv">Acme X ⇄ 40kWh pack <span class="badge certified">Compatible</span></div>
+      <div class="cite">Source: Acme Integration Guide, Rev 7 (2026)</div>  <!-- grounded + cited -->
+      <a class="cta">Configure system</a>                 <!-- ≤2 actions on an inline card -->
+    </div>
+  </div>
+</div>
+```
+
+Expand from one screen to the full journey: entry → configuration → handoff, ending at the off-app
+destination. Verify the built app against the design with `noodle check --target chatgpt`.
+
+For the full quality bar, open a shipped gold-standard set: in the Noodle Seed repository, the
+`design/` folder of the `acme-discovery` (top-of-funnel), `acme-tasks` (two-way), and `acme-bistro`
+(end-to-end) examples each holds a house-style UX Document and a single-file HTML wireframe with an
+embedded OpenAI Apps SDK compliance audit. Match that bar.
+
+## The deliverables
+
+The design phase produces up to three artifacts — worked gold-standard versions live in each
+`acme-*` example's `design/` folder (copy their structure, swap the content):
+
+- **UX Document** — the thinking artifact. House-style sections: product overview / knowledge base,
+  competitive landscape, personas, conversational flow (with tool-call playscripts), widget specs +
+  a display-mode strategy, tool definitions, conversation guardrails, journey map, handoff/auth
+  architecture, demo scope, success metrics, and future enhancements — opening on the funnel-boundary
+  line every scope debate resolves against.
+- **Wireframe** — the single-file HTML alignment artifact (anatomy above) with the embedded compliance
+  audit; see `references/chatgpt-compliance.md`.
+- **API contract** — when the partner's backend must be built or wrapped. Escalate: (1) the MCP
+  tool→call-sequence map (always); (2) "Recommended API Shapes" — concrete request/response JSON per
+  tool, including the hardest nested case; (3) a full OpenAPI spec for transactional apps. Contract
+  rules: shape responses for one-round-trip rendering (embed related objects, pre-sort); put stable
+  ids on anything the user picks; keep validation in the API, not the model; the handoff endpoint
+  mints a signed, expiring URL + attribution and never proxies payment; use server-side partner
+  credentials for v1 (per-user auth only for two-way apps); name tools for user intent.
+
+## From design to build
+
+Once the design spec is settled, build it: `references/authoring-workflow.md` for the author→validate
+loop and connectors, `references/widgets-and-apps.md` for widgets and CSP, `references/examples.md`
+for a flagship to extend, and `references/deploy-and-ops.md` to ship.

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

@@ -25,6 +25,6 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
-| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (`${response.body...}` when the parsed body is bound to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
+| 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}`) |
 | 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.12.0
-hash: 68c2cc25462f5be7
+version: 0.14.0
+hash: e623fd6ca7caad0f
 ---
 
 # 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`.
 
+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).
 2. **Author** — edit `src/server.ts` (the configured entrypoint); follow the capability recipe in `references/sdk-surface.md` and `references/examples.md`.
 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[]`.
@@ -35,11 +37,14 @@ Load these on demand:
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.
 - `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the fit check, the validate→test→dev repair loop, connectors, and secrets/variables.
+- `references/connect-an-api.md` — given an API key: secure it, probe the live API to learn the real shape, model the connector, and prove real output before building.
+- `references/experience-design.md` — design the app experience before authoring: funnel/handoff boundary, grounding, two-users, display modes, and the wireframe/UX spec.
 - `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, the widget hook surface, output shaping, and CSP.
 - `references/test-in-hosts.md` — connect and test in ChatGPT (developer mode), Claude, agent hosts, and MCP Inspector.
 - `references/troubleshooting.md` — runtime symptom → cause → fix, in-host and hosted.
 - `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
 - `references/publishing.md` — submit to the ChatGPT apps directory and Claude connectors directory.
+- `references/chatgpt-compliance.md` — the OpenAI Apps SDK pre-submission checklist (beyond the metadata gate): conversational value, helpful-UI-only, in-chat completion, UI guidelines, domain guardrails, privacy.
 - `references/examples.md` — flagship example index and a canonical `server.ts`.
 
 ## Safety

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

@@ -6,8 +6,8 @@
 - Fit check
 - Repair loop
 - Connectors
-- HTTP connector example
-- Worked example (full server)
+- HTTP connector example (full server)
+- Design tools for the model
 - Compute connector example
 - Tests
 - Secrets and variables
@@ -38,81 +38,126 @@ Tools record connector calls into a flow; recording is not execution. Do not bra
 
 HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `clientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
 
-## HTTP connector example
+## HTTP connector example (full server)
 
-The operation mapping in detail: `request` templates the outbound call, `response` maps the HTTP body into your typed `output`.
+Declare the API as data, bind it with `use`, then record calls in tools. The operation mapping in detail: `request` builds the JSON request body, `query: [...]` names the input args sent as URL query parameters, and `response` maps the parsed HTTP body (bound to `${response}`) into your typed `output`. `auth` reads a managed `secret(...)` — never inline a key. This whole example is compile-verified on every `pnpm test`.
 
 ```ts
-import { connector, secret, variable } from '@noodleseed/one';
+import { connector, secret, variable, server, tool, z } from '@noodleseed/one';
 
 const crm = connector('crm').version('1.0.0').http({
   baseUrl: variable('CRM_BASE_URL'),
-  allowedOrigins: [variable('CRM_BASE_URL')],
+  allowedOrigins: ['https://api.crm.example'],
   auth: { kind: 'bearer', secret: secret('CRM_TOKEN') },
   operations: {
-    findCustomer: {
+    find_customer: {
       type: 'read',
-      input: { email: { type: "string", required: true } },
-      output: { id: { type: "string", required: true }, name: { type: "string" } },
-      method: "GET",
-      path: "/customers",
-      request: { query: { email: "${args.email}" } },
-      response: { id: "${response.body.data.0.id}", name: "${response.body.data.0.name}" },
+      method: 'GET',
+      path: '/customers',
+      query: ['email'],
+      input: { email: { type: 'string', required: true } },
+      output: { id: { type: 'string', required: true }, name: { type: 'string' } },
+      response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
     },
-    createTicket: {
+    create_ticket: {
       type: 'action',
-      input: { customerId: { type: "string", required: true }, body: { type: "string", required: true } },
-      output: { ticketId: { type: "string", required: true } },
-      method: "POST",
-      path: "/tickets",
-      request: { body: { customer_id: "${args.customerId}", body: "${args.body}" } },
-      response: { ticketId: "${response.body.id}" },
+      method: 'POST',
+      path: '/tickets',
+      input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
+      output: { ticket_id: { type: 'string', required: true } },
+      request: { customer_id: '${args.customer_id}', body: '${args.body}' },
+      response: { ticket_id: '${response.id}' },
     },
   },
 });
+
+export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
+  tool('find_customer', {
+    description: 'Find a customer by email address.',
+    input: z.object({ email: z.string() }),
+    output: z.object({ id: z.string(), name: z.string().optional() }),
+    fulfil: ({ input, connectors }) => {
+      const customer = connectors.crm.find_customer({ email: input.email });
+      return { id: customer.id, name: customer.name };
+    },
+  }),
+  tool('open_ticket', {
+    description: 'Open a support ticket for a customer.',
+    input: z.object({ customer_id: z.string(), body: z.string() }),
+    output: z.object({ ticket_id: z.string() }),
+    fulfil: ({ input, connectors }) => {
+      const ticket = connectors.crm.create_ticket({ customer_id: input.customer_id, body: input.body });
+      return { ticket_id: ticket.ticket_id };
+    },
+  }),
+]);
 ```
 
-Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
+Naming: connector operation names and tool names are lowercase-with-underscores. Map with `${args.field}` for tool/operation inputs and `${response.path}` for the response — the parsed JSON body is bound directly to `${response}`, so there is **no `.body` envelope**; use bracket syntax for array indices (`${response.data[0].id}`) — a dotted numeric index like `.0.` is invalid. Declare URL query parameters with the operation-level `query: ["arg"]` array, **not** inside `request` (which builds only the JSON body). `allowedOrigins` must be literal origin URLs (the SSRF allowlist); `baseUrl` may be a `variable(...)` that differs by env.
+
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. For client credentials use `{ kind: "clientCredentials", tokenUrl, clientId, clientSecret, scopes? }` (RFC-6749 grant); for a non-standard partner token endpoint add `profile: "custom"` with a `custom: { requestFormat, clientIdField, clientSecretField, tokenResponsePath, expirySource }` descriptor. Do not put credential headers in operation `headers`; use connector `auth`. For per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+
+## Design tools for the model
+
+Design tools around what a user says, not 1:1 around API endpoints. A raw wrapper per endpoint (`get_task`, `list_tasks`, `close_task`) forces the model to orchestrate low-level calls and to know identifiers the user never sees — an MCP connector, but not a usable product. Instead:
 
-## Worked example (full server)
+- **Shape by intent.** Name and scope tools for the job to be done — "find my overdue tasks", "complete the task matching this text" — combining multiple backing calls in one recorded flow (`when(...)`) where it helps.
+- **Prefer names/text over raw IDs.** When an action needs an id the user does not know, pair the id-taking operation with a find/search operation that returns model-friendly summaries (id + a human label), so the model resolves text → id itself. Write descriptions that tell the model when to use each tool and how they chain.
+- **Return only what the model needs.** Map the response to a small, typed `output` (a few labelled fields), not the raw API payload.
 
-Declare the API as data, bind it with `use`, then record a call in a tool. `auth` reads a managed `secret(...)` — never inline a key. Map the HTTP body into your typed `output` with `${response...}`.
+This example pairs a name resolver with an id-taking action: the model calls `find_tasks` to turn the user’s words into an id, then `complete_task`. It is compile-verified on every `pnpm test`.
 
 ```ts
 import { connector, secret, server, tool, z } from '@noodleseed/one';
 
-const crm = connector('acme_crm')
-  .version('1.0.0')
-  .http({
-    baseUrl: 'https://api.acme.example',
-    allowedOrigins: ['https://api.acme.example'],
-    auth: { kind: 'apiKey', header: 'X-Api-Key', secret: secret('ACME_CRM_TOKEN') },
-    operations: {
-      get_ticket: {
-        type: 'read',
-        method: 'GET',
-        path: '/v1/tickets/{id}',
-        input: { id: { type: 'string', required: true } },
-        output: { subject: { type: 'string' }, status: { type: 'string' } },
-        response: { subject: '${response.data.subject}', status: '${response.data.state}' },
-      },
+const tasks = connector('tasks').version('1.0.0').http({
+  baseUrl: 'https://api.tasks.example',
+  allowedOrigins: ['https://api.tasks.example'],
+  auth: { kind: 'bearer', secret: secret('TASKS_TOKEN') },
+  operations: {
+    search_tasks: {
+      type: 'read',
+      method: 'GET',
+      path: '/tasks',
+      query: ['query'],
+      input: { query: { type: 'string', required: true } },
+      output: { matches: { type: 'array', required: true } },
+      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 } },
+      response: { ok: '${response.ok}' },
+    },
+  },
+});
 
-export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
-  tool('ticket_status', {
-    description: 'Look up a support ticket by id.',
-    input: z.object({ ticket_id: z.string() }),
-    output: z.object({ subject: z.string(), status: z.string() }),
+export default server('todo', { title: 'Tasks', version: '1.0.0', use: { tasks } }, [
+  tool('find_tasks', {
+    description: 'Find tasks whose text matches a query — call this first to resolve a task the user names by text into its id, then pass that id to complete_task.',
+    input: z.object({ query: z.string() }),
+    output: z.object({ matches: z.array(z.object({ id: z.string(), title: z.string() })) }),
+    fulfil: ({ input, connectors }) => {
+      const found = connectors.tasks.search_tasks({ query: input.query });
+      return { matches: found.matches };
+    },
+  }),
+  tool('complete_task', {
+    description: 'Mark a task complete by its id (get the id from find_tasks).',
+    input: z.object({ id: z.string() }),
+    output: z.object({ ok: z.boolean() }),
     fulfil: ({ input, connectors }) => {
-      const ticket = connectors.crm.get_ticket({ id: input.ticket_id });
-      return { subject: ticket.subject, status: ticket.status };
+      const result = connectors.tasks.close_task({ id: input.id });
+      return { ok: result.ok };
     },
   }),
 ]);
 ```
 
-More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+The model never sees a task id from the user; `find_tasks` returns `{ id, title }` summaries it can pick from, then `complete_task` acts by id. Keep write actions (`complete_task`) separate and explicitly described so the host can gate them.
 
 ## Compute connector example
 
@@ -120,10 +165,10 @@ More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `clientCredentials`
 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 } },
-  calls: { findCustomer: 'crm.findCustomer' },
+  calls: { find_customer: 'crm.find_customer' },
   limits: { timeoutMs: 1000, maxHostCalls: 2 },
   run(input, { callOperation }) {
-    const customer = callOperation("findCustomer", { email: input.email }) as { id?: string };
+    const customer = callOperation("find_customer", { email: input.email }) as { id?: string };
     return { score: customer.id && input.priority === "high" ? 100 : 50 };
   },
 });

package/skills/codex/references/chatgpt-compliance.md

@@ -0,0 +1,63 @@
+# ChatGPT App compliance (pre-submission)
+
+`noodle check --target chatgpt` verifies the *metadata* prerequisites; app-store submission also faces a
+human review against OpenAI’s Apps SDK UX principles. Run this checklist against the built app before
+submitting, and render it as an audit table in the design wireframe (`design/wireframe.html` in the
+`acme-*` examples) so partners and reviewers see it up front.
+
+## Contents
+
+- Metadata gate vs review
+- Pre-submission checklist
+- UI guidelines
+- Domain guardrails
+- Privacy and data
+
+## Metadata gate vs review
+
+`noodle check --target chatgpt --json` returning `ok:true` means the widget is *metadata-ready* (widget
+`domain`, `openai/outputTemplate`, CSP, tool annotations, and `invoking`/`invoked` invocation copy are
+present) — it does NOT prove host rendering, conversation UX, or submission acceptance. Validate real
+rendering in ChatGPT Developer Mode / MCP Inspector, then run the checklist below.
+
+## Pre-submission checklist (what review looks for)
+
+1. **Conversational value** — at least one capability relies on ChatGPT’s strengths: natural-language
+   actions no tap-driven app can do (e.g. "two margheritas and a lemon tart" parses into a cart). Cite
+   concrete app behavior, not aspirations.
+2. **Beyond base ChatGPT** — new knowledge, actions, or presentation (grounded partner data, live
+   inventory, signed handoffs, real-world routing).
+3. **Atomic, model-friendly actions** — self-contained tools with explicit input/output schemas, and an
+   annotation on every tool (`annotations.readOnly()` / `.action()` / `.openAction()`).
+4. **Helpful UI only** — justify each widget (would plain text degrade UX?), and note what you
+   deliberately did NOT build a widget for (payment is off-app → no payment widget).
+5. **In-chat task completion** — the user finishes a meaningful task in chat. For a top-of-funnel app,
+   the task is the discovery/config loop completed in-chat with an intentional handoff.
+6. **Performance** — tool calls scoped per step; response-time targets stated.
+7. **Discoverability** — broad, natural trigger prompts listed; description keywords planned. Golden
+   prompt sets and metadata optimization are a launch workstream, not polish.
+8. **Platform fit** — multi-turn dialogue, conversation memory, and multimodality where genuinely useful.
+
+## UI guidelines
+
+System fonts, monochrome outlined icons, WCAG AA contrast, at most two actions on inline cards, no nested
+scroll, and the right display mode per intent (inline by default; fullscreen only where browsing needs
+it; picture-in-picture only for live state). Brand only through `server` `branding` tokens — accent on
+the primary CTA, logo, and badges, nothing else; the compiler derives the palette. Never inject raw
+global CSS.
+
+## Domain guardrails
+
+For regulated-adjacent apps, add app-specific trust behaviors and **show them in the rendered pixels**:
+cite the source and its revision for consequential lookups; frame regulated content as "considerations,
+not a ruling"; never invent compatibility, availability, or pricing; and always show the relevant
+caution/disclaimer. These are what make a regulated-adjacent app approvable.
+
+## Privacy and data
+
+Data flows through OpenAI; tool payloads and whatever the server stores must match the partner’s privacy
+policy. No payment happens in chat (PCI stays off-app). Avoid per-user OAuth in a top-of-funnel v1 (use
+service credentials via a `connector`); add end-user auth only for two-way apps (`customerAuth`). Keep
+secrets out of tool output, widgets, and logs. If the partner’s published policy predates the app, flag a
+privacy gap for their counsel before submission. Re-run this checklist against the *built* app before
+every submission — not just the wireframe.

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

@@ -0,0 +1,76 @@
+# Connect a live API (you were given a key)
+
+When the user hands you an API key or credentials, don't infer the data from documentation — docs
+drift. Probe the live API, learn the real shape, then encode it as a `connector`. The loop:
+
+## Contents
+
+- Secure the key first
+- Probe the live API
+- Model the connector from the observed shape
+- Design intent tools
+- Prove real output
+- Then build the app
+
+## Secure the key first
+
+Never inline or log the key. Have the user put it in an environment variable, then store it as a
+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
+```
+
+In `server.ts` the key is only ever `secret("SOME_API_KEY")` — keep the raw value out of code, tests,
+prompts, logs, and generated files.
+
+## Probe the live API
+
+Learn the actual response shape empirically. Two ways — capture one real example response per endpoint
+you will use, and read its field names, nesting, array shapes, pagination, and id-vs-label fields:
+
+- **With your own HTTP/shell tool** — call a representative read endpoint using the key **from the env
+  var**, never the literal (so it stays out of logs): `curl -H "Authorization: Bearer $SOME_API_KEY"
+  https://api.example.com/things`. Inspect the returned JSON.
+- **Noodle-native** — author a minimal read operation that maps the whole body (`response: { raw:
+  '${response}' }`), `noodle secrets set` the key, then `noodle tools call` it to see the real payload
+  in-process.
+
+## Model the connector from the observed shape
+
+Encode the API as an HTTP connector, mapping only the fields you actually saw into a small typed
+`output`:
+
+- `connector("id").version("1.0.0").http({ baseUrl, allowedOrigins, auth, operations })`.
+- `auth: { kind: 'bearer', secret: secret('SOME_API_KEY') }` — or `{ kind: 'apiKey', header: 'X-API-Key',
+  secret: secret('SOME_API_KEY') }`. Never put the credential in operation `headers`.
+- Per operation: `method`, `path` (with `{id}` templates), `query: ["arg"]` for URL params, `input`,
+  `output`, and a `response` mapping whose `${response.path}` matches the real JSON — the parsed body is
+  bound directly to `${response}` (no `.body` envelope); use bracket indices for arrays
+  (`${response.results[0].id}`).
+
+The full connector shape, every `auth.kind`, and compute connectors are in
+`references/authoring-workflow.md`.
+
+## Design intent tools
+
+Shape tools around what the user says, not 1:1 around endpoints. Pair an id-taking action with a
+find/search operation that returns `{ id, label }` summaries so the model resolves text → id itself,
+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`.
+
+## Prove real output
+
+`noodle validate` / `noodle test` prove a connector tool *compiles and registers* — not that its
+mapping returns data. With the secret set, run a live read: `noodle tools call <read_tool> --args
+'{…}'` executes the connector against the real API in-process. Confirm the mapped fields are populated,
+not `undefined`; if they are empty, fix the `${response…}` paths against the real payload and re-run.
+Only run a live write if it is safe or the user approved it.
+
+## Then build the app
+
+With real data flowing, design the experience (`references/experience-design.md`), add widgets where a
+UI genuinely helps (`references/widgets-and-apps.md`), and verify with `noodle check`. Deploy per
+`references/deploy-and-ops.md`, and set the same secret in the hosted environment with `noodle secrets
+set` before the first hosted call.

package/skills/codex/references/examples.md

@@ -1,12 +1,15 @@
 # Examples
 
-Flagship examples (one per capability). Read the matching example for the pattern you need; extend an existing flagship rather than inventing a new shape.
+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.
 
 | 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/experience-design.md

@@ -0,0 +1,142 @@
+# Experience design
+
+Design the app experience before you author it. A ChatGPT app is a conversation with tools and
+widgets, not a website — decide the funnel, the tools, the widgets, and the handoff first, then
+build with the SDK (`references/authoring-workflow.md`, `references/widgets-and-apps.md`). This
+reference is the design discipline; the build references are the mechanics.
+
+## Contents
+
+- Design first
+- The handoff is the product
+- Grounded, never guessing
+- Two users: the human and the model
+- ChatGPT-native surface
+- Scope discipline and auth stance
+- Wireframe and UX-spec anatomy
+- The deliverables
+- From design to build
+
+## Design first
+
+Write a short design spec before you author `server.ts` — a `SPEC.md`-style note you keep updated as
+the app evolves. It has required fields:
+
+- **Funnel boundary** — one sentence stating exactly what happens in ChatGPT and what happens off-app.
+- **Tools** — each model-visible tool, snake_case, with what it takes and returns.
+- **Widgets and display modes** — each widget, PascalCase, and the display mode it renders in
+  (inline card / carousel / fullscreen / picture-in-picture). State the modes you deliberately do
+  *not* use, and why.
+- **Grounding sources** — where each fact comes from (a `connector` operation, a provided dataset).
+- **Handoff domains** — the external origins the app links out to (these become server
+  `handoff.allowedDomains`).
+- **Exceptions** — any deliberate departure from the defaults below, each with its reason.
+
+Then author, preview with `noodle dev` / `noodle devtools`, and iterate. The spec is the contract the
+tools, widgets, and handoff all trace back to.
+
+## The handoff is the product
+
+Default scope is **top-of-funnel**: ChatGPT owns discovery, intent-shaping, and configuration; the
+partner's own platform owns the transaction, the account, and everything after. The app hands off with
+a deep link that carries the configured state (a pre-filled cart, a chosen configuration), and the
+external target is declared in the server-level `handoff.allowedDomains`. This is a feature: it keeps
+payment and account burden off the app and keeps the partner's platform central.
+
+Deliberate exceptions exist — an app that completes the transaction in-chat (handing off for payment
+only), or a two-way app that reads and writes a connected account. When you break the top-of-funnel
+default, write down why in the design spec.
+
+## Grounded, never guessing
+
+The app's credibility is that it answers from the partner's own data, reached through a `connector`,
+never invented. Never fabricate compatibility, availability, pricing, or eligibility. For
+consequential lookups, **cite the source and its revision in the widget** (e.g. a spec-sheet name and
+revision date) and route unknowns to a human path rather than improvising. Guardrails belong in the
+rendered pixels, not just in prose.
+
+## Two users: the human and the model
+
+Every tool and widget serves two users at once — the human who interacts and the model that reads the
+result. Keep tools atomic with inputs the model can fill from natural language, and return enough
+structure that the model can speak confidently in one round-trip. Build a widget only where plain text
+would genuinely degrade the experience (photos, comparisons, carts, configuration). If text would do,
+don't build the widget.
+
+## ChatGPT-native surface
+
+Widgets should read as native to the host. Brand through the `server` `branding` tokens only — the
+compiler derives the palette — and reserve the accent for the primary CTA, the logo, and badges. No
+brand gradients, no app-shoved-into-chat. Keep inline cards to at most two actions and avoid nested
+scroll. Pick each display mode deliberately (fullscreen only where browsing genuinely needs it;
+picture-in-picture only for live ongoing state). See `references/widgets-and-apps.md` for the widget
+mechanics — do not restyle with raw global CSS.
+
+## Scope discipline and auth stance
+
+Lock the funnel boundary in writing before designing, and keep a "future enhancements" list as the
+pressure valve. No payment happens in chat. Avoid per-user auth in a top-of-funnel v1 — use the
+partner's service credentials via a `connector`; add end-user auth only when the app is two-way by
+nature (see the `customer-auth` example in `references/examples.md`).
+
+## Wireframe and UX-spec anatomy
+
+For anything non-trivial, sketch the experience as a wireframe before authoring — a walk through the
+conversation, screen by screen. Each screen shows a real user message, the **tool call that precedes
+the widget**, and the widget filled with plausible, internally consistent data (never lorem ipsum).
+Label each widget with its component name so the wireframe, the spec, and the code share one
+vocabulary; put the funnel boundary at the top; and render off-app destinations distinctly (they are
+reached only after the handoff). Each wireframe screen maps directly to noodle: a screen with a widget
+is a `toolWithWidget` + a React `view`; a plain answer is a `tool`; an off-app destination is a
+`handoff.allowedDomains` entry. A compact single screen, anonymized to a fictional "Acme" business:
+
+```html
+<div class="phone">
+  <div class="chatgpt-header">ChatGPT · Acme</div>
+  <div class="msg user">14kW array, ~40kWh battery — what pairs with the Acme X?</div>
+  <!-- tool call precedes every widget; the model fills inputs from the message -->
+  <div class="tool-call">check_compatibility { model: "Acme X", battery_kwh: 40 }</div>
+  <div class="wcard">
+    <div class="wcard-head">CompatibilityCard</div>       <!-- component name = code + spec -->
+    <div class="wcard-body">
+      <div class="kv">Acme X ⇄ 40kWh pack <span class="badge certified">Compatible</span></div>
+      <div class="cite">Source: Acme Integration Guide, Rev 7 (2026)</div>  <!-- grounded + cited -->
+      <a class="cta">Configure system</a>                 <!-- ≤2 actions on an inline card -->
+    </div>
+  </div>
+</div>
+```
+
+Expand from one screen to the full journey: entry → configuration → handoff, ending at the off-app
+destination. Verify the built app against the design with `noodle check --target chatgpt`.
+
+For the full quality bar, open a shipped gold-standard set: in the Noodle Seed repository, the
+`design/` folder of the `acme-discovery` (top-of-funnel), `acme-tasks` (two-way), and `acme-bistro`
+(end-to-end) examples each holds a house-style UX Document and a single-file HTML wireframe with an
+embedded OpenAI Apps SDK compliance audit. Match that bar.
+
+## The deliverables
+
+The design phase produces up to three artifacts — worked gold-standard versions live in each
+`acme-*` example's `design/` folder (copy their structure, swap the content):
+
+- **UX Document** — the thinking artifact. House-style sections: product overview / knowledge base,
+  competitive landscape, personas, conversational flow (with tool-call playscripts), widget specs +
+  a display-mode strategy, tool definitions, conversation guardrails, journey map, handoff/auth
+  architecture, demo scope, success metrics, and future enhancements — opening on the funnel-boundary
+  line every scope debate resolves against.
+- **Wireframe** — the single-file HTML alignment artifact (anatomy above) with the embedded compliance
+  audit; see `references/chatgpt-compliance.md`.
+- **API contract** — when the partner's backend must be built or wrapped. Escalate: (1) the MCP
+  tool→call-sequence map (always); (2) "Recommended API Shapes" — concrete request/response JSON per
+  tool, including the hardest nested case; (3) a full OpenAPI spec for transactional apps. Contract
+  rules: shape responses for one-round-trip rendering (embed related objects, pre-sort); put stable
+  ids on anything the user picks; keep validation in the API, not the model; the handoff endpoint
+  mints a signed, expiring URL + attribution and never proxies payment; use server-side partner
+  credentials for v1 (per-user auth only for two-way apps); name tools for user intent.
+
+## From design to build
+
+Once the design spec is settled, build it: `references/authoring-workflow.md` for the author→validate
+loop and connectors, `references/widgets-and-apps.md` for widgets and CSP, `references/examples.md`
+for a flagship to extend, and `references/deploy-and-ops.md` to ship.

package/skills/codex/references/troubleshooting.md

@@ -25,6 +25,6 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
-| A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (`${response.body...}` when the parsed body is bound to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |
+| 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}`) |
 | 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` |