@noodleseed/agent-kit 0.20.0 → 0.21.1

package/skills/claude-code/references/sdk-surface.md

@@ -38,7 +38,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 
 ### Customer auth
 
-- `customerAuth.oidc(...)`, `.firebase(...)`, `.microsoft(...)`, or `.bridge(...)` — end-user/customer identity for `--access customers` deployments.
+- `customerAuth.oidc(...)`, `.firebase(...)`, `.microsoft(...)`, or `.bridge(...)` — end-user/customer identity for `--access customers` deployments. Firebase Web App fields are browser-visible configuration: use `variable(...)`, not `secret(...)`, and restrict the key in Firebase.
 
 ### Sessions
 
@@ -60,7 +60,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.
 - `customerAuth.*(...)` belongs in `server` options when deployed customer callers need verified identity; inspect `examples/customer-auth` or `examples/sharepoint` before using it.
-- `state` defines durable widget state handles; `handoff` declares allowed external domains for safe host handoff.
+- `state` defines durable widget state handles; handle schemas may use `.optional()`/`.default()` — defaulted fields are optional on write, so a save that omits them still validates. `handoff` declares allowed external domains for safe host handoff.
 
 ## Recipes
 

package/skills/claude-code/references/widgets-and-apps.md

@@ -18,6 +18,12 @@ Use `tool(name, { description, input, output, fulfil, view })` for a model-visib
 
 Generated widgets, official examples, and agent-authored MCP Apps must start with `@noodleseed/one/react` primitives and semantic tokens. Custom React/CSS or third-party components remain valid when the kit lacks the required behavior or the developer explicitly requests them.
 
+`noodle init my-app` defaults to a comprehensive server—tools, resource, prompt, state contract, branding, handoff, widget, and embedded assistant—so begin by adapting that complete surface. Use `--template hello` only when the product explicitly needs the minimal server.
+
+The default composition rule is: build the smallest useful conversational surface. Inline has one purpose, one primary action, and at most two visible actions. Use progressive disclosure or a later conversational turn for secondary detail; request fullscreen only when the user asks or the task genuinely needs it. Never use nested scrolling. At 280px and wider, the widget must remain one-column, readable, touch-safe, and free of horizontal overflow. Remove secondary chrome before shrinking essential content.
+
+Every production widget handles loading, empty, partial, stale, error, retry, and success states. Prefill fields from known tool results and choose safe, reversible defaults; preserve the user’s work across rerenders, and never preselect a consequential action. Use public React primitives and branding tokens. Never author against `ns-*`, `nsr-*`, or example-local `--nw-*` classes/tokens; those are implementation details, not alternate design systems.
+
 ## React hook surface
 
 Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
@@ -47,7 +53,7 @@ Author React. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react
 
 ```tsx
 import type { ServerDefinition } from '@noodleseed/one';
-import { generateHelpers } from '@noodleseed/one/react';
+import { Action, ActionBar, AsyncBoundary, Feedback, Field, Flow, Frame, Region, Select, generateHelpers } from '@noodleseed/one/react';
 
 // One call wires the typed host bridge; destructure only the hooks this view uses.
 const { useToolInfo, useCallTool, useViewState, useOpenExternal } =
@@ -71,28 +77,32 @@ export default function OrderStatus() {
 
   return (
     // data-llm mirrors the visible state back to the model as text context.
-    <main data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
-      <h1>Pickup order</h1>
-      <label>
-        Item
-        <select value={item} onChange={(event) => setItem(event.currentTarget.value)}>
-          <option value="falafel_wrap">Falafel Wrap</option>
-          <option value="lentil_soup">Lentil Soup</option>
-          <option value="mint_lemonade">Mint Lemonade</option>
-        </select>
-      </label>
-      <button
-        type="button"
-        disabled={placeOrder.isPending}
+    <Frame title="Pickup order" displayMode="auto" data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
+      <Flow variant="stack">
+      <AsyncBoundary state={placeOrder} loading="Placing order…" error={(error) => error.message}>
+      <Region title="Order" description="Choose one item for pickup.">
+      <Field label="Item">
+        <Select value={item} onChange={(event) => setItem(event.currentTarget.value)} options={[
+          { value: 'falafel_wrap', label: 'Falafel Wrap' },
+          { value: 'lentil_soup', label: 'Lentil Soup' },
+          { value: 'mint_lemonade', label: 'Mint Lemonade' },
+        ]} />
+      </Field>
+      </Region>
+      {confirmed?.status ? <Feedback status="success">{confirmed.status}</Feedback> : null}
+      <ActionBar>
+      <Action variant="primary" pending={placeOrder.isPending} pendingLabel="Placing…"
         onClick={() => placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item })}
       >
-        {placeOrder.isPending ? 'Placing…' : 'Place order'}
-      </button>
-      <p>{confirmed?.status ?? `Total: $${total}`}</p>
-      <button type="button" onClick={() => openExternal(checkoutUrl)}>
+        Place order
+      </Action>
+      <Action onClick={() => openExternal(checkoutUrl)}>
         Continue checkout
-      </button>
-    </main>
+      </Action>
+      </ActionBar>
+      </AsyncBoundary>
+      </Flow>
+    </Frame>
   );
 }
 ```
@@ -169,7 +179,7 @@ export default server(
 A "ChatGPT App" is not a separate authoring surface — it is exactly this MCP Apps widget rendered by the ChatGPT host. From the same declaration you author three things:
 
 - `domain` on the widget — one https origin per app (required for app-store submission, optional for dev-mode testing).
-- `csp: { connectDomains, resourceDomains }` — the exact network/resource origins the widget may reach; keep them minimal. Add `frameDomains` only if the widget embeds an iframe (it relaxes subframe rendering and draws stricter review).
+- `csp: { connectDomains, resourceDomains }` — the exact network/resource origins the widget may reach; keep them minimal. Add `frameDomains` only if the widget embeds an iframe (it relaxes subframe rendering and draws stricter review). These three lists are the complete CSP surface — there is no `base-uri` list.
 - server `handoff.allowedDomains` — the external-link targets `useOpenExternal()` opens.
 
 The compiler emits the rest automatically: the `openai/*` metadata (`openai/outputTemplate`, `openai/widgetCSP`, `openai/widgetDescription`) and ChatGPT’s `redirect_domains` (derived from `handoff.allowedDomains`). `window.openai` and Claude’s ext-apps bridge are auto-detected at startup, so the same widget renders in both Claude and ChatGPT with no host-specific code.

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.20.0
-hash: 39c6a606c728d164
+version: 0.21.1
+hash: cd25535e1d6dbf4f
 ---
 
 # Noodle Seed
@@ -25,7 +25,7 @@ Before authoring, design the experience — the funnel/handoff boundary, tools,
 4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
 5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
 6. **Prove real output** — `validate`/`test` prove a connector tool *compiles and registers*, not that its response mapping returns data. Set the secret at the scope your local `noodle dev` resolves (`noodle secrets set <NAME> --runtime local --scope org --org local --from-env <ENV>`; a secret set at the wrong scope leaves the loopback returning `-32600 "not found"` — see `references/connect-an-api.md`), then run a live read — `noodle tools call <read_tool> --args '{...}'` executes the connector against the real API in-process — and confirm the mapped fields are populated, not `undefined`, before trusting it. Only run a live write if it is safe/approved.
-7. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
+7. **Apps/widgets/embed** — `noodle check --json` (add `--target chatgpt|claude|embedded-assistant`), then `noodle devtools`; use `references/widgets-and-apps.md` for MCP Apps and `references/embedded-assistant.md` for a SaaS embed.
 8. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
 9. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
 10. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
@@ -39,6 +39,7 @@ Scan all of these during discovery; open in full the ones your task touches:
 - `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/embedded-assistant.md` — HTTPS origins, managed model config, deploy-before-client sequencing, backend session exchange, browser mounting, and credential boundaries.
 - `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.

package/skills/codex/examples/acme-bistro/README.md

@@ -34,7 +34,7 @@ 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 tools call create_checkout --args '{"customer":"Asha","cartToken":"cart_1","total":36}'
 noodle check --target chatgpt
 ```
 

package/skills/codex/examples/acme-tasks/README.md

@@ -97,13 +97,18 @@ assistant: embeddedAssistant({
 The assistant automatically inherits this server's existing `branding` block, so its name, accent,
 light/dark surfaces, density, and radius match the `TaskList` widget without a second brand declaration.
 
+Every assistant origin is exact and HTTPS-only. If the customer web app needs local browser testing, it
+must serve itself over development HTTPS and add its `https://localhost:<port>` origin; `noodle dev` does
+not provide TLS for that separate SaaS app.
+
 The customer backend exchanges its authenticated user through `@noodleseed/assistant/server`; the browser
 uses the Web Component or React wrapper and never receives the embed client or model secret. Validate with
 `noodle check --target embedded-assistant`, then create the backend credential with
-`noodle assistant clients create` after deployment.
+`noodle assistant clients create` after deployment. Model URL/name/key values stay in Noodle managed config;
+only the Noodle service URL and assistant client ID/secret belong in the authenticated customer backend.
 
-Install the independently versioned embed SDK in the customer web application with
-`pnpm add @noodleseed/assistant`.
+Install the independently versioned embed SDK with the customer web application's existing package manager;
+do not introduce a second lockfile.
 
 This example has no connector secrets and does not include tokens, caller-key mechanisms, or
 `.env.noodle` values. All tasks are fictional seed data.

package/skills/codex/examples/food-ordering/README.md

@@ -21,6 +21,14 @@ private customer data.
 | Handoff | `handoff.allowedDomains` allows only `https://orders.example.com` checkout URLs |
 | Progressive enhancement | Non-Apps hosts still receive stores, featured items, and a readable fallback summary |
 
+The example is intentionally richer than the generated starter, but each inline view still follows the
+same default: one immediate purpose, one primary action, at most one subordinate action, and progressive
+disclosure for the rest. Preview it at 280px before adding navigation or local CSS; loading, empty, stale,
+error/retry, and success states must remain readable without nested vertical scrolling.
+
+Like the comprehensive default `noodle init my-app` scaffold, this flagship keeps the server feature-rich
+while making each individual widget view focused; server capability breadth and screen density are separate.
+
 ## Local Author Loop
 
 ```sh

package/skills/codex/examples/food-ordering/src/server.ts

@@ -151,7 +151,9 @@ const cartStateSchema = z.object({
   customer: z.string(),
   notes: z.string().optional(),
   subtotal: z.number(),
-  status: z.enum(['draft', 'review', 'handoff']),
+  // `.default()`/`.optional()` state fields are optional on write: a cart save that omits
+  // `status` still validates, and a fresh cart starts in `draft`.
+  status: z.enum(['draft', 'review', 'handoff']).default('draft'),
   checkoutUrl: z.string().optional(),
 });
 

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

@@ -10,4 +10,8 @@ noodle dev examples/hello/src/server.ts --app hello
 noodle deploy examples/hello/src/server.ts --org acme --app hello
 ```
 
+`noodle export manifest examples/hello/src/server.ts` compiles the same entrypoint locally and prints
+the portable, vendor-neutral manifest JSON — the eject path: your `server.ts` plus this manifest is
+the whole app, yours to read, diff, and keep.
+
 It is also the fixture for `pnpm smoke:dev` and the e2e harness, so keep its tool surface stable.

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

@@ -1,4 +1,4 @@
-import { server, tool, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 export default server(
   'hello',
@@ -16,11 +16,14 @@ export default server(
     tool('greet', {
       description: 'Greet someone by name.',
       input: z.object({
-        name: z.string(),
+        // Defaults are advertised to the model and applied at runtime when the argument is omitted.
+        name: z.string().default('world'),
       }),
       output: z.object({
         message: z.string(),
       }),
+      // Read-only, closed-world: assistant surfaces run this without a consent prompt.
+      annotations: annotations.readOnly(),
       fulfil: ({ input }) => {
         return { message: `Hello, ${input.name}!` };
       },

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

@@ -5,4 +5,15 @@ describe('hello example', () => {
   it('exports a Noodle server definition', () => {
     expect(typeof app.toManifest).toBe('function');
   });
+
+  it('advertises the greet default and keeps the argument optional', async () => {
+    const manifest = await app.toManifest();
+    const greet = manifest.tools?.find((tool) => tool.name === 'greet');
+    const schema = greet?.inputSchema as {
+      properties?: { name?: { default?: unknown } };
+      required?: string[];
+    };
+    expect(schema.properties?.name?.default).toBe('world');
+    expect(schema.required ?? []).not.toContain('name');
+  });
 });

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

@@ -200,7 +200,7 @@ Author managed config as `secret("NAME")` / `variable("NAME")` and operate it wi
 
 ## Embedded assistant
 
-To place the same server tools inside the SaaS web app, declare the shared identity once with `branding: { name: "Acme", accent: "#3157D5", surface: "#FFFFFF", surfaceDark: "#161B26", theme: { dark: { accent: "#9FB4FF" } } }`, then add `assistant: embeddedAssistant({ model: openAICompatible({ baseUrl: variable("ASSISTANT_MODEL_BASE_URL"), model: variable("ASSISTANT_MODEL"), apiKey: secret("ASSISTANT_MODEL_API_KEY") }), allowedOrigins: ["https://app.example.com"], layout: { mode: "floating", position: "bottom-right" } })`. Widgets and the embed inherit the same brand kit. Keep origins exact. Install the independently versioned embed SDK with `pnpm add @noodleseed/assistant`; the customer backend uses its `/server` export to exchange the already-authenticated user for a short-lived browser session, while the browser uses the package root or `/react` export. Client and model secrets never enter the browser. Run `noodle check --target embedded-assistant` before deploy, then manage backend credentials with `noodle assistant clients create|list|rotate|revoke`.
+To place the same server tools inside a SaaS web app, declare `assistant: embeddedAssistant(...)` alongside the one server-level brand kit. Read `embedded-assistant.md` before integrating: it owns the HTTPS-origin rule, managed model configuration, required deploy-before-client sequence, customer-backend exchange, browser mount, and verification checklist.
 
 ## Boundaries
 

package/skills/codex/references/compile-errors.md

@@ -18,6 +18,7 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `invalid_name` | Rename the identifier to match the allowed pattern (lowercase, no spaces/reserved characters) cited at `path`. |
 | `duplicate_name` | Two tools/components share a name; give each a unique name at the cited `path`. |
 | `unsupported_manifest_version` | Update the SDK/CLI so the emitted manifest version is supported; do not pin an old manifest shape. |
+| `reserved_for_future_version` | The verb at `path` (e.g. `compute`, `elicit`) is reserved for a future core version; express the step with `use` (a connector operation) or `map` (a pure mapping) instead. |
 | `invalid_operation_ref` | Fix the connector operation reference to `alias.operation` for an operation that exists on that connector. |
 | `external_ref` | Remove the external/remote `$ref`; schemas must be self-contained — inline the definition instead of dereferencing a URL. |
 | `invalid_schema_ref` | Correct the `$use` schema reference syntax at `path`; it does not name a resolvable local schema. |

package/skills/codex/references/deploy-and-ops.md

@@ -5,6 +5,7 @@
 - Authenticate
 - Link and target
 - Deploy and inspect
+- Eject path (portable manifest)
 - Connect into a host
 - Access modes
 - Org and members
@@ -24,6 +25,10 @@
 
 `noodle deploy` deploys the server. Then `noodle open` (latest URL), `noodle status`, `noodle inspect` (metadata, no secrets), `noodle smoke` (readiness diagnostics), and `noodle rollback <deploymentId>` to revert.
 
+## Eject path (portable manifest)
+
+`noodle export manifest [--output <file>]` compiles the entrypoint locally and emits the portable, vendor-neutral manifest JSON — no service, no login, no account. A Noodle app is just `src/server.ts` plus this manifest: the user can read it, diff it, and keep it.
+
 ## Connect into a host
 
 Once deployed, register the server as a tool in a host with `noodle connect <host>` (`claude-code`, `codex`, `chatgpt`, `cursor`, `vscode`, `claude`, `inspector`) — it prints the exact config to paste.

package/skills/codex/references/embedded-assistant.md

@@ -0,0 +1,208 @@
+# Embedded assistant
+
+## Contents
+
+- Architecture
+- Author and validate
+- Configure and deploy
+- Access modes and customer auth
+- Create the backend client
+- Integrate the customer backend
+- Verified session context (identity and claims)
+- The session response
+- Mount the browser component
+- Toolchain requirements
+- Verify the boundary
+- Troubleshooting: symptom to diagnosis
+
+## Architecture
+
+The browser never receives a model key, assistant client secret, MCP token, or raw application session. The embedding SaaS authenticates its own user, its backend exchanges that verified identity through `@noodleseed/assistant/server`, and the browser receives only a short-lived assistant session.
+
+Keep the two configuration sets separate:
+
+| Owner | Values | Destination |
+| --- | --- | --- |
+| Noodle deployment | `ASSISTANT_MODEL_BASE_URL`, `ASSISTANT_MODEL`, `ASSISTANT_MODEL_API_KEY` | `noodle variables set` / `noodle secrets set`; never the SaaS environment |
+| SaaS backend | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET` | Backend-only environment or secret manager; never browser code or `NEXT_PUBLIC_*`/equivalent variables |
+
+## Author and validate
+
+Use the same server tools in the embed; do not create a second tool set. Declare one server-level brand kit and an assistant configuration:
+
+```ts
+branding: { name: "Acme", accent: "#3157D5" },
+assistant: embeddedAssistant({
+  model: openAICompatible({
+    baseUrl: variable("ASSISTANT_MODEL_BASE_URL"),
+    model: variable("ASSISTANT_MODEL"),
+    apiKey: secret("ASSISTANT_MODEL_API_KEY"),
+  }),
+  allowedOrigins: ["http://localhost:3000", "https://app.example.com"],
+  layout: { mode: "floating", position: "bottom-right" },
+}),
+```
+
+`allowedOrigins` are exact origins: scheme, host, and optional port, with no path, trailing slash, or wildcard. Production origins must be HTTPS; plain HTTP is accepted only for loopback development origins (`http://localhost:<port>`, `http://127.0.0.1:<port>`). `noodle dev` serves the MCP project, not the embedding SaaS.
+
+Run:
+
+```sh
+noodle validate --json
+noodle check --target embedded-assistant --json
+```
+
+Use `noodle commands --json` before proposing command flags; do not invent flags from memory.
+
+## Configure and deploy
+
+Local MCP authoring and tests need no account, but an external browser embed needs an active assistant-enabled deployment before a backend client can be created. Set the model values on the target org/app/env, then deploy:
+
+```sh
+noodle variables set ASSISTANT_MODEL_BASE_URL --scope env --org <org> --app <app> --env <env> --value <https-model-base-url>
+noodle variables set ASSISTANT_MODEL --scope env --org <org> --app <app> --env <env> --value <model>
+noodle secrets set ASSISTANT_MODEL_API_KEY --scope env --org <org> --app <app> --env <env> --from-env ASSISTANT_MODEL_API_KEY
+noodle deploy --org <org> --app <app> --env <env>
+```
+
+Do not put these model values in the embedding SaaS environment. A production deployment may omit a local origin; include a loopback origin only when local browser integration is required.
+
+## Access modes and customer auth
+
+Session exchange authenticates with the backend client credentials, so the embed works under any `--access` mode. Add `--access customers` only when verified end customers should also call the MCP endpoint directly. That mode requires `server.auth`; `noodle deploy` preflights the rule locally and fails with `server_auth_required` before contacting the service. Fix by adding auth to server options:
+
+```ts
+auth: customerAuth.bridge({ verifyUrl: "https://app.example.com/api/auth/verify" }),
+// or a concrete adapter: customerAuth.firebase({ projectId, apiKey })
+```
+
+## Create the backend client
+
+After the deployment is active:
+
+```sh
+noodle assistant clients create --name web --org <org> --app <app> --env <env>
+```
+
+The CLI writes `{ clientId, clientSecret }` to a mode-`0600` file and prints only its path. Move the values into the SaaS backend secret manager without printing or committing them. Rotation invalidates the previous secret.
+
+## Integrate the customer backend
+
+Read the customer repository lockfile or `packageManager` field and install `@noodleseed/assistant` with that existing package manager; never introduce a second lockfile.
+
+Create an authenticated same-origin backend route:
+
+```ts
+import { createAssistantSession } from "@noodleseed/assistant/server";
+
+export async function POST(request: Request) {
+  const user = await requireCurrentUser(request);
+  const { context } = await request.json();
+  const session = await createAssistantSession({
+    serviceUrl: process.env.NOODLE_SERVICE_URL!,
+    clientId: process.env.NOODLE_ASSISTANT_CLIENT_ID!,
+    clientSecret: process.env.NOODLE_ASSISTANT_CLIENT_SECRET!,
+    origin: process.env.PUBLIC_APP_ORIGIN!,
+    user: { id: user.id, email: user.email, roles: user.roles },
+    context,
+  });
+  return Response.json(session);
+}
+```
+
+Authenticate before exchange. Source `origin` from trusted server configuration or strictly match the request origin against the same exact allowlist; never accept an arbitrary request header. Treat page context as untrusted model context, never authorization. Forward the helper response unchanged.
+
+`serviceUrl` is the Noodle Seed control-plane base URL: the value `noodle assistant clients create` prints, also stored as `serviceUrl` in `deployment.json`. It is NOT the deployment MCP endpoint (`url`, which ends in `/v1/mcp` and rejects session exchange). Never probe or guess endpoints with real credentials.
+
+## Verified session context (identity and claims)
+
+The embedding developer defines what authenticated session context the assistant receives. One mechanism, three hops:
+
+1. The authenticated backend passes standard identity and any verified claims at session exchange (flat scalars only):
+
+```ts
+const session = await createAssistantSession({
+  serviceUrl, clientId, clientSecret, origin,
+  user: { id: user.id, email: user.email, name: user.name },
+  claims: { displayName: user.name, accountTier: account.tier, region: account.region },
+});
+```
+
+2. The server author declares the allowlist in `server.ts` — undeclared claims are dropped at session exchange (never rejected, so backend and server deploys may skew safely):
+
+```ts
+assistant: embeddedAssistant({
+  model, allowedOrigins,
+  sessionClaims: {
+    displayName: { exposeToModel: true },
+    accountTier: { exposeToModel: true },
+    region: {}, // tools only, never in the prompt
+  },
+}),
+```
+
+3. Consumption. Tools read the verified identity and declared claims through the `user` scope:
+
+```ts
+tool("greet", {
+  description: "Greet the signed-in user.",
+  input: z.object({}),
+  annotations: annotations.readOnly(),
+  fulfil: ({ user }) => ({ message: `Hello, ${user.name}!`, tier: user.claims.accountTier }),
+});
+```
+
+Manifest expressions use `${user.name}`, `${user.email}`, `${user.subject}`, `${user.claims.<key>}`. The model receives one platform identity line automatically: standard identity (name/email) whenever present, plus only the claims marked `exposeToModel: true` — so the assistant greets the actual user and can pass identity into tool arguments. `noodle check --target embedded-assistant` lists the declared claim contract.
+
+Page `context` from the widget remains untrusted hint data; verified facts belong in `claims`, never in `context`.
+
+## The session response
+
+The exchange returns the versioned Embedded Assistant v1 contract. `token`, `expiresAt`, and `endpoints.turns` / `endpoints.toolConfirmations` (absolute URLs) are always present; `configuration` is optional theming data. Forward the body unchanged; the widget posts turns to `endpoints.turns` itself. Do not rebuild, filter, or rewrite the response.
+
+## Mount the browser component
+
+Use the React wrapper in React applications:
+
+```tsx
+import { NoodleAssistant } from "@noodleseed/assistant/react";
+
+<NoodleAssistant sessionEndpoint="/api/assistant/session" theme="auto" />;
+```
+
+Or import the package root once and mount `<noodle-assistant session-endpoint="/api/assistant/session" theme="auto"></noodle-assistant>`. Mount only inside the authenticated application surface.
+
+The component renders a custom element and must mount client-side. In a Next.js App Router tree, put the mount in a `"use client"` component; from a server component or the Pages Router, load it with `next/dynamic` and `ssr: false`.
+
+## Toolchain requirements
+
+- Node.js 20+ for `@noodleseed/assistant/server`.
+- The package ships ESM and CommonJS with full export conditions; no bundler aliases, `transpilePackages`, or ambient type shims are needed. If resolution fails, the installed package version is outdated: update `@noodleseed/assistant` instead of adding workarounds.
+- TypeScript `moduleResolution` `bundler` or `node16` recommended; classic `node` also resolves the `/react` and `/server` subpaths.
+
+## Verify the boundary
+
+- Signed-out session exchange returns `401`.
+- The browser network/DOM/storage contains no client secret or model key.
+- The local and production origins match `allowedOrigins` character-for-character.
+- Auto-run requires the full safe-read annotation (`annotations.readOnly()`: read-only, non-destructive, closed-world); unannotated or partially annotated tools always confirm. Writes require confirmation by design.
+- An expired turn re-exchanges once; confirmations never replay.
+- Wrong-origin and malformed-origin requests fail closed.
+
+## Troubleshooting: symptom to diagnosis
+
+| Symptom | Diagnosis | Fix |
+| --- | --- | --- |
+| Widget renders but no reply arrives and model usage stays zero | Turns are not reaching the service: outdated `@noodleseed/assistant` package, or the session response was rebuilt/filtered by the backend route | Update the package to the latest version; forward the session response unchanged |
+| `assistant-error` with code `invalid_response` | The turn endpoint returned HTML or non-SSE content (auth redirect, proxy page) | Check the backend session route path and any middleware/rewrites on the embedding app |
+| Build error `Package path ./react is not exported` | Outdated package version with import-only export conditions | Update `@noodleseed/assistant`; do not add webpack aliases or type shims |
+| Deploy fails with `server_auth_required` | `--access customers` without `server.auth` | Add `customerAuth.bridge(...)` or an adapter to server options |
+| Validate rejects an origin | Non-loopback HTTP origin in `allowedOrigins` | Use the exact HTTPS production origin; HTTP is only for `localhost`/`127.0.0.1` |
+| Session exchange returns 404 | `serviceUrl` points at the deployment MCP endpoint | Use the control-plane service URL printed by `noodle assistant clients create` |
+| Session exchange returns 403 `origin is not allowed` | Request origin differs from `allowedOrigins` character-for-character | Align the exact scheme/host/port on both sides and redeploy |
+| Hydration or `HTMLElement is not defined` errors | The component mounted during server rendering | Mount client-only (`"use client"` or `next/dynamic` with `ssr: false`) |
+| A read-only tool still asks for confirmation | Its annotations fail the safe-read rule: auto-run requires `readOnlyHint: true`, `destructiveHint: false`, AND `openWorldHint: false` (use `annotations.readOnly()`; `readOnly({ openWorld: true })` confirm-gates) | Fix the annotations; `noodle check --target embedded-assistant` lists every confirm-gated tool |
+| `${user.claims.<key>}` is empty | Claim not declared in `sessionClaims` (or key typo) — undeclared claims are dropped at exchange | Declare the key in `embeddedAssistant({ sessionClaims })` and redeploy |
+| `${user.name}` is empty | Backend did not pass `user.name` to `createAssistantSession` | Pass the verified name from the authenticated backend session |
+| The model does not know a claim you passed | Claim is tools-only | Mark it `exposeToModel: true` in `sessionClaims` |
+| Behavior does not change after `noodle deploy` | Outdated platform: before the 2026-07 fix, clients were pinned to their creation-time deployment | Update the platform; sessions now follow the tenant's active deployment |

package/skills/codex/references/sdk-surface.md

@@ -38,7 +38,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 
 ### Customer auth
 
-- `customerAuth.oidc(...)`, `.firebase(...)`, `.microsoft(...)`, or `.bridge(...)` — end-user/customer identity for `--access customers` deployments.
+- `customerAuth.oidc(...)`, `.firebase(...)`, `.microsoft(...)`, or `.bridge(...)` — end-user/customer identity for `--access customers` deployments. Firebase Web App fields are browser-visible configuration: use `variable(...)`, not `secret(...)`, and restrict the key in Firebase.
 
 ### Sessions
 
@@ -60,7 +60,7 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
 - View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.
 - `customerAuth.*(...)` belongs in `server` options when deployed customer callers need verified identity; inspect `examples/customer-auth` or `examples/sharepoint` before using it.
-- `state` defines durable widget state handles; `handoff` declares allowed external domains for safe host handoff.
+- `state` defines durable widget state handles; handle schemas may use `.optional()`/`.default()` — defaulted fields are optional on write, so a save that omits them still validates. `handoff` declares allowed external domains for safe host handoff.
 
 ## Recipes
 

package/skills/codex/references/widgets-and-apps.md

@@ -18,6 +18,12 @@ Use `tool(name, { description, input, output, fulfil, view })` for a model-visib
 
 Generated widgets, official examples, and agent-authored MCP Apps must start with `@noodleseed/one/react` primitives and semantic tokens. Custom React/CSS or third-party components remain valid when the kit lacks the required behavior or the developer explicitly requests them.
 
+`noodle init my-app` defaults to a comprehensive server—tools, resource, prompt, state contract, branding, handoff, widget, and embedded assistant—so begin by adapting that complete surface. Use `--template hello` only when the product explicitly needs the minimal server.
+
+The default composition rule is: build the smallest useful conversational surface. Inline has one purpose, one primary action, and at most two visible actions. Use progressive disclosure or a later conversational turn for secondary detail; request fullscreen only when the user asks or the task genuinely needs it. Never use nested scrolling. At 280px and wider, the widget must remain one-column, readable, touch-safe, and free of horizontal overflow. Remove secondary chrome before shrinking essential content.
+
+Every production widget handles loading, empty, partial, stale, error, retry, and success states. Prefill fields from known tool results and choose safe, reversible defaults; preserve the user’s work across rerenders, and never preselect a consequential action. Use public React primitives and branding tokens. Never author against `ns-*`, `nsr-*`, or example-local `--nw-*` classes/tokens; those are implementation details, not alternate design systems.
+
 ## React hook surface
 
 Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
@@ -47,7 +53,7 @@ Author React. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react
 
 ```tsx
 import type { ServerDefinition } from '@noodleseed/one';
-import { generateHelpers } from '@noodleseed/one/react';
+import { Action, ActionBar, AsyncBoundary, Feedback, Field, Flow, Frame, Region, Select, generateHelpers } from '@noodleseed/one/react';
 
 // One call wires the typed host bridge; destructure only the hooks this view uses.
 const { useToolInfo, useCallTool, useViewState, useOpenExternal } =
@@ -71,28 +77,32 @@ export default function OrderStatus() {
 
   return (
     // data-llm mirrors the visible state back to the model as text context.
-    <main data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
-      <h1>Pickup order</h1>
-      <label>
-        Item
-        <select value={item} onChange={(event) => setItem(event.currentTarget.value)}>
-          <option value="falafel_wrap">Falafel Wrap</option>
-          <option value="lentil_soup">Lentil Soup</option>
-          <option value="mint_lemonade">Mint Lemonade</option>
-        </select>
-      </label>
-      <button
-        type="button"
-        disabled={placeOrder.isPending}
+    <Frame title="Pickup order" displayMode="auto" data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
+      <Flow variant="stack">
+      <AsyncBoundary state={placeOrder} loading="Placing order…" error={(error) => error.message}>
+      <Region title="Order" description="Choose one item for pickup.">
+      <Field label="Item">
+        <Select value={item} onChange={(event) => setItem(event.currentTarget.value)} options={[
+          { value: 'falafel_wrap', label: 'Falafel Wrap' },
+          { value: 'lentil_soup', label: 'Lentil Soup' },
+          { value: 'mint_lemonade', label: 'Mint Lemonade' },
+        ]} />
+      </Field>
+      </Region>
+      {confirmed?.status ? <Feedback status="success">{confirmed.status}</Feedback> : null}
+      <ActionBar>
+      <Action variant="primary" pending={placeOrder.isPending} pendingLabel="Placing…"
         onClick={() => placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item })}
       >
-        {placeOrder.isPending ? 'Placing…' : 'Place order'}
-      </button>
-      <p>{confirmed?.status ?? `Total: $${total}`}</p>
-      <button type="button" onClick={() => openExternal(checkoutUrl)}>
+        Place order
+      </Action>
+      <Action onClick={() => openExternal(checkoutUrl)}>
         Continue checkout
-      </button>
-    </main>
+      </Action>
+      </ActionBar>
+      </AsyncBoundary>
+      </Flow>
+    </Frame>
   );
 }
 ```
@@ -169,7 +179,7 @@ export default server(
 A "ChatGPT App" is not a separate authoring surface — it is exactly this MCP Apps widget rendered by the ChatGPT host. From the same declaration you author three things:
 
 - `domain` on the widget — one https origin per app (required for app-store submission, optional for dev-mode testing).
-- `csp: { connectDomains, resourceDomains }` — the exact network/resource origins the widget may reach; keep them minimal. Add `frameDomains` only if the widget embeds an iframe (it relaxes subframe rendering and draws stricter review).
+- `csp: { connectDomains, resourceDomains }` — the exact network/resource origins the widget may reach; keep them minimal. Add `frameDomains` only if the widget embeds an iframe (it relaxes subframe rendering and draws stricter review). These three lists are the complete CSP surface — there is no `base-uri` list.
 - server `handoff.allowedDomains` — the external-link targets `useOpenExternal()` opens.
 
 The compiler emits the rest automatically: the `openai/*` metadata (`openai/outputTemplate`, `openai/widgetCSP`, `openai/widgetDescription`) and ChatGPT’s `redirect_domains` (derived from `handoff.allowedDomains`). `window.openai` and Claude’s ext-apps bridge are auto-detected at startup, so the same widget renders in both Claude and ChatGPT with no host-specific code.