@noodleseed/agent-kit 0.8.1 → 0.10.0

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

@@ -3,8 +3,13 @@
 ## Contents
 
 - Input paths
+- Fit check
 - Repair loop
 - Connectors
+- HTTP connector example
+- Worked example (full server)
+- Compute connector example
+- Tests
 - Secrets and variables
 - Boundaries
 
@@ -14,6 +19,10 @@
 2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
 3. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
 
+## Fit check
+
+Before building, confirm the idea fits a conversational surface: 1–3 focused actions where saying it beats clicking, plus data or actions the model lacks on its own. Poor fits — long-form or static content, dashboards, deep multi-step navigation, or a full app port. When an idea does not fit, narrow the scope to the actions that do.
+
 ## Repair loop
 
 Author in `server.ts`, then `noodle validate` → fix cited errors (see `compile-errors.md`) → re-validate → `noodle test` → `noodle dev`. Keep the loop tight and error-driven.
@@ -27,6 +36,118 @@ Declare connectors as data, not imperative code:
 
 Tools record connector calls into a flow; recording is not execution. Do not branch on runtime outputs with native `if` — use declarative `when(...)` conditions.
 
+HTTP connector auth variants: `bearer` (`{ kind: "bearer", secret: secret("API_TOKEN") }`), `apiKey` (`{ kind: "apiKey", header: "X-API-Key", secret: secret("API_KEY") }`), `oauth2ClientCredentials`, `delegatedOAuth`, and `delegatedSessionCookie`. Use managed `secret(...)` / `variable(...)` refs for all values that differ by org/app/env.
+
+## 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';
+
+const crm = connector('crm').version('1.0.0').http({
+  baseUrl: variable('CRM_BASE_URL'),
+  allowedOrigins: [variable('CRM_BASE_URL')],
+  auth: { kind: 'bearer', secret: secret('CRM_TOKEN') },
+  operations: {
+    findCustomer: {
+      type: 'read',
+      input: { email: { type: "string", required: true } },
+      output: { id: { type: "string", required: true }, name: { type: "string" } },
+      method: "GET",
+      path: "/customers",
+      request: { query: { email: "${args.email}" } },
+      response: { id: "${response.body.data.0.id}", name: "${response.body.data.0.name}" },
+    },
+    createTicket: {
+      type: 'action',
+      input: { customerId: { type: "string", required: true }, body: { type: "string", required: true } },
+      output: { ticketId: { type: "string", required: true } },
+      method: "POST",
+      path: "/tickets",
+      request: { body: { customer_id: "${args.customerId}", body: "${args.body}" } },
+      response: { ticketId: "${response.body.id}" },
+    },
+  },
+});
+```
+
+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
+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 } },
+  calls: { findCustomer: 'crm.findCustomer' },
+  limits: { timeoutMs: 1000, maxHostCalls: 2 },
+  run(input, { callOperation }) {
+    const customer = callOperation("findCustomer", { email: input.email }) as { id?: string };
+    return { score: customer.id && input.priority === "high" ? 100 : 50 };
+  },
+});
+```
+
+Compute `run` functions are serialized and sandboxed: no imports, no closure capture, no `fetch`, no `process`. Any backing-system call must be declared in `calls` and invoked through `callOperation`. For conditional flow edges, use `when(...)` in recorded fulfilment instead of native branching on connector outputs.
+
+## Tests
+
+Use Vitest for app-local tests. Keep fixtures project-local; do not import from `examples/`. A minimum test suite imports the default server, checks the intended definitions compile, then lets `noodle test --json` perform the loopback MCP smoke.
+
+```ts
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('server', () => {
+  it('declares the expected tool surface', () => {
+    expect(app.name).toBe('support_assistant');
+  });
+});
+```
+
+After focused tests pass, run `noodle validate --json`, `noodle test --json`, and then `noodle dev` for interactive local verification.
+
 ## Secrets and variables
 
 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.

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

@@ -54,7 +54,7 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | `noodle rollback` | Roll back to a previous deployment. |
 | `noodle archive` | Archive the whole app: endpoints answer 410 Gone; hard-deleted after the retention window. |
 | `noodle restore` | Restore an archived app within the retention window. |
-| `noodle access` | Set the access mode (owner-only|org-members|authenticated|customers). |
+| `noodle access` | Set the access mode (owner-only\|org-members\|authenticated\|customers). |
 | `noodle apps` | List or inspect hosted apps for an org (`apps list`/`apps inspect <app>`). |
 | `noodle envs` | List or inspect environments for an app (`envs list`/`envs inspect <env>`). |
 | `noodle deployments` | List or inspect individual deployments (`deployments list`/`deployments inspect <id>`). |
@@ -64,7 +64,7 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | `noodle whoami` | Print the current authenticated user. |
 | `noodle list` | Removed — promoted to `deployments list` (prints the recovery pointer and exits 2). |
 | `noodle github` | Connect, inspect, or disconnect the GitHub repository behind an app’s GitHub-native deploys (`connect`/`status`/`disconnect`; `connect` opens a browser install, `--repo` for headless). |
-| `noodle target` | Show or set the deployment target (local|cloud|other). |
+| `noodle target` | Show or set the deployment target (local\|cloud\|other). |
 
 ## Org & members
 
@@ -87,8 +87,8 @@ Every `noodle` command, grouped by area. Local authoring commands (`validate`, `
 | `noodle audit` | Operator governance audit status and event queries. |
 | `noodle logs` | View service/deployment logs. |
 | `noodle metrics` | MCP analytics for a deployed server (volume, sessions, latency percentiles, two-tier errors, tools, clients). Agents: `noodle metrics --agent-output` for a health verdict + next actions. |
-| `noodle events` | The per-request MCP event stream with status/tool/client filters; `--session <id>` replays one session in order. Agents: add `--json` and filter (`--status tool_error|mcp_error`) when debugging. |
-| `noodle alerts` | Analytics alert rules (`add|list|remove|test`): an edge-triggered webhook fires when error share, error count, calls, or p95 latency breaches. Webhook URLs are stored server-side and shown redacted. |
+| `noodle events` | The per-request MCP event stream with status/tool/client filters; `--session <id>` replays one session in order. Agents: add `--json` and filter (`--status tool_error\|mcp_error`) when debugging. |
+| `noodle alerts` | Analytics alert rules (`add\|list\|remove\|test`): an edge-triggered webhook fires when error share, error count, calls, or p95 latency breaches. Webhook URLs are stored server-side and shown redacted. |
 | `noodle policy` | Manage policy (status/list/show/effective/simulate/suspend/quota/rate/...). |
 
 ## CLI maintenance

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

@@ -7,7 +7,7 @@
 
 ## 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`.
+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,9 +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
 
@@ -21,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.
@@ -33,6 +54,26 @@
 
 Manage runtime config with `noodle secrets` / `noodle variables` (scoped org/app/env). Operators use `noodle logs`, `noodle audit`, and `noodle policy` for logs, governance audit, and policy.
 
+## Agent-safe CLI recipes
+
+Use explicit flags in headless runs so commands never wait for a prompt:
+
+```sh
+noodle link --org acme --app support-assistant --env prod
+noodle secrets set CRM_TOKEN --scope env --org acme --app support-assistant --env prod --from-env CRM_TOKEN
+noodle secrets set CRM_CERT --scope env --org acme --app support-assistant --env prod --from-file ./cert.pem
+printf %s "$CRM_TOKEN" | noodle secrets set CRM_TOKEN --scope env --org acme --app support-assistant --env prod --from-stdin
+noodle variables set CRM_BASE_URL --scope env --org acme --app support-assistant --env prod --value https://crm.example.com
+noodle secrets list --scope env --org acme --app support-assistant --env prod --json
+noodle validate --json
+noodle test --json
+noodle deploy --json
+noodle smoke --json
+noodle agents doctor --json
+```
+
+`secrets resolve` is for local diagnostics only; do not print resolved values into prompts, logs, tests, or docs. Prefer `--from-env`, `--from-file`, or `--from-stdin` over inline `--value` for sensitive values. Variables may use `--value` when the value is non-secret.
+
 ## Analytics (verify after deploy, debug errors)
 
-After a deploy gets traffic, verify with `noodle metrics --agent-output` — it returns a `health` verdict (`ok`/`attention`), a one-line summary, and `attention[]` items each carrying the exact next command. When a tool errors, drill in with `noodle events --tool <name> --json` (filters: `--status tool_error|mcp_error`, `--client <name>`); `noodle events --session <id> --json` replays one session chronologically. `--json` on both returns the full payload; human runs get the branded report. Two-tier errors: `tool_error` is recoverable (handed back to the model), `mcp_error` needs attention (protocol/timeout/internal).
+After a deploy gets traffic, verify with `noodle metrics --agent-output` — it returns a `health` verdict (`ok`/`attention`), a one-line summary, and `attention[]` items each carrying the exact next command. When a tool errors, drill in with `noodle events --tool <name> --json` (filters: `--status tool_error|mcp_error`, `--client <name>`); `noodle events --session <id> --json` replays one session chronologically. `--json` on both returns the full payload; human runs get the branded report. Two-tier errors: `tool_error` is recoverable (handed back to the model), `mcp_error` needs attention (protocol/timeout/internal). Wire edge-triggered webhooks on error share, error count, calls, or p95 latency with `noodle alerts add|list|remove|test`.

package/skills/codex/references/examples.md

@@ -6,11 +6,14 @@ 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`. |
+| `bitcoin` | API-key HTTP connector, custom auth header, and compute normalization. |
+| `sharepoint` | Microsoft SharePoint delegated Microsoft Entra auth and Graph tools. |
 | `internal-ops-demo` | Governed internal connectivity — tools/resources/prompts, role-shaped output. |
+| `docs-assistant` | Docs/knowledge assistant grounding coding agents in the live docs export. |
 
 ## Canonical server.ts
 

package/skills/codex/references/publishing.md

@@ -0,0 +1,31 @@
+# Publish to app directories
+
+Directory requirements evolve — treat this as the workflow map and verify against the host’s current submission docs before submitting.
+
+## Contents
+
+- Readiness gate
+- ChatGPT apps directory
+- Claude connectors directory
+
+## Readiness gate
+
+Before any submission:
+
+1. `noodle check --target chatgpt` must be clean — every widget needs `domain` (one https origin per app) and an exact `csp` (hosts require the CSP to list precisely the domains you fetch from).
+2. Audit tool responses in developer mode: run realistic prompts and strip anything not strictly needed — PII, internal identifiers (session/trace/request IDs, internal account IDs), and any secrets.
+3. The server must be deployed and publicly reachable: `noodle deploy`, confirm with `noodle open --print` and `noodle smoke`. Reviewers connect to the real endpoint — never submit a placeholder or loopback URL, and the access mode must not be `owner-only` (`noodle access set`).
+4. Polish the listing surface: tool descriptions, widget titles, and the `server` branding tokens are what reviewers and users see.
+
+## ChatGPT apps directory
+
+Submit from the OpenAI developer dashboard (platform.openai.com → Apps):
+
+- Complete organization identity verification first (individual or business) — it is enforced at review time.
+- The submission form asks for the app name, logo, description, company and privacy policy URLs, MCP server URL and tool information, screenshots, test prompts with expected responses, and localization details.
+- One version may be published and one in review at a time; to revise a pending submission, cancel the review and resubmit rather than creating a new app.
+- Review combines automated checks and manual evaluation; rejections come with feedback — fix and resubmit, or reply to appeal. An approved app is also distributed as a Codex plugin.
+
+## Claude connectors directory
+
+Anthropic runs a connectors directory for Claude; submission goes through Anthropic’s published process (see the Anthropic connectors directory FAQ on support.claude.com). The same readiness gate applies: deployed public endpoint, clean `noodle check`, and graceful degradation where Apps rendering is unavailable.

package/skills/codex/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/codex/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/codex/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` |