@noodleseed/agent-kit 0.8.1 → 0.10.0

package/README.md

@@ -8,9 +8,10 @@ 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
-  `references/*.md` files (sdk-surface, cli-commands, compile-errors, authoring-workflow,
-  widgets-and-apps, deploy-and-ops, examples).
+- `skills/codex/` — the Codex (Codex CLI / AGENTS.md) skill: a `SKILL.md` router plus eleven
+  `references/*.md` files (sdk-surface, cli-commands, agent-contract, compile-errors,
+  authoring-workflow, 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 +27,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,124 @@
 {
-  "packageVersion": "0.8.1",
+  "packageVersion": "0.10.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "f95d48599e316191d1ddc6c2091eab4bc6528c0fef7055a79844a1645d966386",
+      "sha256": "9b4a0f08e67add37749096b5cb496d29407637d9602d0f3015f1362dff2a29f7",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/sdk-surface.md",
-      "sha256": "808225f0ae340016ee5826016770425cc83e19247cc892d4e98f76b66c067830",
+      "sha256": "d5da0c1ec33aa8d2770e145293174e99cff0c73264756dafe121e818ade14abf",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/cli-commands.md",
-      "sha256": "387bb7e4850dd13d220987cf829f2749c9561045d06bec3307eec9643a7d0972",
+      "sha256": "c50bf5ec6f43bd9fb7115ea9c9eb8de33c93e123f3e2d396785fe75ba094d40d",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/agent-contract.md",
+      "sha256": "8e884a90f7c155a9f1d3773c7c037f88a98ac8d5c5d23e8100349ae82d068e6d",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/compile-errors.md",
-      "sha256": "d1a22fb9a897714a069390d00eecfc0b4d0f87a64fdf15c94970ecb6c166dfa8",
+      "sha256": "22692f2fda9c7d8ef0aa54e58148d22cf740bf722ceb79a942f6f146009a6bda",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "85f8cbbd628e8108e813d0606edd9243441c912fa2a68fb2824663df5b738ea9",
+      "sha256": "ad5866ad739885592eb729fdd0bf18d602b886021309e28565a090d66f7c2e9a",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/widgets-and-apps.md",
-      "sha256": "ddff34458ad8f5e57db9f8501d0f2381098ec999fd9fcab031881e5c1c978110",
+      "sha256": "46ee39731565bf6bbf2b818125685b64599011bcd825b4c279f1232ecebd5839",
+      "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": "0175101939ca5ea6823a18ce83a32311f5d9937ef8469a431dd0576ad0997fe4",
+      "agentTarget": "codex"
+    },
+    {
+      "path": "skills/codex/references/publishing.md",
+      "sha256": "fb0be4c9c9bc9fd68f4e7ed8e9b7e4c8677c415130d441c28590ba0df6cb5aae",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/examples.md",
-      "sha256": "e1871dbf9ea1dac079cd77b4f33467a99c7b03d06bc4ece30f8909398bf6d7b5",
+      "sha256": "9f3ce479669040f0c58c9876b2bbca90821c69a760d0b020a56072bd6e549d73",
       "agentTarget": "codex"
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "1812332d59779f157893ed5329db7760f0f68baec52fbe900a09c45691689b9d",
+      "sha256": "8b900dc831b5dde27f3b1859041b688ec0b04be940e8748e2329a5e92014abd2",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/sdk-surface.md",
-      "sha256": "808225f0ae340016ee5826016770425cc83e19247cc892d4e98f76b66c067830",
+      "sha256": "d5da0c1ec33aa8d2770e145293174e99cff0c73264756dafe121e818ade14abf",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/cli-commands.md",
-      "sha256": "387bb7e4850dd13d220987cf829f2749c9561045d06bec3307eec9643a7d0972",
+      "sha256": "c50bf5ec6f43bd9fb7115ea9c9eb8de33c93e123f3e2d396785fe75ba094d40d",
+      "agentTarget": "claude-code"
+    },
+    {
+      "path": "skills/claude-code/references/agent-contract.md",
+      "sha256": "8e884a90f7c155a9f1d3773c7c037f88a98ac8d5c5d23e8100349ae82d068e6d",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/compile-errors.md",
-      "sha256": "d1a22fb9a897714a069390d00eecfc0b4d0f87a64fdf15c94970ecb6c166dfa8",
+      "sha256": "22692f2fda9c7d8ef0aa54e58148d22cf740bf722ceb79a942f6f146009a6bda",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "85f8cbbd628e8108e813d0606edd9243441c912fa2a68fb2824663df5b738ea9",
+      "sha256": "ad5866ad739885592eb729fdd0bf18d602b886021309e28565a090d66f7c2e9a",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/widgets-and-apps.md",
-      "sha256": "ddff34458ad8f5e57db9f8501d0f2381098ec999fd9fcab031881e5c1c978110",
+      "sha256": "46ee39731565bf6bbf2b818125685b64599011bcd825b4c279f1232ecebd5839",
+      "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": "0175101939ca5ea6823a18ce83a32311f5d9937ef8469a431dd0576ad0997fe4",
+      "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": "9f3ce479669040f0c58c9876b2bbca90821c69a760d0b020a56072bd6e549d73",
       "agentTarget": "claude-code"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.8.1",
+  "version": "0.10.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.1
-hash: 0d6c0f71af5c88ec
+version: 0.10.0
+hash: 5aa15e5bf381543c
 ---
 
 # Noodle Seed
@@ -13,22 +13,32 @@ Use this skill for project-local Noodle Seed authoring in Claude Code; preserve
 
 ## Golden path
 
-1. `noodle validate` — author-time compile/schema/connector check. On failure, fix the cited errors (see `references/compile-errors.md`) and re-validate; do not freeform re-edit.
-2. `noodle test` — local compile plus a loopback MCP smoke.
-3. `noodle dev` — local loopback runtime that serves and hot-reloads the manifest.
-4. `noodle check` / `noodle devtools` — MCP Apps/widget readiness and preview (see `references/widgets-and-apps.md`).
-5. `noodle deploy` after `noodle login` + `noodle link` (see `references/deploy-and-ops.md`).
+This CLI is agent-native: the cold-agent-path commands speak the `--json` envelope (hosted admin/ops commands are still being normalized). Drive the loop by parsing machine state, not human prose. The full envelope, exit codes, and output modes are in `references/agent-contract.md`.
+
+1. **Discover** — `noodle commands --json`: every command, subcommand, flag, and exit code (don't read source).
+2. **Author** — edit `src/server.ts` (the configured entrypoint); follow the capability recipe in `references/sdk-surface.md` and `references/examples.md`.
+3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
+4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
+5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
+6. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
+7. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
+8. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
+9. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
 
 ## References
 
 Load these on demand:
 
+- `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.
 - `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.
-- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the validate→test→dev repair loop, connectors, and secrets/variables.
-- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, and CSP.
+- `references/authoring-workflow.md` — input paths (scrape / OpenAPI import / user interview), the fit check, the validate→test→dev repair loop, connectors, and secrets/variables.
+- `references/widgets-and-apps.md` — MCP Apps, React `view` widgets, the widget hook surface, output shaping, and CSP.
+- `references/test-in-hosts.md` — connect and test in ChatGPT (developer mode), Claude, agent hosts, and MCP Inspector.
+- `references/troubleshooting.md` — runtime symptom → cause → fix, in-host and hosted.
 - `references/deploy-and-ops.md` — login/link/deploy/status/access and hosted operations.
+- `references/publishing.md` — submit to the ChatGPT apps directory and Claude connectors directory.
 - `references/examples.md` — flagship example index and a canonical `server.ts`.
 
 ## Safety

package/skills/claude-code/references/agent-contract.md

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

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

@@ -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/claude-code/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/claude-code/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/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.