@noodleseed/agent-kit 0.16.0 → 0.18.0

package/skills/claude-code/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/claude-code/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/claude-code/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/claude-code/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');
 
@@ -17,28 +6,28 @@ const state = connector('noodle_state')
   .version('1.0.0')
   .operation('read_state', {
     type: 'read',
-    input: {
-      handle: { type: 'string', required: true },
-      key: { type: 'string' },
-    },
-    output: {
-      value: { type: 'object', required: true },
-      revision: { type: 'integer', required: true },
-      status: { type: 'string', required: true },
-    },
+    input: z.object({
+      handle: z.string(),
+      key: z.string().optional(),
+    }),
+    output: z.object({
+      value: z.record(z.string(), z.unknown()),
+      revision: z.number().int(),
+      status: z.string(),
+    }),
   })
   .operation('patch_state', {
     type: 'action',
-    input: {
-      handle: { type: 'string', required: true },
-      expectedRevision: { type: 'integer', required: true },
-      value: { type: 'object', required: true },
-    },
-    output: {
-      value: { type: 'object', required: true },
-      revision: { type: 'integer', required: true },
-      status: { type: 'string', required: true },
-    },
+    input: z.object({
+      handle: z.string(),
+      expectedRevision: z.number().int(),
+      value: z.record(z.string(), z.unknown()),
+    }),
+    output: z.object({
+      value: z.record(z.string(), z.unknown()),
+      revision: z.number().int(),
+      status: z.string(),
+    }),
   });
 
 const stores = [
@@ -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/claude-code/examples/weather/src/server.ts

@@ -19,13 +19,13 @@ const geocoding = connector('open_meteo_geocoding')
         method: 'GET',
         path: '/v1/search',
         query: ['name'],
-        input: { name: { type: 'string', required: true } },
-        output: {
-          latitude: { type: 'number', required: true },
-          longitude: { type: 'number', required: true },
-          place: { type: 'string' },
-          country: { type: 'string' },
-        },
+        input: z.object({ name: z.string() }),
+        output: z.object({
+          latitude: z.number(),
+          longitude: z.number(),
+          place: z.string().optional(),
+          country: z.string().optional(),
+        }),
         response: {
           latitude: '${response.results[0].latitude}',
           longitude: '${response.results[0].longitude}',
@@ -44,13 +44,8 @@ const geocoding = connector('open_meteo_geocoding')
         method: 'GET',
         path: '/v1/search',
         query: ['name', 'count'],
-        input: {
-          name: { type: 'string', required: true },
-          count: { type: 'number' },
-        },
-        output: {
-          results: { type: 'array' },
-        },
+        input: z.object({ name: z.string(), count: z.number().optional() }),
+        output: z.object({ results: z.array(z.unknown()).optional() }),
         response: {
           results: '${response.results}',
         },
@@ -69,15 +64,12 @@ const forecast = connector('open_meteo_forecast')
         method: 'GET',
         path: '/v1/forecast?current_weather=true',
         query: ['latitude', 'longitude'],
-        input: {
-          latitude: { type: 'number', required: true },
-          longitude: { type: 'number', required: true },
-        },
-        output: {
-          temperature: { type: 'number' },
-          windspeed: { type: 'number' },
-          weathercode: { type: 'number' },
-        },
+        input: z.object({ latitude: z.number(), longitude: z.number() }),
+        output: z.object({
+          temperature: z.number().optional(),
+          windspeed: z.number().optional(),
+          weathercode: z.number().optional(),
+        }),
         response: {
           temperature: '${response.current_weather.temperature}',
           windspeed: '${response.current_weather.windspeed}',
@@ -91,18 +83,18 @@ const brief = connector('weather_brief')
   .version('1.0.0')
   .compute('summarize', {
     type: 'read',
-    input: {
-      place: { type: 'string', required: true },
-      country: { type: 'string' },
-      temperature: { type: 'number', required: true },
-      windspeed: { type: 'number', required: true },
-      weathercode: { type: 'number', required: true },
-    },
-    output: {
-      conditions: { type: 'string', required: true },
-      headline: { type: 'string', required: true },
-      advice: { type: 'string', required: true },
-    },
+    input: z.object({
+      place: z.string(),
+      country: z.string().optional(),
+      temperature: z.number(),
+      windspeed: z.number(),
+      weathercode: z.number(),
+    }),
+    output: z.object({
+      conditions: z.string(),
+      headline: z.string(),
+      advice: z.string(),
+    }),
     // A real function — type-checked here, serialized to source and run in the sandbox. It must be
     // self-contained: no imports, no closure over outer variables, synchronous.
     run: (input) => {
@@ -162,12 +154,8 @@ const placeNarrow = connector('geo_places')
   .version('1.0.0')
   .compute('narrow', {
     type: 'read',
-    input: {
-      results: { type: 'unknown' },
-    },
-    output: {
-      places: { type: 'array', required: true },
-    },
+    input: z.object({ results: z.unknown().optional() }),
+    output: z.object({ places: z.array(z.unknown()) }),
     // Self-contained: no imports, no closure over outer variables, synchronous.
     run: (input) => {
       const raw = input.results;

package/skills/claude-code/references/authoring-workflow.md

@@ -11,6 +11,7 @@
 - Compute connector example
 - Tests
 - Secrets and variables
+- Embedded assistant
 - Boundaries
 
 ## Input paths
@@ -55,16 +56,16 @@ const crm = connector('crm').version('1.0.0').http({
       method: 'GET',
       path: '/customers',
       query: ['email'],
-      input: { email: { type: 'string', required: true } },
-      output: { id: { type: 'string', required: true }, name: { type: 'string' } },
+      input: z.object({ email: z.string() }),
+      output: z.object({ id: z.string(), name: z.string().optional() }),
       response: { id: '${response.data[0].id}', name: '${response.data[0].name}' },
     },
     create_ticket: {
       type: 'action',
       method: 'POST',
       path: '/tickets',
-      input: { customer_id: { type: 'string', required: true }, body: { type: 'string', required: true } },
-      output: { ticket_id: { type: 'string', required: true } },
+      input: z.object({ customer_id: z.string(), body: z.string() }),
+      output: z.object({ ticket_id: z.string() }),
       request: { customer_id: '${args.customer_id}', body: '${args.body}' },
       response: { ticket_id: '${response.id}' },
     },
@@ -120,16 +121,16 @@ const tasks = connector('tasks').version('1.0.0').http({
       method: 'GET',
       path: '/tasks',
       query: ['query'],
-      input: { query: { type: 'string', required: true } },
-      output: { matches: { type: 'array', required: true } },
+      input: z.object({ query: z.string() }),
+      output: z.object({ matches: z.array(z.unknown()) }),
       response: { matches: '${response.results}' },
     },
     close_task: {
       type: 'action',
       method: 'POST',
       path: '/tasks/{id}/close',
-      input: { id: { type: 'string', required: true } },
-      output: { ok: { type: 'boolean', required: true } },
+      input: z.object({ id: z.string() }),
+      output: z.object({ ok: z.boolean() }),
       response: { ok: '${response.ok}' },
     },
   },
@@ -163,8 +164,8 @@ The model never sees a task id from the user; `find_tasks` returns `{ id, title
 
 ```ts
 const scoring = connector('scoring').version('1.0.0').compute('normalize', {
-  input: { email: { type: "string", required: true }, priority: { type: "string" } },
-  output: { score: { type: "number", required: true } },
+  input: z.object({ email: z.string(), priority: z.string().optional() }),
+  output: z.object({ score: z.number() }),
   calls: { find_customer: 'crm.find_customer' },
   limits: { timeoutMs: 1000, maxHostCalls: 2 },
   run(input, { callOperation }) {
@@ -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, 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"], appearance: { brand: { name: "Acme Assistant" }, theme: { defaultMode: "auto", light: { accent: "#3157D5" }, dark: { accent: "#9FB4FF" } } } })` to the server options. 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/claude-code/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/claude-code/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/claude-code/references/connect-an-api.md

@@ -62,7 +62,7 @@ Most real tools return a variable-length list (search results, a user’s tasks)
 
 ```ts
 // The API returns { results: [ { id, name, country, … }, … ] }
-output: { places: { type: 'array' } },
+output: z.object({ places: z.array(z.unknown()) }),
 response: { places: '${response.results}' },
 ```
 
@@ -96,7 +96,7 @@ Pair the read/list with the mutations your intent tools need:
 ```ts
 close_task: {
   type: 'action', method: 'POST', path: '/tasks/{id}/close',
-  input: { id: { type: 'string', required: true } },
+  input: z.object({ id: z.string() }),
   responseType: 'empty',
 },
 ```

package/skills/claude-code/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/claude-code/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.
 
@@ -144,8 +144,8 @@ const crm = connector('crm')
         method: 'GET',
         path: '/tickets',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ subject: z.string().optional(), status: z.string().optional() }),
         response: { subject: '${response.subject}', status: '${response.status}' },
       },
     },
@@ -195,8 +195,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/orders',
         query: ['id'],
-        input: { id: { type: 'string', required: true } },
-        output: { id: { type: 'string' }, status: { type: 'string' } },
+        input: z.object({ id: z.string() }),
+        output: z.object({ id: z.string().optional(), status: z.string().optional() }),
         response: { id: '${response.id}', status: '${response.status}' },
       },
       get_tracking: {
@@ -204,8 +204,8 @@ const orders = connector('orders')
         method: 'GET',
         path: '/tracking',
         query: ['order_id'],
-        input: { order_id: { type: 'string', required: true } },
-        output: { url: { type: 'string' } },
+        input: z.object({ order_id: z.string() }),
+        output: z.object({ url: z.string().optional() }),
         response: { url: '${response.url}' },
       },
     },

package/skills/claude-code/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 |