@noodleseed/agent-kit 0.8.0 → 0.9.0

package/README.md

@@ -8,9 +8,9 @@ into a project's `.agents/` and `.claude/` skill directories via `noodle agents
 
 ## Contents
 
-- `skills/codex/` — the Codex (Codex CLI / AGENTS.md) skill: a `SKILL.md` router plus seven
+- `skills/codex/` — the Codex (Codex CLI / AGENTS.md) skill: a `SKILL.md` router plus ten
   `references/*.md` files (sdk-surface, cli-commands, compile-errors, authoring-workflow,
-  widgets-and-apps, deploy-and-ops, examples).
+  widgets-and-apps, test-in-hosts, troubleshooting, deploy-and-ops, publishing, examples).
 - `skills/claude-code/` — the Claude Code skill, same hierarchical tree.
 - `manifest.json` — `{ packageVersion, files: [{ path, sha256, agentTarget }] }`. The CLI verifies every
   file's sha256 against this manifest before writing it into a user's project; a mismatch refuses the
@@ -26,12 +26,13 @@ Skills updated in vX — run `noodle agents setup --write` to refresh.
 ```
 
 `noodle agents setup --write` then fetches this package, sha256-verifies it against the manifest, and
-writes the fresh `SKILL.md` bodies into the project (the managed `AGENTS.md`/`CLAUDE.md` block stays
-bundled, since it is project-specific). Offline or on verification failure it falls back to the bundled
-snapshot. Run `noodle agents doctor` to see installed vs registry skill versions.
+writes the fresh skill tree into the project (the managed `AGENTS.md`/`CLAUDE.md` block stays bundled,
+since it is project-specific). Offline or on verification failure it falls back to the bundled snapshot.
+Run `noodle agents doctor` to see installed vs registry skill versions and detect local edits to bundled
+reference files.
 
 ## License
 
 Apache-2.0. This package is generated and published from the
 [`noodle-borg`](https://github.com/NoodleSeed-com/noodle-borg) repository; the renderer is the private
-`@noodle-borg/agent-kit` workspace package.
+`@noodle-borg/agent-kit` workspace package.

package/manifest.json

@@ -1,84 +1,114 @@
 {
-  "packageVersion": "0.8.0",
+  "packageVersion": "0.9.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "e17881258c58d957ad48050828c8c0362b6ecde062b25dbdb7836a4e0a2923b9",
+      "sha256": "f2481e82944f3369735b3f09965454d94333966546ae2718d0ac6dd5be186467",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/sdk-surface.md",
-      "sha256": "808225f0ae340016ee5826016770425cc83e19247cc892d4e98f76b66c067830",
+      "sha256": "959fa5fee6d2f0fbd82d8f8d39424deb5f6a4e1be2c1bfa4950a1a253c178045",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/cli-commands.md",
-      "sha256": "387bb7e4850dd13d220987cf829f2749c9561045d06bec3307eec9643a7d0972",
+      "sha256": "c50bf5ec6f43bd9fb7115ea9c9eb8de33c93e123f3e2d396785fe75ba094d40d",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/compile-errors.md",
-      "sha256": "d1a22fb9a897714a069390d00eecfc0b4d0f87a64fdf15c94970ecb6c166dfa8",
+      "sha256": "977d9b0022f7bb280cff1ff5737890f16eba1fee632868678dbdb45f9526e79a",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "85f8cbbd628e8108e813d0606edd9243441c912fa2a68fb2824663df5b738ea9",
+      "sha256": "d88ee3cd351ce4a438bc5c2ecd2afae56b191d1a53954562bb38e116e554047f",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/widgets-and-apps.md",
-      "sha256": "e6b43810ca7a5f1e3e5191532557c0ac7857881b3e589448e514334fbbacbbfb",
+      "sha256": "10d644eb421deee8a99a366f18c848ca769116ec051b7c35a4ee7e2c7b5e2f0d",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/test-in-hosts.md",
+      "sha256": "08e44784a0d838c322d443eae6b35d5c75b4252a0975db835ef504535e25584a",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/troubleshooting.md",
+      "sha256": "4e0446d67d4ab037ecb6c9ffdf28494b42ed410f5c94ad7c498c3545f746eefb",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/deploy-and-ops.md",
-      "sha256": "3184d0855f08ddda65d2a551906e796f5552c22ffce61949747dc365f2de78df",
+      "sha256": "33c902d900b60202331cbbcc09b683d91e5c23a07ec7c11c66e48e1a9726f33b",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/publishing.md",
+      "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/examples.md",
-      "sha256": "e1871dbf9ea1dac079cd77b4f33467a99c7b03d06bc4ece30f8909398bf6d7b5",
+      "sha256": "560d7874eaccd209b2c358060327bce0051ad73cf9d12bdf13636c202835c83f",
       "agentTarget": "codex"
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "c0fdfe3aedfc710b1766d879068fa1c184f8d219c099b994af11887e779f2535",
+      "sha256": "0871a7834077a3970960f341baa4bff37836b530ae227a1381c31a59ecc232f8",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/sdk-surface.md",
-      "sha256": "808225f0ae340016ee5826016770425cc83e19247cc892d4e98f76b66c067830",
+      "sha256": "959fa5fee6d2f0fbd82d8f8d39424deb5f6a4e1be2c1bfa4950a1a253c178045",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/cli-commands.md",
-      "sha256": "387bb7e4850dd13d220987cf829f2749c9561045d06bec3307eec9643a7d0972",
+      "sha256": "c50bf5ec6f43bd9fb7115ea9c9eb8de33c93e123f3e2d396785fe75ba094d40d",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/compile-errors.md",
-      "sha256": "d1a22fb9a897714a069390d00eecfc0b4d0f87a64fdf15c94970ecb6c166dfa8",
+      "sha256": "977d9b0022f7bb280cff1ff5737890f16eba1fee632868678dbdb45f9526e79a",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "85f8cbbd628e8108e813d0606edd9243441c912fa2a68fb2824663df5b738ea9",
+      "sha256": "d88ee3cd351ce4a438bc5c2ecd2afae56b191d1a53954562bb38e116e554047f",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/widgets-and-apps.md",
-      "sha256": "e6b43810ca7a5f1e3e5191532557c0ac7857881b3e589448e514334fbbacbbfb",
+      "sha256": "10d644eb421deee8a99a366f18c848ca769116ec051b7c35a4ee7e2c7b5e2f0d",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/test-in-hosts.md",
+      "sha256": "08e44784a0d838c322d443eae6b35d5c75b4252a0975db835ef504535e25584a",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/troubleshooting.md",
+      "sha256": "4e0446d67d4ab037ecb6c9ffdf28494b42ed410f5c94ad7c498c3545f746eefb",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/deploy-and-ops.md",
-      "sha256": "3184d0855f08ddda65d2a551906e796f5552c22ffce61949747dc365f2de78df",
+      "sha256": "33c902d900b60202331cbbcc09b683d91e5c23a07ec7c11c66e48e1a9726f33b",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/publishing.md",
+      "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/examples.md",
-      "sha256": "e1871dbf9ea1dac079cd77b4f33467a99c7b03d06bc4ece30f8909398bf6d7b5",
+      "sha256": "560d7874eaccd209b2c358060327bce0051ad73cf9d12bdf13636c202835c83f",
       "agentTarget": "claude-code"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/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.0
-hash: 0d6c0f71af5c88ec
+version: 0.9.0
+hash: afde8ab3db819772
 ---
 
 # Noodle Seed
@@ -18,6 +18,7 @@ Use this skill for project-local Noodle Seed authoring in Claude Code; preserve
 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`.
 
 ## References
 
@@ -26,9 +27,12 @@ Load these on demand:
 - `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/claude-code/references/authoring-workflow.md

@@ -3,8 +3,12 @@
 ## Contents
 
 - Input paths
+- Fit check
 - Repair loop
 - Connectors
+- HTTP connector example
+- Compute connector example
+- Tests
 - Secrets and variables
 - Boundaries
 
@@ -14,6 +18,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 +35,76 @@ 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
+
+```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.
+
+## 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/claude-code/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/claude-code/references/compile-errors.md

@@ -3,12 +3,40 @@
 ## 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`.
+
 ## Error codes
 
 | Code | Fix |

package/skills/claude-code/references/deploy-and-ops.md

@@ -8,6 +8,7 @@
 - Access modes
 - Org and members
 - Config and observability
+- Agent-safe CLI recipes
 
 ## Authenticate
 
@@ -33,6 +34,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/claude-code/references/examples.md

@@ -10,7 +10,10 @@ Flagship examples (one per capability). Read the matching example for the patter
 | `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/claude-code/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/claude-code/references/sdk-surface.md

@@ -1,6 +1,7 @@
 # @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
 
@@ -30,10 +31,25 @@ Import these from `@noodleseed/one`. They are declarative builders that emit man
 - `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
 - `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
 
+## 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
 
-- `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
+- `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.

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

@@ -4,7 +4,10 @@
 
 - Tools and views
 - React authoring
-- CSP and permissions
+- React hook surface
+- Shaping tool output for widgets
+- Widget state and model context
+- CSP, domain, and permissions
 - Host bridge
 - Readiness and boundaries
 
@@ -18,15 +21,39 @@ Author views as React components. Get typed helpers from `@noodleseed/one/react`
 
 ```ts
 import { generateHelpers } from '@noodleseed/one/react';
-const { useCallTool, useLayout, useToolInfo, useViewState } = generateHelpers<AppType>();
+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>`).
 
-## CSP and permissions
+## React hook surface
+
+| 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. |
+| `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. |
+
+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.
+
+## Shaping tool output for widgets
+
+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.
+
+## Widget state and model context
+
+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.
+
+## CSP, domain, and permissions
 
 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.
 
+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.
+
 ## 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.

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.0
-hash: f297c7e0fa62058d
+version: 0.9.0
+hash: 097c37f2e7a3e482
 ---
 
 # Noodle Seed
@@ -18,6 +18,7 @@ Use this skill for local Noodle Seed project work in Codex.
 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`.
 
 ## References
 
@@ -26,9 +27,12 @@ Load these on demand:
 - `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/authoring-workflow.md

@@ -3,8 +3,12 @@
 ## Contents
 
 - Input paths
+- Fit check
 - Repair loop
 - Connectors
+- HTTP connector example
+- Compute connector example
+- Tests
 - Secrets and variables
 - Boundaries
 
@@ -14,6 +18,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 +35,76 @@ 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
+
+```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.
+
+## 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

@@ -3,12 +3,40 @@
 ## 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`.
+
 ## Error codes
 
 | Code | Fix |

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

@@ -8,6 +8,7 @@
 - Access modes
 - Org and members
 - Config and observability
+- Agent-safe CLI recipes
 
 ## Authenticate
 
@@ -33,6 +34,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

@@ -10,7 +10,10 @@ Flagship examples (one per capability). Read the matching example for the patter
 | `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,6 +1,7 @@
 # @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
 
@@ -30,10 +31,25 @@ Import these from `@noodleseed/one`. They are declarative builders that emit man
 - `secret("NAME")` — reference a managed secret (operated via `noodle secrets`).
 - `variable("NAME")` — reference a managed variable (operated via `noodle variables`).
 
+## 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
 
-- `z` — Zod, for input/output schemas (compiles to JSON Schema 2020-12).
+- `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.

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

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

@@ -4,7 +4,10 @@
 
 - Tools and views
 - React authoring
-- CSP and permissions
+- React hook surface
+- Shaping tool output for widgets
+- Widget state and model context
+- CSP, domain, and permissions
 - Host bridge
 - Readiness and boundaries
 
@@ -18,15 +21,39 @@ Author views as React components. Get typed helpers from `@noodleseed/one/react`
 
 ```ts
 import { generateHelpers } from '@noodleseed/one/react';
-const { useCallTool, useLayout, useToolInfo, useViewState } = generateHelpers<AppType>();
+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>`).
 
-## CSP and permissions
+## React hook surface
+
+| 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. |
+| `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. |
+
+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.
+
+## Shaping tool output for widgets
+
+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.
+
+## Widget state and model context
+
+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.
+
+## CSP, domain, and permissions
 
 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.
 
+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.
+
 ## 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.