@noodleseed/agent-kit 0.13.0 → 0.15.0

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.15.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/examples/acme-bistro/README.md

@@ -0,0 +1,51 @@
+# Acme Bistro — end-to-end ordering with payment-only handoff
+
+A Noodle MCP App for **Acme Bistro**, a fictional restaurant. It is the flagship for the **end-to-end
+transaction** pattern: the customer browses the menu and builds the order *in chat*, and the order
+completes in chat — only **payment** hands off, via a signed checkout deep link (the card never touches
+the app). It pairs a `toolWithWidget` menu/cart with `toolForWidget` cart helpers and a model-visible
+`create_checkout` tool backed by `handoff.allowedDomains`.
+
+Capability slot: **end-to-end in-chat transaction + payment-only handoff**, plus a worked **design-first**
+deliverable set (`design/` — a UX Document, a single-file HTML wireframe with an embedded OpenAI Apps SDK
+compliance audit, and a Recommended API contract). It sets the quality bar the `noodle-seed` skill's
+`references/experience-design.md` and `references/chatgpt-compliance.md` teach. (Distinct from
+`food-ordering`, which is the broad widget-composition proof; this one owns the design-first end-to-end +
+compliance exemplar.)
+
+## Design deliverables (the standard to match)
+
+- [`design/UX-Document.md`](design/UX-Document.md) — the house-style UX Document.
+- [`design/wireframe.html`](design/wireframe.html) — the single-file wireframe (open in a browser) with the
+  embedded OpenAI Apps SDK compliance audit.
+- [`design/api-contract.md`](design/api-contract.md) — the Recommended API shapes for the partner's kitchen/
+  ordering backend.
+
+## Local author loop
+
+```sh
+noodle validate
+noodle test
+noodle dev
+```
+
+In another terminal:
+
+```sh
+noodle tools list
+noodle tools call show_menu --args '{"customer":"Asha"}'
+noodle tools call create_checkout --args '{"customer":"Asha","cartToken":"stone_pizzax2-lemon_tartx1","total":36}'
+noodle check --target chatgpt
+```
+
+## Deploy
+
+```sh
+noodle link --org demo --app acme-bistro
+noodle deploy --access owner-only
+noodle open
+```
+
+This example has no connector secrets and does not include tokens, caller-key mechanisms, or
+`.env.noodle` values. The menu, prices, and URLs are fictional; payment is handled off-app on
+`acme.example`, never in chat.