@noodleseed/agent-kit 0.17.0 → 0.19.0

package/skills/codex/examples/acme-discovery/src/server.ts

@@ -1,4 +1,4 @@
-import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 // Acme Getaways is a fictional travel brand. This app is deliberately top-of-funnel: discovery and
 // configuration happen inside ChatGPT; the booking/transaction happens off-app on Acme's own site,
@@ -115,7 +115,7 @@ export default server(
     },
   },
   [
-    toolWithWidget('discover_getaways', {
+    tool('discover_getaways', {
       description:
         'Suggest Acme Getaways destinations for a vibe and month and render a discovery carousel.',
       annotations: readOnly,
@@ -136,7 +136,7 @@ export default server(
         travelers: input.travelers,
         options: catalog,
       }),
-      widgetTitle: 'Discover getaways',
+      viewTitle: 'Discover getaways',
       // ChatGPT host status copy (openai/toolInvocation/*) — required for widget-opening tools.
       invoking: 'Finding getaways…',
       invoked: 'Getaways ready',
@@ -145,7 +145,7 @@ export default server(
         component: 'discovery-carousel',
         entry: './views/discovery-carousel.tsx',
       },
-      widgetDescription:
+      viewDescription:
         'A top-of-funnel discovery carousel: pick a destination, then hand off to Acme to book.',
       csp: {
         connectDomains: ['https://acme.example'],
@@ -180,7 +180,8 @@ export default server(
         handoffUrl: `https://book.acme.example/plan?dest=${input.destination}&month=${input.month}&pax=${input.travelers}&src=chatgpt`,
       }),
     }),
-    toolForWidget('shortlist_getaway', {
+    tool('shortlist_getaway', {
+      visibility: ['app'],
       description: 'Record the traveler’s shortlisted destination from the discovery widget.',
       annotations: localWrite,
       input: z.object({

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

@@ -7,7 +7,7 @@ in one `TaskList` widget. It shows the "identify and prioritize the flows first,
 the `noodle-seed` skill's `references/experience-design.md` teaches.
 
 Capability slots: prioritized multi-flow app design, a two-way (read + write) in-chat pattern, a task-list
-widget with `toolForWidget` helpers, and a worked **design-first** artifact (the flow spec + wireframe
+widget with `tool` helpers, and a worked **design-first** artifact (the flow spec + wireframe
 below). A real deployment would connect the user's account with the end-user auth pattern — see
 [`../customer-auth/README.md`](../customer-auth/README.md); this example seeds a list so the focus stays
 on the flows.
@@ -76,5 +76,31 @@ noodle deploy --access owner-only
 noodle open
 ```
 
+## Optional in-product assistant
+
+The same task tools can also sit inside Acme's authenticated web app. Add an `assistant` option to this
+server without creating a second tool set:
+
+```ts
+assistant: embeddedAssistant({
+  model: openAICompatible({
+    baseUrl: variable('ASSISTANT_MODEL_BASE_URL'),
+    model: variable('ASSISTANT_MODEL'),
+    apiKey: secret('ASSISTANT_MODEL_API_KEY'),
+  }),
+  allowedOrigins: ['https://tasks.example.com'],
+  layout: { mode: 'floating', position: 'bottom-right' },
+  labels: { welcomeHeading: 'How can I help with Acme Tasks?' },
+}),
+```
+
+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.
+
+The customer backend exchanges its authenticated user through `@noodleseed/assistant/server`; the browser
+uses the Web Component or React wrapper and never receives the embed client or model secret. Validate with
+`noodle check --target embedded-assistant`, then create the backend credential with
+`noodle assistant clients create` after deployment.
+
 This example has no connector secrets and does not include tokens, caller-key mechanisms, or
 `.env.noodle` values. All tasks are fictional seed data.

package/skills/codex/examples/acme-tasks/design/UX-Document.md

@@ -155,7 +155,7 @@ All tools are atomic, model-fillable from natural language, and each returns a s
 **★ `list_today`** *(read-only · renders `TaskList`)*
 - **Input:** `{ focus: string = "today" }`
 - **Output:** `{ status, focus, tasks: [{ id, title, priority, done }] }`
-- **Notes:** `toolWithWidget` — the one tool that opens the widget. Host status copy: invoking "Loading your tasks…", invoked "Tasks ready".
+- **Notes:** `tool` — the one tool that opens the widget. Host status copy: invoking "Loading your tasks…", invoked "Tasks ready".
 
 **★ `add_task`** *(local write, non-destructive · model-visible)*
 - **Input:** `{ title: string, priority: "high"|"medium"|"low" = "medium" }`
@@ -170,7 +170,7 @@ All tools are atomic, model-fillable from natural language, and each returns a s
 **`set_priority`** *(local write, non-destructive · widget-only)*
 - **Input:** `{ task: string (id), priority: "high"|"medium"|"low" }`
 - **Output:** `{ status, task, priority }`
-- **Notes:** `toolForWidget` — hidden from the model; the `<select>` in `TaskList` is its only caller, keeping the model's tool surface to the three it should reason about.
+- **Notes:** `tool` — hidden from the model; the `<select>` in `TaskList` is its only caller, keeping the model's tool surface to the three it should reason about.
 
 ---
 

package/skills/codex/examples/acme-tasks/design/wireframe.html

@@ -217,7 +217,7 @@
     <div class="rationale">
       <h4>How to read these wireframes</h4>
       <p>Solid-border phones are the <strong>in-ChatGPT app</strong>. Acme Tasks is a <strong>two-way (read + write) app</strong>, not a discovery funnel: every widget reflects the user's real list, and each action — capture, re-prioritize, complete — is <strong>recorded through a tool call</strong> and confirmed in-chat. The single dashed phone is the <strong>one-time account link</strong> (<span class="mono">customerAuth</span>); there is no transactional off-app step.</p>
-      <p>Widgets are built with the Noodle Seed authoring SDK — <span class="mono">toolWithWidget</span> renders <span class="mono">TaskList</span>; <span class="mono">toolForWidget</span> powers the in-widget re-prioritize. Styling uses host/Noodle Seed semantic tokens via CSS cascade layers; the brand accent (<span class="mono">#7C3AED</span>) is reserved for the logo, checks, primary CTA and <em>high</em> emphasis. Priority uses fixed semantic colors: high red · medium amber · low slate.</p>
+      <p>Widgets are built with the Noodle Seed authoring SDK — <span class="mono">tool + view</span> renders <span class="mono">TaskList</span>; <span class="mono">tool + app visibility</span> powers the in-widget re-prioritize. Styling uses host/Noodle Seed semantic tokens via CSS cascade layers; the brand accent (<span class="mono">#7C3AED</span>) is reserved for the logo, checks, primary CTA and <em>high</em> emphasis. Priority uses fixed semantic colors: high red · medium amber · low slate.</p>
       <p><span class="r-tag ux">UX</span> flow rationale &nbsp; <span class="r-tag ui">UI</span> interface rationale &nbsp; <span class="r-tag acme">ACME</span> product-model fit &nbsp; <span class="r-tag trust">TRUST</span> write-safety / grounding guardrail</p>
     </div>
   </div>
@@ -401,11 +401,11 @@
   <div class="section" id="prioritize">
     <span class="section-label">Flow 2 · the hub</span>
     <h2 class="section-title">Prioritize — read the day, then re-order it in place</h2>
-    <p class="section-subtitle"><span class="mono">list_today</span> renders the grounded list, highest priority first; the per-row priority control (a <span class="mono">toolForWidget</span> helper hidden from the model) lets the user re-rank without describing the task twice. This is the widget the other two flows write into.</p>
+    <p class="section-subtitle"><span class="mono">list_today</span> renders the grounded list, highest priority first; the per-row priority control (a <span class="mono">tool + app visibility</span> helper hidden from the model) lets the user re-rank without describing the task twice. This is the widget the other two flows write into.</p>
     <div class="rationale">
       <h4>Why it's built this way</h4>
       <p><span class="r-tag ux">UX</span> "What's on my plate?" wants an answer <em>and</em> a next move. The list is grouped high → low so the triager sees the real order at a glance and adjusts with one tap.</p>
-      <p><span class="r-tag acme">ACME</span> Re-prioritize is <span class="mono">set_priority</span> as <span class="mono">toolForWidget</span> — <strong>widget-only</strong>, hidden from the model's tool surface. The model reasons about three tools (list, add, complete); the fourth is pure UI plumbing, keeping the model's choices clean.</p>
+      <p><span class="r-tag acme">ACME</span> Re-prioritize is <span class="mono">set_priority</span> as <span class="mono">tool + app visibility</span> — <strong>widget-only</strong>, hidden from the model's tool surface. The model reasons about three tools (list, add, complete); the fourth is pure UI plumbing, keeping the model's choices clean.</p>
       <p><span class="r-tag trust">TRUST</span> The list only ever shows tasks that exist — the app never invents a task or a priority. Every re-rank echoes a confirmation ("Set review_pr to high priority").</p>
     </div>
     <div class="phones-row">
@@ -543,7 +543,7 @@
   <div class="section" id="api">
     <span class="section-label">Technical appendix</span>
     <h2 class="section-title">MCP tools &amp; call sequence</h2>
-    <p class="section-subtitle">The four tools behind the flows. <span class="mono">list_today</span> is the only widget-opening tool (<span class="mono">toolWithWidget</span>); <span class="mono">set_priority</span> is widget-only (<span class="mono">toolForWidget</span>, hidden from the model); <span class="mono">add_task</span> and <span class="mono">complete_task</span> are model-visible.</p>
+    <p class="section-subtitle">The four tools behind the flows. <span class="mono">list_today</span> is the only widget-opening tool (<span class="mono">tool + view</span>); <span class="mono">set_priority</span> is widget-only (<span class="mono">tool + app visibility</span>, hidden from the model); <span class="mono">add_task</span> and <span class="mono">complete_task</span> are model-visible.</p>
 
     <div class="api-panel">
       <h4>Read &amp; render (Flow 2 · the hub)</h4>
@@ -559,7 +559,7 @@
 
     <div class="api-panel">
       <h4>Prioritize (Flow 2 helper) &amp; Complete (Flow 3)</h4>
-      <div class="api-step"><span class="verb">WRITE</span><span><span class="tname">set_priority</span> — returns { status, task, priority } · toolForWidget, hidden from the model</span></div>
+      <div class="api-step"><span class="verb">WRITE</span><span><span class="tname">set_priority</span> — returns { status, task, priority } · tool + app visibility, hidden from the model</span></div>
       <div class="api-note">Input <span class="mono">{ task:id, priority }</span>. Called only by the priority ▾ in TaskList — keeps the model's tool surface to the three it should reason about.</div>
       <div class="api-step"><span class="verb">WRITE</span><span><span class="tname">complete_task</span> — returns { status, task } · model-visible</span></div>
       <div class="api-note">Input <span class="mono">{ task:id, title:"" }</span>. Model-visible so "I finished X" completes directly; local non-destructive write, confirmed with the remaining count.</div>
@@ -596,7 +596,7 @@
 
 <div class="footer">
   Acme Tasks × ChatGPT — Two-Way App Wireframes · Noodle Seed · v1 · July 2026<br>
-  Illustrative wireframes for a fictional app. Built with the Noodle Seed authoring SDK (toolWithWidget / toolForWidget · customerAuth). This flagship seeds the task list; a production deployment connects the user's account. Task data shown is sample content.
+  Illustrative wireframes for a fictional app. Built with the Noodle Seed authoring SDK (tool + view / tool + app visibility · customerAuth). This flagship seeds the task list; a production deployment connects the user's account. Task data shown is sample content.
 </div>
 
 </body>

package/skills/codex/examples/acme-tasks/src/server.ts

@@ -1,4 +1,4 @@
-import { annotations, server, tool, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 // Acme Tasks is a fictional productivity app. It is a two-way (read + write) experience rather than a
 // top-of-funnel handoff: the top-3 prioritized user flows all complete in chat — Capture, Prioritize,
@@ -52,7 +52,7 @@ export default server(
   },
   [
     // Flow 2 — Prioritize / Today: render the list so the human triages and the model can speak to it.
-    toolWithWidget('list_today', {
+    tool('list_today', {
       description: 'Show today’s Acme Tasks and render the task-list widget.',
       annotations: readOnly,
       input: z.object({ focus: z.string().default('today') }),
@@ -66,8 +66,8 @@ export default server(
         focus: input.focus,
         tasks: today,
       }),
-      widgetTitle: 'Today’s tasks',
-      widgetDescription: 'A prioritized task list: capture, re-prioritize, and complete in place.',
+      viewTitle: 'Today’s tasks',
+      viewDescription: 'A prioritized task list: capture, re-prioritize, and complete in place.',
       // ChatGPT host status copy (openai/toolInvocation/*) — required for widget-opening tools.
       invoking: 'Loading your tasks…',
       invoked: 'Tasks ready',
@@ -119,7 +119,8 @@ export default server(
       }),
     }),
     // Flow 2 helper (widget-only): re-prioritize a task from the list widget.
-    toolForWidget('set_priority', {
+    tool('set_priority', {
+      visibility: ['app'],
       description: 'Re-prioritize a task from the list widget.',
       annotations: localWrite,
       input: z.object({

package/skills/codex/examples/food-ordering/src/server.ts

@@ -1,15 +1,4 @@
-import {
-  annotations,
-  asset,
-  connector,
-  resource,
-  server,
-  tool,
-  toolForWidget,
-  toolWithWidget,
-  widget,
-  z,
-} from '@noodleseed/one';
+import { annotations, asset, connector, resource, server, tool, z } from '@noodleseed/one';
 
 const heroImage = asset('assets/noodle-bowl.jpg');
 
@@ -235,7 +224,7 @@ export default server(
     },
   },
   [
-    toolWithWidget('open_ordering', {
+    tool('open_ordering', {
       description:
         'Open a complete food-ordering widget with store discovery, menu browsing, cart review, and checkout handoff.',
       annotations: readOnly,
@@ -257,13 +246,13 @@ export default server(
         featuredItems: menu,
         fallback: 'Open stores: Harbor Noodles (Noodles), Garden Wraps (Vegetarian).',
       }),
-      widgetTitle: 'Food ordering',
+      viewTitle: 'Food ordering',
       domain: 'https://orders.example.com',
       view: {
         component: 'ordering-flow',
         entry: './views/ordering-flow.tsx',
       },
-      widgetDescription:
+      viewDescription:
         'A complete consumer ordering surface with app-only helper tools, cart state, and checkout handoff.',
       csp: {
         connectDomains: ['https://orders.example.com'],
@@ -272,7 +261,8 @@ export default server(
       },
       permissions: { clipboardWrite: {} },
     }),
-    toolForWidget('search_stores', {
+    tool('search_stores', {
+      visibility: ['app'],
       description: 'Filter synthetic restaurants for the ordering widget.',
       annotations: readOnly,
       input: z.object({
@@ -282,7 +272,8 @@ export default server(
       output: z.object({ stores: z.array(storeShape) }),
       fulfil: () => ({ stores }),
     }),
-    toolForWidget('load_menu', {
+    tool('load_menu', {
+      visibility: ['app'],
       description: 'Load synthetic menu categories and items for one store.',
       annotations: readOnly,
       input: z.object({ storeId: z.string() }),
@@ -293,14 +284,16 @@ export default server(
       }),
       fulfil: ({ input }) => ({ storeId: input.storeId, stores, items: menu }),
     }),
-    toolForWidget('load_item', {
+    tool('load_item', {
+      visibility: ['app'],
       description: 'Load item details and modifier options for the ordering widget.',
       annotations: readOnly,
       input: z.object({ itemId: z.string() }),
       output: z.object({ itemId: z.string(), items: z.array(menuItemShape) }),
       fulfil: ({ input }) => ({ itemId: input.itemId, items: menu }),
     }),
-    toolForWidget('read_cart', {
+    tool('read_cart', {
+      visibility: ['app'],
       description: 'Read the caller-scoped ordering cart state.',
       annotations: readOnly,
       input: z.object({}),
@@ -314,7 +307,8 @@ export default server(
         return { value: state.value, revision: state.revision, status: state.status };
       },
     }),
-    toolForWidget('sync_cart', {
+    tool('sync_cart', {
+      visibility: ['app'],
       description: 'Patch the caller-scoped ordering cart with the widget cart mirror.',
       annotations: action,
       input: cartInput,
@@ -333,7 +327,8 @@ export default server(
         return { cart, revision: state.revision, status: state.status };
       },
     }),
-    toolForWidget('prepare_checkout', {
+    tool('prepare_checkout', {
+      visibility: ['app'],
       description: 'Prepare the caller-scoped cart for checkout handoff.',
       annotations: action,
       input: cartInput,
@@ -375,6 +370,17 @@ export default server(
         status: 'Food Ordering widget capabilities are ready.',
         note: 'Standalone preview covers React views, helper tools, cart state, handoff, CSP, and permissions.',
       }),
+      viewName: 'capabilities_card',
+      viewTitle: 'Food Ordering capabilities',
+      viewDescription: 'Standalone widget resource for previewing the ordering capability surface.',
+      domain: 'https://orders.example.com',
+      view: { component: 'capabilities-card', entry: './views/capabilities-card.tsx' },
+      csp: {
+        connectDomains: ['https://orders.example.com'],
+        resourceDomains: ['https://orders.example.com'],
+        frameDomains: ['https://orders.example.com'],
+      },
+      permissions: { clipboardWrite: {} },
     }),
     resource('food_ordering_guide', {
       uri: 'docs://food-ordering',
@@ -392,21 +398,5 @@ export default server(
           '- Checkout opens an allowlisted example URL; payment and final ordering remain out of scope.',
         ].join('\n'),
     }),
-    widget('capabilities_card', {
-      tool: 'show_capabilities',
-      title: 'Food Ordering capabilities',
-      domain: 'https://orders.example.com',
-      description: 'Standalone widget resource for previewing the ordering capability surface.',
-      view: {
-        component: 'capabilities-card',
-        entry: './views/capabilities-card.tsx',
-      },
-      csp: {
-        connectDomains: ['https://orders.example.com'],
-        resourceDomains: ['https://orders.example.com'],
-        frameDomains: ['https://orders.example.com'],
-      },
-      permissions: { clipboardWrite: {} },
-    }),
   ],
 );

package/skills/codex/references/authoring-workflow.md

@@ -11,6 +11,7 @@
 - Compute connector example
 - Tests
 - Secrets and variables
+- Embedded assistant
 - Boundaries
 
 ## Input paths
@@ -197,6 +198,10 @@ After focused tests pass, run `noodle validate --json`, `noodle test --json`, an
 
 Author managed config as `secret("NAME")` / `variable("NAME")` and operate it with `noodle secrets set` / `noodle variables set` (scoped org/app/env). Never inline secret values in `server.ts`, tests, or generated files.
 
+## Embedded assistant
+
+To place the same server tools inside the SaaS web app, declare the shared identity once with `branding: { name: "Acme", accent: "#3157D5", surface: "#FFFFFF", surfaceDark: "#161B26", theme: { dark: { accent: "#9FB4FF" } } }`, then add `assistant: embeddedAssistant({ model: openAICompatible({ baseUrl: variable("ASSISTANT_MODEL_BASE_URL"), model: variable("ASSISTANT_MODEL"), apiKey: secret("ASSISTANT_MODEL_API_KEY") }), allowedOrigins: ["https://app.example.com"], layout: { mode: "floating", position: "bottom-right" } })`. Widgets and the embed inherit the same brand kit. Keep origins exact. The customer backend uses `@noodleseed/assistant/server` to exchange its already-authenticated user for a short-lived browser session; client and model secrets never enter the browser. Run `noodle check --target embedded-assistant` before deploy, then manage backend credentials with `noodle assistant clients create|list|rotate|revoke`.
+
 ## Boundaries
 
 Do not hand-author manifest JSON/YAML, runtime artifacts, connector IR, or hosted asset metadata. Do not read or copy secrets, bearer tokens, refresh tokens, static access keys, `.env.noodle`, or `~/.noodle/config.json`. Hosted access is identity-based — do not add static data-plane credential paths.

package/skills/codex/references/cli-commands.md

@@ -46,6 +46,7 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | Command | What it does |
 | :-- | :-- |
 | `noodle link` | Bind this directory to a Noodle Seed Cloud target (org/app/env). |
+| `noodle assistant` | Manage backend credentials for customer-branded embedded assistant clients. |
 | `noodle deploy` | Deploy the server to Noodle Seed Cloud. |
 | `noodle open` | Open or print the latest deployment URL. |
 | `noodle status` | Show hosted deployment status. |

package/skills/codex/references/compile-errors.md

@@ -38,8 +38,8 @@ Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-pr
 | `duplicate_prompt` | Two prompts share a name; rename one `prompt(...)`. |
 | `duplicate_resource_uri` | Two resources resolve to the same URI; make each resource URI unique. |
 | `unsupported_uri_template` | Fix the resource URI template to a supported form at the cited `path`. |
-| `duplicate_widget` | Two widgets share an identity; give each `widget(...)`/`view` a unique component name. |
-| `unknown_widget_tool` | The widget references a tool that does not exist; point `toolWithWidget`/`view` at a declared tool (see `didYouMean`). |
+| `duplicate_widget` | Two tool views share an identity; give each `viewName` or `view.component` a unique name. |
+| `unknown_widget_tool` | The widget references a tool that does not exist; point `tool`/`view` at a declared tool (see `didYouMean`). |
 | `unknown_widget_action_tool` | A widget action calls a tool that is not declared; declare it or fix the action target name. |
 | `duplicate_widget_tool` | A tool is bound to more than one widget; bind each tool to a single widget. |
 | `invalid_widget_binding` | Fix the `data-bind`/binding expression in the widget; it does not resolve against the tool output. |

package/skills/codex/references/experience-design.md

@@ -87,7 +87,7 @@ the widget**, and the widget filled with plausible, internally consistent data (
 Label each widget with its component name so the wireframe, the spec, and the code share one
 vocabulary; put the funnel boundary at the top; and render off-app destinations distinctly (they are
 reached only after the handoff). Each wireframe screen maps directly to noodle: a screen with a widget
-is a `toolWithWidget` + a React `view`; a plain answer is a `tool`; an off-app destination is a
+is a `tool` + a React `view`; a plain answer is a `tool`; an off-app destination is a
 `handoff.allowedDomains` entry. A compact single screen, anonymized to a fictional "Acme" business:
 
 ```html

package/skills/codex/references/sdk-surface.md

@@ -14,13 +14,10 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 ### Server & tools
 
 - `server(name, options, definitions)` — the server/app root.
-- `tool(name, { description, input, output, fulfil })` — a model-visible tool.
-- `toolWithWidget(name, { ..., view })` — a model-visible tool that renders an MCP Apps widget.
-- `toolForWidget(name, { ... })` — a widget-only helper tool, hidden from the model.
+- `tool(name, options)` — declare every tool; add `view` to render an MCP App or `visibility: ["app"]` for an app-only helper.
 
-### Widgets & assets
+### Views & assets
 
-- `widget(...)` — declare a widget/view component.
 - `asset("./path")` — reference a packaged asset (e.g. an image).
 - `annotations(...)` — tool/Apps annotation metadata.
 
@@ -51,14 +48,17 @@ Platform helper connectors are explicit subpath imports from `@noodleseed/one/pl
 
 - `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
 
+### Other
+
+- `embeddedAssistant`
+- `openAICompatible`
+
 ## Authoring signatures
 
-- `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts/widgets.
-- `tool(name, { description, input, output, annotations?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`.
-- `toolWithWidget(name, { description, input, output, fulfil, view })` — same as `tool`, plus `view: { component, entry }` for a React widget.
-- `toolForWidget(name, { input, output, fulfil })` — helper tool for widget actions; hidden from the model.
+- `server(name, options, definitions)` — `options` commonly includes `title`, `version`, `instructions`, `branding`, `auth`, `use`, `provides`, `state`, and `handoff`; `definitions` is the array of tools/resources/prompts.
+- `tool(name, { description, input, output, annotations?, visibility?, view?, fulfil })` — `input`/`output` are Zod schemas; `fulfil({ input, connectors, user })` returns data matching `output`. Add `view: { component, entry }` for a React widget; use `visibility: ["app"]` for an app-only helper.
 - `resource(name, { uri, description?, mimeType?, fulfil })` and `prompt(name, { description?, arguments?, fulfil })` expose MCP resources/prompts.
-- `widget(name, { title, view, csp?, domain?, permissions? })` declares reusable view metadata; `asset("./path")` packages local files.
+- View metadata (`viewTitle`, `viewDescription`, `csp`, `domain`, `permissions`) belongs on the tool that renders it; `asset("./path")` packages local files.
 - `customerAuth.*(...)` belongs in `server` options when deployed customer callers need verified identity; inspect `examples/customer-auth` or `examples/sharepoint` before using it.
 - `state` defines durable widget state handles; `handoff` declares allowed external domains for safe host handoff.
 

package/skills/codex/references/troubleshooting.md

@@ -19,9 +19,9 @@ For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `n
 | ChatGPT warns “Widget CSP is not set” | The widget declares no `csp` | Declare `csp` on the widget with the exact origins it uses |
 | ChatGPT warns “Widget domain is not set” | No `domain` on the widget (required for app-store submission) | Set `domain: "https://…"` (one https origin per app) on each widget |
 | External links do nothing, or show a safe-link warning | Link opened outside the host bridge, or the target origin is not allowlisted | Use `useOpenExternal()` (never `window.open`) and add the target origins to the server-level `handoff.allowedDomains` |
-| Tool succeeds but no widget appears | The tool has no view, or the host surface doesn’t support MCP Apps | Use `toolWithWidget`, run `noodle check`, preview with `noodle devtools`; on non-Apps surfaces only the text/structured result renders |
+| 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 `toolForWidget` |
+| `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` |
 | 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 |

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

@@ -12,7 +12,7 @@
 
 ## Tools and views
 
-Use `toolWithWidget(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and `toolForWidget(name, { ... })` for a widget-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
+Use `tool(name, { description, input, output, fulfil, view })` for a model-visible tool that renders a widget, and the same `tool(name, { ..., visibility: ["app"] })` for an app-only helper hidden from the model. A `view` is `{ component: "name", entry: "./views/name.tsx" }` — a React component the compiler bundles at validate/deploy time.
 
 ## React hook surface
 
@@ -21,9 +21,10 @@ Author views as React components. `generateHelpers<ServerDefinition>()` (from `@
 | Hook | Use for |
 | :-- | :-- |
 | `useToolInfo` | Read the invoking tool result; `structuredContent` is the widget’s typed data payload. |
-| `useCallTool` | Call a tool from the widget — returns `{ status, callTool, callToolAsync, data, structuredContent, error, reset }`; target a model-visible tool or a hidden `toolForWidget` helper. |
+| `useCallTool` | Call a tool from the widget — returns `{ status, callTool, callToolAsync, data, structuredContent, error, reset }`; target a model-visible tool or a hidden `tool` helper. |
 | `useViewState` | Persist per-widget UI state across re-renders and restores: `const [value, setValue] = useViewState("key", initial)`. |
 | `useLayout` | Read host layout: `{ theme, displayMode, locale?, host?, supports? }` (`displayMode` is `"inline"`/`"pip"`/`"fullscreen"`) — adapt styling to the host theme and mode. |
+| `useBranding` | Read the server-level brand name and themed logo/mark/avatar URLs when widget content needs identity assets; CSS tokens are applied automatically. |
 | `useRequestDisplayMode` | Request a host-mediated layout change such as fullscreen; treat it as best-effort and keep inline rendering useful. |
 | `useOpenExternal` | Open an external link through the host (never `window.open`); the target origin must be listed in the server-level `handoff.allowedDomains`. |
 | `useSendFollowUpMessage` | Send a follow-up prompt to the model from a user interaction: `send({ prompt })` — trigger only from an explicit user action. |
@@ -94,10 +95,10 @@ export default function OrderStatus() {
 
 ### 2. The tool declaration
 
-`toolWithWidget` is the model-visible tool that renders the view; pair it with `toolForWidget` helpers the view calls (hidden from the model). Wire `view: { component, entry }`, `csp`, a widget `domain`, and a real `output` schema so non-Apps hosts still receive structured data. Inside `fulfil`, `input` is a symbolic ref recorded into a flow — reference it in output/template strings, but never use it as an object key or `if` condition.
+`tool` declares both the model-visible tool that renders the view and app-only helpers the view calls. Put `visibility: ["app"]` on each helper. Wire `view: { component, entry }`, `csp`, a widget `domain`, and a real `output` schema so non-Apps hosts still receive structured data. Inside `fulfil`, `input` is a symbolic ref recorded into a flow — reference it in output/template strings, but never use it as an object key or `if` condition.
 
 ```ts
-import { annotations, server, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+import { annotations, server, tool, z } from '@noodleseed/one';
 
 const item = z.enum(['falafel_wrap', 'lentil_soup', 'mint_lemonade']).default('falafel_wrap');
 const checkoutUrl = (customer: string) =>
@@ -112,7 +113,7 @@ export default server(
     handoff: { allowedDomains: ['https://orders.example.com'] },
   },
   [
-    toolWithWidget('show_order', {
+    tool('show_order', {
       description: 'Show the pickup order and render the ordering widget.',
       // Declare tool annotations — a ChatGPT-submission requirement. A read → `readOnly()`.
       annotations: annotations.readOnly(),
@@ -129,8 +130,8 @@ export default server(
         total: 12,
         checkoutUrl: checkoutUrl(input.customer),
       }),
-      widgetTitle: 'Pickup order',
-      widgetDescription: 'Pick an item and place a pickup order.',
+      viewTitle: 'Pickup order',
+      viewDescription: 'Pick an item and place a pickup order.',
       // A ChatGPT App is this widget + a domain: one https origin per app.
       domain: 'https://pickup.example.com',
       view: { component: 'order-status', entry: './views/order-status.tsx' },
@@ -142,7 +143,8 @@ export default server(
       },
     }),
     // Widget-only helper the view calls with useCallTool('place_order'); hidden from the model.
-    toolForWidget('place_order', {
+    tool('place_order', {
+      visibility: ['app'],
       description: 'Place a pickup order from the widget.',
       // A write that reaches the outside world → `action()` (not read-only, not destructive).
       annotations: annotations.action(),