@cyanheads/mcp-ts-core 0.9.6 → 0.9.8

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Package:** `@cyanheads/mcp-ts-core`
-**Version:** 0.9.6
+**Version:** 0.9.8
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -316,7 +316,7 @@ if (ctx.elicit) {
   const result = await ctx.elicit('What format?', z.object({
     format: z.enum(['json', 'csv']).describe('Output format'),
   }));
-  if (result.action === 'accept') useFormat(result.data.format);
+  if (result.action === 'accept') useFormat(result.content.format);
 }
 ```
 
@@ -550,4 +550,4 @@ Badge order when both set: `· ⚠️ Breaking · 🛡️ Security`. Summary > 3
 
 If the user requests it, run the `release-and-publish` skill — it runs the verification gate (`devcheck`, `rebuild`, `test:all`), pushes commits and tags, and publishes to every applicable destination. After pushing, create a GitHub Release on the annotated tag (`gh release create v<VERSION> --verify-tag --notes-from-tag`) — no assets to attach, but the Release surfaces the tag's notes in the repo UI. **Skip the Docker build/push step** — this framework package is consumed via npm, not as a container image.
 
-**Tag annotation subjects must omit the version number.** GitHub prepends `v<VERSION>:` to the release title when using `--notes-from-tag`. A subject like `0.9.5 — some change` renders as `v0.9.5: 0.9.5 — some change`. Write the subject as just the description: `mcpbignore recursive-match fix, zod to dependencies`.
+**Tag annotations render as GitHub Release bodies** via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject must omit the version number (GitHub prepends `v<VERSION>:`). Body uses Keep a Changelog sections with bullets. See `changelog/template.md` for the full format reference including an example.

package/README.md

@@ -7,7 +7,7 @@
 
 [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
-[![Version](https://img.shields.io/badge/Version-0.9.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx)
+[![Version](https://img.shields.io/badge/Version-0.9.8-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx)
 
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -23,6 +23,7 @@ The framework handles the plumbing: transports, auth, config, logging, telemetry
 
 ```ts
 import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 
 const greet = tool('greet', {
   description: 'Greet someone by name and return a personalized message.',
@@ -38,7 +39,7 @@ const greet = tool('greet', {
       reason: 'name_blocked',
       code: JsonRpcErrorCode.Forbidden,
       when: 'The provided name is on the configured block list.',
-      recovery: 'Use a different name.',
+      recovery: 'Use a different name that is not on the block list.',
     },
   ],
   handler: async (input, ctx) => {
@@ -66,7 +67,7 @@ Start your coding agent (i.e. Claude Code, Codex) and describe what you want. Th
 
 ### What you get
 
-Here's what tool definitions look like:
+Here's what tool definitions look like. Add `format()` to render structured output as markdown — different MCP clients read different surfaces (`structuredContent` vs `content[]`), and `format()` ensures both carry the same data:
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
@@ -151,13 +152,13 @@ It also works on Cloudflare Workers with `createWorkerHandler()` — same defini
 - **Unified Context** — one `ctx` for logging, tenant-scoped storage, elicitation, sampling, cancellation, and task progress.
 - **Auth** — `auth: ['scope']` on definitions, checked before dispatch (no wrapper code). Modes: `none`, `jwt`, or `oauth` (local secret or JWKS).
 - **Task tools** — `task: true` for long-running ops; framework manages create/poll/progress/complete/cancel.
-- **Definition linter** — validates names, schemas, auth scopes, annotations, format-parity, and cross-vendor JSON Schema portability at startup. Standalone via `lint:mcp` or devcheck.
+- **Definition linter** — validates names, schemas, auth scopes, annotations, format-parity, and cross-vendor JSON Schema portability at build time. Run via `lint:mcp` or `devcheck` — not invoked at server startup.
 - **Typed error contracts** — declare `errors: [{ reason, code, when, recovery, retryable? }]` and handlers get a typed `ctx.fail(reason, …)`. Contracts publish in `tools/list` so clients preview failure modes; the linter cross-checks the handler. Factories (`notFound()`, `httpErrorFromResponse()`, …) cover ad-hoc throws; plain `Error` auto-classifies.
 - **Multi-backend storage** — `in-memory`, filesystem, Supabase, Cloudflare D1/KV/R2. Swap via env var; handlers don't change.
 - **DataCanvas (optional)** — Tier 3 SQL/analytical workspace backed by DuckDB. Register tabular data from upstream APIs, run SQL across registered tables, export CSV/Parquet/JSON. Token-sharing model (opaque `canvas_id`) for multi-agent collaboration; sliding TTL + per-tenant scoping. Opt-in via `CANVAS_PROVIDER_TYPE=duckdb`; fails closed on Workers.
 - **Observability** — Pino logging + optional OpenTelemetry traces/metrics. Request correlation and tool metrics automatic.
 - **Tiered dependencies** — parsers, OTEL SDK, Supabase, OpenAI as optional peers. Install what you use.
-- **Agent-first DX** — ships `CLAUDE.md` / `AGENTS.md` with the codebase documented throughout Agent Skills.
+- **Agent-first DX** — ships `CLAUDE.md` / `AGENTS.md` and Agent Skills that give your coding agent full framework knowledge — it can scaffold tools, write tests, run security audits, and ship releases without you writing the boilerplate.
 
 ## Server structure
 
@@ -206,7 +207,7 @@ See [CLAUDE.md](CLAUDE.md) for the full configuration reference.
 | Function | Purpose |
 |:---------|:--------|
 | `createApp(options)` | Node.js server — handles full lifecycle |
-| `createWorkerHandler(options)` | Cloudflare Workers — returns `{ fetch, scheduled }` |
+| `createWorkerHandler(options)` | Cloudflare Workers — returns an `ExportedHandler` |
 
 ### Builders
 
@@ -228,9 +229,12 @@ Handlers receive a unified `Context` object:
 | `ctx.state` | `ContextState` | Tenant-scoped key-value storage |
 | `ctx.elicit` | `Function?` | Ask the user for input (when client supports it) |
 | `ctx.sample` | `Function?` | Request LLM completion from the client |
+| `ctx.fail` | `(reason, msg?, data?) => McpError` | Typed error throw — reason checked against `errors[]` contract at compile time |
 | `ctx.signal` | `AbortSignal` | Cancellation signal |
 | `ctx.notifyResourceUpdated` | `Function?` | Notify subscribed clients a resource changed |
 | `ctx.notifyResourceListChanged` | `Function?` | Notify clients the resource list changed |
+| `ctx.notifyPromptListChanged` | `Function?` | Notify clients the prompt list changed |
+| `ctx.notifyToolListChanged` | `Function?` | Notify clients the tool list changed |
 | `ctx.progress` | `ContextProgress?` | Task progress reporting (when `task: true`) |
 | `ctx.requestId` | `string` | Unique request ID |
 | `ctx.tenantId` | `string?` | Tenant ID (JWT `tid` claim, or `'default'` for stdio and HTTP+`MCP_AUTH_MODE=none`) |
@@ -296,9 +300,9 @@ Also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_ST
 
 ## Documentation
 
-- **[CLAUDE.md/AGENTS.md](CLAUDE.md)** — Framework reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
+- **[CLAUDE.md/AGENTS.md](CLAUDE.md)** — Framework reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package and is auto-accessible in your project after `init`.
 - **[docs/telemetry/](docs/telemetry/)** — OpenTelemetry: full catalog of spans, metrics, and attributes the framework emits ([observability.md](docs/telemetry/observability.md)), plus an example Grafana dashboard and vendor-agnostic query recipes for Datadog, New Relic, Honeycomb ([dashboards.md](docs/telemetry/dashboards.md)).
-- **[CHANGELOG.md](CHANGELOG.md)** — Version history - Directory based for easier parsing by agents. Each entry includes a summary, migration notes, and links to commits/issues.
+- **[CHANGELOG.md](CHANGELOG.md)** — Version history. Each entry includes a summary, migration notes, and links to commits/issues.
 
 ## Development
 

package/biome.json

@@ -45,7 +45,7 @@
         "noImportCycles": "error",
         "noUnusedExpressions": "error",
         "noDeprecatedImports": "error",
-        "noDuplicateDependencies": "warn"
+        "noDuplicateDependencies": "off"
       },
       "complexity": {
         "noUselessUndefined": "error"

package/changelog/0.9.x/0.9.7.md

@@ -0,0 +1,18 @@
+---
+summary: "biome noDuplicateDependencies off, structured tag annotation format, release artifact verification, skills updates"
+breaking: false
+---
+
+# 0.9.7 — 2026-05-23
+
+## Changed
+
+- `biome.json`: `noDuplicateDependencies` warn → off (zod intentionally in both `dependencies` and `peerDependencies`)
+- `CLAUDE.md`/`AGENTS.md`: tag annotation guidance rewritten — structured markdown format with `changelog/template.md` reference
+- `changelog/template.md`: tag annotation format example added (subject, prose intro, sectioned bullets, dep arrows, test footer)
+- `templates/CLAUDE.md`/`templates/AGENTS.md`: install badge config updated (split `command`/`args`, `env` for API keys), tag annotation guidance added
+- `templates/changelog/template.md`: tag annotation format example synced from core
+- `skills/multi-server-orchestration/references/wrapup-pass.md` v1.2: structured tag annotation format replaces flat-string guidance
+- `skills/release-and-publish/SKILL.md`: Step 9 — verify published artifacts are reachable (npm, MCP Registry, GH Release, GHCR)
+- `skills/multi-server-orchestration/references/greenfield-buildout.md`: recommended additional phases (design gate, test quality review, field test, pre-launch sweep) and 5 new gotchas
+- `skills/polish-docs-meta/references/readme.md`: agent-friendly output subsection added to Features section guidance

package/changelog/0.9.x/0.9.8.md

@@ -0,0 +1,24 @@
+---
+summary: "Docs fixes, README context table updates, skill sync, @hono/node-server ^2.0.3 → ^2.0.4"
+breaking: false
+security: false
+---
+
+# 0.9.8 — 2026-05-24
+
+## Added
+
+- **`git-wrapup` skill** — codifies the version-bump, changelog, commit, and tag workflow as a reusable agent skill.
+- **`ctx.fail`** documented in README context table — typed error throw checked against the `errors[]` contract at compile time.
+- **`ctx.notifyPromptListChanged`**, **`ctx.notifyToolListChanged`** documented in README context table.
+
+## Changed
+
+- **README** — clarified `format()` purpose, corrected linter description (build-time, not startup), updated `createWorkerHandler` return type, expanded Agent-first DX description.
+- **Skills** — bulk refresh across 37 skill files; version bumps and content updates from upstream.
+- **`@hono/node-server`** ^2.0.3 → ^2.0.4.
+- **`@cloudflare/workers-types`** ^4.20260523.1 → ^4.20260524.1.
+
+## Fixed
+
+- **`ctx.elicit` example** in CLAUDE.md/AGENTS.md — `result.data.format` → `result.content.format` to match SDK's `ElicitResult.content` property.

package/changelog/template.md

@@ -66,6 +66,32 @@ security: false
   Never speculate on a future number — `#42` for an upcoming PR silently
   resolves to whatever real item already owns 42, and timeline previews pull
   in that unrelated item's metadata.
+
+  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
+  via `gh release create --notes-from-tag`. The tag is a derivative of this
+  changelog entry — a condensed, scannable version, not a copy. Format:
+
+    <theme — omit version number, GitHub prepends it>
+                                                          ← blank line
+    <1-2 sentence context: what this release does>
+                                                          ← blank line
+    Dependency bumps:                                     ← section header
+                                                          ← blank line
+    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
+                                                          ← blank line
+    Changed:                                              ← only sections with entries
+                                                          ← blank line
+    - `format()` output includes `query` in text mode
+                                                          ← blank line
+    Added:
+                                                          ← blank line
+    - `manifest.json` scaffolded for MCPB bundle support
+    - Install badges (Claude Desktop, Cursor, VS Code)
+                                                          ← blank line
+    <N> tests pass; `bun run devcheck` clean.             ← footer
+
+  Never a flat comma-separated string. Always structured markdown with
+  sections. The tag must scan well as a rendered GitHub Release page.
 -->
 
 ## Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -170,7 +170,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
     "@cloudflare/vitest-pool-workers": "^0.16.9",
-    "@cloudflare/workers-types": "^4.20260523.1",
+    "@cloudflare/workers-types": "^4.20260524.1",
     "@duckdb/node-api": "^1.5.3-r.1",
     "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
@@ -228,7 +228,6 @@
     "cloudflare-workers",
     "declarative",
     "framework",
-    "llm",
     "mcp",
     "mcp-server",
     "mcp-framework",
@@ -270,7 +269,7 @@
   },
   "dependencies": {
     "@hono/mcp": "^0.3.0",
-    "@hono/node-server": "^2.0.3",
+    "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",

package/skills/add-app-tool/SKILL.md

@@ -30,11 +30,11 @@ MCP Apps extend the standard tool pattern with an interactive HTML UI rendered i
 
 Both builders are exported from `@cyanheads/mcp-ts-core`. They handle `_meta.ui.resourceUri`, the compat key (`ui/resourceUri`), and the correct MIME type (`text/html;profile=mcp-app`) automatically.
 
-For the full API, Context interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+For the full API, Context interface, and error codes, read the framework's `CLAUDE.md` (loaded at session start).
 
 ## Steps
 
-1. **Ask the user** for the tool's name, purpose, input/output shape, and what the UI should display
+1. **Confirm the three conditions** in "When to Use" apply — if any is uncertain, default to `add-tool` instead. Then **gather** the tool's name, purpose, input/output shape, and what the UI should display from the user's request — ask only if genuinely absent
 2. **Choose a URI** — convention: `ui://{{tool-name}}/app.html`
 3. **Create the app tool** at `src/mcp-server/tools/definitions/{{tool-name}}.app-tool.ts`
 4. **Create the app resource** at `src/mcp-server/resources/definitions/{{tool-name}}-ui.app-resource.ts`
@@ -233,10 +233,12 @@ If the repo already uses `definitions/index.ts` barrels, update those instead of
 - [ ] App resource created at `src/mcp-server/resources/definitions/{{tool-name}}-ui.app-resource.ts` using `appResource()`
 - [ ] `resourceUri` matches between tool and resource (`ui://{{tool-name}}/app.html`)
 - [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types
-- [ ] `format()` renders JSON first block (for UI) + human-readable, content-complete fallback blocks (for non-app hosts and LLMs)
-- [ ] App resource `_meta.ui.csp` covers any external iframe dependencies, or a custom `format()` adds equivalent per-read metadata
+- [ ] `format()` first block is `JSON.stringify(result)` — the full output object for the UI to parse via `app.ontoolresult`. Subsequent blocks are human-readable, content-complete fallback for non-app hosts and LLMs
+- [ ] App resource `_meta.ui.csp.resourceDomains` lists every external domain loaded by the UI
 - [ ] UI bundles or inlines the client SDK for the shipped HTML, and handles `app.ontoolresult`
 - [ ] UI applies host context updates via `app.onhostcontextchanged`
+- [ ] App resource has a `list` callback returning at least one URI so resource-aware clients can discover it
 - [ ] Both registered in the project's existing `createApp()` arrays (directly or via barrels)
+- [ ] Handler tested directly via `createMockContext()`, or `add-test` skill run to scaffold the test file
 - [ ] `bun run devcheck` passes (linter validates `_meta.ui` and tool/resource pairing)
 - [ ] Smoke-tested with `bun run rebuild && bun run start:stdio` (or `start:http`)

package/skills/add-export/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 Subpath exports are defined in `package.json` under the `exports` field. Each subpath maps to a source entry point that gets compiled to `dist/`. The exports catalog in `CLAUDE.md` must stay in sync with `package.json`.
 
-The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src` and `include: ["src/**/*"]`. This means every source file at `src/foo/bar.ts` compiles to `dist/foo/bar.js` — the `dist/` paths in `exports` must mirror the source tree exactly, not flatten it.
+The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src` and `include: ["src/**/*"]`. This means every source file at `src/foo/bar.ts` compiles to `dist/foo/bar.js` — the `dist/` path in each export entry must match wherever `tsc` produces the compiled output for the named source file. Choose your source file location to produce the `dist/` path you want in the export entry.
 
 ## Steps
 
@@ -28,16 +28,16 @@ The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src`
    }
    ```
 
-3. **Update the exports catalog** in `CLAUDE.md` — add a row to the table
+3. **Update the exports catalog** in both `CLAUDE.md` and `AGENTS.md` — add a row to the table. These files must stay byte-identical; the simplest approach is `cp CLAUDE.md AGENTS.md` after editing
 4. **Build** with `bun run build` to generate `dist/` output
-5. **Verify the export** by inspecting the compiled output directly:
+5. **Verify the export** resolves through the package's `exports` map:
 
    ```bash
    # Confirm the compiled file exists at the expected dist path
    ls dist/utils/new-util.js
 
-   # Confirm the declared exports resolve to real files
-   bun -e "import('./dist/utils/new-util.js').then(m => console.log(Object.keys(m)))"
+   # Confirm the subpath export resolves correctly (tests the exports map, not just the dist file)
+   bun -e "import('@cyanheads/mcp-ts-core/newutil').then(m => console.log(Object.keys(m)))"
    ```
 
 6. **Run `bun run devcheck`** to verify
@@ -46,7 +46,7 @@ The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src`
 
 | Convention | Rule |
 |:-----------|:-----|
-| Subpath | lowercase, no underscores (e.g., `utils/errorHandler`) |
+| Subpath | all-lowercase, no underscores (e.g., `utils`, `storage/types`, `testing/fuzz`) |
 | Source file | kebab-case (e.g., `error-handler.ts`) |
 | Export name | camelCase for values, PascalCase for types |
 
@@ -54,7 +54,9 @@ The build uses `tsconfig.build.json` (not `tsconfig.json`) with `rootDir: ./src`
 
 - [ ] Source entry point file created with JSDoc header
 - [ ] Subpath added to `package.json` `exports` with `types` and `import` conditions
-- [ ] Exports catalog in `CLAUDE.md` updated with new row
+- [ ] Exports catalog updated in both `CLAUDE.md` and `AGENTS.md` (must be byte-identical)
+- [ ] If the new export has optional peer dependencies: entries added to both `peerDependencies` and `peerDependenciesMeta` in `package.json`
 - [ ] `bun run build` succeeds
-- [ ] Compiled file exists at expected `dist/` path and exports the expected symbols
+- [ ] Compiled file exists at expected `dist/` path and subpath import resolves correctly
+- [ ] Integration test at `tests/integration/package-consumer.int.test.ts` updated: new subpath added to the import spec list and `toHaveLength` count incremented
 - [ ] `bun run devcheck` passes

package/skills/add-prompt/SKILL.md

@@ -11,15 +11,13 @@ metadata:
 
 ## Context
 
-Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt lives in `src/mcp-server/prompts/definitions/` with a `.prompt.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some repos later add `definitions/index.ts` barrels; match the project's current pattern.
+Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt lives in `src/mcp-server/prompts/definitions/` with a `.prompt.ts` suffix. The standard registration pattern uses a `definitions/index.ts` barrel that collects all prompts into an `allPromptDefinitions` array for `createApp()`. Fresh scaffolds start with direct imports in `src/index.ts` — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.
 
-Prompts are pure message templates — no `Context`, no auth, no side effects.
-
-For the full `prompt()` API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+Prompts are pure message templates — no `Context`, no auth, no side effects. `generate` can be sync or async (returns `PromptMessage[] | Promise<PromptMessage[]>`).
 
 ## Steps
 
-1. **Ask the user** for the prompt's name, purpose, and arguments
+1. **Gather** the prompt's name, purpose, and arguments from the user's request — ask only if genuinely absent
 2. **Create the file** at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
 3. **Register** the prompt in the project's existing `createApp()` prompt list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
 4. **Run `bun run devcheck`** to verify
@@ -36,6 +34,8 @@ import { prompt, z } from '@cyanheads/mcp-ts-core';
 
 export const {{PROMPT_EXPORT}} = prompt('{{prompt_name}}', {
   description: '{{PROMPT_DESCRIPTION}}',
+  // args is optional — omit entirely for prompts with no parameters.
+  // When present, all fields need .describe(). Only JSON-Schema-serializable types allowed.
   args: z.object({
     // All fields need .describe()
   }),
@@ -86,14 +86,21 @@ await createApp({
 });
 ```
 
-If the repo already uses `src/mcp-server/prompts/definitions/index.ts`, update that barrel instead.
+If the repo already uses `src/mcp-server/prompts/definitions/index.ts`, add the export to that barrel instead:
+
+```typescript
+export { {{PROMPT_EXPORT}} } from './{{prompt-name}}.prompt.js';
+```
 
 ## Checklist
 
 - [ ] File created at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
-- [ ] All Zod `args` fields have `.describe()` annotations
+- [ ] Prompt name passed to `prompt()` uses snake_case
+- [ ] `description` field set (lint warns if absent, but `devcheck` won't hard-fail — verify it's present)
+- [ ] All Zod `args` fields have `.describe()` annotations — or `args` omitted entirely for no-parameter prompts
+- [ ] `args` fields use only JSON-Schema-serializable Zod types (no `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.custom()`, etc.)
 - [ ] JSDoc `@fileoverview` and `@module` header present
-- [ ] `generate` function returns valid message array
+- [ ] `generate` function present and returns at least one `{ role, content: { type: 'text', text } }` message
 - [ ] No side effects — prompts are pure templates
 - [ ] Registered in the project's existing `createApp()` prompt list (directly or via barrel)
 - [ ] `bun run devcheck` passes

package/skills/add-provider/SKILL.md

@@ -15,6 +15,10 @@ Providers implement interfaces defined in core. They are selected at runtime via
 (e.g., `STORAGE_PROVIDER_TYPE`). Tier 3 providers lazy-load their dependencies to keep the
 core bundle small.
 
+Providers live inside the package source tree — import the interface via relative path
+(e.g., `import type { IStorageProvider } from '../core/IStorageProvider.js'`), not via the
+package subpath exports (those are for consumers).
+
 ## Provider interfaces
 
 | Domain  | Interface file                                    |
@@ -32,9 +36,11 @@ these flags drive routing in `SpeechService`.
 
 Provider file location and naming differ by domain:
 
-- **Storage** — nested subdirectory, PascalCase file:
-  `src/storage/providers/{{provider-name}}/{{provider-name}}Provider.ts`
-  (e.g., `src/storage/providers/inMemory/inMemoryProvider.ts`)
+- **Storage** — nested subdirectory, camelCase directory name, PascalCase-suffixed provider file.
+  Each provider gets its own subdirectory for the provider file plus any co-located types:
+  `src/storage/providers/{{providerName}}/{{providerName}}Provider.ts`
+  (e.g., `src/storage/providers/inMemory/inMemoryProvider.ts`,
+  `src/storage/providers/supabase/supabaseProvider.ts` + `supabase.types.ts`)
 
 - **LLM / Speech** — flat directory, kebab-case with `.provider.ts` suffix:
   `src/services/llm/providers/{{provider-name}}.provider.ts`
@@ -63,8 +69,11 @@ Provider file location and naming differ by domain:
 
 5. **Register the provider** — the registration point differs by domain:
 
-   - **Storage** — add a `case` to the `switch` in `src/storage/core/storageFactory.ts`
-     inside `createStorageProvider()`. Import the new provider class at the top of that file.
+   - **Storage** — two changes required:
+     1. Add the new provider string to the `z.enum` for `STORAGE_PROVIDER_TYPE` in
+        `src/config/index.ts` — without this, the config schema rejects the env var at runtime.
+     2. Add a `case` to the `switch` in `src/storage/core/storageFactory.ts`
+        inside `createStorageProvider()`. Import the new provider class at the top of that file.
 
    - **Speech** — two changes required:
      1. Add the new provider string literal to the `provider` union in
@@ -75,8 +84,10 @@ Provider file location and naming differ by domain:
 
    - **LLM** — currently only one provider exists (`OpenRouterProvider`); it is
      instantiated directly in `src/core/app.ts` rather than through a factory switch.
-     Add a factory function or extend `app.ts` as needed, then update `ILlmProvider`
-     consumers accordingly.
+     There is no factory pattern yet — adding a second provider requires introducing
+     one (a selector env var, a factory function, and a conditional in `app.ts`).
+     Read `src/core/app.ts` to understand the current instantiation site before
+     designing the wiring.
 
 6. **Update the Worker-compatible provider list** if the new storage provider runs in
    Cloudflare Workers. The list is an inline array in `storageFactory.ts` at the
@@ -90,8 +101,11 @@ Provider file location and naming differ by domain:
    Add the new provider string to this array. Non-storage providers have no equivalent
    gate.
 
-7. **Add the dependency** as an optional peer dependency in `package.json` if Tier 3.
-8. **Run `bun run devcheck`** to verify.
+7. **Add the dependency** if Tier 3: add to both `peerDependencies` and
+   `peerDependenciesMeta` (with `{ "optional": true }`) in `package.json`.
+   Without the `peerDependenciesMeta` entry, the dep appears required rather than optional.
+8. **Run `bun run rebuild`** — since this is package source, verify the build output compiles.
+9. **Run `bun run devcheck`** to verify.
 
 ## Checklist
 
@@ -99,8 +113,11 @@ Provider file location and naming differ by domain:
 - [ ] Interface fully implemented (including `name`, `supportsTTS`/`supportsSTT` for speech)
 - [ ] Tier 3 dependencies lazy-loaded (not top-level imports)
 - [ ] Registered in the correct factory for the domain (see Step 5)
-- [ ] Speech: `provider` literal added to `SpeechProviderConfig` union in `types.ts`
+- [ ] Storage: provider string added to `z.enum` in `src/config/index.ts`
 - [ ] Storage: Worker-compatible array in `storageFactory.ts` updated if applicable
-- [ ] Optional peer dependency added to `package.json` if Tier 3
+- [ ] Speech: `provider` literal added to `SpeechProviderConfig` union in `types.ts`
+- [ ] LLM: `src/core/app.ts` instantiation logic updated if adding a second LLM provider
+- [ ] Optional peer dependency added to both `peerDependencies` and `peerDependenciesMeta` in `package.json` if Tier 3
+- [ ] `bun run rebuild` succeeds
 - [ ] `bun run devcheck` passes
-- [ ] Integration tested with the target backend
+- [ ] Test file created at `src/storage/providers/{{name}}/{{name}}Provider.test.ts` (or equivalent path for the domain) and `bun run test` passes

package/skills/add-resource/SKILL.md

@@ -11,15 +11,13 @@ metadata:
 
 ## Context
 
-Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resource lives in `src/mcp-server/resources/definitions/` with a `.resource.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some repos later add `definitions/index.ts` barrels; follow the pattern already used by the project.
+Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resource lives in `src/mcp-server/resources/definitions/` with a `.resource.ts` suffix. The standard registration pattern uses a `definitions/index.ts` barrel that collects all resources into an `allResourceDefinitions` array for `createApp()`. Fresh scaffolds start with direct imports in `src/index.ts` — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.
 
 **Tool coverage.** Not all MCP clients expose resources — many are tool-only (Claude Code, Cursor, most chat UIs). Before adding a resource, verify the same data is reachable via the tool surface — either through a dedicated tool, included in another tool's output, or bundled into a broader tool. A resource whose data has no tool path is invisible to a large share of agents.
 
-For the full `resource()` API, pagination utilities, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
-
 ## Steps
 
-1. **Ask the user** for the resource's URI template, purpose, and data shape
+1. **Gather** the resource's URI template, purpose, and data shape from the user's request — ask only if genuinely absent
 2. **Design the URI** — use `{paramName}` for path parameters (e.g., `myscheme://{itemId}/data`)
 3. **Create the file** at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
 4. **Register** the resource in the project's existing `createApp()` resource list (directly in `src/index.ts` for fresh scaffolds, or via a barrel if the repo already has one)
@@ -105,7 +103,11 @@ await createApp({
 });
 ```
 
-If the repo already uses `src/mcp-server/resources/definitions/index.ts`, update that barrel instead of changing the registration style.
+If the repo already uses `src/mcp-server/resources/definitions/index.ts`, add the export to that barrel instead:
+
+```typescript
+export { {{RESOURCE_EXPORT}} } from './{{resource-name}}.resource.js';
+```
 
 ### Optional: declarative `errors[]` contract
 
@@ -118,11 +120,14 @@ export const articleResource = resource('article://{pmid}', {
   description: 'Read an article by PMID.',
   errors: [
     { reason: 'no_pmid_match', code: JsonRpcErrorCode.NotFound,
-      when: 'PMID not found in the index.' },
+      when: 'PMID not found in the index.',
+      recovery: 'Use pubmed_search_articles to discover valid PMIDs first.' },
     { reason: 'withdrawn', code: JsonRpcErrorCode.NotFound,
-      when: 'Article was withdrawn upstream.' },
+      when: 'Article was withdrawn upstream.',
+      recovery: 'Check PubMed directly for retraction or withdrawal notices.' },
     { reason: 'upstream_throttled', code: JsonRpcErrorCode.RateLimited,
-      when: 'Upstream PubMed quota hit.', retryable: true },
+      when: 'Upstream PubMed quota hit.', retryable: true,
+      recovery: 'Wait a few seconds and retry the request.' },
   ],
   params: z.object({ pmid: z.string().describe('PubMed ID') }),
   async handler(params, ctx) {
@@ -142,21 +147,25 @@ Beyond `description`, `params`, `handler`, and `list`, the builder also supports
 
 | Field | Purpose |
 |:------|:--------|
+| `name` | Short human-readable name for `resources/list`. Defaults to a slug derived from the URI template if omitted. |
 | `output` | Optional Zod schema for runtime validation of the handler return value (parity with `tool()`'s `output`). |
 | `format` | Optional formatter mapping the handler's return to the `ReadResourceResult.contents[]` shape. Default: string passthrough; objects serialized to JSON. Override when you need to attach permissions, custom encodings, or split into multiple content items. |
 | `annotations` | Resource annotations (e.g., `audience`, `priority`) — see `ResourceAnnotations`. |
 | `title` | Human-readable display title (defaults to `name`). |
+| `examples` | Array of `{ name, uri }` example entries surfaced in `resources/list` for discoverability. |
 
 ## Checklist
 
 - [ ] File created at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
-- [ ] URI template uses `{paramName}` syntax for path parameters
+- [ ] Resource name passed to `resource()` uses a valid URI template with `{paramName}` syntax
 - [ ] All Zod `params` fields have `.describe()` annotations
+- [ ] `output` schema added if the handler returns structured data that benefits from runtime validation
 - [ ] JSDoc `@fileoverview` and `@module` header present
 - [ ] `handler(params, ctx)` is pure — throws on failure, no try/catch
-- [ ] Data is reachable via the tool surface (dedicated tool, another tool's output, or not needed for tool-only agents)
+- [ ] If `errors[]` contract declared: every entry has a `recovery` field (≥5 words, lint-enforced)
+- [ ] Data is reachable via the tool surface — confirm by checking `src/mcp-server/tools/definitions/` for a tool that exposes this data, or document why this resource is resources-only
 - [ ] `list()` function provided if the resource is discoverable
-- [ ] Pagination used for large result sets (`extractCursor`/`paginateArray`)
+- [ ] Pagination used for large result sets (`extractCursor`/`paginateArray`) — applies to both `handler` data and `list()` catalogs with many entries
 - [ ] Registered in the project's existing `createApp()` resource list (directly or via barrel)
 - [ ] `bun run devcheck` passes
 - [ ] Smoke-tested with `bun run rebuild && bun run start:stdio` (or `start:http`)

package/skills/add-service/SKILL.md

@@ -15,11 +15,11 @@ Services use the init/accessor pattern: initialized once in `createApp`'s `setup
 
 Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
 
-For the full service pattern, `CoreServices`, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
+For the full service pattern, `CoreServices`, and `Context` interface, read the framework's `CLAUDE.md` (loaded at session start).
 
 ## Steps
 
-1. **Ask the user** for the service domain name and what it integrates with
+1. **Gather** the service domain name and what it integrates with from the user's request — ask only if genuinely absent
 2. **Create the directory** at `src/services/{{domain}}/`
 3. **Create the service file** at `src/services/{{domain}}/{{domain}}-service.ts`
 4. **Create types** at `src/services/{{domain}}/types.ts` if needed
@@ -71,19 +71,16 @@ export function get{{ServiceName}}(): {{ServiceName}} {
 
 ### Entry point registration
 
+Add the `setup()` callback and import to the existing `createApp()` call — preserve the existing tool/resource/prompt arrays:
+
 ```typescript
-// src/index.ts
-import { createApp } from '@cyanheads/mcp-ts-core';
+// In src/index.ts (or src/worker.ts for Worker-only servers)
 import { init{{ServiceName}} } from './services/{{domain}}/{{domain}}-service.js';
 
-await createApp({
-  tools: [/* existing tools */],
-  resources: [/* existing resources */],
-  prompts: [/* existing prompts */],
-  setup(core) {
-    init{{ServiceName}}(core.config, core.storage);
-  },
-});
+// Add setup() alongside existing options:
+setup(core) {
+  init{{ServiceName}}(core.config, core.storage);
+},
 ```
 
 ### Usage in tool handlers
@@ -133,13 +130,13 @@ async fetchItem(id: string, ctx: Context): Promise<Item> {
 ### Key principles
 
 1. **Calibrate backoff to the upstream.** 200–500ms for ephemeral failures, 1–2s for rate-limited APIs, 2–5s for service degradation. The default `baseDelayMs: 1000` suits most APIs.
-2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws `ServiceUnavailable` on non-OK responses — this prevents feeding HTML error pages into XML/JSON parsers.
+2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws on non-OK responses with granular status mapping (401→`Unauthorized`, 403→`Forbidden`, 404→`NotFound`, 408/425→`Timeout`, 422→`ValidationError`, 429→`RateLimited`, 5xx→`ServiceUnavailable`/`InternalError`) — this prevents feeding HTML error pages into XML/JSON parsers.
 3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient).
 4. **Exhausted retries say so.** `withRetry` automatically enriches the final error with attempt count — callers know retries were already attempted.
 
 ### When you need finer-grained HTTP error classification
 
-`fetchWithTimeout` collapses every non-2xx into `ServiceUnavailable`. That's the safe default but it isn't always right — a `401` should be `Unauthorized`, a `429` should be `RateLimited` (and is retryable), a `408` should be `Timeout` (and is retryable). When you need the nuance, drop down to raw `fetch` + `httpErrorFromResponse`:
+`fetchWithTimeout` already maps status codes to appropriate error codes (see key principle 2 above). Use `httpErrorFromResponse` instead when you need `Retry-After` header capture, request body passthrough in error data, or custom `service`/`data` fields on the thrown error:
 
 ```typescript
 import { httpErrorFromResponse, withRetry } from '@cyanheads/mcp-ts-core/utils';
@@ -289,11 +286,12 @@ Silent truncation is a data integrity bug — the caller thinks it has all resul
 ## Checklist
 
 - [ ] Directory created at `src/services/{{domain}}/`
-- [ ] Service file created with init/accessor pattern
+- [ ] Service file created — `init` function accepts `(config: AppConfig, storage: StorageService)` and stores the instance
+- [ ] Accessor function exported — throws `Error` if not initialized
 - [ ] JSDoc `@fileoverview` and `@module` header present
+- [ ] No `console` calls — use `ctx.log` for service-level logging
 - [ ] Service methods accept `Context` for logging and storage
-- [ ] `init` function registered in `setup()` callback in `src/index.ts`
-- [ ] Accessor throws `Error` if not initialized
+- [ ] `init` function registered in `setup()` callback in the server's entry point (`src/index.ts` or `src/worker.ts`)
 - [ ] If wrapping external API: retry covers full pipeline (fetch + parse), backoff calibrated
 - [ ] If wrapping external API: raw/domain types reflect real upstream sparsity; missing values are preserved as unknown, not fabricated into concrete facts
 - [ ] If wrapping external API: batch endpoints used where available, field selection applied, pagination handled