@noodleseed/agent-kit 0.9.0 → 0.11.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 ten
-  `references/*.md` files (sdk-surface, cli-commands, compile-errors, authoring-workflow,
-  widgets-and-apps, test-in-hosts, troubleshooting, deploy-and-ops, publishing, 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

package/manifest.json

@@ -1,14 +1,14 @@
 {
-  "packageVersion": "0.9.0",
+  "packageVersion": "0.11.0",
   "files": [
     {
       "path": "skills/codex/SKILL.md",
-      "sha256": "f2481e82944f3369735b3f09965454d94333966546ae2718d0ac6dd5be186467",
+      "sha256": "54f2a9d84455361127f40fe079715ec69c1ef737b491fc2ace896cb754ff4fe3",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/sdk-surface.md",
-      "sha256": "959fa5fee6d2f0fbd82d8f8d39424deb5f6a4e1be2c1bfa4950a1a253c178045",
+      "sha256": "d5da0c1ec33aa8d2770e145293174e99cff0c73264756dafe121e818ade14abf",
       "agentTarget": "codex"
     },
     {
@@ -16,19 +16,24 @@
       "sha256": "c50bf5ec6f43bd9fb7115ea9c9eb8de33c93e123f3e2d396785fe75ba094d40d",
       "agentTarget": "codex"
     },
+    {
+      "path": "skills/codex/references/agent-contract.md",
+      "sha256": "8e884a90f7c155a9f1d3773c7c037f88a98ac8d5c5d23e8100349ae82d068e6d",
+      "agentTarget": "codex"
+    },
     {
       "path": "skills/codex/references/compile-errors.md",
-      "sha256": "977d9b0022f7bb280cff1ff5737890f16eba1fee632868678dbdb45f9526e79a",
+      "sha256": "22692f2fda9c7d8ef0aa54e58148d22cf740bf722ceb79a942f6f146009a6bda",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/authoring-workflow.md",
-      "sha256": "d88ee3cd351ce4a438bc5c2ecd2afae56b191d1a53954562bb38e116e554047f",
+      "sha256": "ad5866ad739885592eb729fdd0bf18d602b886021309e28565a090d66f7c2e9a",
       "agentTarget": "codex"
     },
     {
       "path": "skills/codex/references/widgets-and-apps.md",
-      "sha256": "10d644eb421deee8a99a366f18c848ca769116ec051b7c35a4ee7e2c7b5e2f0d",
+      "sha256": "dea06536f780f0bb6d26dc63a6f1f35e2d6eb97f7a9c1c8574ed7377ccfe37a8",
       "agentTarget": "codex"
     },
     {
@@ -43,7 +48,7 @@
     },
     {
       "path": "skills/codex/references/deploy-and-ops.md",
-      "sha256": "33c902d900b60202331cbbcc09b683d91e5c23a07ec7c11c66e48e1a9726f33b",
+      "sha256": "0175101939ca5ea6823a18ce83a32311f5d9937ef8469a431dd0576ad0997fe4",
       "agentTarget": "codex"
     },
     {
@@ -53,17 +58,17 @@
     },
     {
       "path": "skills/codex/references/examples.md",
-      "sha256": "560d7874eaccd209b2c358060327bce0051ad73cf9d12bdf13636c202835c83f",
+      "sha256": "9f3ce479669040f0c58c9876b2bbca90821c69a760d0b020a56072bd6e549d73",
       "agentTarget": "codex"
     },
     {
       "path": "skills/claude-code/SKILL.md",
-      "sha256": "0871a7834077a3970960f341baa4bff37836b530ae227a1381c31a59ecc232f8",
+      "sha256": "fa975102477cd02ecdb083b4b8f747fc3fee3a7bcb5b725fe63ca9504258ba39",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/sdk-surface.md",
-      "sha256": "959fa5fee6d2f0fbd82d8f8d39424deb5f6a4e1be2c1bfa4950a1a253c178045",
+      "sha256": "d5da0c1ec33aa8d2770e145293174e99cff0c73264756dafe121e818ade14abf",
       "agentTarget": "claude-code"
     },
     {
@@ -71,19 +76,24 @@
       "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": "977d9b0022f7bb280cff1ff5737890f16eba1fee632868678dbdb45f9526e79a",
+      "sha256": "22692f2fda9c7d8ef0aa54e58148d22cf740bf722ceb79a942f6f146009a6bda",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/authoring-workflow.md",
-      "sha256": "d88ee3cd351ce4a438bc5c2ecd2afae56b191d1a53954562bb38e116e554047f",
+      "sha256": "ad5866ad739885592eb729fdd0bf18d602b886021309e28565a090d66f7c2e9a",
       "agentTarget": "claude-code"
     },
     {
       "path": "skills/claude-code/references/widgets-and-apps.md",
-      "sha256": "10d644eb421deee8a99a366f18c848ca769116ec051b7c35a4ee7e2c7b5e2f0d",
+      "sha256": "dea06536f780f0bb6d26dc63a6f1f35e2d6eb97f7a9c1c8574ed7377ccfe37a8",
       "agentTarget": "claude-code"
     },
     {
@@ -98,7 +108,7 @@
     },
     {
       "path": "skills/claude-code/references/deploy-and-ops.md",
-      "sha256": "33c902d900b60202331cbbcc09b683d91e5c23a07ec7c11c66e48e1a9726f33b",
+      "sha256": "0175101939ca5ea6823a18ce83a32311f5d9937ef8469a431dd0576ad0997fe4",
       "agentTarget": "claude-code"
     },
     {
@@ -108,7 +118,7 @@
     },
     {
       "path": "skills/claude-code/references/examples.md",
-      "sha256": "560d7874eaccd209b2c358060327bce0051ad73cf9d12bdf13636c202835c83f",
+      "sha256": "9f3ce479669040f0c58c9876b2bbca90821c69a760d0b020a56072bd6e549d73",
       "agentTarget": "claude-code"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.9.0",
+  "version": "0.11.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.9.0
-hash: afde8ab3db819772
+version: 0.11.0
+hash: 5aa15e5bf381543c
 ---
 
 # Noodle Seed
@@ -13,17 +13,23 @@ 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`).
-6. Prove it in a real host — `noodle connect <client>` (see `references/test-in-hosts.md`); debug symptoms with `references/troubleshooting.md`.
+This CLI is agent-native: the cold-agent-path commands speak the `--json` envelope (hosted admin/ops commands are still being normalized). Drive the loop by parsing machine state, not human prose. The full envelope, exit codes, and output modes are in `references/agent-contract.md`.
+
+1. **Discover** — `noodle commands --json`: every command, subcommand, flag, and exit code (don't read source).
+2. **Author** — edit `src/server.ts` (the configured entrypoint); follow the capability recipe in `references/sdk-surface.md` and `references/examples.md`.
+3. **Validate** — `noodle validate --json`; on failure `{ok:false,error:{code,message,fix,next,errors:[{code,path,message}]}}` — the per-field detail is in `error.errors[]`.
+4. **Repair** — fix each `error.errors[]` entry at its `path`, then re-run `noodle validate --json`; `noodle validate --fix-prompt` emits ready-to-apply repair prose. Never freeform re-edit (see `references/compile-errors.md`).
+5. **Smoke** — `noodle test --json`: local compile plus a loopback MCP smoke.
+6. **Apps/widgets** — `noodle check --json` (add `--target chatgpt|claude`), then `noodle devtools` (see `references/widgets-and-apps.md`).
+7. **Deploy** — `noodle deploy`; auth fails clean with `error.next` = `noodle login` (see `references/deploy-and-ops.md`).
+8. **Wire into a host** — `noodle connect <codex|claude-code|chatgpt>` (prove it in a real host per `references/test-in-hosts.md`; debug symptoms with `references/troubleshooting.md`).
+9. **Health** — `noodle metrics --agent-output`: a health verdict plus the exact next command per attention item.
 
 ## References
 
 Load these on demand:
 
+- `references/agent-contract.md` — the `--json` envelope, exit codes, and the three output modes.
 - `references/sdk-surface.md` — what to import from `@noodleseed/one` and which builder to use.
 - `references/cli-commands.md` — every `noodle` command, grouped by area.
 - `references/compile-errors.md` — fix `noodle validate` errors by code.

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

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

package/skills/claude-code/references/compile-errors.md

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

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

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

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

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

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

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