@noodleseed/agent-kit 0.48.0 → 0.48.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/SKILL.md

@@ -3,7 +3,7 @@ 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."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:cd6ca0d915e6acb9 -->
+<!-- noodle-skill version:0.48.2 hash:cd6ca0d915e6acb9 -->
 
 # Noodle Seed
 

package/skills/claude-code/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.48.2 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

package/skills/claude-code/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.48.2 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/claude-code/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.48.2 hash:1e86b8704f407bd3 -->
 
 # connecting-apis-to-mcp
 

package/skills/claude-code/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.48.2 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/claude-code/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.48.2 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/claude-code/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.48.2 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/claude-code/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:5d8f40f904d6ab4b -->
+<!-- noodle-skill version:0.48.2 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 
@@ -22,6 +22,7 @@ Deliver the requested assistant embed with identity and credential separation pr
 ## Required inputs
 
 - Application origin and mounting point.
+- Desired built-in or custom browser experience.
 - Identity/session boundary.
 - Requested local or hosted evidence level.
 

package/skills/claude-code/examples/customer-auth/README.md

@@ -335,6 +335,19 @@ rerenders keep the iframe and only a different view or unmount tears down the br
 Never inject `part.data.html`, assign it to `srcdoc`, fetch a `ui://` URI, or reproduce the bridge directly. Pages with a
 Content-Security-Policy must include the Noodle service origin in both `connect-src` and `frame-src`.
 
+Before the production-equivalent host build, run the presence-only handoff check:
+
+```sh
+noodle assistant embed --check --json
+```
+
+Add application-owned delegated-exchange requirements with repeatable `--require-env NAME` flags. The JSON
+reports required and missing names, CSP status, and post-deploy probes without returning environment values
+or writing scaffold files. Map the names through the production secret manager, CI environment, and any
+secret allowlist; regenerate existing framework-owned environment binding types before the build. Default
+Devtools/model exercises to synthetic data, and obtain approval before sending real connector data to an
+external model.
+
 After deployment, verify the public delegated exchange without extracting a customer bearer token or invoking
 a business operation:
 

package/skills/claude-code/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.48.2 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/claude-code/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.48.2 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/claude-code/references/embedded-assistant.md

@@ -3,6 +3,7 @@
 ## Contents
 
 - Architecture
+- Choose the host experience
 - Author and validate
 - Customize the presentation
 - Configure and deploy
@@ -13,6 +14,7 @@
 - Verified session context (identity and claims)
 - The session response
 - Choose a browser renderer
+- Host readiness and promotion
 - Toolchain requirements
 - Verify the boundary
 - Troubleshooting: symptom to diagnosis
@@ -21,12 +23,19 @@
 
 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:
+Keep every credential and identity layer separate:
 
 | Owner | Values | Destination |
 | --- | --- | --- |
+| Noodle operator | Login, selected org/app/env | Plugin-managed CLI profile and explicit target; never the SaaS runtime |
 | 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 |
+| Connector/delegated exchange | Connector credentials and any customer-owned token-exchange client | Noodle managed configuration plus the matching customer backend secret manager |
+| SaaS backend | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET`, `PUBLIC_APP_ORIGIN` | Backend-only environment or secret manager; never browser code or public-prefixed variables |
+| Browser | Short-lived assistant session only | In memory; never a client secret, model key, connector credential, or raw application session |
+
+## Choose the host experience
+
+Before choosing code, ask the user which experience belongs in the existing product: the built-in floating, inline, or drawer assistant; a custom chat-first renderer; or a headless client feeding application-owned UI. Default to the built-in floating assistant only when the user has no preference. Preserve the host application until the user opens or submits into the assistant; do not copy one flagship layout into every product.
 
 ## Author and validate
 
@@ -464,6 +473,23 @@ assistant.subscribe((event) => {
 
 `clientContext` and typed `pageContext` are recomputed for each turn. `updateContext(...)` remains the legacy session-exchange context; `updatePageContext(...)` replaces the fresh per-turn application hint. `updateModelContext({ content, structuredContent })` publishes one cohesive renderer snapshot for later message turns without starting a turn; every call replaces the prior snapshot rather than merging fields. These are untrusted data, not conversation history or authorization input, and the boundaries reject credential-shaped or unbounded updates. A message may re-exchange once after a pre-execution `401`; the client never auto-retries interaction decisions. `tool_proposed.arguments` is a complete schema-aware review projection and, for connector-backed tools, names the sole exact connector version/operation/resolved arguments. Sensitive/write-only fields are redacted; truncating or omitting any non-sensitive action field fails closed. Accept is bound to the server-held action and claims at most one execution attempt—clients cannot replace it. Normal terminal outcomes scrub private arguments and continuations immediately; only an accepted action still executing retains them for the one-hour unknown-outcome recovery window, after which it records `interaction_outcome_unknown` and scrubs. Without downstream idempotency this is not an exactly-once business-effect guarantee. To reconcile a lost response, explicitly repeat the same id and decision: the service returns its durable stored outcome without re-execution.
 
+## Host readiness and promotion
+
+Run the non-mutating host preflight from the embedding application before its production build:
+
+```sh
+noodle assistant embed --check --json
+noodle assistant embed --check --json --require-env EXAMPLE_DELEG_CLIENT_SECRET
+```
+
+The check reports only required and missing environment names, never their values. It checks both `connect-src` and `frame-src` when a common static host CSP is determinable, fails on missing directives, and marks a dynamic expression unverified instead of guessing. Additional `--require-env` names are application-owned; use them for the customer side of delegated exchange or other backend-only integration requirements.
+
+Inspect the host repository for generated environment bindings after adding names. Run its existing generator, review the diff, commit generated types only when that repository requires them, then run the production-equivalent host build. Do not invent a framework command or add a second generator.
+
+Promotion checklist: provision each environment in the backend secret manager; map names through the CI environment and any secret allowlist or secrets file; run the presence-only preflight before asset upload; promote configuration before code; run the post-deploy probes from the JSON contract; rotate the assistant client and delegated credential independently, then rerun the same checks.
+
+Devtools privacy gate: default model and connector exercises to synthetic or mock data. Before Devtools Chat sends real connector data to an external model, disclose the data flow and obtain the user's approval. A local validation pass is not that approval.
+
 ## Toolchain requirements
 
 - Node.js 20+ for `@noodleseed/assistant/server`.
@@ -479,6 +505,8 @@ assistant.subscribe((event) => {
 - An expired turn re-exchanges once; interaction decisions never auto-retry. An explicit same-decision repeat returns the stored outcome without executing again.
 - Accept, decline, and cancel are single-use. Only accept executes; the server ignores replacement tool arguments.
 - Wrong-origin and malformed-origin requests fail closed.
+- Run the production-equivalent host build after regenerating environment bindings.
+- In a real browser, submit with the keyboard, inspect console and network failures, complete session exchange and one tool turn, and render one linked App before claiming the host works.
 
 ## Troubleshooting: symptom to diagnosis
 
@@ -492,6 +520,10 @@ assistant.subscribe((event) => {
 | 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 |
+| Host session 503 | A required backend environment name is absent or mapped into the wrong deployment environment | Run `noodle assistant embed --check --json`, repair the host CI mapping, then probe the session route again |
+| `HEAD` on a widget or session path looks broken | The route contract is `GET` for the hosted sandbox/widget document or `POST` for session exchange; `HEAD` is not the product flow | Exercise the documented method and inspect its response instead of inferring readiness from `HEAD` |
+| Local server reports `listen EPERM` | The coding sandbox blocked loopback binding before application behavior ran | Rerun the same local/browser test with approved loopback permissions; do not change product code |
+| Tool succeeds but the widget is empty | The linked App delivery layer failed: result shape, resource link, CSP frame, or bridge hydration | Inspect the typed result, `view_available`, resource URI, browser console, and hosted frame separately |
 | 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 tool runs without the expected confirmation | Its compiled annotations omit `confirm: true` or explicitly set `false` | Pass `{ confirm: true }` to the action helper; action hints alone never gate. `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 |

package/skills/claude-code/references/troubleshooting.md

@@ -22,7 +22,7 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | Tool succeeds but no widget appears | The tool has no view, or the host surface doesn’t support MCP Apps | Use `tool`, run `noodle check`, preview with `noodle devtools`; on non-Apps surfaces only the text/structured result renders |
 | Widget shows stale or missing data | The widget reads `structuredContent`, which must match the `output` schema | Make `fulfil` return exactly the `output` shape (arrays and nested objects are supported); inspect the live result with `noodle devtools` |
 | `useCallTool` fails from the widget | Tool name mismatch, or the helper tool is model-visible | List names with `noodle tools`; widget-only helpers must be declared with `tool` |
-| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
+| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Vite is missing from the app dependencies or its dependencies are not installed — widget bundling uses the app-local Vite | Run `npm install --save-dev vite`, then retry `noodle validate` / `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
 | A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (a `.body` segment, when the parsed body is bound directly to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |

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

@@ -270,4 +270,6 @@ Declare extra host capabilities with `permissions` (e.g. `permissions: { clipboa
 
 ## Readiness and boundaries
 
-Run `noodle check` for widget/Apps readiness and `noodle devtools` to preview metadata and rendering. Brand via the `server` `branding` tokens (the compiler derives the palette); do not inject raw global CSS.
+React views use the app-local Vite bundler. When adding a view to an existing project that does not declare Vite, run `npm install --save-dev vite` before validation.
+
+Run `noodle validate` first, `noodle check` for widget/Apps readiness, and `noodle devtools` to preview metadata and rendering. Brand via the `server` `branding` tokens (the compiler derives the palette); do not inject raw global CSS.

package/skills/claude-code/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.48.2 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/claude-code/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.48.2 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/codex/SKILL.md

@@ -3,7 +3,7 @@ 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."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:cd6ca0d915e6acb9 -->
+<!-- noodle-skill version:0.48.2 hash:cd6ca0d915e6acb9 -->
 
 # Noodle Seed
 

package/skills/codex/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.48.2 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

package/skills/codex/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.48.2 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/codex/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.48.2 hash:1e86b8704f407bd3 -->
 
 # connecting-apis-to-mcp
 

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.48.2 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.48.2 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/codex/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.48.2 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:5d8f40f904d6ab4b -->
+<!-- noodle-skill version:0.48.2 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 
@@ -22,6 +22,7 @@ Deliver the requested assistant embed with identity and credential separation pr
 ## Required inputs
 
 - Application origin and mounting point.
+- Desired built-in or custom browser experience.
 - Identity/session boundary.
 - Requested local or hosted evidence level.
 

package/skills/codex/examples/customer-auth/README.md

@@ -335,6 +335,19 @@ rerenders keep the iframe and only a different view or unmount tears down the br
 Never inject `part.data.html`, assign it to `srcdoc`, fetch a `ui://` URI, or reproduce the bridge directly. Pages with a
 Content-Security-Policy must include the Noodle service origin in both `connect-src` and `frame-src`.
 
+Before the production-equivalent host build, run the presence-only handoff check:
+
+```sh
+noodle assistant embed --check --json
+```
+
+Add application-owned delegated-exchange requirements with repeatable `--require-env NAME` flags. The JSON
+reports required and missing names, CSP status, and post-deploy probes without returning environment values
+or writing scaffold files. Map the names through the production secret manager, CI environment, and any
+secret allowlist; regenerate existing framework-owned environment binding types before the build. Default
+Devtools/model exercises to synthetic data, and obtain approval before sending real connector data to an
+external model.
+
 After deployment, verify the public delegated exchange without extracting a customer bearer token or invoking
 a business operation:
 

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.48.2 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.48.2 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

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

@@ -3,6 +3,7 @@
 ## Contents
 
 - Architecture
+- Choose the host experience
 - Author and validate
 - Customize the presentation
 - Configure and deploy
@@ -13,6 +14,7 @@
 - Verified session context (identity and claims)
 - The session response
 - Choose a browser renderer
+- Host readiness and promotion
 - Toolchain requirements
 - Verify the boundary
 - Troubleshooting: symptom to diagnosis
@@ -21,12 +23,19 @@
 
 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:
+Keep every credential and identity layer separate:
 
 | Owner | Values | Destination |
 | --- | --- | --- |
+| Noodle operator | Login, selected org/app/env | Plugin-managed CLI profile and explicit target; never the SaaS runtime |
 | 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 |
+| Connector/delegated exchange | Connector credentials and any customer-owned token-exchange client | Noodle managed configuration plus the matching customer backend secret manager |
+| SaaS backend | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET`, `PUBLIC_APP_ORIGIN` | Backend-only environment or secret manager; never browser code or public-prefixed variables |
+| Browser | Short-lived assistant session only | In memory; never a client secret, model key, connector credential, or raw application session |
+
+## Choose the host experience
+
+Before choosing code, ask the user which experience belongs in the existing product: the built-in floating, inline, or drawer assistant; a custom chat-first renderer; or a headless client feeding application-owned UI. Default to the built-in floating assistant only when the user has no preference. Preserve the host application until the user opens or submits into the assistant; do not copy one flagship layout into every product.
 
 ## Author and validate
 
@@ -464,6 +473,23 @@ assistant.subscribe((event) => {
 
 `clientContext` and typed `pageContext` are recomputed for each turn. `updateContext(...)` remains the legacy session-exchange context; `updatePageContext(...)` replaces the fresh per-turn application hint. `updateModelContext({ content, structuredContent })` publishes one cohesive renderer snapshot for later message turns without starting a turn; every call replaces the prior snapshot rather than merging fields. These are untrusted data, not conversation history or authorization input, and the boundaries reject credential-shaped or unbounded updates. A message may re-exchange once after a pre-execution `401`; the client never auto-retries interaction decisions. `tool_proposed.arguments` is a complete schema-aware review projection and, for connector-backed tools, names the sole exact connector version/operation/resolved arguments. Sensitive/write-only fields are redacted; truncating or omitting any non-sensitive action field fails closed. Accept is bound to the server-held action and claims at most one execution attempt—clients cannot replace it. Normal terminal outcomes scrub private arguments and continuations immediately; only an accepted action still executing retains them for the one-hour unknown-outcome recovery window, after which it records `interaction_outcome_unknown` and scrubs. Without downstream idempotency this is not an exactly-once business-effect guarantee. To reconcile a lost response, explicitly repeat the same id and decision: the service returns its durable stored outcome without re-execution.
 
+## Host readiness and promotion
+
+Run the non-mutating host preflight from the embedding application before its production build:
+
+```sh
+noodle assistant embed --check --json
+noodle assistant embed --check --json --require-env EXAMPLE_DELEG_CLIENT_SECRET
+```
+
+The check reports only required and missing environment names, never their values. It checks both `connect-src` and `frame-src` when a common static host CSP is determinable, fails on missing directives, and marks a dynamic expression unverified instead of guessing. Additional `--require-env` names are application-owned; use them for the customer side of delegated exchange or other backend-only integration requirements.
+
+Inspect the host repository for generated environment bindings after adding names. Run its existing generator, review the diff, commit generated types only when that repository requires them, then run the production-equivalent host build. Do not invent a framework command or add a second generator.
+
+Promotion checklist: provision each environment in the backend secret manager; map names through the CI environment and any secret allowlist or secrets file; run the presence-only preflight before asset upload; promote configuration before code; run the post-deploy probes from the JSON contract; rotate the assistant client and delegated credential independently, then rerun the same checks.
+
+Devtools privacy gate: default model and connector exercises to synthetic or mock data. Before Devtools Chat sends real connector data to an external model, disclose the data flow and obtain the user's approval. A local validation pass is not that approval.
+
 ## Toolchain requirements
 
 - Node.js 20+ for `@noodleseed/assistant/server`.
@@ -479,6 +505,8 @@ assistant.subscribe((event) => {
 - An expired turn re-exchanges once; interaction decisions never auto-retry. An explicit same-decision repeat returns the stored outcome without executing again.
 - Accept, decline, and cancel are single-use. Only accept executes; the server ignores replacement tool arguments.
 - Wrong-origin and malformed-origin requests fail closed.
+- Run the production-equivalent host build after regenerating environment bindings.
+- In a real browser, submit with the keyboard, inspect console and network failures, complete session exchange and one tool turn, and render one linked App before claiming the host works.
 
 ## Troubleshooting: symptom to diagnosis
 
@@ -492,6 +520,10 @@ assistant.subscribe((event) => {
 | 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 |
+| Host session 503 | A required backend environment name is absent or mapped into the wrong deployment environment | Run `noodle assistant embed --check --json`, repair the host CI mapping, then probe the session route again |
+| `HEAD` on a widget or session path looks broken | The route contract is `GET` for the hosted sandbox/widget document or `POST` for session exchange; `HEAD` is not the product flow | Exercise the documented method and inspect its response instead of inferring readiness from `HEAD` |
+| Local server reports `listen EPERM` | The coding sandbox blocked loopback binding before application behavior ran | Rerun the same local/browser test with approved loopback permissions; do not change product code |
+| Tool succeeds but the widget is empty | The linked App delivery layer failed: result shape, resource link, CSP frame, or bridge hydration | Inspect the typed result, `view_available`, resource URI, browser console, and hosted frame separately |
 | 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 tool runs without the expected confirmation | Its compiled annotations omit `confirm: true` or explicitly set `false` | Pass `{ confirm: true }` to the action helper; action hints alone never gate. `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 |

package/skills/codex/references/troubleshooting.md

@@ -22,7 +22,7 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | Tool succeeds but no widget appears | The tool has no view, or the host surface doesn’t support MCP Apps | Use `tool`, run `noodle check`, preview with `noodle devtools`; on non-Apps surfaces only the text/structured result renders |
 | Widget shows stale or missing data | The widget reads `structuredContent`, which must match the `output` schema | Make `fulfil` return exactly the `output` shape (arrays and nested objects are supported); inspect the live result with `noodle devtools` |
 | `useCallTool` fails from the widget | Tool name mismatch, or the helper tool is model-visible | List names with `noodle tools`; widget-only helpers must be declared with `tool` |
-| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Project dependencies are not installed — widget bundling uses the app-local Vite | Run the project’s package install, then retry `noodle dev` / `noodle deploy` |
+| `noodle validate` passes but React views fail to bundle (“requires Vite”) | Vite is missing from the app dependencies or its dependencies are not installed — widget bundling uses the app-local Vite | Run `npm install --save-dev vite`, then retry `noodle validate` / `noodle dev` / `noodle deploy` |
 | Hosted endpoint returns 401 to probes | Expected: hosted servers challenge unauthenticated calls with OAuth metadata | Sign in from the host when prompted; widen who may call with `noodle access set` if testers are outside the org |
 | Tools error only after deploy | Runtime/config differences surface hosted (secrets, connector reachability) | Run `noodle smoke`, then `noodle metrics --agent-output` and `noodle events --tool <name> --status tool_error --json`; check `noodle secrets list` scope |
 | A connector tool validates and lists, but returns empty or `undefined` fields | The `response` mapping references a path the API does not return — usually the wrong root (a `.body` segment, when the parsed body is bound directly to `${response}`) or the wrong shape | Run `noodle tools call <name> --args <json>` with the secret set and compare the mapped result to the API’s real JSON; map from `${response.<path>}` (the body is `${response}`, there is no `.body`) and use bracket array indices (`${response.items[0].id}`) |

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

@@ -270,4 +270,6 @@ Declare extra host capabilities with `permissions` (e.g. `permissions: { clipboa
 
 ## Readiness and boundaries
 
-Run `noodle check` for widget/Apps readiness and `noodle devtools` to preview metadata and rendering. Brand via the `server` `branding` tokens (the compiler derives the palette); do not inject raw global CSS.
+React views use the app-local Vite bundler. When adding a view to an existing project that does not declare Vite, run `npm install --save-dev vite` before validation.
+
+Run `noodle validate` first, `noodle check` for widget/Apps readiness, and `noodle devtools` to preview metadata and rendering. Brand via the `server` `branding` tokens (the compiler derives the palette); do not inject raw global CSS.

package/skills/codex/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.48.2 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/codex/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.48.0 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.48.2 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery