@cyanheads/mcp-ts-core 0.12.8 → 0.13.0

package/dist/services/mirror/types.d.ts

@@ -158,7 +158,11 @@ export interface QueryResult {
 }
 /** A schema migration: bump `version` and apply `up` on open when the stored version is lower. */
 export interface Migration {
-    /** Apply the migration. Runs inside the open handle; should be idempotent. */
+    /**
+     * Apply the migration. Runs inside the open handle, on first creation as well
+     * as on upgrade, so it must be idempotent and tolerate a database that already
+     * has the current declarative schema.
+     */
     up(handle: SqliteHandle): void;
     /** Target schema version this migration produces. */
     version: number;

package/dist/services/mirror/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/mirror/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/mirror/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/internal/performance.d.ts

@@ -12,7 +12,7 @@ export declare function initHandlerMetrics(): void;
  * Returns the current time in milliseconds using `globalThis.performance.now()`.
  *
  * Sub-millisecond resolution is guaranteed on all supported engine floors
- * (Node ≥24, Bun ≥1.3, Cloudflare Workers). The returned value is suitable for
+ * (Node ≥24, Bun ≥1.4, Cloudflare Workers). The returned value is suitable for
  * computing durations but its epoch origin is implementation-defined — do not
  * treat it as a wall-clock timestamp.
  *

package/dist/utils/internal/performance.js

@@ -54,14 +54,14 @@ function getActiveRequestsGauge() {
  * Returns the current time in milliseconds using `globalThis.performance.now()`.
  *
  * Sub-millisecond resolution is guaranteed on all supported engine floors
- * (Node ≥24, Bun ≥1.3, Cloudflare Workers). The returned value is suitable for
+ * (Node ≥24, Bun ≥1.4, Cloudflare Workers). The returned value is suitable for
  * computing durations but its epoch origin is implementation-defined — do not
  * treat it as a wall-clock timestamp.
  *
  * @returns Current time in milliseconds.
  */
 // performance is an ambient global declared by @types/node (perf_hooks.d.ts)
-// and available in all supported environments (Node ≥24, Bun ≥1.3, workerd).
+// and available in all supported environments (Node ≥24, Bun ≥1.4, workerd).
 export const nowMs = () => performance.now();
 // Module-level TextEncoder singleton (stateless, safe to reuse)
 let cachedEncoder;

package/dist/utils/network/fetchWithTimeout.js

@@ -479,7 +479,7 @@ export async function fetchWithTimeout(url, timeoutMs, context, options) {
     const timeoutReason = new DOMException(`${operationDescription} timed out after ${timeoutMs}ms.`, 'TimeoutError');
     const timeoutId = setTimeout(() => controller.abort(timeoutReason), timeoutMs);
     // Compose the timeout signal with any caller-supplied signal. AbortSignal.any
-    // is available on all supported floors (Node ≥24, Bun ≥1.3, workerd).
+    // is available on all supported floors (Node ≥24, Bun ≥1.4, workerd).
     const fetchSignal = externalSignal
         ? AbortSignal.any([controller.signal, externalSignal])
         : controller.signal;

package/dist/utils/network/retry.js

@@ -209,7 +209,7 @@ function sleep(ms, signal) {
             return;
         }
         const controller = new AbortController();
-        // AbortSignal.any is available on all supported floors (Node ≥24, Bun ≥1.3, workerd).
+        // AbortSignal.any is available on all supported floors (Node ≥24, Bun ≥1.4, workerd).
         const combined = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
         const timer = setTimeout(() => {
             controller.abort();

package/dist/utils/security/idGenerator.d.ts

@@ -64,8 +64,10 @@ export declare class IdGenerator {
     /**
      * Generates a cryptographically secure random string.
      * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
-     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @param charset - The character set to use, 1 to 256 characters. Defaults to `IdGenerator.DEFAULT_CHARSET`.
      * @returns The generated random string.
+     * @throws {McpError} With {@link JsonRpcErrorCode.ValidationError} when `charset` is empty
+     *   or longer than 256 characters — the sampler cannot terminate on either.
      */
     generateRandomString(length?: number, charset?: string): string;
     /**

package/dist/utils/security/idGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AA8CA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IACxE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IACvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAA0B;IAChD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;IACH,YAAY,cAAc,GAAE,kBAAuB,EAGlD;IAED;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAWjE;IAED;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB,CAE7C;IAED;;;;;OAKG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM,CAER;IAED;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAW1E;IAED;;;;;;OAMG;IACI,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAMtF;IAED;;;;;;;OAOG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAqBzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAGxF;IAED;;;;;;OAMG;IACI,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAe1F;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAStF;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAG3C,CAAC"}
+{"version":3,"file":"idGenerator.d.ts","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"AAqDA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA0C;IACxE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAO;IACvC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAAK;IAElC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAA0B;IAChD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAA8B;IAExD;;;OAGG;IACH,YAAY,cAAc,GAAE,kBAAuB,EAGlD;IAED;;;OAGG;IACI,iBAAiB,CAAC,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAWjE;IAED;;;OAGG;IACI,iBAAiB,IAAI,kBAAkB,CAE7C;IAED;;;;;;;OAOG;IACI,oBAAoB,CACzB,MAAM,GAAE,MAAmC,EAC3C,OAAO,GAAE,MAAoC,GAC5C,MAAM,CAQR;IAED;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAW1E;IAED;;;;;;OAMG;IACI,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAMtF;IAED;;;;;;;OAOG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAqBzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAGxF;IAED;;;;;;OAMG;IACI,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAe1F;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,MAAsC,GAAG,MAAM,CAStF;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAG3C,CAAC"}

package/dist/utils/security/idGenerator.js

@@ -21,6 +21,8 @@ function getRandomBytes(count) {
     crypto.getRandomValues(bytes);
     return bytes;
 }
+/** Largest charset the byte-wise rejection sampler below can draw from. */
+const MAX_CHARSET_LENGTH = 256;
 /**
  * Builds a random string of `length` characters drawn uniformly from `charset`.
  *
@@ -28,6 +30,10 @@ function getRandomBytes(count) {
  * multiple of `charset.length` that fits in 256, so `byte % charset.length`
  * never biases toward the low characters. Bytes are drawn in over-sized chunks
  * rather than one at a time, so a typical ID costs one `getRandomValues` call.
+ *
+ * `charset` must hold 1 to {@link MAX_CHARSET_LENGTH} characters: an empty
+ * charset never grows `result`, and a longer one rejects every byte, so either
+ * would spin here forever. Public callers validate before reaching this.
  */
 function randomStringFromCharset(length, charset) {
     const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
@@ -103,10 +109,15 @@ export class IdGenerator {
     /**
      * Generates a cryptographically secure random string.
      * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
-     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @param charset - The character set to use, 1 to 256 characters. Defaults to `IdGenerator.DEFAULT_CHARSET`.
      * @returns The generated random string.
+     * @throws {McpError} With {@link JsonRpcErrorCode.ValidationError} when `charset` is empty
+     *   or longer than 256 characters — the sampler cannot terminate on either.
      */
     generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        if (charset.length === 0 || charset.length > MAX_CHARSET_LENGTH) {
+            throw validationError(`Charset must contain between 1 and ${MAX_CHARSET_LENGTH} characters; received ${charset.length}.`, { charsetLength: charset.length, max: MAX_CHARSET_LENGTH });
+        }
         return randomStringFromCharset(length, charset);
     }
     /**

package/dist/utils/security/idGenerator.js.map

@@ -1 +1 @@
-{"version":3,"file":"idGenerator.js","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"idGenerator.js","sourceRoot":"","sources":["../../../src/utils/security/idGenerator.ts"],"names":[],"mappings":"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"}

package/framework-skills/README.md

@@ -0,0 +1,40 @@
+# Framework skills
+
+Agent Skills for `@cyanheads/mcp-ts-core`. Each subdirectory contains a `SKILL.md` following the [Agent Skills specification](https://agentskills.io/specification).
+
+The directory is `framework-skills/`, not `skills/`, on purpose. Claude Code and Codex auto-load a plugin's root `skills/`, and these are development-time skills for building a server — not skills for the agents that use one. A server that ships a plugin manifest keeps `skills/` free for that second kind.
+
+## Three-Tier Distribution
+
+Skills flow through three locations. Each tier has a distinct role:
+
+| Tier | Location | Written by | Purpose |
+|:-----|:---------|:-----------|:--------|
+| 1. Package | `node_modules/@cyanheads/mcp-ts-core/framework-skills/` | `npm publish` / `bun publish` | Canonical source. Ships with the package. |
+| 2. Project | `framework-skills/` (project root) | `@cyanheads/mcp-ts-core init` CLI | Project's source of truth. Committed to git. Server-specific skills live here too. |
+| 3. Agent | `.claude/skills/`, `.codex/skills/`, etc. | The agent itself | Agent's working copy. Synced from project `framework-skills/`. Checklists are checked here. |
+
+### Flow
+
+```text
+npm publish                    init CLI                    agent sync
+[package framework-skills/] ──────────> [project framework-skills/] ──────────> [.claude/skills/]
+                                     │
+                                     ├── core skills (from package)
+                                     └── server-specific skills (added by devs)
+```
+
+## Audience
+
+Each skill declares `metadata.audience` in its SKILL.md frontmatter:
+
+- **`external`** — For consumers building MCP servers. Copied to project `framework-skills/` by `init`.
+- **`internal`** — For core package developers. Stays in `node_modules`, not copied.
+
+## Versioning
+
+Skills declare `metadata.version` in frontmatter. The `maintenance` skill's Phase A compares versions after `bun update` and replaces a skill directory when the package version is newer; `init` only fills in what is missing and never overwrites an existing file. To pin a skill against those replacements, bump its local `metadata.version` above the package's.
+
+## Adding Server-Specific Skills
+
+Create a new directory in `framework-skills/` with a `SKILL.md` following the same format. The agent will pick it up on next sync. Use the core skills as examples for structure and checklist conventions.

package/{skills → framework-skills}/add-app-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold an MCP App tool + UI resource pair. Use when the user asks to add a tool with interactive UI, create an MCP App, or build a visual/interactive tool.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: reference
 ---
@@ -117,7 +117,7 @@ const APP_HTML = `<!DOCTYPE html>
       applyDocumentTheme,
       applyHostFonts,
       applyHostStyleVariables,
-    } from "https://unpkg.com/@modelcontextprotocol/ext-apps@1/app-with-deps";
+    } from "https://unpkg.com/@modelcontextprotocol/ext-apps@2/app-with-deps";
 
     const app = new App({ name: "{{TOOL_TITLE}}", version: "1.0.0" });
 

package/{skills → framework-skills}/add-resource/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
 metadata:
   author: cyanheads
-  version: "1.5"
+  version: "1.6"
   audience: external
   type: reference
 ---
@@ -139,7 +139,7 @@ export const articleResource = resource('article://{pmid}', {
 });
 ```
 
-Without `errors[]`, the handler receives plain `Context` (no `fail` method) and throws via error factories (`notFound`, `serviceUnavailable`, …) directly. The contract is opt-in. See `skills/api-errors/SKILL.md` for the full pattern, baseline codes, and conformance rules.
+Without `errors[]`, the handler receives plain `Context` (no `fail` method) and throws via error factories (`notFound`, `serviceUnavailable`, …) directly. The contract is opt-in. See `framework-skills/api-errors/SKILL.md` for the full pattern, baseline codes, and conformance rules.
 
 ### URI template variable completion
 

package/{skills → framework-skills}/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.10"
   audience: external
   type: reference
 ---
@@ -95,7 +95,7 @@ handler: async (input, ctx) => {
 
 ## Resilience (External API Services)
 
-When a service wraps an external API, apply these patterns. For the framework retry contract, see `skills/api-utils/SKILL.md`.
+When a service wraps an external API, apply these patterns. For the framework retry contract, see `framework-skills/api-utils/SKILL.md`.
 
 ### Retry wraps the full pipeline
 

package/{skills → framework-skills}/add-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a matching test file.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -15,7 +15,7 @@ Tests use Vitest and `createMockContext` from `@cyanheads/mcp-ts-core/testing`.
 
 For the full `createMockContext` API and testing patterns, read:
 
-    skills/api-testing/SKILL.md
+    framework-skills/api-testing/SKILL.md
 
 ## Steps
 

package/{skills → framework-skills}/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.22"
+  version: "2.24"
   audience: external
   type: reference
 ---
@@ -26,9 +26,9 @@ Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in
 
 Tools use lowercase snake_case with a canonical server/domain prefix: `{server}_{verb}_{noun}` — 3 words.
 
-Examples: `pubmed_search_articles`, `pubmed_fetch_fulltext`, `clinicaltrials_find_studies`.
+Examples: `pubmed_search_articles`, `pubmed_fetch_fulltext`, `clinicaltrials_find_eligible`.
 
-The server prefix uses the canonical platform/brand name, not an abbreviation (`patentsview_` not `patents_`, `clinicaltrials_` not `ct_`). When a name resists the schema — can't pick a verb, noun feels generic, wants 4+ segments — that's usually a signal the scope is fuzzy; split the tool, rename, or reconsider.
+The server prefix is judged on clarity, not length: the brand name or the plain well-known word for the domain both pass (`pubmed_`, `patents_`); an abbreviation fails only when it reads as something else out of context (`loc_`, `ct_`). A fourth segment is fine when the noun is inherently two words (`openfda_search_device_clearances`). When a name resists the schema — can't pick a verb, noun feels generic, the *verb* wants a second word — that's usually a signal the scope is fuzzy; split the tool, rename, or reconsider.
 
 For shape selection (Workflow or Instruction variants — standard single-action tools are the default), see the `design-mcp-server` skill's Tool shapes section.
 
@@ -169,7 +169,7 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
 });
 ```
 
-Write it as `return ctx.requestInput(...)` — the `never` return type makes it valid in return position for any output, and it is what lets TypeScript narrow the line below. Full reference (`inputRequired.elicitUrl` / `.createMessage` / `.listRoots`, `requestState`, decline handling): `skills/api-context`.
+Write it as `return ctx.requestInput(...)` — the `never` return type makes it valid in return position for any output, and it is what lets TypeScript narrow the line below. Full reference (`inputRequired.elicitUrl` / `.createMessage` / `.listRoots`, `requestState`, decline handling): `framework-skills/api-context`.
 
 ### Registration
 
@@ -413,7 +413,7 @@ async handler(input, ctx) {
 },
 ```
 
-The alternative — declaring `previewData: z.string()` in `output` and emitting the block from `format()` — ships the bytes twice (once in `structuredContent`, once in the block). Reserve `output` for data the agent reasons over; route raw media through `ctx.content`. Test with `getContentBlocks(ctx)`. Full reference: `skills/api-context` § `ctx.content`.
+The alternative — declaring `previewData: z.string()` in `output` and emitting the block from `format()` — ships the bytes twice (once in `structuredContent`, once in the block). Reserve `output` for data the agent reasons over; route raw media through `ctx.content`. Test with `getContentBlocks(ctx)`. Full reference: `framework-skills/api-context` § `ctx.content`.
 
 ### Capped lists must disclose truncation
 
@@ -714,7 +714,7 @@ throw invalidParams(
 );
 ```
 
-**Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `skills/api-errors/SKILL.md` for the full contract pattern, factories list, auto-classification table, and error-path parity (how `data.recovery.hint` reaches both client surfaces).
+**Error messages are recovery instructions.** Name what went wrong, why, and what action to take. The message is the agent's only signal — a bare "Not found" is a dead end. See `framework-skills/api-errors/SKILL.md` for the full contract pattern, factories list, auto-classification table, and error-path parity (how `data.recovery.hint` reaches both client surfaces).
 
 ### Include operational metadata
 
@@ -774,7 +774,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - **Lists**: Return top N with a total count and pagination cursor, not unbounded arrays
 - **Large objects**: Return key fields by default; accept a `fields` or `verbose` parameter for full data
 - **Binary/blob content**: Return metadata and a reference, not the raw content
-- **Analytical working sets**: When upstream returns more *analytical* rows (data an agent would SQL — aggregate, group, join) than fit in context, `DataCanvas` (`ctx.core.canvas?`, Tier 3 — opt-in via `CANVAS_PROVIDER_TYPE=duckdb`) lets you register the rows and return the `canvas_id` plus a preview so the agent can run SQL to slice down without a re-fetch. The `spillover()` helper (`@cyanheads/mcp-ts-core/canvas`) automates the overflow case: drain rows up to a character budget for the inline preview, auto-register the full source on overflow, return both as a discriminated union. **Two gates:** it must be analytical, not a discovery/search surface of categorical metadata (those don't earn a canvas regardless of row count — use MCP-side list filtering or pagination); and a tool emitting a `canvas_id` MUST be paired with a registered `dataframe_query` tool, or the handle is unreachable. Compute distributions or refinement hints across the full result — not the preview — so the agent gets honest aggregate signal on the rows it didn't read. See `api-canvas` for the register / query / export pattern and the spillover flow.
+- **Analytical working sets**: When upstream returns more *analytical* rows (data an agent would SQL — aggregate, group, join) than fit in context, `DataCanvas` (`core.canvas`, wired in `setup()` via `setCanvas`; Tier 3 — opt-in via `CANVAS_PROVIDER_TYPE=duckdb`) lets you register the rows and return the `canvas_id` plus a preview so the agent can run SQL to slice down without a re-fetch. The `spillover()` helper (`@cyanheads/mcp-ts-core/canvas`) automates the overflow case: drain rows up to a character budget for the inline preview, auto-register the full source on overflow, return both as a discriminated union. **Two gates:** it must be analytical, not a discovery/search surface of categorical metadata (those don't earn a canvas regardless of row count — use MCP-side list filtering or pagination); and a tool emitting a `canvas_id` MUST be paired with a registered `dataframe_query` tool, or the handle is unreachable. Compute distributions or refinement hints across the full result — not the preview — so the agent gets honest aggregate signal on the rows it didn't read. See `api-canvas` for the register / query / export pattern and the spillover flow.
 - **One large document**: When a single call returns one document-shaped record (not a row set) that can overflow context, return a section *outline* — top-level keys + per-section byte size — and let the agent re-call with `sections: [...]` for only what it needs, instead of truncating one surface. `outlineOnOverflow()` with `OUTLINE_VARIANT` / `selectSections()` / `formatOutline()` (`@cyanheads/mcp-ts-core/utils`) measures the payload and returns a `full | outline` result. Declare the tool's `output` as a flat `z.object` with a `kind` discriminator and presence-based optional arms (fold in `OUTLINE_VARIANT.shape.sections` / `.notice`) — `tool()` rejects a `z.discriminatedUnion` output — and render each arm on field presence in `format()` so parity holds. Pure measure + key-slice — Workers-portable, unlike canvas `spillover()`. Use for one fat record; use `spillover()` for a row collection. See the `techniques` skill's `outline-on-overflow` reference.
 
 ## MCP-side list filtering

package/{skills → framework-skills}/api-config/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
 metadata:
   author: cyanheads
-  version: "1.16"
+  version: "1.17"
   audience: external
   type: reference
 ---
@@ -262,6 +262,8 @@ export function getServerConfig(): ServerConfig {
 
 **Env booleans — use `z.stringbool()`, never `z.coerce.boolean()`.** `z.coerce.boolean()` runs `Boolean(value)`, so `"false"`, `"0"`, and `"no"` all coerce to `true` — the flag becomes impossible to disable through the environment except by omitting it entirely. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` (case-insensitive) and rejects anything else, so `MY_VERBOSE_LOGGING=false` actually disables and a typo fails loudly at startup instead of silently coercing. Empty string and unset both fall through to `.default()`.
 
+**Unset means unset.** `parseEnvConfig` and the framework's own config both treat an empty string and a whole-value `${…}` placeholder — what an MCPB or plugin host forwards when a user leaves an option blank and nothing substitutes it — as the variable being absent: an optional field stays `undefined`, a defaulted field takes its default, and a required field fails as missing rather than as a format error against the literal text. A value that merely contains `${…}` is kept. No per-field `z.preprocess` guard is needed for either case.
+
 **Why `parseEnvConfig`?** It maps Zod schema paths to env var names so validation errors name the actual variable at fault. A missing `MY_API_KEY` produces:
 
 ```

package/{skills → framework-skills}/api-context/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, its `RequestContext` base, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.requestInput`, `ctx.inputs`, `ctx.enrich`, `ctx.content`), and when to use each.
 metadata:
   author: cyanheads
-  version: "2.2"
+  version: "2.3"
   audience: external
   type: reference
 ---
@@ -594,7 +594,7 @@ async handler(input, ctx) {
 }
 ```
 
-The contract is opt-in. See `skills/api-errors/SKILL.md` for the full type-driven pattern, lint rules, and baseline-codes guidance.
+The contract is opt-in. See `framework-skills/api-errors/SKILL.md` for the full type-driven pattern, lint rules, and baseline-codes guidance.
 
 ---
 
@@ -737,7 +737,7 @@ async handler(input, ctx) {
 
 The `capped-list-no-truncation` lint rule fires when a cap-like input + array output shape is present without any of: `truncated` or `totalCount` in the declared `enrichment`, or `truncated` or `totalCount` in `output`. Using `ctx.enrich.total(n)` (writes `totalCount`) is also recognized as honest disclosure.
 
-See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*` rules) for the full pattern. Test enrichment with `getEnrichment(ctx)` from `@cyanheads/mcp-ts-core/testing`.
+See `add-tool`'s **Tool Response Design** and `framework-skills/api-linter` (`enrichment-*` rules) for the full pattern. Test enrichment with `getEnrichment(ctx)` from `@cyanheads/mcp-ts-core/testing`.
 
 ---
 

package/{skills → framework-skills}/api-errors/SKILL.md

@@ -4,7 +4,7 @@ description: >
   McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.10"
   audience: external
   type: reference
 ---
@@ -363,6 +363,7 @@ Important properties:
 - **`data` propagation is restricted** to explicitly-thrown `McpError.data` and `ZodError.issues`. Auto-classified plain errors (`TypeError`, network errors, etc.) emit `code` + `message` only — no `data` — so internal classification context never leaks to clients.
 - **Recovery hint mirroring is automatic.** When the thrown `McpError` carries `data.recovery.hint`, the handler factory appends it to the `content[]` text so the markdown surface matches the JSON surface. Authors don't need to format the hint manually.
 - **Argument-schema rejection is a tool error with the same envelope.** An unknown root key, a wrong type, a missing required field, or a failed constraint returns `isError: true` with `structuredContent.error.code = -32602` (`InvalidParams`) and the readable `Invalid arguments for tool <name>: …` diagnostic in `content[]`. The handler never runs. Two neighbouring failures keep the protocol error path instead, arriving as a JSON-RPC error rather than a tool result: an unknown or disabled tool name, and a malformed request envelope.
+- **A schema constraint cannot carry a declared reason.** Because the handler never runs, a rejection by `.max()`, `.regex()`, `.min()`, or any other Zod refinement bypasses `errors[]` entirely: it arrives as `InvalidParams` with `data.issues` and no `data.reason`, so a caller has nothing to branch on and gets no recovery hint. Decide per constraint which surface it belongs on. A bound that is purely structural — the input is the wrong shape and no guidance beyond the diagnostic would help — belongs on the schema, where it also advertises itself in `inputSchema`. A bound a caller is expected to recover from belongs in the handler as `ctx.fail('reason', message, ctx.recoveryFor('reason'))` against a declared `errors[]` entry, with the limit restated in the field's `.describe()` so it is still visible before the call. Enforcing the same bound in both places is the trap: the schema wins, and the contract entry becomes unreachable while still reading as covered.
 
 **Handler — throw freely, no try/catch:**
 

package/{skills → framework-skills}/api-linter/SKILL.md

@@ -4,7 +4,7 @@ description: >
   MCP definition linter rules reference. Use when `bun run lint:mcp` or `bun run devcheck` reports a lint error or warning (`format-parity`, `schema-is-object`, `name-format`, `server-json-*`, etc.) and you need to understand the rule, its severity, and how to fix it. Every rule ID the linter emits has an entry in this doc.
 metadata:
   author: cyanheads
-  version: "1.13"
+  version: "1.14"
   audience: external
   type: reference
 ---
@@ -18,7 +18,7 @@ The linter validates tool, resource, and prompt definitions against the MCP spec
 | `bun run lint:mcp` | Manual or CI | Prints errors + warnings, exits non-zero on errors. |
 | `bun run devcheck` | Pre-commit workflow | Wraps `lint:mcp` alongside typecheck, format, `bun audit`, `bun outdated`. |
 
-Both surface the same `LintReport` from `validateDefinitions()` (exported from `@cyanheads/mcp-ts-core/linter`). Each diagnostic has a stable `rule` ID — that's the anchor you land on via the `See: skills/api-linter/SKILL.md#<rule>` breadcrumb appended to every message.
+Both surface the same `LintReport` from `validateDefinitions()` (exported from `@cyanheads/mcp-ts-core/linter`). Each diagnostic has a stable `rule` ID — that's the anchor you land on via the `See: framework-skills/api-linter/SKILL.md#<rule>` breadcrumb appended to every message.
 
 **Severity:**
 - **error** — MUST-level spec violation; blocks `devcheck`.
@@ -615,7 +615,7 @@ Validate the `landing` config passed to `createApp()` (the config object that dr
 | `landing-theme-accent` | error | `theme.accent` is present but not a string |
 | `landing-theme-accent-format` | error | `theme.accent` doesn't match the expected color format |
 
-Diagnostic anchors for these rules are the rule ID — e.g. `skills/api-linter/SKILL.md#landing-shape`. Pass `landing` to `validateDefinitions({ landing, tools, resources, prompts })` to opt in.
+Diagnostic anchors for these rules are the rule ID — e.g. `framework-skills/api-linter/SKILL.md#landing-shape`. Pass `landing` to `validateDefinitions({ landing, tools, resources, prompts })` to opt in.
 
 ---
 
@@ -692,7 +692,7 @@ throw serviceUnavailable('Upstream failed', { upstreamError: e }, { cause: e });
 
 Validate the optional `errors[]` declarative contract on tool/resource definitions. Structural rules check the shape of contract entries; conformance rules cross-check the handler body against the declared codes.
 
-When a contract is declared, the handler receives a typed `ctx.fail(reason, …)` keyed by the declared reason union. See `skills/api-errors/SKILL.md` for runtime semantics.
+When a contract is declared, the handler receives a typed `ctx.fail(reason, …)` keyed by the declared reason union. See `framework-skills/api-errors/SKILL.md` for runtime semantics.
 
 ### error-contract-type
 

package/{skills → framework-skills}/api-mirror/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Stand up a persistent, self-refreshing local mirror of a bulk upstream dataset with the MirrorService (@cyanheads/mcp-ts-core/mirror). Use when a server wraps a large or slow API and should query a synced local index (embedded SQLite + FTS5) instead of paginating the live API per request.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -81,6 +81,8 @@ Why they can't merge: during a from-scratch init the records aren't ordered by t
 
 For access paths the generic query can't express — junction tables for index-backed multi-value filtering, denormalized counters, bespoke `bm25` weighting — use the **raw handle**: `const db = await mirror.raw();` then run prepared statements against your own auxiliary tables (declare them via a migration). Add the auxiliary DDL in a `migrations` step; maintain it from your `sync` mapping or SQL triggers.
 
+A migration runs identically on first creation and on upgrade: a fresh database runs every migration up to `version` right after the declarative DDL, an existing one runs only those above its stored version. So `up()` must tolerate a database that already has the current declarative shape — `CREATE TABLE IF NOT EXISTS` for auxiliary objects, never an `ALTER` that assumes an older layout of a declared column.
+
 ## Readiness — key off the completion marker, not live status
 
 `status().ready` is `true` once a full sync has **ever completed** (`completedAt != null`), not when `status === 'complete'`. The dataset stays transactionally queryable during a refresh, so a mirror mid-refresh — or one whose last refresh failed — is still ready and should keep serving. Gate the mirror read path on `await mirror.ready()`; fall back to the live API only when it is `false` (cold, never-completed init).