@noodleseed/agent-kit 0.9.0 → 0.10.0

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

@@ -3,60 +3,206 @@
 ## Contents
 
 - Tools and views
-- React authoring
 - React hook surface
-- Shaping tool output for widgets
-- Widget state and model context
-- CSP, domain, and permissions
-- Host bridge
+- Worked widget recipe
+- ChatGPT App = this widget + a domain
+- Knowledge/source apps (search + fetch)
+- Permissions and host bridge
 - Readiness and boundaries
 
 ## 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" }`.
-
-## React authoring
-
-Author views as React components. Get typed helpers from `@noodleseed/one/react`:
-
-```ts
-import { generateHelpers } from '@noodleseed/one/react';
-const { useToolInfo, useCallTool, useViewState, useLayout, useOpenExternal, useSendFollowUpMessage } =
-  generateHelpers<AppType>();
-```
-
-Bind interactive elements to tools (`useCallTool("place_order")`) and annotate model-facing context with `data-llm`. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
+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.
 
 ## React hook surface
 
+Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
+
 | 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 `{ callTool, data, error, isPending }`; 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 `toolForWidget` 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? }` (`theme` is `"light"`/`"dark"`, `displayMode` is `"inline"`/`"fullscreen"`) — adapt styling to the host theme and mode. |
 | `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. |
+| `useAppFlow` | Manage named widget views with persisted params and back-stack state: `const flow = useAppFlow({ initialView, views })`. |
+| `useHandoff` | Open server-created HTTP(S) handoff URLs through the host with status/error state; domain policy still comes from `handoff.allowedDomains`. |
+
+Bind interactive elements to tools (`useCallTool("place_order")`), drive named views with `useAppFlow(...)`, open server-created handoffs with `useHandoff()`, and annotate model-facing context with `data-llm`. Use `createViewStore("key", initial)` for multi-component widget state such as carts, filters, or drafts. Use the domain-neutral React components from `@noodleseed/one/react` (`AppShell`, `ShellNav`, `ViewStack`, `AsyncBoundary`, `ActionBar`, `Field`, `QuantityStepper`, `ChoiceGroup`, `HandoffButton`, and related state components) for rich apps before inventing local shell/control scaffolding. Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()`, `useHandoff()`, and `useSendFollowUpMessage()` only from explicit user actions. A raw `html` escape hatch exists for self-contained widgets (declarative `data-bind`/`data-action`; no inline `<script>`).
+
+## Worked widget recipe
+
+Minimal, complete, and compile-verified — `noodle validate` bundles the view and `noodle check --target chatgpt` audits it. Author two files: the view (`src/views/order-status.tsx`) and the tool declaration (`src/server.ts`).
+
+### 1. The view component
+
+Author React. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks: read the tool result with `useToolInfo`, call a widget-only helper with `useCallTool`, keep local UI state that survives re-render with `useViewState`, open an allowlisted link with `useOpenExternal`, and mirror model-facing context back to the model as text with `data-llm`.
 
-Adapt to the host with `useLayout()` — style for both `theme` values, and keep the inline `displayMode` compact (content fits the space; no internal scrolling). Trigger `useOpenExternal()` and `useSendFollowUpMessage()` only from explicit user actions.
+```tsx
+import type { ServerDefinition } from '@noodleseed/one';
+import { generateHelpers } from '@noodleseed/one/react';
+
+// One call wires the typed host bridge; destructure only the hooks this view uses.
+const { useToolInfo, useCallTool, useViewState, useOpenExternal } =
+  generateHelpers<ServerDefinition>();
+
+type OrderResult = {
+  readonly customer?: string;
+  readonly item?: string;
+  readonly total?: number;
+  readonly checkoutUrl?: string;
+};
+
+export default function OrderStatus() {
+  const shown = useToolInfo('show_order').structuredContent as OrderResult | undefined;
+  const placeOrder = useCallTool('place_order'); // calls the widget-only helper tool
+  const openExternal = useOpenExternal();
+  const [item, setItem] = useViewState('item', shown?.item ?? 'falafel_wrap'); // survives re-render
+  const confirmed = placeOrder.data?.structuredContent as { readonly status?: string } | undefined;
+  const total = shown?.total ?? 0;
+  const checkoutUrl = shown?.checkoutUrl ?? '';
+
+  return (
+    // data-llm mirrors the visible state back to the model as text context.
+    <main data-llm={`Pickup order for ${shown?.customer ?? 'Guest'}: ${item}, total ${total}`}>
+      <h1>Pickup order</h1>
+      <label>
+        Item
+        <select value={item} onChange={(event) => setItem(event.currentTarget.value)}>
+          <option value="falafel_wrap">Falafel Wrap</option>
+          <option value="lentil_soup">Lentil Soup</option>
+          <option value="mint_lemonade">Mint Lemonade</option>
+        </select>
+      </label>
+      <button
+        type="button"
+        disabled={placeOrder.isPending}
+        onClick={() => placeOrder.callTool({ customer: shown?.customer ?? 'Guest', item })}
+      >
+        {placeOrder.isPending ? 'Placing…' : 'Place order'}
+      </button>
+      <p>{confirmed?.status ?? `Total: $${total}`}</p>
+      <button type="button" onClick={() => openExternal(checkoutUrl)}>
+        Continue checkout
+      </button>
+    </main>
+  );
+}
+```
+
+### 2. The tool declaration
 
-## Shaping tool output for widgets
+`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.
+
+```ts
+import { annotations, server, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
+
+const item = z.enum(['falafel_wrap', 'lentil_soup', 'mint_lemonade']).default('falafel_wrap');
+const checkoutUrl = (customer: string) =>
+  `https://orders.example.com/pickup?customer=${customer}`;
+
+export default server(
+  'pickup',
+  {
+    title: 'Pickup',
+    version: '1.0.0',
+    // External-link targets the widget opens; the compiler derives ChatGPT redirect_domains from this.
+    handoff: { allowedDomains: ['https://orders.example.com'] },
+  },
+  [
+    toolWithWidget('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(),
+      input: z.object({ customer: z.string().default('Guest') }),
+      output: z.object({
+        customer: z.string(),
+        item: z.string(),
+        total: z.number(),
+        checkoutUrl: z.string(),
+      }),
+      fulfil: ({ input }) => ({
+        customer: input.customer,
+        item: 'falafel_wrap',
+        total: 12,
+        checkoutUrl: checkoutUrl(input.customer),
+      }),
+      widgetTitle: 'Pickup order',
+      widgetDescription: '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' },
+      csp: {
+        connectDomains: ['https://orders.example.com'],
+        resourceDomains: ['https://example.com'],
+        // Keep CSP origins exact and minimal. Add `frameDomains` ONLY if the widget embeds an
+        // iframe — it relaxes subframe rendering and triggers stricter ChatGPT review.
+      },
+    }),
+    // Widget-only helper the view calls with useCallTool('place_order'); hidden from the model.
+    toolForWidget('place_order', {
+      description: 'Place a pickup order from the widget.',
+      // A write that reaches the outside world → `action()` (not read-only, not destructive).
+      annotations: annotations.action(),
+      input: z.object({ customer: z.string().default('Guest'), item }),
+      output: z.object({ status: z.string(), item: z.string(), checkoutUrl: z.string() }),
+      fulfil: ({ input }) => ({
+        status: `Order placed for ${input.customer}.`,
+        item: input.item,
+        checkoutUrl: checkoutUrl(input.customer),
+      }),
+    }),
+  ],
+);
+```
 
-The widget reads the tool result’s `structuredContent`, typed by the tool’s `output` schema — arrays and nested objects are fully supported, so model the data naturally (`z.array(z.object({ ... }))`) instead of flattening. Keep the result’s `content` useful on its own: hosts without MCP Apps support show only the text/structured result, so the tool must degrade gracefully.
+## ChatGPT App = this widget + a domain
 
-## Widget state and model context
+A "ChatGPT App" is not a separate authoring surface — it is exactly this MCP Apps widget rendered by the ChatGPT host. From the same declaration you author three things:
 
-Persist UI state (selections, drafts, pagination) with `useViewState("key", initial)` — it survives re-renders and conversation restores. For durable, caller-scoped state handles with optimistic revisions, follow the `stateful-draft` example. Mark the DOM the model should see with `data-llm` attributes; everything else stays widget-only.
+- `domain` on the widget — one https origin per app (required for app-store submission, optional for dev-mode testing).
+- `csp: { connectDomains, resourceDomains }` — the exact network/resource origins the widget may reach; keep them minimal. Add `frameDomains` only if the widget embeds an iframe (it relaxes subframe rendering and draws stricter review).
+- server `handoff.allowedDomains` — the external-link targets `useOpenExternal()` opens.
 
-## CSP, domain, and permissions
+The compiler emits the rest automatically: the `openai/*` metadata (`openai/outputTemplate`, `openai/widgetCSP`, `openai/widgetDescription`) and ChatGPT’s `redirect_domains` (derived from `handoff.allowedDomains`). `window.openai` and Claude’s ext-apps bridge are auto-detected at startup, so the same widget renders in both Claude and ChatGPT with no host-specific code.
 
-Declare network/host needs explicitly: `csp: { connectDomains, resourceDomains, frameDomains }` and `permissions` (e.g. `clipboardWrite`). Secrets are never injected into widgets; tool output is redacted before widget delivery.
+Verify it in the loop: `noodle check --target chatgpt --json` returning `ok:true` means the widget is **metadata-ready** for ChatGPT’s checks (`domain`, `openai/outputTemplate`, CSP present) — it does NOT prove host rendering, conversation UX, or submission acceptance. Fix any `severity:"error"` finding by its `fix`, then re-check. Validate real rendering in ChatGPT Developer Mode / MCP Inspector as a higher level before submitting.
+
+**Every tool needs annotations** (`annotations.readOnly()` / `.action()` / `.openAction()`) — missing or wrong `readOnlyHint`/`openWorldHint`/`destructiveHint` is a common submission rejection. **App-store submission is more than building**: a public https endpoint, exact CSP, org verification, app info, screenshots, and test prompts are required — follow OpenAI’s Apps submission guidelines; `noodle check --target chatgpt` covers only the metadata prerequisites.
+
+## Knowledge/source apps (ChatGPT): search + fetch
+
+If the app is a read-only knowledge/source connector (docs, wiki, CRM lookups) meant for ChatGPT company-knowledge, implement exactly two tools — `search` and `fetch`, both read-only. ChatGPT only surfaces knowledge apps that match these signatures:
+
+```ts
+import { annotations, server, tool, z } from '@noodleseed/one';
+
+export default server('kb', { title: 'Knowledge base', version: '1.0.0' }, [
+  tool('search', {
+    description: 'Search the knowledge base; return citable results.',
+    annotations: annotations.readOnly(),
+    input: z.object({ query: z.string() }),
+    output: z.object({
+      results: z.array(z.object({ id: z.string(), title: z.string(), url: z.string() })),
+    }),
+    fulfil: ({ input }) => ({ results: [{ id: 'doc-1', title: `Match: ${input.query}`, url: 'https://example.com/doc-1' }] }),
+  }),
+  tool('fetch', {
+    description: 'Fetch one document by id for citation.',
+    annotations: annotations.readOnly(),
+    input: z.object({ id: z.string() }),
+    output: z.object({ id: z.string(), title: z.string(), text: z.string(), url: z.string() }),
+    fulfil: ({ input }) => ({ id: input.id, title: 'Doc', text: 'Full document text…', url: 'https://example.com/doc-1' }),
+  }),
+]);
+```
 
-For ChatGPT: set `domain` on each widget (one https origin per app; required for app-store submission, optional for dev-mode testing), and declare external-link targets in the server-level `handoff.allowedDomains` — the compiler derives ChatGPT’s `redirect_domains` from it so `useOpenExternal()` links open without the safe-link warning. `noodle check --target chatgpt` verifies all of this.
+`search` → `{ results: [{ id, title, url }] }`; `fetch` → `{ id, title, text, url, metadata? }`. `url` must be an absolute, user-openable https link for citation.
 
-## Host bridge
+## Permissions and host bridge
 
-One runtime targets both Claude’s ext-apps bridge and ChatGPT’s `window.openai`, detected at startup. Tool results still carry useful `content`/`structuredContent` so non-Apps hosts degrade gracefully.
+Declare extra host capabilities with `permissions` (e.g. `permissions: { clipboardWrite: {} }`). Secrets are never injected into widgets and tool output is redacted before widget delivery. Tool results still carry useful `content`/`structuredContent`, so non-Apps hosts degrade gracefully.
 
 ## Readiness and boundaries
 

package/skills/codex/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: noodle-seed
 description: Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI.
-version: 0.9.0
-hash: 097c37f2e7a3e482
+version: 0.10.0
+hash: 7cae1fbf5bdf6a0d
 ---
 
 # Noodle Seed
@@ -13,17 +13,23 @@ Use this skill for local Noodle Seed project work in Codex.
 
 ## Golden path
 
-1. `noodle validate` — author-time compile/schema/connector check. On failure, fix the cited errors (see `references/compile-errors.md`) and re-validate; do not freeform re-edit.
-2. `noodle test` — local compile plus a loopback MCP smoke.
-3. `noodle dev` — local loopback runtime that serves and hot-reloads the manifest.
-4. `noodle check` / `noodle devtools` — MCP Apps/widget readiness and preview (see `references/widgets-and-apps.md`).
-5. `noodle deploy` after `noodle login` + `noodle link` (see `references/deploy-and-ops.md`).
-6. Prove it in a real host — `noodle connect <client>` (see `references/test-in-hosts.md`); debug symptoms with `references/troubleshooting.md`.
+This CLI is agent-native: the cold-agent-path commands speak the `--json` envelope (hosted admin/ops commands are still being normalized). Drive the loop by parsing machine state, not human prose. The full envelope, exit codes, and output modes are in `references/agent-contract.md`.
+
+1. **Discover** — `noodle commands --json`: every command, subcommand, flag, and exit code (don't read source).
+2. **Author** — edit `src/server.ts` (the configured entrypoint); follow the capability recipe in `references/sdk-surface.md` and `references/examples.md`.
+3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
+4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
+5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
+6. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
+7. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
+8. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
+9. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
 
 ## References
 
 Load these on demand:
 
+- `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.
 - `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.

package/skills/codex/references/agent-contract.md

@@ -0,0 +1,43 @@
+# Agent contract: --json, exit codes, output modes
+
+The cold-agent-path commands (`init`, `validate`, `test`, `check`, `tools`/`resources`/`prompts`, `deploy`, `metrics`, `events`, `agents`) are agent-native and return the envelope below; hosted admin/ops commands (`status`, `inspect`, `smoke`, `logs`, `update`) are still being normalized. Decide what to do next by parsing machine state — do not scrape human prose.
+
+## Contents
+
+- Response envelope
+- Exit codes
+- Output modes
+- Repair loop
+
+## Response envelope
+
+A `--json` command returns exactly one JSON object:
+
+- **Success**: `{ ok: true, data, warnings? }` — `data` is the command payload; `warnings?` is an optional array of non-fatal notes.
+- **Failure**: `{ ok: false, error: { code, message, cause?, fix, next, requestId? } }` — `code` is the stable machine code to branch on, `message` is human text, `cause?` is the underlying error, `fix` states the correction, `next` names the command to run next, `requestId?` correlates a hosted call.
+- **Field errors** carry a dotted `path`: multi-error commands (e.g. `noodle validate`) nest them under `error.errors[]`, each `{ code, path, message }`. The top-level `error` still carries `code`/`message`/`fix`/`next`; the per-field `path`s live in `error.errors[]`.
+- **Repair prose is isolated**: ready-to-apply repair text appears only under `error.fixPrompt` (surfaced by `--fix-prompt`), never mixed into `message` or `data`.
+
+## Exit codes
+
+Branch on the process exit code before parsing the body:
+
+| Code | Meaning |
+| :-- | :-- |
+| `0` | ok |
+| `1` | failure (command ran, the work failed) |
+| `2` | usage (bad flags or arguments) |
+| `3` | auth (login or permission required) |
+| `4` | unreachable (service or network) |
+| `5` | mcp/tool-call error (a `tools`/`resources`/`prompts`/`test` smoke call failed) |
+
+## Output modes
+
+Two kinds of output — never mix them:
+
+- `--json` — **machine state**: the envelope above. Use it to decide what to do next.
+- `--fix-prompt` / `--agent-output` (aliases) — **agent-readable text**, not the envelope: a ready-to-apply repair prompt for authoring commands (`validate`/`test`/`check`), or an operational `health` verdict (`ok`/`attention`) with `attention[]` next-commands for ops commands (`metrics`/`doctor`/`alerts`). Use it to author a fix or judge a running deployment.
+
+## Repair loop
+
+On a `validate` failure: parse `error.code` + `path`, fix exactly that field in `src/server.ts`, then re-run `noodle validate --json`. Never freeform re-edit. Repeat until `ok: true`, then `noodle test --json`.

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

@@ -7,6 +7,7 @@
 - Repair loop
 - Connectors
 - HTTP connector example
+- Worked example (full server)
 - Compute connector example
 - Tests
 - Secrets and variables
@@ -39,6 +40,8 @@ HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_T
 
 ## HTTP connector example
 
+The operation mapping in detail: `request` templates the outbound call, `response` maps the HTTP body into your typed `output`.
+
 ```ts
 import { connector, secret, variable } from '@noodleseed/one';
 
@@ -71,6 +74,46 @@ const crm = connector('crm').version('1.0.0').http({
 
 Use `${args.field}` for tool/operation inputs and `${response.body.path}` for response mapping. Prefer explicit `allowedOrigins`; OAuth token/session URLs must also be on an allowed origin. For client credentials use `{ kind: "oauth2ClientCredentials", tokenUrl, clientId, clientSecret, scopes? }`; for per-customer downstream calls use `delegatedOAuth` or `delegatedSessionCookie` with a matching `customerAuth` server option.
 
+## Worked example (full server)
+
+Declare the API as data, bind it with `use`, then record a call in a tool. `auth` reads a managed `secret(...)` — never inline a key. Map the HTTP body into your typed `output` with `${response...}`.
+
+```ts
+import { connector, secret, server, tool, z } from '@noodleseed/one';
+
+const crm = connector('acme_crm')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://api.acme.example',
+    allowedOrigins: ['https://api.acme.example'],
+    auth: { kind: 'apiKey', header: 'X-Api-Key', secret: secret('ACME_CRM_TOKEN') },
+    operations: {
+      get_ticket: {
+        type: 'read',
+        method: 'GET',
+        path: '/v1/tickets/{id}',
+        input: { id: { type: 'string', required: true } },
+        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        response: { subject: '${response.data.subject}', status: '${response.data.state}' },
+      },
+    },
+  });
+
+export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
+  tool('ticket_status', {
+    description: 'Look up a support ticket by id.',
+    input: z.object({ ticket_id: z.string() }),
+    output: z.object({ subject: z.string(), status: z.string() }),
+    fulfil: ({ input, connectors }) => {
+      const ticket = connectors.crm.get_ticket({ id: input.ticket_id });
+      return { subject: ticket.subject, status: ticket.status };
+    },
+  }),
+]);
+```
+
+More: `auth.kind` is `bearer` | `apiKey` (needs `header`) | `oauth2ClientCredentials` | `delegatedOAuth` | `delegatedSessionCookie`. Use `.compute(name, { input, output, run })` for a sandboxed transform; `provides:` (instead of `use:`) exposes a connector only to compute `callOperation`; and `noodle import openapi <file>` generates a connector from an OpenAPI spec.
+
 ## Compute connector example
 
 ```ts

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

@@ -3,39 +3,11 @@
 ## Contents
 
 - The repair loop
-- JSON shape
-- Fix prompt
 - Error codes
 
 ## The repair loop
 
-Run `noodle validate` (add `--json` for machine-readable output, `--fix-prompt` for an agent repair prompt). Each error carries a `code`, a dotted `path` to the offending field, and a `message`; many also carry `expected`/`got`, `didYouMean`/`suggestions`, and a `docAnchor`. Fix the specific error the `path` locates, then re-validate. Do not freeform re-edit. Once `noodle validate` passes, run `noodle test`, then `noodle dev`.
-
-## JSON shape
-
-Use `noodle validate --json` in automated repair loops. Treat `errors[]` as the work queue and change only the cited file/path before re-running validation.
-
-```json
-{
-  "ok": false,
-  "errors": [
-    {
-      "code": "unknown_operation",
-      "path": "tools.search.fulfil.steps.0.operation",
-      "message": "Unknown connector operation.",
-      "expected": "operation declared on connector alias `crm`",
-      "got": "crm.find_customer",
-      "didYouMean": "crm.findCustomer",
-      "suggestions": ["crm.findCustomer"],
-      "docAnchor": "connectors.operations"
-    }
-  ]
-}
-```
-
-## Fix prompt
-
-`noodle validate --fix-prompt` prints a compact agent repair prompt with the same structured errors. Use it when delegating a repair pass, but still inspect the resulting code and re-run `noodle validate --json`.
+Run `noodle validate` (add `--json` for the machine-readable envelope, `--fix-prompt` for an agent repair prompt). On failure the envelope is `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}`: each entry in `error.errors[]` carries a `code`, a dotted `path` to the offending field, and a `message`; many also carry `expected`/`got`, `didYouMean`/`suggestions`, and a `docAnchor` (the full envelope is in `agent-contract.md`). Fix the specific error the `path` locates, then re-validate. Do not freeform re-edit. Once `noodle validate` passes, run `noodle test`, then `noodle dev`.
 
 ## Error codes
 

package/skills/codex/references/deploy-and-ops.md

@@ -5,10 +5,12 @@
 - Authenticate
 - Link and target
 - Deploy and inspect
+- Connect into a host
 - Access modes
 - Org and members
 - Config and observability
 - Agent-safe CLI recipes
+- Analytics
 
 ## Authenticate
 
@@ -22,6 +24,24 @@
 
 `noodle deploy` deploys the server. Then `noodle open` (latest URL), `noodle status`, `noodle inspect` (metadata, no secrets), `noodle smoke` (readiness diagnostics), and `noodle rollback <deploymentId>` to revert.
 
+## Connect into a host
+
+Once deployed, register the server as a tool in a host with `noodle connect <host>` (`claude-code`, `codex`, `chatgpt`, `cursor`, `vscode`, `claude`, `inspector`) — it prints the exact config to paste.
+
+- **Claude Code / Claude Desktop** (verified) — add the `mcpServers` block, or one-shot `claude mcp add-json noodle-server '<json>'`:
+
+```json
+{
+  "mcpServers": {
+    "noodle-server": { "type": "https", "url": "https://<app>.mcp.noodleseed.dev" }
+  }
+}
+```
+
+- **Codex / Cursor / VS Code** — the same `mcpServers` block is emitted as a starting point (these hosts' config formats are not officially documented). Wiring a deployed Noodle server into Codex means registering that block in Codex's MCP config.
+- **ChatGPT / Claude.ai** — no config file: open the host's Settings → Connectors → Add custom connector, paste the MCP URL, then authenticate.
+- `noodle connect codex|claude-code --write` writes the project-local agent files (only these two targets).
+
 ## Access modes
 
 `noodle access set owner-only|org-members|authenticated|customers` controls who can call the deployed server. Hosted access is identity-based; never add static data-plane keys.

package/skills/codex/references/examples.md

@@ -6,7 +6,7 @@ Flagship examples (one per capability). Read the matching example for the patter
 | :-- | :-- |
 | `hello` | Minimal TypeScript quickstart — a single tool, no connectors/widgets. |
 | `weather` | HTTP connectors, multi-step flows, and the sandboxed compute connector. |
-| `restaurant-pickup` | MCP Apps widgets, React `view` authoring, assets, branding, and handoff. |
+| `food-ordering` | Consumer ordering MCP App widgets, app-only helpers, cart state, assets, branding, and handoff. |
 | `customer-auth` | End-user (customer) auth via OIDC/Firebase bridge with delegated credentials. |
 | `stateful-draft` | Durable, caller-scoped widget state handles with optimistic revisions. |
 | `perplexity` | A real SaaS API with bearer auth and a managed `secret`. |