@cyanheads/mcp-ts-core 0.12.9 → 0.13.1

package/dist/utils/parsing/frontmatterParser.js

@@ -9,14 +9,88 @@ import { logger } from '../internal/logger.js';
 import { requestContextService, withExtra, } from '../internal/requestContext.js';
 import { assertTextInputBudget } from './inputBudget.js';
 import { yamlParser } from './yamlParser.js';
+/** The `---` fence that opens and closes a frontmatter block. */
+const DELIMITER = '---';
+/** Single-character `\s` test — no quantifier, so no backtracking. */
+const WHITESPACE = /\s/;
 /**
- * Regular expression to extract frontmatter from markdown.
- * Matches YAML content between --- delimiters at the start of the document.
- * - Group 1: YAML content between delimiters
- * - Group 2: Remaining markdown content
- * @private
+ * Positions a regex `^` matches under the `m` flag: the start of input, and
+ * anything immediately after a LineTerminator (LF, CR, LS, PS).
  */
-const frontmatterRegex = /^---\s*\n([\s\S]*?)^---\s*([\s\S]*)$/m;
+function isLineTerminator(char) {
+    return char === '\n' || char === '\r' || char === '\u2028' || char === '\u2029';
+}
+/** Index just past the next line terminator at or after `from`, or `-1`. */
+function nextLineStart(text, from) {
+    for (let i = from; i < text.length; i++) {
+        if (isLineTerminator(text.charAt(i)))
+            return i + 1;
+    }
+    return -1;
+}
+/**
+ * End of an opening `---` fence — the index just past the last newline in the
+ * whitespace run that follows it, or `-1` when that run carries no newline.
+ * Mirrors greedy `\s*` backtracking to the final `\n` it can leave for the
+ * literal `\n` that follows.
+ */
+function endOfOpeningFence(text, from) {
+    let lastNewline = -1;
+    for (let i = from; i < text.length && WHITESPACE.test(text.charAt(i)); i++) {
+        if (text.charAt(i) === '\n')
+            lastNewline = i;
+    }
+    return lastNewline === -1 ? -1 : lastNewline + 1;
+}
+/** Index of the next line-initial `---` at or after `from`, or `-1`. */
+function findClosingFence(text, from) {
+    for (let i = from; i >= 0 && i <= text.length; i = nextLineStart(text, i)) {
+        if (text.startsWith(DELIMITER, i))
+            return i;
+    }
+    return -1;
+}
+/**
+ * Splits a markdown document into its YAML frontmatter block and the content
+ * after it, or returns `null` when no complete block is present.
+ *
+ * A linear-time index walk replacing the equivalent
+ * `/^---\s*\n([\s\S]*?)^---\s*([\s\S]*)$/m`, whose lazy `[\s\S]*?` between two
+ * line-anchored fences takes time quadratic in the input when the closing fence
+ * is absent — reachable whenever a server hands this parser markdown it
+ * received over the wire (CodeQL `js/polynomial-redos`).
+ *
+ * Behavior is preserved exactly, including the shapes the regex decided
+ * implicitly: the opening fence is the first line-initial `---` followed by a
+ * whitespace run containing a newline (not necessarily the document's first
+ * line); the closing fence is the next line-initial `---`, so a `----` line
+ * closes the block and leaves its fourth dash on the content, and a `---`
+ * inside the YAML that is not line-initial does not; and the whitespace after
+ * the closing fence belongs to neither half.
+ *
+ * @param markdown - Document to split.
+ * @returns The YAML source and the content that follows it, or `null`.
+ */
+function splitFrontmatter(markdown) {
+    for (let open = 0; open >= 0 && open <= markdown.length; open = nextLineStart(markdown, open)) {
+        if (!markdown.startsWith(DELIMITER, open))
+            continue;
+        const yamlStart = endOfOpeningFence(markdown, open + DELIMITER.length);
+        if (yamlStart === -1)
+            continue;
+        const close = findClosingFence(markdown, yamlStart);
+        // No closing fence after the earliest viable opening fence means none after
+        // a later one either — every later search window is a subset of this one.
+        if (close === -1)
+            return null;
+        let contentStart = close + DELIMITER.length;
+        while (contentStart < markdown.length && WHITESPACE.test(markdown.charAt(contentStart))) {
+            contentStart++;
+        }
+        return { yaml: markdown.slice(yamlStart, close), content: markdown.slice(contentStart) };
+    }
+    return null;
+}
 /**
  * Utility class for extracting and parsing YAML frontmatter from markdown documents.
  * Supports Obsidian-style and Jekyll-style frontmatter (YAML between `---` delimiters).
@@ -26,11 +100,12 @@ export class FrontmatterParser {
     /**
      * Extracts and parses YAML frontmatter from a markdown string.
      *
-     * Looks for a `---`-delimited block at the very start of the document. If
-     * found, the YAML inside is parsed via {@link yamlParser} and the remaining
-     * markdown is returned separately. An empty `---\n---` block is accepted and
-     * returns `frontmatter: {}` with `hasFrontmatter: true`. If no frontmatter
-     * block is present, the original string is returned unchanged.
+     * Looks for a `---`-delimited block opening on the first line that starts
+     * with `---`. If found, the YAML inside is parsed via {@link yamlParser} and
+     * the markdown after the closing fence is returned separately. An empty
+     * `---\n---` block is accepted and returns `frontmatter: {}` with
+     * `hasFrontmatter: true`. If no complete block is present, the original
+     * string is returned unchanged.
      *
      * @template T - The expected shape of the parsed frontmatter object. Defaults to `unknown`.
      * @param markdown - The markdown string that may contain a frontmatter block.
@@ -46,13 +121,13 @@ export class FrontmatterParser {
      * const md = `---\ntitle: Hello\ntags: [a, b]\n---\n\n# Body`;
      * const result = await frontmatterParser.parse<{ title: string; tags: string[] }>(md);
      * // result.frontmatter → { title: 'Hello', tags: ['a', 'b'] }
-     * // result.content     → '\n# Body'
+     * // result.content     → '# Body'
      * // result.hasFrontmatter → true
      * ```
      */
     async parse(markdown, context, budget) {
         assertTextInputBudget(markdown, budget);
-        const match = markdown.match(frontmatterRegex);
+        const match = splitFrontmatter(markdown);
         if (!match) {
             // No frontmatter found - return original content
             const logContext = context ||
@@ -66,8 +141,8 @@ export class FrontmatterParser {
                 hasFrontmatter: false,
             };
         }
-        const yamlContent = match[1] ?? '';
-        const markdownContent = match[2] ?? '';
+        const yamlContent = match.yaml;
+        const markdownContent = match.content;
         const logContext = context ||
             requestContextService.createRequestContext({
                 operation: 'FrontmatterParser.parse',
@@ -145,7 +220,7 @@ export class FrontmatterParser {
  *
  * const result = await frontmatterParser.parse(markdown, context);
  * console.log(result.frontmatter);    // { title: 'My Note', tags: [...], date: '2025-01-15' }
- * console.log(result.content);        // '\n# Note Content\nThis is the actual note.'
+ * console.log(result.content);        // '# Note Content\nThis is the actual note.'
  * console.log(result.hasFrontmatter); // true
  *
  * // Markdown without frontmatter

package/dist/utils/parsing/frontmatterParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatterParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/frontmatterParser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"frontmatterParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/frontmatterParser.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.23"
+  version: "2.25"
   audience: external
   type: reference
 ---
@@ -131,7 +131,7 @@ export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
 
 ### Multi-round-trip variant
 
-A handler that needs something the caller didn't supply returns `ctx.requestInput(...)` and is re-entered with the answers on `ctx.inputs`. There is no mid-handler `await` for user input, and no capability check — the surface is always present, on every transport and both protocol eras. Whether the caller can *answer* is a separate question — a 2025-era HTTP client cannot when the server runs `MCP_SESSION_MODE=stateless` (`api-context` § `ctx.requestInput`). Treat an unanswered round as terminal, never as consent.
+A handler that needs something the caller didn't supply returns `ctx.requestInput(...)` and is re-entered with the answers on `ctx.inputs`. There is no mid-handler `await` for user input, and no capability check — the surface is always present, on every transport and both protocol eras. Whether the caller can *answer* is a separate question — a 2025-era HTTP client cannot when the server runs `MCP_SESSION_MODE=stateless`, which a server needing that leg declares with `createApp({ sessionMode: { require: 'stateful' } })` rather than leaving to a deployment (`api-context` § `ctx.requestInput`). Treat an unanswered round as terminal, never as consent.
 
 ```typescript
 import { inputRequired, tool, z } from '@cyanheads/mcp-ts-core';
@@ -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
 

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.18"
   audience: external
   type: reference
 ---
@@ -25,7 +25,8 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 
 1. `name`/`version`/`title`/`websiteUrl`/`description`/`icons` options passed to `createApp()` or `createWorkerHandler()`
 2. Environment variables
-3. `package.json` fields
+3. `sessionMode.default` passed to `createApp()` — a default, so it sits *below* the env var it seeds, unlike the identity options above
+4. `package.json` fields
 
 **Where `package.json` is read from:** the application root — the nearest `package.json` at or above the process entry module (`process.argv[1]`), which is the served package on every launch path (`npx`, `.mcpb`, a client config naming `dist/index.js`), none of which run from the package root. The launching client's working directory is never the anchor: a stdio client starts the server from wherever it happens to be, so reading identity from there makes a server report a foreign project's name and version. When the entry module is a tool installed under the project's own `node_modules` and the process runs from that project — a test runner is the usual case — the project's manifest wins. With no manifest reachable, the framework's own identity is the fallback.
 
@@ -50,6 +51,7 @@ Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variable
 | `description` | `string?` | One-line description; wins over `MCP_SERVER_DESCRIPTION` when set |
 | `icons` | `Implementation['icons']?` | Array of icon objects: `{ src, mimeType?, sizes?: string[], theme?: 'light'\|'dark' }` |
 | `cacheHints` | `CacheHints?` | Cache hints for the 2026-07-28 cacheable results, keyed by operation — see below |
+| `sessionMode` | `SessionMode \| { default?: SessionMode; require?: 'stateful' }` | Session posture declared in code — see below |
 
 #### Cache hints (`cacheHints`)
 
@@ -69,6 +71,20 @@ await createApp({
 - A resource's own `cacheHint` overrides the `resources/read` entry for that resource, field by field — see the `add-resource` skill.
 - Omitting a hint keeps the SDK defaults (`ttlMs: 0`, `cacheScope: 'private'`). Responses to 2025-era clients are never affected.
 
+#### Session mode (`sessionMode`)
+
+Declares the session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`. The bare string is shorthand for `{ default }`. HTTP only — `MCP_SESSION_MODE` has no effect on stdio.
+
+```ts
+await createApp({ sessionMode: 'stateless' });                                  // default only
+await createApp({ sessionMode: { default: 'stateful', require: 'stateful' } }); // and enforced
+```
+
+- **`default`** applies only when `MCP_SESSION_MODE` carries no meaningful value. An empty string and a whole-value unsubstituted `${…}` placeholder both read as unset on the config path, so both fall through to the option rather than to the schema default (`auto`). An explicit `MCP_SESSION_MODE` always wins.
+- **`require: 'stateful'`** fails startup with a `ConfigurationError` naming the conflicting env value when the resolved HTTP mode is `stateless`, before any service is constructed. Declare it when a handler gates a destructive action behind `ctx.requestInput` / `inputRequired.elicit` — see the `MCP_SESSION_MODE` row for why that combination is unusable for 2025-era clients. There is no `require: 'stateless'`; nothing needs statelessness to work.
+- The advertised `transport.sessionMode` follows automatically — `resolveSessionMode` is the single resolution the manifest, the session store, and the `ctx.sessionId` gate all read — and still never publishes `auto`.
+- Cloudflare Workers are outside this contract: `MCP_SESSION_MODE` is not in `CORE_ENV_BINDINGS`, so a `[vars]` entry reaches `process.env` only through `extraEnvBindings`.
+
 ---
 
 ### Environment & logging
@@ -90,7 +106,7 @@ await createApp({
 | `MCP_HTTP_MAX_BODY_BYTES` | `mcpHttpMaxBodyBytes` | `1048576` (1 MiB) | Max **inbound** JSON-RPC request body; oversized requests get `413` before per-request allocation. Does **not** cap upstream data staged into a canvas or response sizes. `0` disables (defer to runtime/proxy). |
 | `MCP_HTTP_MAX_PORT_RETRIES` | `mcpHttpMaxPortRetries` | `15` | Rungs of the port ladder walked when a bind collides; each rung tries `port + 1`. See [Port binding](#port-binding) |
 | `MCP_HTTP_PORT_RETRY_DELAY_MS` | `mcpHttpPortRetryDelayMs` | `50` | Delay between port retries (ms) |
-| `MCP_SESSION_MODE` | `mcpSessionMode` | `auto` | `stateless` \| `stateful` \| `auto`; `auto` resolves to `stateful`. `stateless` also disables the 2025-era multi-round-trip shim, so v1 HTTP clients cannot answer a `ctx.requestInput` round — 2026-07-28 clients and stdio are unaffected |
+| `MCP_SESSION_MODE` | `mcpSessionMode` | `auto` | `stateless` \| `stateful` \| `auto`; `auto` resolves to `stateful`. Under `stateless`, the 2025-era multi-round-trip shim still runs but its capability gate refuses: each request is served by an instance that never processed `initialize`, so the client-capability view is empty and a `ctx.requestInput` round can never be answered — fail-closed, but unconditional, so the tool is unusable for those clients rather than merely guarded. 2026-07-28 clients and stdio are unaffected. Seed it from code with `createApp({ sessionMode })` — see below |
 | `MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS` | `mcpStatefulSessionStaleTimeoutMs` | `1800000` | 30 min; stale session eviction |
 | `MCP_HTTP_RESUMABILITY` | `mcpHttpResumability` | `true` | SSE stream replay under stateful HTTP. On by default — selecting a session mode is the opt-in. Kill switch only; no effect on stateless serving or the session-less 2026-07-28 era |
 | `MCP_HTTP_RESUMABILITY_MAX_EVENTS` | `mcpHttpResumabilityMaxEvents` | `512` | Events retained per session for replay; oldest evicted first. Lower it on a server whose tools return large results |
@@ -262,6 +278,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.4"
   audience: external
   type: reference
 ---
@@ -328,6 +328,8 @@ One code path serves both eras. A 2026-07-28 client fulfils the embedded request
 
 **`MCP_SESSION_MODE` decides whether that second leg exists.** Under `stateful` / `auto` the shim has the session it needs. Under `stateless` each 2025-era request is served by a fresh instance that never saw `initialize`, so its client-capability view is empty and the round trip is refused rather than attempted — fail-closed, but the handler never gets its answer. Ship `stateless` on a server whose destructive tools gate on `ctx.requestInput` and those tools become unusable for v1 HTTP clients. 2026-07-28 clients are unaffected in either mode: that revision has no server→client request channel at all, which is precisely why `input_required` exists. stdio is unaffected in either mode.
 
+**Declare the requirement rather than documenting it.** `createApp({ sessionMode: { default: 'stateful', require: 'stateful' } })` seeds the mode from code and refuses to start over HTTP when the resolved mode is `stateless`, so the incompatibility surfaces at boot instead of at the first refused confirmation. `MCP_SESSION_MODE` still wins over the default; the requirement is what an operator cannot silently override. Nothing derives this from handler code — `ctx.requestInput` is present on every transport and both eras, so whether a server needs a live session is a decision its author makes. Full precedence and error shape: `api-config` § Session mode.
+
 ### The shape of a multi-round-trip handler
 
 Read `ctx.inputs` first, request only what is still missing, and write the call in return position so TypeScript narrows the line below it.
@@ -594,7 +596,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 +739,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-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-telemetry/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Catalog of OpenTelemetry instrumentation built into framework `@cyanheads/mcp-ts-core` — spans, metrics, completion logs, env config, runtime caveats, custom instrumentation patterns, and cardinality rules. Use when enabling OTel export, adding custom spans or metrics in services, debugging missing telemetry, looking up attribute names, or deciding what's safe to put on a metric attribute vs. a span.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -59,18 +59,21 @@ Cloud platform detection auto-populates resource attributes:
 
 ## Flush at exit
 
-Spans batch and metrics push on a 15-second cycle, so a process that exits between cycles takes its telemetry with it. `ServerHandle.shutdown()` is the drain: it stops the transport, then force-flushes traces and metrics through the OTLP exporters and closes the logger.
+Spans batch and metrics push on a 15-second cycle, so a process that exits between cycles takes its telemetry with it. `ServerHandle.shutdown()` is the drain: it stops the transport, runs the `teardown` hook, then force-flushes traces and metrics through the OTLP exporters and closes the logger.
 
-| Trigger | Path |
-|:--------|:-----|
-| `SIGTERM` / `SIGINT` | `shutdown(signal)` |
-| `uncaughtException` / `unhandledRejection` | `shutdown(signal)`, then `process.exit(1)` |
-| stdin EOF, stdio transport | `shutdown('STDIN_EOF')`, then `process.exit(0)` |
-| `ServerHandle.shutdown()` called directly | the same drain, no exit |
+| Trigger | Path | Exit |
+|:--------|:-----|:-----|
+| `SIGTERM` / `SIGINT` | `shutdown(signal)`, then an explicit exit | `0`, or `1` when the backstop fires |
+| `uncaughtException` / `unhandledRejection` | `shutdown(signal)`, then an explicit exit | `1` |
+| stdin EOF, stdio transport | `shutdown('STDIN_EOF')`, then an explicit exit | `0`, backstop or not |
+| a second signal during shutdown | none — the handlers are already detached | the OS default (`143` / `130`) |
+| `ServerHandle.shutdown()` called directly | the same drain | none — exit-free by contract |
 
-**Stdin EOF is a disconnect.** A stdio host closing the pipe runs the cleanup a signal runs, exactly once — the shutdown detaches the signal handlers and the EOF watcher as it starts, so neither can re-enter it — and the process then exits explicitly instead of waiting to run out of handles. Two things follow: the OTLP export leaves the process, and a `setInterval` a service registered without `unref()` can no longer keep the server resident after its client is gone. The path writes nothing to stdout.
+**A signal ends the process.** Every exit-bearing path runs the cleanup exactly once — shutdown detaches the signal handlers and the EOF watcher as it starts, so neither can re-enter it — and then exits explicitly instead of waiting to run out of handles. Two things follow: the OTLP export leaves the process, and a handle registered outside framework teardown (a recursive `fs.watch`, a `setInterval` without `unref()`) can no longer keep the server resident. A second signal arriving mid-shutdown reaches no handler, so the default disposition terminates immediately — the operator's force-kill escape hatch. Neither path writes to stdout.
 
-**The drain is bounded.** Shutdown-on-exit races a 10-second backstop, so a cleanup step that never settles still terminates the process. The logger bounds its own flush separately, per pino instance: a completing callback is awaited in full, and a runtime whose callback never arrives releases shutdown rather than hanging it.
+**The drain is bounded.** Shutdown-on-exit races a 10-second backstop that bounds the shutdown as a whole, not any single await: a step that settles inside the ceiling is never truncated, and only one that never settles is cut. A signal cut exits 1 after a warning naming that step; a stdin-EOF cut exits 0 without one. The logger bounds its own flush separately, per pino instance: a completing callback is awaited in full, and a runtime whose callback never arrives releases shutdown rather than hanging it.
+
+**Release what the framework cannot see.** `createApp({ teardown })` is the `setup` counterpart: it runs after the transport stops and before the logger closes, on every shutdown path, with `CoreServices` still alive. Close a watcher, socket, or poller there rather than leaving it for the backstop, which cuts a ref'd handle rather than closing it. An error it raises is logged and never blocks the exit; a hook that never settles is what the ceiling then bounds. Node/Bun only — `createWorkerHandler` does not accept it.
 
 Workers has no `ServerHandle` and no `NodeSDK` — flush whatever exporter you wired there yourself, via `ctx.waitUntil()`.
 

package/{skills → framework-skills}/code-simplifier/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: code-simplifier
 description: >
-  Post-session code review and cleanup against a working tree of changes. Analyzes `git diff` to simplify, consolidate, and align changed code with the existing codebase — modernize syntax, remove unnecessary complexity, consolidate duplicated logic, catch efficiency issues. Use after a substantive working session, or when asked to clean up, simplify, reduce slop, consolidate, modernize, tighten up, or de-slop code. For `@cyanheads/mcp-ts-core` projects, includes specific transformations for tool/resource/prompt definitions, the ctx pattern, error factories, and framework idioms.
+  Code review and cleanup against a working tree of changes, or against a named path or whole codebase. Analyzes `git diff` (or the named target) to simplify, consolidate, and align code with the existing codebase — modernize syntax, remove unnecessary complexity, consolidate duplicated logic, catch efficiency issues. Use after a substantive working session, or when asked to clean up, simplify, reduce slop, consolidate, modernize, tighten up, de-slop, or scan a codebase. For `@cyanheads/mcp-ts-core` projects, includes specific transformations for tool/resource/prompt definitions, the ctx pattern, error factories, and framework idioms.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: workflow
 ---
 
 # Code Simplifier
 
-Post-session cleanup pass. Reviews what changed, understands how it fits the existing codebase, and makes targeted improvements — modernizing syntax, removing unnecessary complexity, consolidating duplicated logic, catching efficiency issues. Prioritizes codebase cohesion over local perfection.
+Cleanup pass over a session's changes or a named target. Reviews the code in scope, understands how it fits the existing codebase, and makes targeted improvements — modernizing syntax, removing unnecessary complexity, consolidating duplicated logic, catching efficiency issues. Prioritizes codebase cohesion over local perfection.
 
 ## Core philosophy
 
@@ -19,9 +19,12 @@ Post-session cleanup pass. Reviews what changed, understands how it fits the exi
 
 ## Procedure
 
-### Phase 1: Identify changes
+### Phase 1: Set the scope
 
-Run `git status` to see the shape of the working tree, then `git diff HEAD` for all uncommitted changes (staged and unstaged). Untracked files never appear in the diff — read new files directly. If the diff is empty and there are no untracked files, review the last commit (`git diff HEAD~1 HEAD`); if that is also empty, say the tree is clean and stop. Don't go hunting through the codebase for files to improve.
+Two scopes; the caller's wording picks one, and the diff is the default.
+
+- **Diff** (nothing named): run `git status` to see the shape of the working tree, then `git diff HEAD` for all uncommitted changes (staged and unstaged). Untracked files never appear in the diff — read new files directly. If the diff is empty and there are no untracked files, review the last commit (`git diff HEAD~1 HEAD`); if that is also empty, say the tree is clean and stop. Don't go hunting through the codebase for files to improve.
+- **Target** (a named path, module, or "the whole codebase"): the named files are the scope, whatever their git state. Work one module or directory at a time and re-run the gate after each, so a large scan never becomes one unverifiable diff. Take the target as named — don't rank or narrow it by commit history.
 
 ### Phase 2: Understand the surrounding codebase
 
@@ -47,6 +50,8 @@ Evaluate the changes across these dimensions. Not every dimension applies to eve
 
 - **Redundant state** — State that duplicates existing state, cached values that could be derived.
 - **Unnecessary complexity** — Deep nesting that could be guard clauses, premature abstractions, over-engineered solutions to simple problems.
+- **Pass-through layers** — Apply the deletion test to a wrapper, helper, or module: if deleting it and inlining its body makes the complexity vanish, it was a pass-through — inline it. If the same logic would reappear across several callers, it earns its keep. An interface, port, or injected dependency with a single implementation and no test double is a hypothetical seam, not a real one — collapse it until something actually varies across it.
+- **Test-only reach** — A function extracted or exported only so a test can get at it is a shape problem, not a cleanup: name it in the summary with the module it belongs to. Don't restructure it here — the tests would have to move with it.
 - **Dead code** — Unreachable branches, unused variables, commented-out code. An export nothing imports is dead in an application or a package-internal module; on a published package's public surface it is API — leave it and note it in the summary.
 - **Defensive code for impossible states** — Guards for cases the type system or upstream validation already prevents. Drop them.
 - **Type escapes** — `any`, `as` casts that paper over a mismatch, non-null `!`, and `@ts-ignore`. Each is a claim the compiler couldn't check: replace with a narrowed type, a type guard, or a parse at the boundary. Keep the ones documenting a genuine type-system or third-party-types limitation, and prefer `@ts-expect-error` with a one-line reason over `@ts-ignore`.
@@ -74,13 +79,14 @@ Evaluate the changes across these dimensions. Not every dimension applies to eve
 - **Tool annotations** — `readOnlyHint`, `idempotentHint`, `openWorldHint` should reflect reality. A read-only tool with `readOnlyHint: false` gives clients the wrong picture.
 - **`exactOptionalPropertyTypes` boundaries** — If a downstream type insists on the field being present-or-not-present (not present-as-undefined), use a mapped widening type at the boundary. The pattern is documented in the framework.
 - **`format()` ↔ `structuredContent` parity** — Different MCP clients forward different surfaces. Tests should assert both surfaces carry equivalent data.
+- **Framework layering is not a pass-through** — the init/accessor pair (`initFooService()` / `getFooService()`), the tool definition → service split, and a provider interface the framework selects by config are prescribed convention; the deletion test doesn't apply to them, and a single-implementation service accessor is the framework's seam, not a hypothetical one.
 - **Defensive code** — the "impossible states" the framework already prevents include malformed params (Zod-validated before the handler runs) and unclassified errors (caught and classified after it throws). Guards for either are dead.
 - **Public surface** — the MCP surface (every tool input/output schema advertised to clients) is public API for the "API compatibility" rule; changing one is a breaking change, not a refactor.
 
 ### Phase 4: Apply transformations
 
 1. **Filter findings ruthlessly.** If a finding is a false positive or not worth the churn, skip it. Don't argue with yourself about borderline cases — move on.
-2. **Stay in scope.** Edit only files in the diff or new this session. Touch a file outside that set only when a finding requires it — importing an existing helper, deleting a private export the diff just orphaned — and only on the lines that finding names. Anything broader goes in the summary as a recommendation, not into the tree.
+2. **Stay in scope.** Edit only files inside the Phase 1 scope — the diff plus files new this session, or the named target. Touch a file outside that set only when a finding requires it — importing an existing helper, deleting a private export the diff just orphaned — and only on the lines that finding names. Anything broader goes in the summary as a recommendation, not into the tree.
 3. **Correctness bugs are not this pass's job.** A real defect doesn't get folded into a cleanup diff — name it in the summary with file and line so it can be handled as its own change.
 4. **Transform incrementally** — one category of change at a time (modernize syntax, then reduce nesting, then consolidate).
 5. **Verify equivalence** — all functionality, types, and public interfaces must remain unchanged. Re-run the gate from Phase 2 after transforming; a simplification that breaks the build is worse than the verbosity it removed.

package/{skills → framework-skills}/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.25"
+  version: "2.26"
   audience: external
   type: workflow
 ---
@@ -251,7 +251,7 @@ Tools that perform multi-step mutations (the Workflow shape) have two safety con
 
 **Confirmation-gated destructive modes, with an annotation fallback.** When a workflow's `mode` parameter switches between safe and destructive arms (`draft` vs `send`, `plan` vs `apply`), gate the destructive arm on a confirmation the handler asks for via `ctx.requestInput(...)`, so a human approves before the irreversible step fires. The handler is re-entered with the answer on `ctx.inputs`; it does not `await` mid-call.
 
-The gate is always *reachable* — `ctx.requestInput` is present on every transport and both protocol revisions (2025-11-25 legacy, 2026-07-28 current) — but it is not always *answerable*: a client that never fulfils the `input_required` result simply doesn't retry, and the destructive step never runs. The same holds for a 2025-11-25 HTTP client when the server runs `MCP_SESSION_MODE=stateless`, which disables the legacy round-trip shim — the gate refuses and the destructive step never fires. That is the safe outcome, but it makes the tool unusable for those clients, so weigh it before defaulting such a server to `stateless` (`api-context` § `ctx.requestInput`). Keep `destructiveHint: true` in annotations so those clients' own approval flows still surface the risk. A decline is terminal — the handler fails the call rather than re-asking, which would loop until the round budget runs out. The handler shape is in `api-context` § *The shape of a multi-round-trip handler*.
+The gate is always *reachable* — `ctx.requestInput` is present on every transport and both protocol revisions (2025-11-25 legacy, 2026-07-28 current) — but it is not always *answerable*: a client that never fulfils the `input_required` result simply doesn't retry, and the destructive step never runs. The same holds for a 2025-11-25 HTTP client when the server runs `MCP_SESSION_MODE=stateless`: the legacy round-trip shim still runs, but its capability gate refuses because the serving instance never processed `initialize` — the destructive step never fires. That is the safe outcome, but it makes the tool unusable for those clients, so a server built around such a gate declares `createApp({ sessionMode: { default: 'stateful', require: 'stateful' } })` and refuses to start stateless rather than degrading (`api-context` § `ctx.requestInput`). Keep `destructiveHint: true` in annotations so those clients' own approval flows still surface the risk. A decline is terminal — the handler fails the call rather than re-asking, which would loop until the round budget runs out. The handler shape is in `api-context` § *The shape of a multi-round-trip handler*.
 
 **Safe defaults on parameters that determine blast radius.** When a workflow accepts a parameter that controls how far-reaching a mutation is, default to the safer value. A bulk file-update tool defaulting `mode: 'preview'` (no writes) means a sloppy agent call shows a diff rather than blasting changes; an apply-plan tool defaulting `dryRun: true` means a misread plan previews rather than executes; an object-delete tool requiring an explicit `confirmCount` matching the result-set size means an unscoped query can't silently nuke a million rows. Agents that genuinely want the destructive behavior have to name it explicitly, which surfaces intent in the tool call and in logs.