@noodleseed/agent-kit 0.20.0 → 0.21.1

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.1",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "a62843d66b5bde2d718f394b4d78ce25a7f5808884d8e29789480bc16f198406",
+      "sha256": "4a48b0a357c2dfab02ff191d68a9ebb47ad8396a63f476a0f60ba69cc7b943ad",
       "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": "687666010deb32bb605ccc23aeac8778fd1d02c53d7d8e232b6d0b8aeef77668",
       "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": "5b7dd35428128cfe0f506054e80b060d8a87ef157b03d2ce94d304b14df6e521",
       "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": "23754f0386b77f112249ca8b948b479792895303f0257ab0961cbbb81a857693",
       "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": "687666010deb32bb605ccc23aeac8778fd1d02c53d7d8e232b6d0b8aeef77668",
       "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": "5b7dd35428128cfe0f506054e80b060d8a87ef157b03d2ce94d304b14df6e521",
       "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.1",
   "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.1
+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

@@ -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/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,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 |