@noodleseed/agent-kit 0.13.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.13.0",
+  "packageVersion": "0.14.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "4dfd82f9f2acf59f7df30617b8f319b8cc0a743c721aeb027e454cb1af0f1c0a",
+      "sha256": "430e32c03fd13e62cc285280ed846178ae941821516445ba210e5a77fb9e49cd",
       "agentTarget": "codex"
     },
     {
@@ -31,6 +31,16 @@
       "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"
+    },
     {
       "path": "skills/codex/references/widgets-and-apps.md",
       "sha256": "dea06536f780f0bb6d26dc63a6f1f35e2d6eb97f7a9c1c8574ed7377ccfe37a8",
@@ -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": "6027e2822f6045e36955996c3757370cc287966493ef3bb0dd56420eeeb47f1e",
+      "sha256": "859218a6d7b97bc9a2b7da698550c5505b2ffab8370aecd3a21814ab3f4dd05f",
       "agentTarget": "claude-code"
     },
     {
@@ -91,6 +106,16 @@
       "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"
+    },
     {
       "path": "skills/claude-code/references/widgets-and-apps.md",
       "sha256": "dea06536f780f0bb6d26dc63a6f1f35e2d6eb97f7a9c1c8574ed7377ccfe37a8",
@@ -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.13.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.13.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/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/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.13.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/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.