@noodleseed/one 0.151.1 → 0.153.0

package/node_modules/@noodle-borg/agent-kit/dist/skill-embedded-assistant-ref.js

@@ -1,3 +1,5 @@
+import { renderEmbeddedAssistantOperationsReference } from './skill-embedded-assistant-operations-ref.js';
+import { renderEmbeddedAssistantRendererReference } from './skill-embedded-assistant-renderer-ref.js';
 /** Curated external-developer workflow for embedding a deployed Noodle assistant in a SaaS app. */
 export function renderEmbeddedAssistantReference() {
     return [
@@ -6,7 +8,7 @@ export function renderEmbeddedAssistantReference() {
         '## Contents',
         '',
         '- Architecture',
-        '- Choose the host experience',
+        '- Select the architecture before code',
         '- Author and validate',
         '- Product workflow guidance',
         '- Customize the presentation',
@@ -19,6 +21,7 @@ export function renderEmbeddedAssistantReference() {
         '- The session response',
         '- Choose a browser renderer',
         '- Host readiness and promotion',
+        '- Launch and qualified-usage proof',
         '- Toolchain requirements',
         '- Verify the boundary',
         '- Troubleshooting: symptom to diagnosis',
@@ -38,9 +41,32 @@ export function renderEmbeddedAssistantReference() {
         '| 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',
+        '## Select the architecture before code',
         '',
-        '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.',
+        'Do not edit either codebase until one architecture brief is decision-complete. Name the external end user, the conversational job, one to three workflows, the exact access mode, renderer, existing host framework, identity/session boundary, server-owned routing authority, model owner, exact origin and mount point, and requested evidence level.',
+        '',
+        'If the external user, job, or workflow set is still vague, hand off to `designing-mcp-products` before code. Preserve its bounded product outcome and resume this workflow only when the value path and one representative success path are explicit.',
+        '',
+        'Treat the MCP application and embedding application as two code ownership roots, usually two repositories and sometimes two explicitly separate directories in one repository:',
+        '',
+        '| Code owner | Owns | Must not own |',
+        '| --- | --- | --- |',
+        '| MCP application | `server.ts`, tools, App views, access surfaces, portable branding defaults, model declaration, validation, and deployment | Host cookies, login UI, application middleware, or browser mounting |',
+        '| Embedding application | Existing framework and package manager, user authentication, same-origin session route when required, browser mount, CSP, cookies/CSRF, and production build | MCP tool semantics, model keys, assistant client secrets in browser code, or caller-selected tenant routing |',
+        '',
+        'Develop locally as two local processes: `noodle dev` serves the MCP application, while the embedding application runs its existing development command at the exact authored loopback origin. Do not replace either process with a second scaffold, package manager, chat transport, or copied flagship shell.',
+        '',
+        'Select exactly one recommended topology; do not return an unranked menu:',
+        '',
+        '| User boundary | Recommended topology | Identity and routing consequence |',
+        '| --- | --- | --- |',
+        '| Anonymous public visitor | `publicWebsite(...)` plus the hosted embed ID and managed renderer | No backend session route, `${user}`, roles/scopes, delegated credentials, or customer routing. Require the explicit capability allowlist and confirmation for side effects. |',
+        '| Signed-in application user | `authenticatedWebsite(...)` plus a same-origin backend session route and the managed renderer | The host backend authenticates the user, calls `createAssistantSession`, and supplies only verified identity, claims, preferences, and server-owned routing. |',
+        '| Visitor who may sign in mid-conversation | `publicWebsite({ signIn: true })` plus the hosted embed ID, host application login, and ticket elevation | Anonymous capabilities remain bounded; the host backend spends the ticket after login and continues through a same-origin session endpoint on an allowed origin. |',
+        '',
+        'Use the existing host framework and its package manager. Recommend the managed renderer unless the product names a concrete UI or integration benefit that requires the headless client; a custom renderer accepts the complete transcript-part obligation described below. Recommend `noodleManaged()` when Noodle owns the managed-cloud model for the exact eligible target; recommend `openAICompatible(...)` only when the operator or self-hosted deployment owns that model endpoint and credentials. Never present both as unfinished choices.',
+        '',
+        'The architecture brief must state the selected topology, why it fits the named user and job, the two code owners and two local processes, credential and identity flow, routing authority, model owner, files expected to change, and the first requested evidence boundary. If identity/session ownership, exact origin, tenant-routing authority, model ownership, or evidence target is unavailable, return a blocked architecture brief naming the missing owner or decision and do not edit either codebase.',
         '',
         '## Author and validate',
         '',
@@ -120,11 +146,17 @@ export function renderEmbeddedAssistantReference() {
         '',
         'The sign-in card renders on the same themed chrome as every proposal card and follows the server `branding`. Authoring `signUpAction` adds a second button; leaving it out renders none. Both buttons raise the same `assistant-sign-in-requested` event with the same single-use ticket — the detail adds `intent: "sign-in" | "sign-up"` so the page routes `sign-up` to its registration page instead of its login. The ticket spend after account creation is identical to the one after sign-in; the service does not care which path produced the session. Headless renderers receive the same moment as a `data-sign-in` transcript part from `subscribeChat` (it has no status and is not respondable through `client.respond` — resolution is the elevated session).',
         '',
-        'Elevation runs through the **host application own login**, never a Noodle-operated one. The widget raises `assistant-sign-in-requested` with a single-use `signInTicket` in its detail; the page signs the visitor in as it already does, then its backend spends the ticket with `createAssistantSession({ ..., signInTicket })` from `@noodleseed/assistant/server` — the same session exchange, its own client credentials. A refused spend throws a typed `AssistantSessionExchangeError`: branch on `elevationRefusal` (`elevation_ticket_expired` re-prompt; `elevation_tenant_mismatch` alert, never retry). Possession of the ticket alone elevates nothing, and the service checks the client tenant owns that conversation. The ticket is not the server-held interaction continuation — that value never reaches browser code; this one exists to travel through the page.',
+        '#### Complete mixed-mode handoff',
+        '',
+        '1. **Capture the ticket.** The widget raises `assistant-sign-in-requested` with a single-use `signInTicket`. POST it to the host application same-origin backend and bind it to the short-lived login transaction; keep it out of query strings, logs, analytics, and durable browser storage.',
+        '2. **Use the existing login.** Send the visitor through the host application full-page redirect for sign-in or sign-up. Noodle never becomes the customer identity provider.',
+        '3. **Elevate on the backend.** After authentication, recover the bound ticket and call `createAssistantSession({ ..., signInTicket })` with the verified user, server-owned routing, backend client credentials, and the exact **origin the conversation will continue on**. The allowed destination may differ from the anonymous marketing origin; successful elevation rebinds the session to it.',
+        '4. **Reattach on the destination origin.** Forward the helper response unchanged through the customer-owned same-origin session endpoint. The widget uses `credentials: "same-origin"`; pointing it at a cross-origin endpoint guarantees a cookie-less `401`. The elevated token replaces the anonymous token, which is dead.',
+        '5. **Resume and replay.** The widget repaints the bounded visible transcript from `endpoints.transcript`, emits one secure-continuation status, re-resolves the latest linked App view against the current surface, restores at most one live pending confirmation/input request, and then shows follow-up suggestions. Restoring an interaction suppresses auto-resume. Replay includes only rows the panel showed, never tool internals or a spent ticket, and never App HTML, a DOM snapshot, or exact scroll/focus. On an older service without that endpoint the panel starts visually fresh while the model still remembers, so promise only that "the assistant remembers". Pass `restoreConversation: false` when a privacy-sensitive application must suppress browser replay while retaining bounded server/model continuity.',
         '',
-        'The conversation is kept server-side: same session, new token, the anonymous one dead. By default the pending request also completes itself: the service re-attempts the intercepted tool under the new principal and streams it as the elevated session first turn (one-shot; mooted if the visitor types first; confirm-gated tools stop at their confirmation card; pass `resume: false` beside the ticket to disable). On a backend-exchanged reattach the widget also repaints the bounded visible transcript (`endpoints.transcript`) before the resume runs — only rows the panel actually showed replay, never tool internals or a spent ticket. On an older service without the endpoint the panel starts visually fresh while the model still remembers, so keep copy honest either way: "the assistant remembers". Do not build a second identity provider or client-side resume scaffolding for this.',
+        'Possession of the ticket alone elevates nothing, and the service checks that the backend client tenant owns the conversation. A refused spend throws a typed `AssistantSessionExchangeError`: branch on `elevationRefusal` (`elevation_ticket_expired` re-prompt; `elevation_tenant_mismatch` alert and never retry; `elevation_state_conflict` means the ticket is spent, so open or restart the signed-in flow and never merge generic state). A refused origin does not burn the ticket. The ticket is not the server-held interaction continuation — that value never reaches browser code.',
         '',
-        'When the login lives on a different origin (marketing site + app), the flow is: the visitor signs in via full-page redirect as the site already does; the backend spends the ticket presenting the **origin the conversation will continue on** (any origin in the deployment allowlist — elevation re-pins the session there, and CORS follows); the token reaches the widget through the customer own **same-origin** session endpoint on that origin. The redirect handoff is mandatory, not stylistic: the widget calls the session endpoint with `credentials: "same-origin"`, so pointing a marketing page at a cross-origin endpoint is a guaranteed cookie-less 401. Persist the ticket across the login redirect (single-use, expires in minutes); a refused origin does not burn it.',
+        'By default the pending request completes itself: the service re-attempts the intercepted tool under the new principal and streams it as the elevated session first turn. This is one-shot, is mooted if the visitor types first, and stops at the confirmation card for a confirm-gated tool. Pass `resume: false` beside the ticket only when the application deliberately owns that affordance. Do not build client-side resume scaffolding or a second identity provider.',
         '',
         'A connector-backed side effect needs **two** independent declarations to be reachable from a public or mixed surface: inclusion in `capabilities` **and** `{ confirm: true }` on the operation. Signing in proves who the visitor is; it does not pre-authorize an effect, so confirmation still applies on a mixed surface. Confirmation is never authentication or business authorization — the customer backend still owns payload validation, abuse controls, and idempotency. Local or session-only widget state needs no confirmation.',
         '',
@@ -219,6 +251,10 @@ export function renderEmbeddedAssistantReference() {
         '',
         'Create an authenticated same-origin backend route:',
         '',
+        'The route must return a JSON `401` for a signed-out caller rather than an HTML login redirect, require JSON, and compare the request against the exact configured Origin before exchange. The managed renderer sends same-origin cookies but does not invent an application CSRF token. Treat JSON plus exact Origin as the minimum cookie/CSRF boundary; when the host keeps token-based CSRF middleware, use the DOM-free client with an injected `fetch` that supplies the token instead of exempting the route. Resolve claims and connector routes from the authenticated user and server-owned membership only.',
+        '',
+        'For the complete framework-neutral server-to-server HTTP exchange in a non-Node host, link to the [Django and Vue guide](https://docs.noodleseed.dev/docs/guides/embedded-assistant-django-vue); keep its framework-specific middleware and mounting mechanics there rather than copying them into agent instructions.',
+        '',
         '```ts',
         'import { createAssistantSession } from "@noodleseed/assistant/server";',
         '',
@@ -396,7 +432,9 @@ export function renderEmbeddedAssistantReference() {
         '',
         '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`.',
         '',
-        'For a customer-owned React renderer, use the renderer-free hook. It owns client lifetime and React subscription while `client` remains the one command surface:',
+        '### Minimal fail-closed custom renderer skeleton',
+        '',
+        'Use the renderer-free hook only when the product has a concrete reason to own the conversation UI. This is a minimal fail-closed skeleton, not a production-complete renderer: it keeps one client and App host, renders safe transcript content, and refuses interactions whose complete business presentation the host has not implemented. Start from the managed renderer unless the application accepts the full obligation checklist below.',
         '',
         '```tsx',
         '"use client";',
@@ -405,9 +443,22 @@ export function renderEmbeddedAssistantReference() {
         'import { NoodleAppView } from "@noodleseed/assistant/react";',
         'import { useNoodleAssistant } from "@noodleseed/assistant/react/client";',
         '',
-        'export function CustomAssistant({ principalKey, resolvedTheme }: { principalKey: string; resolvedTheme: "light" | "dark" }) {',
+        'type SignInRequest = { readonly signInTicket: string; readonly expiresAt: string };',
+        '',
+        'export function CustomAssistant({',
+        '  principalKey,',
+        '  resolvedTheme,',
+        '  onSignInRequested,',
+        '}: {',
+        '  principalKey: string;',
+        '  resolvedTheme: "light" | "dark";',
+        '  onSignInRequested: (request: SignInRequest) => Promise<"started" | "cancelled">;',
+        '}) {',
         '  const [draft, setDraft] = useState("");',
-        '  const { client, messages, status, error } = useNoodleAssistant({',
+        '  const [sessionNotice, setSessionNotice] = useState("");',
+        '  const [turnNotice, setTurnNotice] = useState("");',
+        '  const [pendingSignInTicket, setPendingSignInTicket] = useState<string>();',
+        '  const { client, messages, suggestions, status, error } = useNoodleAssistant({',
         '    sessionEndpoint: "/api/assistant/session",',
         '    principalKey,',
         '    clientContext: () => ({',
@@ -421,6 +472,16 @@ export function renderEmbeddedAssistantReference() {
         '      // The hook exposes this same structured failure through `error`.',
         '    });',
         '  };',
+        '  useEffect(',
+        '    () =>',
+        '      client.subscribe((event) => {',
+        '        if (event.event === "session_expired") setSessionNotice("Session expired.");',
+        '        if (event.event === "session_started" || event.event === "session_reset") {',
+        '          setSessionNotice("");',
+        '        }',
+        '      }),',
+        '    [client],',
+        '  );',
         '',
         '  return (',
         '    <section aria-label="Assistant" aria-busy={busy}>',
@@ -434,20 +495,18 @@ export function renderEmbeddedAssistantReference() {
         '                <section key={review.id} aria-label="Review proposed action">',
         '                  <h3>{review.title ?? "Review proposed action"}</h3>',
         '                  {review.description ? <p>{review.description}</p> : null}',
-        '                  <pre aria-label="Proposed action arguments">',
-        '                    {JSON.stringify(review.arguments ?? {}, null, 2)}',
-        '                  </pre>',
+        '                  <p>This custom renderer has not implemented a complete schema-aware review.</p>',
         '                  <button',
         '                    disabled={busy || review.status !== "pending"}',
-        '                    onClick={() => settle(client.respond(review.id, { action: "accept" }))}',
+        '                    onClick={() => settle(client.respond(review.id, { action: "decline" }))}',
         '                  >',
-        '                    Confirm',
+        "                    Don't proceed",
         '                  </button>',
         '                  <button',
         '                    disabled={busy || review.status !== "pending"}',
-        '                    onClick={() => settle(client.respond(review.id, { action: "decline" }))}',
+        '                    onClick={() => settle(client.respond(review.id, { action: "cancel" }))}',
         '                  >',
-        "                    Don't proceed",
+        '                    Cancel',
         '                  </button>',
         '                </section>',
         '              );',
@@ -457,21 +516,28 @@ export function renderEmbeddedAssistantReference() {
         '              return (',
         '                <section key={request.id} aria-label="Assistant needs input">',
         '                  <p>{request.message}</p>',
-        '                  <p>This renderer has not implemented the requested form.</p>',
+        '                  {/* request.requestedSchema is the sole input-form contract. */}',
+        '                  <p>This custom renderer has not implemented the requested schema form.</p>',
         '                  <button',
         '                    disabled={busy || request.status !== "pending"}',
         '                    onClick={() => settle(client.respond(request.id, { action: "decline" }))}',
         '                  >',
-        '                    Cancel request',
+        "                    Don't proceed",
+        '                  </button>',
+        '                  <button',
+        '                    disabled={busy || request.status !== "pending"}',
+        '                    onClick={() => settle(client.respond(request.id, { action: "cancel" }))}',
+        '                  >',
+        '                    Cancel',
         '                  </button>',
         '                </section>',
         '              );',
         '            }',
         '            if (part.type === "data-tool-result") {',
         '              return (',
-        '                <pre key={part.data.id} aria-label={`${part.data.tool} result`}>',
-        '                  {JSON.stringify(part.data.result, null, 2)}',
-        '                </pre>',
+        '                <p key={part.data.id} role="status">',
+        '                  A result is available, but this renderer has no trusted presentation for it.',
+        '                </p>',
         '              );',
         '            }',
         '            if (part.type === "data-view") {',
@@ -484,17 +550,67 @@ export function renderEmbeddedAssistantReference() {
         '                />',
         '              );',
         '            }',
+        '            if (part.type === "data-sign-in") {',
+        '              const request = part.data;',
+        '              return (',
+        '                <section key={request.id} aria-label="Sign in required">',
+        '                  <p>Continue with your account to use this capability.</p>',
+        '                  <button',
+        '                    disabled={busy || pendingSignInTicket !== undefined}',
+        '                    onClick={() => {',
+        '                      setPendingSignInTicket(request.signInTicket);',
+        '                      void Promise.resolve()',
+        '                        .then(() =>',
+        '                          onSignInRequested({',
+        '                            signInTicket: request.signInTicket,',
+        '                            expiresAt: request.expiresAt,',
+        '                          }),',
+        '                        )',
+        '                        .then(',
+        '                        (result) => {',
+        '                          if (result === "cancelled") setPendingSignInTicket(undefined);',
+        '                        },',
+        '                        () => setPendingSignInTicket(undefined),',
+        '                      );',
+        '                    }}',
+        '                  >',
+        '                    Sign in',
+        '                  </button>',
+        '                </section>',
+        '              );',
+        '            }',
         '            return <p key={index}>Unsupported assistant content.</p>;',
         '          })}',
         '        </article>',
         '      ))}',
-        '      {error ? <p role="alert">{error.message}</p> : null}',
+        '      <p role="status" aria-live="polite">',
+        '        {sessionNotice || turnNotice || (busy ? "Assistant is working" : "")}',
+        '      </p>',
+        '      {suggestions?.prompts.length ? (',
+        '        <nav aria-label="Suggested messages">',
+        '          {suggestions.prompts.map((prompt) => (',
+        '            <button',
+        '              key={prompt}',
+        '              type="button"',
+        '              disabled={busy}',
+        '              onClick={() => {',
+        '                setTurnNotice("");',
+        '                settle(client.sendMessage(prompt));',
+        '              }}',
+        '            >',
+        '              {prompt}',
+        '            </button>',
+        '          ))}',
+        '        </nav>',
+        '      ) : null}',
+        '      {error ? <p role="alert">The assistant could not complete that request.</p> : null}',
         '      <form',
         '        onSubmit={(event) => {',
         '          event.preventDefault();',
         '          const message = draft.trim();',
         '          if (!message) return;',
         '          setDraft("");',
+        '          setTurnNotice("");',
         '          settle(client.sendMessage(message));',
         '        }}',
         '      >',
@@ -504,7 +620,15 @@ export function renderEmbeddedAssistantReference() {
         '          onChange={(event) => setDraft(event.currentTarget.value)}',
         '        />',
         '        {busy ? (',
-        '          <button type="button" onClick={() => client.abort()}>Stop</button>',
+        '          <button',
+        '            type="button"',
+        '            onClick={() => {',
+        '              client.abort();',
+        '              setTurnNotice("Response stopped. This does not undo a started action.");',
+        '            }}',
+        '          >',
+        '            Stop',
+        '          </button>',
         '        ) : (',
         '          <button type="submit">Send</button>',
         '        )}',
@@ -514,128 +638,25 @@ export function renderEmbeddedAssistantReference() {
         '}',
         '```',
         '',
-        '`principalKey` is a browser-local identity for the authenticated user/tenant and is never sent to Noodle. Change it whenever that principal changes; the hook then aborts and clears the previous session and transcript. The hook does not register `<noodle-assistant>` or render Noodle markup.',
+        '`principalKey` is a browser-local identity for the authenticated user/tenant and is never sent to Noodle. Change it whenever that principal changes; the hook then aborts and clears the previous session and transcript. The hook does not register `<noodle-assistant>` or render Noodle markup. `suggestions` is hook-owned state: each prompt starts an ordinary message through the same guarded `client.sendMessage` path and disappears when the client clears it.',
         '',
-        'If the product deliberately sends a first turn on mount, make the effect cleanup-aware. React Strict Mode discards the provisional effect, so a persistent "already sent" ref can suppress the stable remount:',
-        '',
-        '```tsx',
-        'useEffect(() => {',
-        '  let active = true;',
-        '  queueMicrotask(() => {',
-        '    if (active) settle(client.sendMessage(initialMessage));',
-        '  });',
-        '  return () => {',
-        '    active = false;',
-        '  };',
-        '}, [client, initialMessage]);',
-        '```',
+        'Do not send a first turn on mount by default. React effect cleanup can suppress one provisional Strict Mode effect, but it cannot make a remount, dependency change, or client replacement idempotent. Require an explicit user action unless the host owns a durable one-shot state and an application idempotency key that makes repeated sends safe.',
         '',
         '`settle` must await or catch the command promise; the same structured failure also appears in the hook `error` state.',
         '',
-        'The sample fails closed on input requests until you replace that branch with a form generated from `requestedSchema`. A custom renderer must show the complete confirmation review and both decisions, handle every part it supports, and surface an explicit unsupported state for the rest. For `data-view`, use the canonical `<noodle-app-view>` host (or its React `NoodleAppView` adapter) to render the linked App, or deliberately map `resourceUri`/tool plus the bounded redacted `result` to an application-trusted native component. JSON result data is not the linked App UI. Never inject `part.data.html`, assign it to `srcdoc`, fetch a `ui://` URI, or reproduce the bridge with a direct Ext Apps dependency. Do not wrap this client in another chat transport or invent user messages for interaction continuations.',
-        '',
-        '`<noodle-app-view>` owns one bridge for the semantic view identity: client + `view.id` + `view.resourceUri`; `NoodleAppView` delegates to it. The host retains the iframe across fresh payload/callback/theme rerenders, publishes later resolved-theme changes through MCP Apps host context, and sends standard App teardown when that semantic identity changes, the element disconnects, or the App requests teardown. App views remain inline by default; the host advertises only inline presentation and rejects widget fullscreen requests. Opt in with `allowFullscreen` on `NoodleAppView` or `allow-fullscreen` on `<noodle-app-view>` only when fullscreen is an intentional part of the customer-owned experience. When fullscreen is accepted, the shared host adds an accessible top-right exit control that returns the same mounted App to inline mode without losing its state. Pass the same resolved application theme used by the conversation shell. Do not key an ancestor by a view object or callback. If the embedding page sets Content-Security-Policy, include the Noodle service origin in both `connect-src` and `frame-src`.',
-        '',
-        'Outside React, use the same DOM-free client directly and import the isolated App-view entry only when rendering linked Apps. The client keeps the session token in memory, the transcript stays React-free, and the element owns only App presentation:',
-        '',
-        '```html',
-        '<noodle-app-view id="assistant-app-view"></noodle-app-view>',
-        '```',
-        '',
-        '```ts',
-        'import { createAssistantClient } from "@noodleseed/assistant/client";',
-        'import "@noodleseed/assistant/app-view";',
-        '',
-        'const assistant = createAssistantClient({',
-        '  sessionEndpoint: "/api/assistant/session",',
-        '  clientContext: () => ({',
-        '    locale: navigator.language,',
-        '    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,',
-        '  }),',
-        '});',
-        '',
-        'const appView = document.querySelector("#assistant-app-view");',
-        'if (!appView) throw new Error("Missing App view host");',
-        'appView.client = assistant;',
-        "appView.theme = document.documentElement.classList.contains('dark') ? 'dark' : 'light';",
-        '',
-        'assistant.updateModelContext({',
-        "  content: [{ type: 'text', text: 'The time-off form is mounted.' }],",
-        "  structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },",
-        '});',
-        '',
-        'let pending: { id: string; requestedSchema?: Readonly<Record<string, unknown>> } | undefined;',
-        'assistant.subscribeChat((state) => {',
-        '  renderUIMessageState(state);',
-        '  pending = undefined;',
-        '  for (const message of state.messages) {',
-        '    for (const part of message.parts) {',
-        "      if (part.type === 'data-confirmation' && part.data.status === 'pending') {",
-        '        pending = { id: part.data.id };',
-        '      }',
-        "      if (part.type === 'data-input-request' && part.data.status === 'pending') {",
-        '        pending = { id: part.data.id, requestedSchema: part.data.requestedSchema };',
-        '      }',
-        "      if (part.type === 'data-view') {",
-        '        appView.view = part.data;',
-        '      }',
-        '    }',
-        '  }',
-        '});',
+        'This sample deliberately does not render Confirm until the application supplies a complete schema-aware review of every non-sensitive business field. It also refuses accepted elicitation until a form covers the compiler-approved portable `requestedSchema` subset; decline and cancel remain available and distinct. Use the managed renderer instead of shipping either unsupported branch. A production custom renderer must handle text, suggestions, sign-in, confirmation, elicitation, tool results, linked views, streaming, cancellation, terminal interaction states, and unknown future parts without silently dropping content.',
         '',
-        'await assistant.sendMessage("Book next Thursday and Friday off");',
-        'if (pending) {',
-        '  const requestedSchema = pending.requestedSchema;',
-        '  const resolution = requestedSchema',
-        "    ? { action: 'accept' as const, content: await renderPortableForm(requestedSchema) }",
-        "    : { action: 'accept' as const };",
-        '  await assistant.respond(pending.id, resolution);',
-        '}',
-        "// The same pending id also accepts { action: 'decline' } or { action: 'cancel' }.",
-        '```',
+        "`data-sign-in` is not an interaction and has no status: never pass its id to `client.respond`. Give `signInTicket` to an application callback that binds it to the host's existing short-lived login transaction; the authenticated backend spends it after login. Resolve the callback as `started` only after the host owns one active login transaction. Resolve it as `cancelled`, or reject it, when no transaction was started so the renderer can restore the sign-in affordance. A mixed custom renderer uses separate public and authenticated client mounts: the public shell starts with `embedId`, `serviceUrl`, and its visitor `principalKey`; after login, the authenticated destination mounts a new client against the same-origin `sessionEndpoint` with the user/tenant `principalKey`. Never pass both source options or mutate the public client source in place. The elevated session response owns bounded transcript repaint and optional resume. Never put the ticket in a query string, log, analytics event, or durable browser storage.",
         '',
-        '`subscribeChat` immediately emits a detached `{ messages, status, error? }` snapshot and then emits as `UIMessage.parts` change. Text uses `text`; Noodle confirmations, input requests, tool results, and linked views use `data-confirmation`, `data-input-request`, `data-tool-result`, and `data-view`. Interaction data moves through pending/submitting/accepted/declined/cancelled. Use raw `subscribe(...)` only for transport/session lifecycle events that are not transcript content.',
+        'The `session_expired` notice is observational. The client owns its one pre-execution `401` re-exchange and message retry; never rebuild tokens or replay an interaction in renderer code. A retryable transport detail is diagnostic, not proof that resending an ordinary message or business action is safe, so the skeleton never offers a generic Retry button. Reconcile a lost interaction response only by repeating the same id and the same decision through an explicit application recovery affordance. Budget exhaustion and tenant-mismatch elevation never retry.',
         '',
-        'For a chat-first custom host, raw `tool_started` carries the direct invocation call `id` and technical `tool` name before execution. Map known tools through a finite application-owned label table and use a neutral fallback such as "Working"; never mechanically expose an internal identifier as customer copy. Reserve one stable region with `role="status"` and `aria-live="polite"` for thinking, the mapped activity label, and the linked-view skeleton. `view_available` makes the view ready; raw `error` or chat `error` replaces it with `role="alert"`. Mark decorative skeleton shapes `aria-hidden="true"` and disable shimmer/transitions under `@media (prefers-reduced-motion: reduce)`.',
+        'For `data-tool-result`, do not expose technical tool names or raw JSON as customer UI. Prefer the linked `data-view`; otherwise map a known bounded result to an application-trusted native component or keep the explicit unsupported-result state. For `data-view`, use the canonical `<noodle-app-view>` host (or its React `NoodleAppView` adapter). Never inject `part.data.html`, assign it to `srcdoc`, fetch a `ui://` URI, reproduce the bridge, wrap the client in another chat transport, or invent user messages for continuations.',
         '',
-        '```ts',
-        'const activityByTool: Readonly<Record<string, string>> = {',
-        '  list_open_items: "Loading open items",',
-        '};',
-        'const viewSlots = new Map([["ui://workspace/current", "current-workspace"]]);',
-        '',
-        'assistant.subscribe((event) => {',
-        '  if (event.event === "tool_started") {',
-        '    showActivity(event.data.id, activityByTool[event.data.tool] ?? "Working");',
-        '  }',
-        '  if (event.event === "view_available") {',
-        '    const key = viewSlots.get(event.data.resourceUri) ?? `${event.data.id}:${event.data.resourceUri}`;',
-        '    showReadyView(key, event.data);',
-        '  }',
-        '  if (event.event === "error") showActivityError(event.data.code);',
-        '});',
-        '```',
-        '',
-        '`data-view` means a completed tool has a linked MCP App view. Pass that typed part and the existing client to `<noodle-app-view>` in Vue, Angular, or plain DOM, or to its `NoodleAppView` React adapter. It retains one bridge for client + `view.id` + `view.resourceUri` and requests standard App teardown on semantic replacement, disconnect, or App request. That pair is transport identity: different call ids are distinct invocations and must not be deduplicated generically. If the product intentionally owns one current panel for a known resource, declare an application-owned slot map and replace only that slot. Deliberately map the bounded result to an application-trusted native component only when replacing the linked App UI.',
+        '`<noodle-app-view>` owns one bridge for the semantic view identity: client + `view.id` + `view.resourceUri`; `NoodleAppView` delegates to it. The host retains the iframe across fresh payload/callback/theme rerenders, publishes later resolved-theme changes through MCP Apps host context, and sends standard App teardown when that semantic identity changes, the element disconnects, or the App requests teardown. App views remain inline by default; the host advertises only inline presentation and rejects widget fullscreen requests. Opt in with `allowFullscreen` on `NoodleAppView` or `allow-fullscreen` on `<noodle-app-view>` only when fullscreen is an intentional part of the customer-owned experience. When fullscreen is accepted, the shared host adds an accessible top-right exit control that returns the same mounted App to inline mode without losing its state. Pass the same resolved application theme used by the conversation shell. Do not key an ancestor by a view object or callback. If the embedding page sets Content-Security-Policy, include the Noodle service origin in both `connect-src` and `frame-src`.',
         '',
+        ...renderEmbeddedAssistantRendererReference(),
         '`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. Pass `--surface public|mixed|authenticated` to match the deployment: `public` drops the backend client id/secret requirement (a public embed has neither), and `public`/`mixed` additionally require `script-src` — the one directive whose failure runs no widget code at all, so nothing can report it from inside the page. CSP directives verify against the service origin exactly, via the env placeholder, or through a covering wildcard (`https://*.example.com`); a dynamic expression is marked unverified instead of guessed. Additional `--require-env` names are application-owned; `--env-alias NAME=HOST_NAME` follows a host repo that names an env var differently.',
-        '',
-        '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 host preflight; run the canonical deploy so its configuration preflight completes before asset upload; 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.",
+        ...renderEmbeddedAssistantOperationsReference(),
         '',
         '## Toolchain requirements',
         '',

package/node_modules/@noodle-borg/agent-kit/dist/skill-embedded-assistant-renderer-ref.js

@@ -0,0 +1,109 @@
+/** Framework-neutral browser-client and linked-App renderer guidance. */
+export function renderEmbeddedAssistantRendererReference() {
+    return [
+        '### Framework-neutral DOM client',
+        '',
+        'Use the same DOM-free client directly without a component wrapper, and import the isolated App-view entry only when rendering linked Apps. The client keeps the session token in memory, and the element owns only App presentation:',
+        '',
+        '```html',
+        '<div id="assistant-app-views"></div>',
+        '```',
+        '',
+        '```ts',
+        'import { createAssistantClient } from "@noodleseed/assistant/client";',
+        'import "@noodleseed/assistant/app-view";',
+        'import {',
+        '  type AssistantViewAvailableDetail,',
+        '  type NoodleAppViewElement,',
+        '} from "@noodleseed/assistant/app-view";',
+        '',
+        'const assistant = createAssistantClient({',
+        '  sessionEndpoint: "/api/assistant/session",',
+        '  clientContext: () => ({',
+        '    locale: navigator.language,',
+        '    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,',
+        '  }),',
+        '});',
+        '',
+        'const appViews = document.querySelector("#assistant-app-views");',
+        'if (!appViews) throw new Error("Missing App views host");',
+        'const mountedViews = new Map<string, NoodleAppViewElement>();',
+        'const readResolvedTheme = (): "light" | "dark" =>',
+        '  document.documentElement.classList.contains("dark") ? "dark" : "light";',
+        'let resolvedTheme: "light" | "dark" = readResolvedTheme();',
+        'const syncResolvedTheme = () => {',
+        '  resolvedTheme = readResolvedTheme();',
+        '  for (const mountedView of mountedViews.values()) mountedView.theme = resolvedTheme;',
+        '};',
+        'new MutationObserver(syncResolvedTheme).observe(document.documentElement, {',
+        '  attributes: true,',
+        '  attributeFilter: ["class"],',
+        '});',
+        'const appViewFor = (view: AssistantViewAvailableDetail) => {',
+        '  const key = `${view.id}:${view.resourceUri}`;',
+        '  let appView = mountedViews.get(key);',
+        '  if (!appView) {',
+        '    appView = document.createElement("noodle-app-view") as NoodleAppViewElement;',
+        '    appView.client = assistant;',
+        '    mountedViews.set(key, appView);',
+        '    appViews.append(appView);',
+        '  }',
+        '  appView.theme = resolvedTheme;',
+        '  return appView;',
+        '};',
+        '',
+        'assistant.updateModelContext({',
+        "  content: [{ type: 'text', text: 'The time-off form is mounted.' }],",
+        "  structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },",
+        '});',
+        '',
+        'assistant.subscribeChat((state) => {',
+        '  renderUIMessageState(state, {',
+        '    respond: (id, response) => assistant.respond(id, response),',
+        '  });',
+        '  const activeViewKeys = new Set<string>();',
+        '  for (const message of state.messages) {',
+        '    for (const part of message.parts) {',
+        "      if (part.type === 'data-view') {",
+        '        const key = `${part.data.id}:${part.data.resourceUri}`;',
+        '        activeViewKeys.add(key);',
+        '        appViewFor(part.data).view = part.data;',
+        '      }',
+        '    }',
+        '  }',
+        '  for (const [key, mountedView] of mountedViews) {',
+        '    if (!activeViewKeys.has(key)) {',
+        '      mountedView.remove();',
+        '      mountedViews.delete(key);',
+        '    }',
+        '  }',
+        '});',
+        '```',
+        '',
+        '`subscribeChat` immediately emits a detached `{ messages, status, error? }` snapshot and then emits as `UIMessage.parts` change. Text uses `text`; Noodle confirmations, input requests, sign-in requests, tool results, and linked views use `data-confirmation`, `data-input-request`, `data-sign-in`, `data-tool-result`, and `data-view`. `renderUIMessageState` is application code: it must show a complete schema-aware review or requested form and require an explicit user gesture before calling the supplied `respond`. Never call `respond` while scanning a transcript snapshot. Interaction data moves through pending/submitting/accepted/declined/cancelled. Use raw `subscribe(...)` only for transport/session lifecycle events that are not transcript content.',
+        '',
+        'For a chat-first custom host, raw `tool_started` carries the direct invocation call `id` and technical `tool` name before execution. Map known tools through a finite application-owned label table and use a neutral fallback such as "Working"; never mechanically expose an internal identifier as customer copy. Reserve one stable region with `role="status"` and `aria-live="polite"` for thinking, the mapped activity label, and the linked-view skeleton. `view_available` makes the view ready; raw `error` or chat `error` replaces it with `role="alert"`. Mark decorative skeleton shapes `aria-hidden="true"` and disable shimmer/transitions under `@media (prefers-reduced-motion: reduce)`.',
+        '',
+        '```ts',
+        'const activityByTool: Readonly<Record<string, string>> = {',
+        '  list_open_items: "Loading open items",',
+        '};',
+        'const viewSlots = new Map([["ui://workspace/current", "current-workspace"]]);',
+        '',
+        'assistant.subscribe((event) => {',
+        '  if (event.event === "tool_started") {',
+        '    showActivity(event.data.id, activityByTool[event.data.tool] ?? "Working");',
+        '  }',
+        '  if (event.event === "view_available") {',
+        '    const key = viewSlots.get(event.data.resourceUri) ?? `${event.data.id}:${event.data.resourceUri}`;',
+        '    showReadyView(key, event.data);',
+        '  }',
+        '  if (event.event === "error") showActivityError(event.data.code);',
+        '});',
+        '```',
+        '',
+        '`data-view` means a completed tool has a linked MCP App view. Pass that typed part and the existing client to `<noodle-app-view>` in another component framework or plain DOM, or to its `NoodleAppView` React adapter. It retains one bridge for client + `view.id` + `view.resourceUri` and requests standard App teardown on semantic replacement, disconnect, or App request. That pair is transport identity: different call ids are distinct invocations and must not be deduplicated generically. If the product intentionally owns one current panel for a known resource, declare an application-owned slot map and replace only that slot. Deliberately map the bounded result to an application-trusted native component only when replacing the linked App UI.',
+        '',
+    ];
+}
+//# sourceMappingURL=skill-embedded-assistant-renderer-ref.js.map

package/node_modules/@noodle-borg/agent-kit/dist/skill-router.d.ts

@@ -3,7 +3,7 @@ import type { AgentTarget } from './index.js';
 export declare const SKILL_DESCRIPTION: string;
 export type SkillReferencePath = `references/${string}.md`;
 export declare const APP_DIRECTORY_COMPLIANCE_REFERENCE: SkillReferencePath;
-export type SkillRouteId = 'design-product' | 'create-product-guide' | 'wrap-existing-app' | 'build-server' | 'connect-api' | 'build-app' | 'verify-recover' | 'debug-recover' | 'inspect-hosted' | 'deploy-hosted' | 'embed-assistant' | 'publish' | 'feedback';
+type SkillRouteId = 'design-product' | 'create-product-guide' | 'wrap-existing-app' | 'build-server' | 'connect-api' | 'build-app' | 'verify-recover' | 'debug-recover' | 'inspect-hosted' | 'deploy-hosted' | 'embed-assistant' | 'publish' | 'feedback';
 export interface SkillRoute {
     readonly id: SkillRouteId;
     readonly intent: string;
@@ -11,7 +11,6 @@ export interface SkillRoute {
     readonly exitCondition: string;
 }
 export declare const SKILL_ROUTES: readonly SkillRoute[];
-/** Complete lookup catalog. Routes above, not this inventory, own discovery. */
-export declare const REFERENCE_INDEX_LINES: readonly string[];
 export declare function skillRouterBody(_target: AgentTarget): string;
+export {};
 //# sourceMappingURL=skill-router.d.ts.map

package/node_modules/@noodle-borg/agent-kit/dist/skill-router.js

@@ -86,7 +86,7 @@ export const SKILL_ROUTES = [
     },
 ];
 /** Complete lookup catalog. Routes above, not this inventory, own discovery. */
-export const REFERENCE_INDEX_LINES = [
+const REFERENCE_INDEX_LINES = [
     '- `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.',
     '- `references/product-agent-guides.md` — decide, interview, propose, prove, preview, and explicitly install one host-neutral product guide.',
     '- `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.',

package/node_modules/@noodle-borg/agent-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodle-borg/agent-kit",
-  "version": "0.91.0",
+  "version": "0.92.0",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {