@noodleseed/agent-kit 0.20.0 → 0.21.0

package/README.md

@@ -15,7 +15,7 @@ into a project's `.agents/` and `.claude/` skill directories via `noodle agents
 - `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
-  write. See [ADR 0102](https://github.com/NoodleSeed-com/noodle-borg/blob/main/docs/decisions/0102-self-checking-skills-via-npm.md).
+  write. The manifest and every generated skill file are available in the public source tree for inspection.
 
 ## How the CLI uses it
 
@@ -35,5 +35,5 @@ reference files.
 ## License
 
 Apache-2.0. This package is generated and published from the
-[`noodle-borg`](https://github.com/NoodleSeed-com/noodle-borg) repository; the renderer is the private
+[`noodle-core`](https://github.com/NoodleSeed-com/noodle-core) repository; the renderer is the
 `@noodle-borg/agent-kit` workspace package.

package/manifest.json

@@ -1,14 +1,14 @@
 {
-  "packageVersion": "0.20.0",
+  "packageVersion": "0.21.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "a62843d66b5bde2d718f394b4d78ce25a7f5808884d8e29789480bc16f198406",
+      "sha256": "09469929851e57fae24fc411a173d0e356aabacb3743beed81232d03e2cc44dd",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/sdk-surface.md",
-      "sha256": "f19560c3232558eb692dc4ff0cee74850ebca9029f95272233e734aa3854faba",
+      "sha256": "0916b1f4df01053c424b46eeb4e8ee0910709d66b956c4d19da77d5abc4b046b",
       "agentTarget": "codex"
     },
     {
@@ -23,12 +23,17 @@
     },
     {
       "path": "skills/codex/references/compile-errors.md",
-      "sha256": "de43b81d6b9c1a065aa1905fdb469e518e50e80bf34306964593e608649f6868",
+      "sha256": "1039e245421e8c128cf1a81cf7a3ce809b0149478917040abebc124ffcb60423",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "fd2a67d3ba67f640edddca6d30ed8d38f278f0f3e9ab1c1669ace2aef8797c01",
+      "sha256": "b4ca23d7545c8e96dbfee6a4cf2235d4eadfb27302e453fe631031041a17a8c6",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/embedded-assistant.md",
+      "sha256": "db1eec6f6eed10b6525efc721b22756ff769b0234358821c15deb45cd61b39fb",
       "agentTarget": "codex"
     },
     {
@@ -43,7 +48,7 @@
     },
     {
       "path": "skills/codex/references/widgets-and-apps.md",
-      "sha256": "86bfc4d43a2d1226dcbce8c41fe0b1f36562a0cc7ac7964f4ee579bd91398d34",
+      "sha256": "69ff229945465793e6c9ae10e5185fc3b5e59b9fb508f03a81ab8d2a12b39efc",
       "agentTarget": "codex"
     },
     {
@@ -58,7 +63,7 @@
     },
     {
       "path": "skills/codex/references/deploy-and-ops.md",
-      "sha256": "0175101939ca5ea6823a18ce83a32311f5d9937ef8469a431dd0576ad0997fe4",
+      "sha256": "1b359a78e76ad6a71003a3d235685019cd2e1e2bbabd95ec520761d9915a2259",
       "agentTarget": "codex"
     },
     {
@@ -78,7 +83,7 @@
     },
     {
       "path": "skills/codex/examples/acme-bistro/README.md",
-      "sha256": "d94f67f7518208cba14920c26ed8aaa1546b496d96e55645e85b5d75a1a64127",
+      "sha256": "2bcf803ea2407479ddc70644a79ad503335880fd8439ed673b17c8d50e7cb59f",
       "agentTarget": "codex"
     },
     {
@@ -193,7 +198,7 @@
     },
     {
       "path": "skills/codex/examples/acme-tasks/README.md",
-      "sha256": "1d65cde8d1b47ade9e895ef99a92a0aec9d9ffe0c578f0d2dc4bafa0bcccca26",
+      "sha256": "e1d654d1a98b721ef7ce4f5d5d3d868611079ed4dbf2126b766018adb95d4194",
       "agentTarget": "codex"
     },
     {
@@ -248,7 +253,7 @@
     },
     {
       "path": "skills/codex/examples/food-ordering/README.md",
-      "sha256": "5524001b5f632f3b5329fbf4e408512d4b45ea29a27893516f8b0eb902bd8618",
+      "sha256": "4d42dfbaf46ee8003ae84b3ef79c9d2a8b716943b85e2e9329fa875007019524",
       "agentTarget": "codex"
     },
     {
@@ -268,7 +273,7 @@
     },
     {
       "path": "skills/codex/examples/food-ordering/src/server.ts",
-      "sha256": "1b1329c99af4798072b69979f1f0861c3b3587b237df46d3cf7b923060f134cb",
+      "sha256": "6e8c4c17e6f3a7867232880e1a8d0e45428ebfd3938282d6bec7d8542ae7d712",
       "agentTarget": "codex"
     },
     {
@@ -298,7 +303,7 @@
     },
     {
       "path": "skills/codex/examples/hello/README.md",
-      "sha256": "f66f3355bc8083fdd86f67b10a3c2d7977ce08369a2ecd62d3a68338f9ae5488",
+      "sha256": "c39b89f95c4ae1a2b78a71f42c00910507c32eaba628be36e5ec3ef32508aaa5",
       "agentTarget": "codex"
     },
     {
@@ -313,12 +318,12 @@
     },
     {
       "path": "skills/codex/examples/hello/src/server.ts",
-      "sha256": "a387dd0a860852753c5aa009604c7b85352baa3d220d2f32e0ecec62b72b5597",
+      "sha256": "f5ac538d951adc4f18b2c14205f4f710e7920da2ea911444d52adeab8f801521",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/examples/hello/test/server.test.ts",
-      "sha256": "e6c5779402eb2974a59c48823d579b745f0406f6a4f51a67b4ba4b19ab6e9cd6",
+      "sha256": "4de4932d95a920f4e5fd78fc58f3583285aab3c3a97a3c1417f8a863ee05aa98",
       "agentTarget": "codex"
     },
     {
@@ -348,12 +353,12 @@
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "1fbf6a1f0649627017b0f296e9458764e345da62a2e326bb8c3238ac3d4a51ae",
+      "sha256": "e31b696b0bcf72de525e0c28ceba8c4d44bd2ce5c6522476a0c33ffc8cb6d677",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/sdk-surface.md",
-      "sha256": "f19560c3232558eb692dc4ff0cee74850ebca9029f95272233e734aa3854faba",
+      "sha256": "0916b1f4df01053c424b46eeb4e8ee0910709d66b956c4d19da77d5abc4b046b",
       "agentTarget": "claude-code"
     },
     {
@@ -368,12 +373,17 @@
     },
     {
       "path": "skills/claude-code/references/compile-errors.md",
-      "sha256": "de43b81d6b9c1a065aa1905fdb469e518e50e80bf34306964593e608649f6868",
+      "sha256": "1039e245421e8c128cf1a81cf7a3ce809b0149478917040abebc124ffcb60423",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "fd2a67d3ba67f640edddca6d30ed8d38f278f0f3e9ab1c1669ace2aef8797c01",
+      "sha256": "b4ca23d7545c8e96dbfee6a4cf2235d4eadfb27302e453fe631031041a17a8c6",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/embedded-assistant.md",
+      "sha256": "db1eec6f6eed10b6525efc721b22756ff769b0234358821c15deb45cd61b39fb",
       "agentTarget": "claude-code"
     },
     {
@@ -388,7 +398,7 @@
     },
     {
       "path": "skills/claude-code/references/widgets-and-apps.md",
-      "sha256": "86bfc4d43a2d1226dcbce8c41fe0b1f36562a0cc7ac7964f4ee579bd91398d34",
+      "sha256": "69ff229945465793e6c9ae10e5185fc3b5e59b9fb508f03a81ab8d2a12b39efc",
       "agentTarget": "claude-code"
     },
     {
@@ -403,7 +413,7 @@
     },
     {
       "path": "skills/claude-code/references/deploy-and-ops.md",
-      "sha256": "0175101939ca5ea6823a18ce83a32311f5d9937ef8469a431dd0576ad0997fe4",
+      "sha256": "1b359a78e76ad6a71003a3d235685019cd2e1e2bbabd95ec520761d9915a2259",
       "agentTarget": "claude-code"
     },
     {
@@ -423,7 +433,7 @@
     },
     {
       "path": "skills/claude-code/examples/acme-bistro/README.md",
-      "sha256": "d94f67f7518208cba14920c26ed8aaa1546b496d96e55645e85b5d75a1a64127",
+      "sha256": "2bcf803ea2407479ddc70644a79ad503335880fd8439ed673b17c8d50e7cb59f",
       "agentTarget": "claude-code"
     },
     {
@@ -538,7 +548,7 @@
     },
     {
       "path": "skills/claude-code/examples/acme-tasks/README.md",
-      "sha256": "1d65cde8d1b47ade9e895ef99a92a0aec9d9ffe0c578f0d2dc4bafa0bcccca26",
+      "sha256": "e1d654d1a98b721ef7ce4f5d5d3d868611079ed4dbf2126b766018adb95d4194",
       "agentTarget": "claude-code"
     },
     {
@@ -593,7 +603,7 @@
     },
     {
       "path": "skills/claude-code/examples/food-ordering/README.md",
-      "sha256": "5524001b5f632f3b5329fbf4e408512d4b45ea29a27893516f8b0eb902bd8618",
+      "sha256": "4d42dfbaf46ee8003ae84b3ef79c9d2a8b716943b85e2e9329fa875007019524",
       "agentTarget": "claude-code"
     },
     {
@@ -613,7 +623,7 @@
     },
     {
       "path": "skills/claude-code/examples/food-ordering/src/server.ts",
-      "sha256": "1b1329c99af4798072b69979f1f0861c3b3587b237df46d3cf7b923060f134cb",
+      "sha256": "6e8c4c17e6f3a7867232880e1a8d0e45428ebfd3938282d6bec7d8542ae7d712",
       "agentTarget": "claude-code"
     },
     {
@@ -643,7 +653,7 @@
     },
     {
       "path": "skills/claude-code/examples/hello/README.md",
-      "sha256": "f66f3355bc8083fdd86f67b10a3c2d7977ce08369a2ecd62d3a68338f9ae5488",
+      "sha256": "c39b89f95c4ae1a2b78a71f42c00910507c32eaba628be36e5ec3ef32508aaa5",
       "agentTarget": "claude-code"
     },
     {
@@ -658,12 +668,12 @@
     },
     {
       "path": "skills/claude-code/examples/hello/src/server.ts",
-      "sha256": "a387dd0a860852753c5aa009604c7b85352baa3d220d2f32e0ecec62b72b5597",
+      "sha256": "f5ac538d951adc4f18b2c14205f4f710e7920da2ea911444d52adeab8f801521",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/examples/hello/test/server.test.ts",
-      "sha256": "e6c5779402eb2974a59c48823d579b745f0406f6a4f51a67b4ba4b19ab6e9cd6",
+      "sha256": "4de4932d95a920f4e5fd78fc58f3583285aab3c3a97a3c1417f8a863ee05aa98",
       "agentTarget": "claude-code"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.20.0",
+  "version": "0.21.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",
@@ -24,7 +24,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/NoodleSeed-com/noodle-borg",
+    "url": "https://github.com/NoodleSeed-com/noodle-core",
     "directory": "packages/agent-kit"
   },
   "author": "Noodle Seed",

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.20.0
-hash: b4952708b1c38f55
+version: 0.21.0
+hash: b4fc528d406e2149
 ---
 
 # 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/claude-code/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/claude-code/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/claude-code/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/claude-code/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/claude-code/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/claude-code/examples/hello/src/server.ts

@@ -16,7 +16,8 @@ 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(),

package/skills/claude-code/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/claude-code/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/claude-code/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/claude-code/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/claude-code/references/embedded-assistant.md

@@ -0,0 +1,160 @@
+# Embedded assistant
+
+## Contents
+
+- Architecture
+- Author and validate
+- Configure and deploy
+- Access modes and customer auth
+- Create the backend client
+- Integrate the customer backend
+- 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.
+
+## 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.
+- Read-only closed-world tools may auto-run; writes require confirmation.
+- 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`) |

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.0
+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

@@ -16,7 +16,8 @@ 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(),

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,160 @@
+# Embedded assistant
+
+## Contents
+
+- Architecture
+- Author and validate
+- Configure and deploy
+- Access modes and customer auth
+- Create the backend client
+- Integrate the customer backend
+- 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.
+
+## 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.
+- Read-only closed-world tools may auto-run; writes require confirmation.
+- 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`) |

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.