@noodleseed/agent-kit 0.8.1 → 0.10.0

package/skills/claude-code/references/sdk-surface.md

@@ -1,39 +1,180 @@
 # @noodleseed/one SDK surface
 
-Import these from `@noodleseed/one`. They are declarative builders that emit manifest data — do not hand-author the manifest or runtime artifacts. React view helpers come from `@noodleseed/one/react` (`generateHelpers`).
+Import these from `@noodleseed/one`. They are declarative builders that emit manifest data — do not hand-author the manifest or runtime artifacts. React view helpers come from `@noodleseed/one/react` (`generateHelpers`); the hook surface is documented in `widgets-and-apps.md`.
+Platform helper connectors are explicit subpath imports from `@noodleseed/one/platform` (`noodlePlatform`, `noodlePlatformCatalog`) when an app needs first-party hosted state APIs.
 
-## Server & tools
+## Contents
+
+- Exports by area
+- Authoring signatures
+- Recipes
+
+## Exports by area
+
+### 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.
 
-## Widgets & assets
+### Widgets & assets
 
 - `widget(...)` — declare a widget/view component.
 - `asset("./path")` — reference a packaged asset (e.g. an image).
 - `annotations(...)` — tool/Apps annotation metadata.
 
-## Connectors & flows
+### Connectors & flows
 
 - `connector("id").version(...).http({...})` or `.compute(...)` — declarative data connectors.
 - `when(...)` — declarative conditions for recorded flows (no native branching on runtime values).
 
-## Resources & prompts
+### Resources & prompts
 
 - `resource(name, { ... })` — an MCP resource.
 - `prompt(name, { ... })` — an MCP prompt.
 
-## Managed config
+### Managed config
 
 - `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
 - `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
 
-## Sessions
+### Customer auth
+
+- `customerAuth.oidc(...)`, `.firebase(...)`, `.microsoft(...)`, or `.bridge(...)` — end-user/customer identity for `--access customers` deployments.
+
+### Sessions
 
 - `handoffSession(...)` — typed cross-host handoff session envelopes.
 
-## Schemas
+### Schemas
+
+- `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
+
+## 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.
+- `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.
+- `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.
+
+## Recipes
+
+Minimal, complete, compiling recipes — author in `src/server.ts`, then `noodle validate`. Inside a `fulfil`, `ctx.input` (a prompt’s arguments or a templated resource’s URI variables) and `ctx.connectors` are **symbolic**: reference them to record a flow. Recording is not execution, so never branch on their runtime values with native `if` — use `when(...)`.
+
+### Resource
+
+`resource(name, { uri, title?, description?, mimeType?, fulfil })`. `fulfil` returns `{ contents: [{ uri, mimeType, text }] }`. Use a fixed URI for a constant document, or a `{var}` template whose variable arrives on `ctx.input`.
+
+```ts
+import { resource } from '@noodleseed/one';
+
+// Fixed-URI resource: one constant document the model can read.
+resource('changelog', {
+  uri: 'docs://changelog',
+  title: 'Changelog',
+  mimeType: 'text/markdown',
+  fulfil: () => ({
+    contents: [
+      { uri: 'docs://changelog', mimeType: 'text/markdown', text: 'Changelog: 1.0.0 first release' },
+    ],
+  }),
+});
+
+// {var} URI-template resource: the URI variable arrives on ctx.input (a symbolic ref).
+resource('ticket', {
+  uri: 'tickets://{id}',
+  title: 'Support ticket',
+  mimeType: 'text/markdown',
+  fulfil: (ctx) => ({
+    contents: [
+      { uri: `tickets://${ctx.input.id}`, mimeType: 'text/markdown', text: `Ticket ${ctx.input.id}` },
+    ],
+  }),
+});
+```
+
+### Prompt
+
+`prompt(name, { title?, description?, arguments?, fulfil })`. `arguments` is a Zod object (each key becomes a `prompts/list` descriptor) or an explicit `[{ name, description?, required? }]` list. `fulfil` returns `{ messages: [{ role, content: { type: 'text', text } }] }`; supplied argument values arrive on `ctx.input`.
+
+```ts
+import { prompt, z } from '@noodleseed/one';
+
+prompt('summarize_ticket', {
+  title: 'Summarize ticket',
+  description: 'Draft a short summary of a support ticket.',
+  // A Zod object: each key becomes a prompts/list descriptor (or pass [{ name, description?, required? }]).
+  arguments: z.object({
+    ticket_id: z.string().describe('Ticket to summarize'),
+    tone: z.enum(['concise', 'detailed']).default('concise'),
+  }),
+  // Argument values arrive on ctx.input; return the prompts/get messages shape.
+  fulfil: (ctx) => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Summarize ticket ${ctx.input.ticket_id} in a ${ctx.input.tone} tone.`,
+        },
+      },
+    ],
+  }),
+});
+```
+
+### Non-trivial tool: ctx connectors, annotations, visibility, async
+
+`ctx` is `{ input, user, connectors }`. Bind connectors with `use` on the server, then call one inside `fulfil` to record a step. `annotations.readOnly()` / `annotations.action()` set the tool hints; `visibility` defaults to `['model', 'app']` — set `['app']` to hide a helper from the model. `fulfil` may be `async` (the compiler awaits it while recording).
+
+```ts
+import { annotations, connector, server, tool, z } from '@noodleseed/one';
+
+// A tool-facing HTTP connector, bound to the server via `use`, reachable as ctx.connectors.crm.
+const crm = connector('crm')
+  .version('1.0.0')
+  .http({
+    baseUrl: 'https://crm.example.com',
+    allowedOrigins: ['https://crm.example.com'],
+    operations: {
+      get_ticket: {
+        type: 'read',
+        method: 'GET',
+        path: '/tickets',
+        query: ['id'],
+        input: { id: { type: 'string', required: true } },
+        output: { subject: { type: 'string' }, status: { type: 'string' } },
+        response: { subject: '${response.subject}', status: '${response.status}' },
+      },
+    },
+  });
 
-- `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
+export default server('support', { title: 'Support', version: '1.0.0', use: { crm } }, [
+  tool('get_ticket', {
+    description: 'Fetch a support ticket by id.',
+    input: z.object({ id: z.string() }),
+    output: z.object({ subject: z.string(), status: z.string() }),
+    annotations: annotations.readOnly(), // read-only hint for hosts
+    visibility: ['model', 'app'], // default; use ['app'] to hide the tool from the model
+    // ctx is { input, user, connectors }. A connector call records one flow step (a Ref) —
+    // recording is not execution, so never branch on the result with native if (use when).
+    fulfil: ({ input, connectors }) => {
+      const found = connectors.crm.get_ticket({ id: input.id });
+      return { subject: found.subject, status: found.status };
+    },
+  }),
+  tool('echo', {
+    description: 'Echo text back.',
+    input: z.object({ text: z.string() }),
+    output: z.object({ echo: z.string() }),
+    annotations: annotations.action(), // mutating / world-affecting hint
+    // fulfil may be async — the compiler awaits it while recording the flow.
+    fulfil: async ({ input }) => ({ echo: input.text }),
+  }),
+]);
+```

package/skills/claude-code/references/test-in-hosts.md

@@ -0,0 +1,39 @@
+# Test in real hosts
+
+Local `noodle dev` and `noodle devtools` prove the server works; the widget experience is only proven inside a real host. `noodle connect <client>` prints the exact setup flow per host.
+
+## Contents
+
+- Local inspection first
+- Agent hosts (Claude Code, Codex, editors)
+- ChatGPT (developer mode)
+- Claude
+- Public URL for a local server
+- What to verify
+
+## Local inspection first
+
+Run `noodle dev` and inspect the loopback endpoint with MCP Inspector: `noodle connect inspector` prints the flow (`npx @modelcontextprotocol/inspector <printed endpoint>`). Preview widget metadata and rendering with `noodle devtools`.
+
+## Agent hosts (Claude Code, Codex, editors)
+
+`noodle connect claude-code` / `noodle connect codex` (add `--write` for project-local setup). For other editors (`cursor`, `vscode`, `gemini`), `noodle connect <client>` prints the setup steps, and `noodle docs export --format llms` produces portable context. With a deployed endpoint, `noodle connect <client> --endpoint <url>` prints the MCP client registration config.
+
+## ChatGPT (developer mode)
+
+1. Deploy: `noodle deploy`, then `noodle open --print` for the hosted MCP URL (ChatGPT needs a public HTTPS endpoint, not loopback).
+2. In ChatGPT: Settings → Connectors → enable Developer mode → add the endpoint (`noodle connect chatgpt` prints these steps).
+3. Toggle the connector on in a new conversation and sign in when prompted; testers outside your org need a wider access mode (`noodle access set`).
+4. Test on mobile too — invoke the same connector from the ChatGPT iOS/Android apps to check widget layout.
+
+## Claude
+
+`noodle connect claude` prints the flow: deploy, then add the hosted MCP URL as a custom connector in Claude settings and sign in when prompted. Widgets render in Apps-capable Claude surfaces; elsewhere the tool’s text/structured result is shown.
+
+## Public URL for a local server
+
+To try an undeployed server in a host that requires a public URL, `noodle dev --tunnel` publishes a temporary public URL for the loopback endpoint (requires the external `cloudflared` binary on PATH). Treat it as a short-lived test URL — deploy for anything shared.
+
+## What to verify
+
+Run a golden prompt set — direct (“use <tool> to…”), indirect (a natural request the model should route), and negative (requests that must not trigger the tool). Confirm the model picks the right tool with the right arguments, the widget renders and its actions work, external links open, and the experience degrades to readable text where Apps are unsupported. Symptoms → `references/troubleshooting.md`.

package/skills/claude-code/references/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting in hosts
+
+## Contents
+
+- First moves
+- Symptom map
+
+## First moves
+
+Re-run the local gates before debugging in-host: `noodle validate`, `noodle check` (add `--target chatgpt` for ChatGPT-specific requirements), and `noodle doctor`. Confirm the CLI is current with `noodle update --check` and that the project-local skill is intact with `noodle agents doctor --json` — host metadata requirements evolve and fixes ship in the CLI/agent-kit. Never paste tokens, secrets, or `.env.noodle` values into prompts or logs while debugging.
+
+For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `noodle` subcommand. Use it against a local `noodle dev` URL without an access token, or against hosted URLs through the host/OAuth flow printed by `noodle connect`.
+
+## Symptom map
+
+| Symptom | Likely cause | Fix |
+| :-- | :-- | :-- |
+| Images, fonts, or styles don’t load inside the widget | The host sandbox silently blocks origins not declared in the widget CSP | Add every asset origin to `csp: { resourceDomains: [...] }` (fetch/XHR origins go in `connectDomains`, embedded iframes in `frameDomains`), then re-run `noodle check --target chatgpt` |
+| 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 |
+| 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` |
+| `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 |
+| Need to invoke a deployed tool from the terminal | The `noodle` CLI is not a general MCP client and has no `call` verb | Use `noodle test` for the local smoke, `noodle tools`/`resources`/`prompts` for local listing, MCP Inspector, or `npx @mcpjam/cli@latest tools call --url <url> ...` for headless MCP probing |
+| One customer/session reports a bad answer or protocol error | The failure may be a model/tool error, host protocol error, or connector/runtime error | Run `noodle metrics --agent-output`, then `noodle events --tool <name> --status tool_error --json`; copy the `sessionId` into `noodle events --session <id> --json`, then match timestamps with `noodle logs` |

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

@@ -3,35 +3,206 @@
 ## Contents
 
 - Tools and views
-- React authoring
-- CSP and permissions
-- Host bridge
+- React hook surface
+- 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" }`.
+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 authoring
+## React hook surface
 
-Author views as React components. Get typed helpers from `@noodleseed/one/react`:
+Author views as React components. `generateHelpers<ServerDefinition>()` (from `@noodleseed/one/react`) returns the typed host hooks:
 
-```ts
+| 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. |
+| `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`.
+
+```tsx
+import type { ServerDefinition } from '@noodleseed/one';
 import { generateHelpers } from '@noodleseed/one/react';
-const { useCallTool, useLayout, useToolInfo, useViewState } = generateHelpers<AppType>();
+
+// 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>
+  );
+}
 ```
 
-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>`).
+### 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.
+
+```ts
+import { annotations, server, toolForWidget, toolWithWidget, z } from '@noodleseed/one';
 
-## CSP, domain, and permissions
+const item = z.enum(['falafel_wrap', 'lentil_soup', 'mint_lemonade']).default('falafel_wrap');
+const checkoutUrl = (customer: string) =>
+  `https://orders.example.com/pickup?customer=${customer}`;
 
-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.
+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),
+      }),
+    }),
+  ],
+);
+```
+
+## ChatGPT App = this widget + a domain
+
+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:
+
+- `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.
+
+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.
+
+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.8.1
-hash: f297c7e0fa62058d
+version: 0.10.0
+hash: 7cae1fbf5bdf6a0d
 ---
 
 # Noodle Seed
@@ -13,22 +13,32 @@ 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`).
+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.
-- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the validate→test→dev repair loop, connectors, and secrets/variables.
-- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, and CSP.
+- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the fit check, the validate→test→dev repair loop, connectors, and secrets/variables.
+- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, the widget hook surface, output shaping, and CSP.
+- `references/test-in-hosts.md` — connect and test in ChatGPT (developer mode), Claude, agent hosts, and MCP Inspector.
+- `references/troubleshooting.md` — runtime symptom → cause → fix, in-host and hosted.
 - `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
+- `references/publishing.md` — submit to the ChatGPT apps directory and Claude connectors directory.
 - `references/examples.md` — flagship example index and a canonical `server.ts`.
 
 ## Safety

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`.