@noodleseed/agent-kit 0.94.0 → 0.96.0

package/skills/codex/embedding-mcp-assistants/references/embedded-assistant.md

@@ -4,6 +4,7 @@
 
 - Architecture
 - Select the architecture before code
+- Install into the existing application
 - Author and validate
 - Product workflow guidance
 - Customize the presentation
@@ -63,6 +64,20 @@ Use the existing host framework and its package manager. Recommend the managed r
 
 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.
 
+## Install into the existing application
+
+Configure or reuse an existing capability before generating files. Public embedding uses the existing script or embed ID and needs no customer backend session/config route. Reuse application APIs and business functions; generate a thin handler only where the approved architecture identifies a missing stable boundary.
+
+For a supported host, first run `noodle assistant embed --framework nextjs --surface public --dry-run --json` in the customer application, substituting `authenticated` or `mixed` only for the selected surface. Read the returned recipe applicability, applicationSeams, generated contents/hashes, skipped conflicts and nextSteps. The output is an installation plan, not permission to change the repository.
+
+For the documented non-Node backend/static-frontend authenticated profile, discover the framework choice through `noodle commands --json` and follow the linked framework guide below. The installer supplies a session view, a fail-closed identity seam, real CSRF-enforced request tests, a browser wrapper and exact-destination CSRF transport tests. Keep the existing package managers, authentication middleware and same-origin proxy. Pass the existing CSRF token and user/tenant principalKey to the wrapper; the managed element supports injected fetch, so preserving CSRF does not require a custom renderer or Node production server. Unsupported combinations use the neutral contract, not a claimed qualified profile.
+
+Once local changes are authorized, rerun without `--dry-run`; never add `--force` to resolve a conflict automatically. Read the installed `NOODLE-INTEGRATION.md` and newly installed project skill before editing. Implement only the named session/business/mount seams and preserve the host framework, package manager, login and authorization. Mixed mode also requires an application-owned login transaction; the generated callback does not implement or verify that transaction.
+
+Use generated tests and independently maintained acceptance cases at the actual customer boundary. A static host check, a mock test or installed files cannot prove application authorization or production browser behavior. Missing identities, sandbox access, customer approval or a reachable service remain unverified. Record the exact application/Noodle revisions, package versions and environment for observed evidence; rerun affected checks after changes.
+
+Unsupported hosts use the framework-neutral integration contract below; do not claim they received a generated, qualified framework profile. Keep direct MCP and headless projections on the same TypeScript source, and preserve their separate identity requirements.
+
 ## Author and validate
 
 `noodle init` and `noodle init --template widget` deliberately produce credential-free MCP Apps. Add an assistant declaration only when the product explicitly includes a customer-hosted assistant; do not make ordinary external-host widgets depend on model-provider settings.
@@ -143,6 +158,16 @@ The sign-in card renders on the same themed chrome as every proposal card and fo
 
 #### Complete mixed-mode handoff
 
+For a small SaaS onboarding flow, first read the bundled [stateful-draft example](../examples/stateful-draft/README.md). Compose the existing capabilities; do not introduce an onboarding platform API, workflow engine, research pipeline, or second identity provider.
+
+Start from one useful result the visitor can see before signup. Ask only for missing information, one short question at a time. Show an editable preview, and offer an account only when it unlocks a meaningful next step. Keep the ordinary signup route available. Research and document parsing are optional enrichment, never required because the flow is conversational.
+
+Use a finite-TTL caller state handle only if the draft needs server persistence. Opt it into `claimOnAuthentication` when it should move to the verified account. An explicit typed read tool supplies the current revision; a typed patch tool sends that revision and the complete reviewed value. Widget state is a display cache, never proof of a save. A failed or missing result must not increment the revision, mark the draft saved, or silently retry a conflicting write.
+
+Keep the final business action in the customer API. Map the reviewed draft to its existing create/update operation after authentication, with confirmation and the backend’s existing authorization and idempotency. Ticket adoption transfers temporary state, not a CRM record or completed onboarding.
+
+Prove this journey before calling it ready: useful anonymous preview; actual saved state; cancelled/expired signup; verified signup with the same draft; a destination conflict without an automatic merge; and no business write merely because login succeeded. A synthetic login demonstrates the integration shape but is not evidence that the customer identity system is connected.
+
 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.
@@ -246,39 +271,20 @@ The doctor reads `NOODLE_ASSISTANT_CLIENT_ID` / `NOODLE_ASSISTANT_CLIENT_SECRET`
 
 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:
+Use the installed same-origin route and `createAssistantSessionHandler` from `@noodleseed/assistant/server`; do not regenerate guards, JSON parsing or token-exchange infrastructure. The only identity seam is `authenticateAssistantRequest` in `lib/noodle-assistant-auth.ts`.
 
-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.
+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. Preserve the host token-based CSRF middleware: inject a same-origin-only token fetch into the managed element before mounting, as the Django/Vue profile does; a custom renderer is not required. Invalid CSRF may correctly fail before authentication. 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";
-
-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,
-      scopes: user.scopes,
-    },
-    context,
-    // Saved, backend-verified user preferences outrank browser hints.
-    preferences: { locale: user.locale, timeZone: user.timeZone },
-  });
-  return Response.json(session);
-}
-```
+Return `AssistantSessionIdentity | null` from the adapter. Null means signed out; service failure must throw rather than masquerade as signed out. Derive `user`, claims, preferences and routes from the existing verified session/membership. The maintained handler owns exact-Origin/JSON checks, bounded flat context, no-store JSON failures, a 15-second deadline, no redirects and no exchange retries. For mixed-mode continuation, return a `signInTicket` only from the backend-bound login transaction; never take it directly from browser JSON.
+
+For saved presentation preferences, return `preferences: { locale: user.locale, timeZone: user.timeZone }` beside the verified `user`. Omit unknown values; browser hints are not verified account preferences.
 
 Authenticate before exchange. Pass backend-verified `user.roles` and OAuth-style `user.scopes` separately; they govern the same per-tool authorization rules as verified MCP bearer claims. 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.
 
+Run the generated `test/noodle-assistant.test.ts` with the application's Vitest runner (add the dev dependency using its existing package manager if absent). It tests the real generated route with synthetic identities. Separately exercise the real session function with signed-out, tenant-A, tenant-B and authorized fixtures before claiming integration proof. A green mock suite does not prove customer authorization.
+
 `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.
 
 ### Route customer endpoints from the backend
@@ -765,7 +771,7 @@ 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.
+The check reports required and missing environment names, never their values. Use the exact command in an installed NOODLE-INTEGRATION.md, including its aliases and additional names, with the host environment exported; the CLI does not load application dotenv files. Pass `--surface public|mixed|authenticated` to match the deployment: `public` needs no backend client credentials. Public script-tag mounts need the service in `script-src`; the generated bundled React mount needs only `connect-src` and `frame-src` for that service. Unknown public mounts retain the conservative script check. CSP verifies an exact service origin, an env placeholder or a covering wildcard; dynamic expressions stay unverified. `--require-env` adds application-owned names and `--env-alias NAME=HOST_NAME` follows existing host naming.
 
 Read `evidence.levels` in order and stop at `evidence.firstUnproven`:
 

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

@@ -116,7 +116,7 @@ assistant: embeddedAssistant({
     model: variable('ASSISTANT_MODEL'),
     apiKey: secret('ASSISTANT_MODEL_API_KEY'),
   }),
-  allowedOrigins: ['https://tasks.example.com'],
+  access: authenticatedWebsite({ origins: [variable('APP_ORIGIN')] }),
   layout: { mode: 'floating', position: 'bottom-right' },
   labels: { welcomeHeading: 'How can I help with Acme Tasks?' },
 }),
@@ -125,9 +125,19 @@ 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.
+Bind `APP_ORIGIN` to the exact website origin. Production uses HTTPS; local development may use an exact
+loopback HTTP origin. The customer application runs its own development server beside `noodle dev`.
+
+In the existing application, preview the adapter with
+`noodle assistant embed --framework nextjs --surface authenticated --dry-run --json`. Review the recipe,
+generated contents/hashes and conflicts before rerunning without `--dry-run`. Implement the named
+`authenticateAssistantRequest` seam with the application's existing login and server-owned membership.
+Follow the installed `NOODLE-INTEGRATION.md` for signed-out, wrong-origin, cross-tenant and browser checks.
+Installed files are not integration proof; missing sandbox identities or backend evidence remain unverified.
+The generated session route delegates guards, bounded parsing and exchange to
+`createAssistantSessionHandler` in `@noodleseed/assistant/server`. Implement the existing-session adapter;
+do not copy token-exchange infrastructure. Run the supplied `test/noodle-assistant.test.ts` with Vitest,
+then test the adapter against the host application's signed-out and cross-tenant membership fixtures.
 
 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

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

@@ -1,5 +1,8 @@
 # Customer Auth - OIDC identity and customer-routed APIs
 
+For a visitor who starts before signup, use the [Stateful Draft reference](../stateful-draft/README.md)
+alongside this authenticated backend integration.
+
 This curated example owns the customer/end-user authentication capability slot. It proves that a SaaS app
 can protect an MCP endpoint with direct OIDC, retain role/scope-based tool authorization, and route ordinary
 reads and confirmed actions to the API origin selected by the verified customer's identity provider.

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

@@ -2,8 +2,11 @@
 
 The smallest deployable Noodle app: a single `greet` tool authored in TypeScript with no
 connectors, secrets, flows, widgets, or handoff policy. It still uses the current server options form
-so new authors see where server-level branding belongs. Use it to smoke the author loop
-(`noodle validate` / `noodle dev`) or a first deploy.
+so new authors see where server-level branding belongs. Use it for a local read or first deploy.
+For a new project, `noodle init --template hello` also supplies isolated behavior tests: compilation,
+tool discovery, an expected greeting and invalid-input rejection. Init installs pinned local tooling and runs
+those checks; use `npm run agent:check` after edits. `--no-install` prepares files without verified readiness.
+If setup fails, repair its reported stage and repeat the safe resume command; do not overwrite your edits.
 
 Protocol negotiation deliberately does not appear in `src/server.ts` or `noodle.json`. MCP versions
 are platform-owned: the same deployed app automatically serves compatible legacy clients and modern
@@ -30,6 +33,7 @@ empty. One-shot commands write one envelope; streaming commands write NDJSON sna
 terminal-failure envelopes so agents can parse each line independently.
 
 ```sh
+noodle test examples/hello/src/server.ts --tool greet --args '{"name":"Ada"}' --json
 noodle dev examples/hello/src/server.ts --app hello
 noodle deploy examples/hello/src/server.ts --org acme --app hello
 ```

package/skills/codex/examples/stateful-draft/README.md

@@ -0,0 +1,115 @@
+# Stateful Draft
+
+**Owns:** The flagship for a useful brief before signup, authoritative caller state, and account continuation.
+**Read when:** You want to compose a small conversational onboarding flow from existing platform capabilities.
+**Do not put here:** Customer credentials, a new identity provider, or business-system records.
+**Update when:** The reference tools, state schema, or runnable journey changes.
+
+Start with the visitor's goal. Help them produce something useful before asking for an account. This
+synthetic example collects a project title, audience, and desired outcome; those fields are illustrative,
+not requirements for any particular SaaS product.
+
+## The journey
+
+1. The visitor describes a goal. The assistant asks only for missing information and proposes a brief.
+2. `open_draft` opens an editable review and reads authoritative state, including its current revision.
+3. `save_draft` saves the reviewed brief after confirmation. It sends the current revision and the complete
+   value to the state API. Failed or missing responses do not appear as successful saves.
+4. The visitor may choose `continue_draft`. This read requires identity, so an anonymous visitor sees the
+   sign-in/signup card. Your host application completes its existing login and spends the bound ticket.
+5. The authenticated assistant reads the same adopted draft. No project, subscription, or business record
+   is created by signing in.
+
+The widget's Continue button requests the identity-dependent tool through the conversation. The ordinary
+signup route should remain available on the embedding page.
+
+## Run the reference
+
+From this repository:
+
+```sh
+pnpm install
+pnpm build
+noodle validate examples/stateful-draft/src/server.ts
+noodle test examples/stateful-draft/src/server.ts
+noodle dev examples/stateful-draft/src/server.ts --org demo --app stateful-draft
+```
+
+The local runtime and widget preview exercise the typed tools. A complete mixed-assistant journey also
+requires two host pages and a backend that verifies the user. The declared development origins are
+`http://localhost:3001` for the public page and `http://localhost:3002` for the authenticated page; replace
+these with your exact deployment origins. The assistant uses `noodleManaged()`, whose hosted availability
+and budget belong to the operator. Local tool tests do not require a model key.
+
+Use the SDK version declared in this example's package file. Older published SDKs may omit the state
+adoption flag when compiling; the example's tests check that the flag reaches the compiled declaration.
+
+Use [signup continuity](https://docs.noodleseed.dev/docs/guides/signup-continuity) for the complete host
+integration and [customer-auth](../customer-auth/README.md) for customer-owned API authentication.
+
+### Loopback demonstration with a hosted assistant
+
+The included host serves the public page on port 3001 and a **simulated** account page on port 3002.
+It binds to loopback and must not be published as a production authentication implementation.
+After deploying this app, copy this directory outside the monorepo and run the commands below from that
+copy. This keeps published dependencies from shadowing the monorepo's workspace SDK.
+
+```sh
+pnpm install --ignore-workspace --lockfile=false
+export NOODLE_EMBED_ID=<embed-id-printed-by-deploy>
+pnpm site
+```
+
+This is enough to test the anonymous conversation and saved brief. To exercise the synthetic account
+handoff, create an assistant backend client for the same org/app/env with
+`noodle assistant clients create --name first-brief-demo --org <org> --app <app> --env <env> --json`.
+Set `NOODLE_ASSISTANT_CREDENTIALS_FILE` to the returned `secretFile` path and restart `pnpm site`.
+The host consumes that private file without printing it or sending its contents to the browser.
+Override `NOODLE_SERVICE_URL` only when deploying to a different hosted service.
+
+The simulated signup chooses a random temporary demo identity and spends the ticket through the real
+backend session helper. The host's login transaction lasts ten minutes; it is local process memory and
+is lost on restart. A production integration replaces it with the customer's existing verified login and
+login transaction. Do not copy the synthetic identity branch into a real application.
+
+## Customer integration map
+
+| Reference | Adaptation in the customer's application |
+| :--- | :--- |
+| Three-field brief | Select the smallest useful outcome and collect only its missing inputs |
+| Public mixed surface | Mount the public embed on the unauthenticated website with an exact allowlist |
+| Expiring `draft` handle | Keep only temporary, bounded coordination state; omit persistence if unnecessary |
+| `continue_draft` | Trigger the existing signup/login at the point the visitor chooses an account |
+| Host session endpoint | Verify the logged-in user, spend the bound ticket, return the SDK session response |
+| Final business action | Add a typed connector to the existing authorized, idempotent create/update API |
+
+The final business action belongs in the customer backend. Show the resulting record or its identifier
+only after that API confirms success. Signup and state adoption alone are not completed onboarding.
+Research or document parsing can be added later when they remove a demonstrated user burden; they are not
+prerequisites for this reference.
+
+## State and failure behavior
+
+The draft uses caller scope, a finite 24-hour TTL, and `claimOnAuthentication: true`. Its `v2` schema
+replaces the earlier title/stage illustration. Widget state is only a display cache. Reads, validation,
+revision checks, expiry, and persistence belong to the runtime.
+
+A stale edit requires an explicit reload and review before another save. Spending the single-use sign-in
+ticket moves only opted-in state to the backend-verified account, preserving its revision and expiry.
+Destination conflicts fail rather than merging two drafts. Abandoned or expired signup leaves the
+anonymous state under its original limits. A 24-hour state TTL does not promise cross-device recovery or
+that an arbitrary new anonymous visit can recover the conversation.
+
+The save is a connector-backed side effect on a public/mixed surface, so it has `confirm: true`. Previewing
+the brief has no side effect and needs neither signup nor confirmation. Do not add a confirmation to each
+conversational answer or treat confirmation as proof of identity.
+
+## Validate before a customer pilot
+
+- Show useful value with no account and without repeating already supplied information.
+- Save, reopen, and edit the actual record; test a stale revision and an unconfirmed save.
+- Verify the same draft after the customer's real signup and login, including cancellation and expiry.
+- Test an existing-account draft conflict and ensure it is not silently overwritten.
+- Ensure signup triggers no unintended business write and account A cannot read account B's draft.
+- Compare onboarding completion and first useful product outcome with the existing flow; count signups
+  separately. A demo is not evidence of improved conversion.

package/skills/codex/examples/stateful-draft/noodle.json

@@ -0,0 +1,5 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "stateful-draft",
+  "template": "widget"
+}

package/skills/codex/examples/stateful-draft/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "stateful-draft",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy",
+    "site": "node site/demo.mjs"
+  },
+  "devDependencies": {
+    "@noodleseed/assistant": "^1.33.0",
+    "@vitejs/plugin-react": "latest",
+    "@noodleseed/one": "^0.154.0",
+    "react": "latest",
+    "react-dom": "latest",
+    "vite": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/codex/examples/stateful-draft/site/client.js

@@ -0,0 +1,44 @@
+import '/sdk/index.js';
+
+const config = await fetch('/demo-config').then((response) => response.json());
+const mount = document.querySelector('#assistant');
+const status = document.querySelector('#status');
+if (config.authenticated && !config.signedIn) {
+  document.querySelector('#demo-login').hidden = false;
+  status.textContent =
+    'Your draft is ready to come with you. This next step simulates the product’s signup.';
+} else {
+  const assistant = document.createElement('noodle-assistant');
+  assistant.setAttribute('theme', 'light');
+  if (config.authenticated) {
+    assistant.setAttribute('session-endpoint', '/assistant-session');
+    status.textContent =
+      'You are using a synthetic demo account. Open the chat to continue with your saved brief.';
+  } else {
+    assistant.setAttribute('embed-id', config.embedId);
+    assistant.setAttribute('service-url', config.serviceUrl);
+    status.textContent =
+      'Start without an account. Open the chat and describe what you want to achieve.';
+  }
+  mount.append(assistant);
+}
+
+document.addEventListener('assistant-sign-in-requested', async (event) => {
+  status.textContent = 'Preparing your account handoff…';
+  try {
+    const response = await fetch('/start', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ signInTicket: event.detail.signInTicket }),
+    });
+    const result = await response.json();
+    if (!response.ok) {
+      status.textContent = result.error ?? 'Handoff not started';
+      return;
+    }
+    window.location.assign(result.destination);
+  } catch {
+    status.textContent =
+      'The handoff did not start. Your brief has not been moved. Please try again.';
+  }
+});

package/skills/codex/examples/stateful-draft/site/demo.mjs

@@ -0,0 +1,158 @@
+/** Loopback-only synthetic host. Replace its demo identity with your existing login in a real app. */
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAssistantSession } from '@noodleseed/assistant/server';
+
+const publicOrigin = 'http://localhost:3001';
+const appOrigin = 'http://localhost:3002';
+const serviceUrl = process.env.NOODLE_SERVICE_URL ?? 'https://cloud.noodleseed.dev';
+const embedId = process.env.NOODLE_EMBED_ID;
+const credentialFile = process.env.NOODLE_ASSISTANT_CREDENTIALS_FILE;
+if (!embedId?.match(/^pub_[a-z0-9]+$/i)) {
+  throw new Error('Set NOODLE_EMBED_ID from the hosted deployment.');
+}
+if (new URL(serviceUrl).protocol !== 'https:')
+  throw new Error('The hosted service must use HTTPS.');
+// Consume only the explicitly supplied backend credential file. Its content is never sent to the browser.
+const credentials = credentialFile ? JSON.parse(await readFile(credentialFile, 'utf8')) : undefined;
+if (
+  credentials &&
+  (typeof credentials.clientId !== 'string' || typeof credentials.clientSecret !== 'string')
+) {
+  throw new Error('The backend credential file is not a CLI-created assistant client file.');
+}
+const sdkDir = dirname(fileURLToPath(import.meta.resolve('@noodleseed/assistant')));
+const siteDir = dirname(fileURLToPath(import.meta.url));
+const transactions = new Map();
+const lifetime = 10 * 60 * 1000;
+
+function send(res, status, value, type = 'application/json') {
+  res.writeHead(status, {
+    'Content-Type': type,
+    'Cache-Control': 'no-store',
+    'Referrer-Policy': 'no-referrer',
+    'X-Content-Type-Options': 'nosniff',
+  });
+  res.end(type === 'application/json' ? JSON.stringify(value) : value);
+}
+function redirect(res, destination) {
+  res.writeHead(303, { Location: destination, 'Cache-Control': 'no-store' });
+  res.end();
+}
+function current(req) {
+  const id = /(?:^|;\s*)brief_demo=([a-f0-9-]+)/.exec(req.headers.cookie ?? '')?.[1];
+  return id ? transactions.get(id) : undefined;
+}
+async function jsonBody(req) {
+  let text = '';
+  for await (const chunk of req) {
+    text += chunk.toString();
+    if (Buffer.byteLength(text) > 8192) throw new Error('Request too large');
+  }
+  return JSON.parse(text);
+}
+
+function handler(origin) {
+  return async (req, res) => {
+    // The fixed loopback host is intentional: never deploy this synthetic-login server to the internet.
+    if (req.headers.host !== new URL(origin).host) return send(res, 403, { error: 'Wrong host' });
+    for (const [id, transaction] of transactions) {
+      if (transaction.expiresAt <= Date.now()) transactions.delete(id);
+    }
+    const path = new URL(req.url ?? '/', origin).pathname;
+    try {
+      if (req.method === 'GET' && path === '/') {
+        return send(
+          res,
+          200,
+          await readFile(join(siteDir, 'index.html')),
+          'text/html; charset=utf-8',
+        );
+      }
+      if (req.method === 'GET' && path === '/demo-config') {
+        return send(res, 200, {
+          serviceUrl,
+          embedId,
+          authenticated: origin === appOrigin,
+          signedIn: Boolean(current(req)?.user),
+        });
+      }
+      if (req.method === 'GET' && path === '/client.js') {
+        return send(res, 200, await readFile(join(siteDir, 'client.js')), 'text/javascript');
+      }
+      if (req.method === 'GET' && /^\/sdk\/[a-z0-9._-]+\.js$/i.test(path)) {
+        return send(res, 200, await readFile(join(sdkDir, path.slice(5))), 'text/javascript');
+      }
+      if (req.method === 'POST') {
+        if (req.headers.origin !== origin) return send(res, 403, { error: 'Wrong origin' });
+        if (origin === publicOrigin && path === '/start') {
+          if (!credentials)
+            return send(res, 503, {
+              error:
+                'Signup demonstration needs an authorized backend client. The anonymous brief is still available.',
+            });
+          if (transactions.size >= 40) return send(res, 429, { error: 'Please try again later' });
+          const body = await jsonBody(req);
+          if (typeof body.signInTicket !== 'string' || body.signInTicket.length > 4096) {
+            return send(res, 400, { error: 'Missing continuation ticket' });
+          }
+          const id = randomUUID();
+          transactions.set(id, {
+            signInTicket: body.signInTicket,
+            expiresAt: Date.now() + lifetime,
+          });
+          res.setHeader(
+            'Set-Cookie',
+            `brief_demo=${id}; HttpOnly; SameSite=Lax; Path=/; Max-Age=600`,
+          );
+          return send(res, 200, { destination: appOrigin });
+        }
+        if (origin === appOrigin && path === '/demo-login') {
+          const transaction = current(req);
+          if (!transaction)
+            return send(res, 410, { error: 'Demo expired. Start again on the public page.' });
+          // Synthetic identity only. A production route must verify its existing application session.
+          transaction.user ??= { id: `demo_${randomUUID()}`, name: 'Demo visitor' };
+          return redirect(res, '/');
+        }
+      }
+      if (origin === appOrigin && req.method === 'GET' && path === '/assistant-session') {
+        if (!credentials) return send(res, 503, { error: 'Configure the backend client first' });
+        if (req.headers['sec-fetch-site'] !== 'same-origin')
+          return send(res, 403, { error: 'Same-origin request required' });
+        const transaction = current(req);
+        if (!transaction?.user)
+          return send(res, 401, { error: 'Choose the synthetic demo account first' });
+        // Reuse the in-flight result so concurrent mounts cannot spend the single-use ticket twice.
+        transaction.session ??= createAssistantSession({
+          serviceUrl,
+          clientId: credentials.clientId,
+          clientSecret: credentials.clientSecret,
+          origin: appOrigin,
+          user: transaction.user,
+          signInTicket: transaction.signInTicket,
+        });
+        const session = await transaction.session;
+        delete transaction.signInTicket;
+        return send(res, 200, session);
+      }
+      return send(res, 404, { error: 'Not found' });
+    } catch {
+      // Do not log credentials, tickets, requests, or raw provider errors.
+      return send(res, 409, {
+        error: 'Continuation was not completed. Return to the public page and start again.',
+      });
+    }
+  };
+}
+for (const [port, origin] of [
+  [3001, publicOrigin],
+  [3002, appOrigin],
+]) {
+  createServer(handler(origin)).listen(port, '127.0.0.1');
+}
+console.log(`Synthetic onboarding demo: ${publicOrigin}`);
+console.log('Loopback only. Uses the hosted assistant; demo signup is not a real account.');

package/skills/codex/examples/stateful-draft/site/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>First Brief · Conversational onboarding demo</title>
+    <style>
+      :root { font-family: system-ui, sans-serif; color: #172033; background: #f6f8fc; }
+      body { margin: 0; }
+      main { max-width: 880px; margin: 0 auto; padding: 64px 28px; }
+      .label { font-size: 12px; font-weight: 700; letter-spacing: .14em; color: #526077; }
+      h1 { max-width: 640px; font-size: clamp(36px, 6vw, 64px); line-height: 1.08; letter-spacing: -.055em; }
+      p { max-width: 570px; line-height: 1.6; color: #526077; }
+      .sample { padding: 24px; border: 1px solid #dce3ee; border-radius: 16px; background: white; margin: 28px 0; max-width: 550px; }
+      a { color: #174bbd; }
+      button { border: none; background: #2563eb; color: white; padding: 14px 20px; border-radius: 9px; font: inherit; cursor: pointer; }
+      :focus-visible { outline: 3px solid #2563eb; outline-offset: 4px; }
+      .notice { font-size: 13px; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <span class="label">FIRST BRIEF · INTERNAL DEMONSTRATION</span>
+      <h1>Make something useful.<br>Then decide to sign up.</h1>
+      <p>Describe a goal. Refine a short brief. See the result before deciding whether to take it into an account.</p>
+      <div class="sample">
+        <strong>Try this in the chat</strong>
+        <p>“I want to help new teammates complete their first useful project in a week.”</p>
+        <p id="status" role="status" aria-live="polite">Connecting…</p>
+      </div>
+      <form id="demo-login" action="/demo-login" method="post" hidden>
+        <p><strong>Simulated signup</strong><br>This creates a temporary demo identity. It does not register an account with any SaaS product.</p>
+        <button type="submit">Continue as a demo user</button>
+        <p><a href="http://localhost:3001">Cancel and return to the public page</a></p>
+      </form>
+      <p class="notice">Use synthetic information only. The assistant and draft storage are hosted by Noodle Seed. Signup is simulated locally; no customer backend is connected. Drafts expire within 24 hours. <a href="https://noodleseed.com/privacy" target="_blank" rel="noreferrer">Privacy</a></p>
+    </main>
+    <div id="assistant"></div>
+    <script type="module" src="/client.js"></script>
+  </body>
+</html>

package/skills/codex/examples/stateful-draft/src/helpers.ts

@@ -0,0 +1,6 @@
+import type { ServerDefinition } from '@noodleseed/one';
+import { generateHelpers } from '@noodleseed/one/react';
+
+export type AppType = ServerDefinition;
+
+export const { useCallTool, useToolInfo, useSendFollowUpMessage } = generateHelpers<AppType>();