@cyanheads/mcp-ts-core 0.9.20 → 0.10.0

package/scripts/check-framework-antipatterns.ts

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 /**
- * @fileoverview Guards against three SDK-coupling antipatterns. Scans `src/`
- * via `git grep` — all rules target framework-internal paths. Shipped to
- * consumers via `package.json` `files:` because `devcheck` invokes it; in
- * consumer projects the scanned paths (`src/mcp-server/tools/`,
- * `src/mcp-server/transports/`) either don't exist or contain consumer code
- * that follows different conventions, so the script exits cleanly with 0
- * findings. Defense-in-depth: harmless when nothing matches, catches real
- * regressions in the framework.
+ * @fileoverview Guards against framework antipatterns via `git grep` over
+ * `src/`. Rules 1–3 are SDK-coupling regressions scoped to framework-internal
+ * paths — they no-op in consumer projects, where those paths either don't exist
+ * or hold consumer code under different conventions. Rule 4 (`z.coerce.boolean()`)
+ * is intentionally consumer-facing: it catches the env-boolean footgun in both
+ * framework and scaffolded-server config. Shipped to consumers via
+ * `package.json` `files:` because `devcheck` invokes it. Defense-in-depth:
+ * harmless when nothing matches, catches real regressions.
  *
  * Rules:
  *   1. Framework must not downgrade the Zod `inputSchema` passed to
@@ -23,6 +23,11 @@
  *      `"Input validation error"`) is brittle across SDK versions. Any fix for
  *      #66 that intervenes at transport should use a structural signal, not a
  *      string match.
+ *   4. `z.coerce.boolean()` on an env flag can't be turned off through the
+ *      environment — `Boolean("false") === true`, so `"false"`/`"0"`/`"no"`
+ *      all coerce to `true` and the only `false` is omitting the variable.
+ *      Use `z.stringbool()` (parses `true/false/1/0/yes/no/on/off`, rejects
+ *      the rest). Scoped to `src/` so it fires in consumer config too.
  *
  * Runs standalone (`bun run scripts/check-framework-antipatterns.ts`) and as
  * a devcheck step.
@@ -62,6 +67,13 @@ const RULES: Rule[] = [
     pathspec: ['src/mcp-server/transports/'],
     message: 'Matching SDK error text in transport layer is brittle across SDK versions',
   },
+  {
+    id: 'coerce-boolean-env-flag',
+    pattern: 'z\\.coerce\\.boolean\\(\\)',
+    pathspec: ['src/', ':!**/*.test.ts'],
+    message:
+      'z.coerce.boolean() can\'t be disabled via env (Boolean("false") is true) — use z.stringbool() for boolean env flags',
+  },
 ];
 
 interface Finding {
@@ -72,6 +84,16 @@ interface Finding {
   ruleMessage: string;
 }
 
+/**
+ * A matched line that is itself a comment is a mention (e.g. JSDoc naming the
+ * antipattern to document the rule), not a real usage. Real violations are
+ * code. Skipping comment lines keeps the rules sound when docs name the pattern.
+ */
+function isCommentLine(line: string): boolean {
+  const t = line.trim();
+  return t.startsWith('//') || t.startsWith('*') || t.startsWith('/*');
+}
+
 function runRule(rule: Rule): Finding[] {
   const result = spawnSync('git', ['grep', '-nE', rule.pattern, '--', ...rule.pathspec], {
     encoding: 'utf-8',
@@ -97,7 +119,8 @@ function runRule(rule: Rule): Finding[] {
       const lineNo = Number(raw.slice(firstColon + 1, secondColon));
       const line = raw.slice(secondColon + 1);
       return { file, lineNo, line, ruleId: rule.id, ruleMessage: rule.message };
-    });
+    })
+    .filter((finding) => !isCommentLine(finding.line));
 }
 
 const findings = RULES.flatMap(runRule);

package/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.12"
+  version: "2.13"
   audience: external
   type: reference
 ---
@@ -575,6 +575,7 @@ Large payloads burn the agent's context window. Default to curated summaries; of
 - **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.
+- **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` discriminated-union `output`; declare `OUTLINE_VARIANT` as a branch so `format()`-parity holds per arm. 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
 
@@ -624,6 +625,7 @@ return { items: hits };
 - [ ] `task: true` added if the tool is long-running
 - [ ] If `task: true`: handler checks `ctx.signal.aborted` in its loop for cancellation support
 - [ ] If tool returns unbounded arrays: pagination with total count, or `spillover()` / DataCanvas for *analytical* working sets (an agent would SQL them — not a discovery/search surface). If any tool emits a `canvas_id`, a `dataframe_query` tool is registered in the same server — a token with no query tool is dead output
+- [ ] If tool returns one large *document* (not a row set) that can overflow context: `outlineOnOverflow()` returns a `full | outline` union so the agent re-calls with `sections: [...]` — not one-sided truncation
 - [ ] If tool is feature-gated: evaluated whether `disabledTool()` wrapper is appropriate (present in manifest but uncallable)
 - [ ] If the tool filters a bounded list locally (no upstream search): a distinct local param (`filter`/`nameContains`, not `query`), filters the full set (not one page), strict token match by default
 - [ ] Registered in the project's existing `createApp()` tool list (directly or via barrel)

package/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.5"
+  version: "1.6"
   audience: external
   type: reference
 ---
@@ -220,6 +220,7 @@ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
   apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
+  verboseLogging: z.stringbool().default(false).describe('Enable verbose logging'),
 });
 
 export type ServerConfig = z.infer<typeof ServerConfigSchema>;
@@ -230,11 +231,14 @@ export function getServerConfig(): ServerConfig {
   _config ??= parseEnvConfig(ServerConfigSchema, {
     apiKey: 'MY_API_KEY',
     maxResults: 'MY_MAX_RESULTS',
+    verboseLogging: 'MY_VERBOSE_LOGGING',
   });
   return _config;
 }
 ```
 
+**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()`.
+
 **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/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.16"
+  version: "2.17"
   audience: external
   type: workflow
 ---
@@ -350,6 +350,7 @@ output: z.object({
 
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
 - **Spill big *analytical* results to a queryable surface.** When a tool's row set is something an agent would run SQL over (aggregate, group, join) *and* can exceed any reasonable context budget — paginated APIs, streamed exports, big query results — pair an inline preview with a `DataCanvas` table holding the full set. **Two rules gate this:** (1) it must earn its keep on *shape, not size* — a discovery/search surface of categorical metadata (titles, IDs) is not analytical and doesn't get a canvas regardless of row count; for name→ID resolution over a bounded list use [MCP-side list filtering](#mcp-side-list-filtering); (2) the `canvas_id` is reachable only if the same server **also exposes a `dataframe_query` tool** — emit one without the other and the handle is dead output. Compute distributions or refinement hints across the full result, not the preview, so aggregate signal stays honest. See `api-canvas` for the `spillover()` helper and both rules in full.
+- **Outline one large *document* into sections.** When a single tool call returns one document-shaped record (not many rows) that can exceed context — a ~130KB FDA drug label, a big API entity dominated by a few fat fields — return a section *outline* (top-level keys + per-section byte size) instead of truncating, and let the agent re-call with `sections: [...]` to pull only what it needs. The `outlineOnOverflow()` helper (`@cyanheads/mcp-ts-core/utils`) measures the payload and returns a `full | outline` discriminated union; declare its `OUTLINE_VARIANT` as a branch of the tool's `output` so `format()`-parity is enforced per branch. Pure measure + key-slice — Workers-portable, unlike canvas-bound `spillover()`. Distinct from spillover on *shape*: spillover splits a row collection, this outlines one fat record. See the `techniques` skill's `outline-on-overflow` reference.
 - **Mirror a bulk upstream instead of paginating it live.** When the server wraps a large or slow API whose corpus is queried far more than it changes, sync it once into a persistent local index and query that as the primary data path — not the live API per request. Match the backend to corpus size: ≲ tens of thousands of rows → an in-memory index (server-level, no primitive); ~10⁴–10⁷ → the `MirrorService` (embedded SQLite + FTS5; declare a schema + a `sync` ingester via `defineMirror`/`sqliteMirrorStore`, then `runSync`/`query`, see `api-mirror`); ≳ 10⁸ → an external store. Distinct lifecycle from DataCanvas: a mirror is long-lived and cross-session, refreshed on a schedule; canvas is ephemeral and per-session.
 - **`format()` is the markdown twin of `structuredContent` — make both content-complete.** Different MCP clients forward different surfaces to the model: some (e.g., Claude Code) read `structuredContent` from `output`, others (e.g., Claude Desktop) read `content[]` from `format()`. Both must carry the same data so every client sees the same picture — `format()` just dresses it up with markdown. A thin `format()` that returns only a count or title leaves `content[]`-only clients blind to data that `structuredContent` clients can see. Render all fields the LLM needs, with structured markdown (headers, bold labels, lists) for readability.
 - **Agent-facing context must reach both client surfaces — put it in `enrichment`.** `structuredContent` (from `output`) and `content[]` (from `format()`) are read by different clients. Empty-result notices, the query/filter as the server parsed it, and pagination totals — the context the agent *reasons with*, distinct from the domain payload — reach only `content[]` if hand-authored into `format()` text alone, leaving `structuredContent`-only clients (Claude Code) blind. (The reverse can't happen: `format-parity` drags every `output` field into `format()`, so `output`-authored context already reaches both.) An `enrichment` block — the success-path counterpart to `errors[]`, populated via `ctx.enrich(...)` — reaches both automatically: merged into `structuredContent`, advertised as `output.extend(enrichment)`, mirrored into a `content[]` trailer, no `format()` entry needed. How each field renders in that trailer is a per-tool call — a kind-tag (`notice`/`total`/`echo`/`delta`) when a canonical form fits, a domain key like `totalFound` otherwise, and an `enrichmentTrailer.render` for any structured (object/array) field so it doesn't ship as a JSON blob. See `add-tool`'s **Tool Response Design**.

package/skills/orchestrations/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   author: cyanheads
   version: "1.2"
-  audience: internal
+  audience: external
   type: workflow
 ---
 

package/skills/orchestrations/workflows/field-test-fix.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   author: cyanheads
   version: "1.0"
-  audience: internal
+  audience: external
   type: workflow
 ---
 

package/skills/orchestrations/workflows/fix-wrapup-release.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   author: cyanheads
   version: "1.0"
-  audience: internal
+  audience: external
   type: workflow
 ---
 

package/skills/orchestrations/workflows/greenfield-build.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   author: cyanheads
   version: "1.0"
-  audience: internal
+  audience: external
   type: workflow
 ---
 

package/skills/orchestrations/workflows/maintenance-release.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   author: cyanheads
   version: "1.1"
-  audience: internal
+  audience: external
   type: workflow
 ---
 

package/skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.8"
+  version: "2.9"
   audience: external
   type: workflow
 ---
@@ -174,6 +174,7 @@ Derive:
 
 ```bash
 docker buildx build --platform linux/amd64,linux/arm64 \
+  --build-arg APP_VERSION=<VERSION> \
   -t ghcr.io/<OWNER>/<REPO>:<VERSION> \
   -t ghcr.io/<OWNER>/<REPO>:latest \
   --push .

package/skills/techniques/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: techniques
+description: >
+  Catalog of reusable response- and data-shaping techniques for MCP servers built on `@cyanheads/mcp-ts-core` — overflow handling, payload shaping, retrieval patterns. Use when a tool's payload is too large, awkwardly shaped, or expensive to retrieve and you want a proven pattern instead of inventing one. Each technique has a self-contained reference under `references/`.
+metadata:
+  author: cyanheads
+  version: "0.1"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+A directory of cross-cutting techniques for shaping what a handler returns and how a client retrieves it — patterns that don't belong to a single API surface. Each entry is a self-contained reference under `references/`: the problem it solves, when to reach for it (and when not to), and how to apply it with current framework primitives.
+
+These are **patterns, not new primitives** — they compose `tool()`, discriminated-union `output`, `ctx.state`, and the existing helpers. Where a technique has (or will have) a dedicated helper, its reference says so and links the tracking issue.
+
+## Techniques
+
+| Technique | Path | Use when |
+|:----------|:-----|:---------|
+| Outline-on-overflow | `references/outline-on-overflow.md` | A single tool call returns one **document-shaped** payload too big to inline (e.g. a ~130KB record), and you want an honest section outline + a re-call contract instead of truncating. |
+
+## Adding a technique
+
+One file under `references/`, one row above. A technique earns a place here when it's a reusable response/retrieval pattern that (a) spans more than one tool or server and (b) isn't already covered by an `api-*` reference. Keep the reference concise: problem → when-to-use → how-to with current primitives → helper status. Bump `metadata.version` on any change (skill-versioning policy).
+
+## Related
+
+- `design-mcp-server` — choosing the tool surface and output shapes up front.
+- `add-tool` — the `tool()` builder, `format()` ⟷ `structuredContent` parity, matching response density to context budget.
+- `api-canvas` — `spillover()`, the row-collection sibling of outline-on-overflow.

package/skills/techniques/references/outline-on-overflow.md

@@ -0,0 +1,124 @@
+# Outline-on-overflow
+
+Return a section **outline** when a single document-shaped payload is too big to inline, and let the agent re-call the same tool for only the sections it needs. The honest alternative to truncation for the *one fat document* case.
+
+Ships as `outlineOnOverflow` + friends in `@cyanheads/mcp-ts-core/utils`.
+
+## The problem
+
+Some tools fetch one large **document-shaped** record. An FDA drug label is a single ~130KB / ~32K-token payload dominated by raw HTML sections. Returning it whole burns the agent's context; truncating it either hides data or — when only `format()` is trimmed — silently desyncs `content[]` from `structuredContent`. Neither is acceptable.
+
+This is distinct from the other two overflow shapes:
+
+| Shape | Technique |
+|:--|:--|
+| Many rows (tabular) | `spillover()` → DataCanvas SQL handle (see `api-canvas`) |
+| Capped list | honest truncation disclosure |
+| **One large document** | **outline-on-overflow (this file)** |
+
+## Philosophy
+
+**Never truncate to fit a budget.** When a payload is too big, return a complete, honest outline of what's available plus how to retrieve it — identically on `content[]` and `structuredContent`.
+
+## The shape — a discriminated-union `output`
+
+The outline is the payload the agent acts on, so it lands in the **main body** (`structuredContent` + `content[]`), as a variant of the tool's own `output`. Not the enrichment block — enrichment is *additive* (`output.extend(...)` merged after `output.parse(result)`), so it can add fields to the fat document but never replace it. Not a post-hoc framework swap either — that would emit a `structuredContent` shape the advertised `outputSchema` (`tools/list`) doesn't describe. A discriminated-union variant is the only placement that replaces the payload, is advertised honestly, and gets `format()`-parity for free.
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import {
+  OUTLINE_VARIANT,
+  outlineOnOverflow,
+  selectSections,
+  formatOutline,
+} from '@cyanheads/mcp-ts-core/utils';
+
+const FullLabel = z.object({ /* every section field */ });
+
+export const getLabel = tool('get_label', {
+  description: 'Fetch a drug label. Returns the full record, or a section outline when it overflows.',
+  input: z.object({
+    query: z.string().describe('Label query'),
+    sections: z
+      .array(z.string())
+      .optional()
+      .describe('Sections to return. Omit for the full label (or an outline if it overflows).'),
+  }),
+  output: z.discriminatedUnion('kind', [
+    FullLabel.extend({ kind: z.literal('full') }),
+    OUTLINE_VARIANT,
+  ]),
+  format: (r) => (r.kind === 'outline' ? formatOutline(r) : renderLabel(r)),
+  async handler(input) {
+    const doc = await fetchLabel(input.query); // deterministic from query
+    if (input.sections?.length) {
+      // selection path — slice to requested keys plus always-kept metadata
+      return { ...selectSections(doc, input.sections, { alwaysKeep: ['id', 'set_id'] }), kind: 'full' as const };
+    }
+    return outlineOnOverflow(doc, { budget: 24_000 }); // disclosure path → full | outline
+  },
+});
+```
+
+`format()`-parity is enforced **per branch** — the linter walks each discriminated-union arm separately, so both `full` and `outline` must render. `formatOutline` is the shipped renderer for the `outline` arm; you supply the `full` renderer. That keeps the two client surfaces in lockstep with no extra work.
+
+## The helper
+
+`@cyanheads/mcp-ts-core/utils` ships the whole pattern — pure measurement + key-slicing, no DuckDB, so it runs on stdio / HTTP / Workers alike:
+
+| Export | Purpose |
+|:--|:--|
+| `outlineOnOverflow(doc, options?)` | Returns `{ kind: 'full', ...doc }` under budget (or with `< 2` sections), else `{ kind: 'outline', sections, notice }`. |
+| `OUTLINE_VARIANT` | The reusable `outline`-arm Zod schema for your discriminated-union `output`. |
+| `selectSections(doc, want, { alwaysKeep })` | Projects the document to requested keys plus always-kept metadata. The selection-path counterpart. |
+| `formatOutline(outline)` | Renders the outline to `content[]` for `format()`. |
+| `DEFAULT_OUTLINE_BUDGET_BYTES` | The default budget (`24_000`) when `options.budget` is omitted. |
+
+`outlineOnOverflow` options:
+
+- `budget` — serialized-byte threshold (default `DEFAULT_OUTLINE_BUDGET_BYTES`). A helper argument, **not** an env var: a deploy-tunable threshold would drift a tool's output *shape* across environments.
+- `extract` — custom section extractor. Default: one section per top-level key, sized by `JSON.stringify(value).length`. Override only when "section" means something other than a top-level key.
+- `notice` — custom re-call notice builder. Default names the three largest sections as examples.
+
+The flow:
+
+1. **Measure** the serialized payload (`JSON.stringify(doc).length`).
+2. **Under budget** → `{ kind: 'full', ...doc }`.
+3. **Over budget, ≥ 2 sections** → the outline (sections sorted largest-first). The agent re-calls with `sections: [...]`.
+4. **Over budget, < 2 sections** → `full` anyway (nothing to pick between). A single section that *alone* exceeds budget is a known limitation — sub-section outlining is out of scope.
+
+## Re-retrieval — why the selection call is stateless
+
+The re-call is **self-contained**, so nothing is stored between the outline call and the selection call:
+
+- The selection call sends the **same input** as the outline call, plus `sections: [...]`.
+- The handler **re-fetches** the document — input-minus-`sections` is identical and the upstream query is deterministic, so it reproduces the exact same record — then applies `selectSections` (a pure projection: requested keys + `alwaysKeep` metadata).
+- You **reconstruct rather than remember**. The agent holds the continuity (it passes `sections`); the upstream holds the document.
+
+The only cost is the redundant fetch. For a **rate-limited or expensive upstream**, trade it for an optional cache:
+
+```ts
+const key = `label:${input.query}`;                          // NOTE: excludes `sections`
+let doc = await ctx.state.get<Label>(key).catch(() => null); // best-effort read
+if (!doc) {
+  doc = await fetchLabel(input.query);
+  await ctx.state.set(key, doc, { ttl: 300 }).catch(() => {}); // best-effort write, 5 min
+}
+```
+
+- **Key excludes the `sections` selector** — otherwise the outline call and the selection call compute different keys and never share the doc.
+- **Best-effort** — a miss or a read/write failure falls through to the stateless refetch, so correctness never depends on the cache.
+- Rides `ctx.state` (the tenant-scoped KV abstraction), which is **independent of `MCP_SESSION_MODE`**. It does *not* require switching the server to stateful sessions and has no end-user-visible effect (a miss behaves exactly like the stateless path). Tenant-scoping isolates per-identity under `jwt`/`oauth`; the shared `default` tenant (stdio, HTTP + `none`) is benign because the cached value is a deterministic public-query → document map, not user state. If the upstream itself returns identity-scoped data, fold the auth principal into the key.
+
+The framework ships no cache-key helper — the pattern above is one line and tool-specific (which fields key the doc, what TTL). **Default to stateless.** Reach for the cache only where the upstream cost is real.
+
+## When to use
+
+- A single tool result is one **document-shaped** record that can exceed a context-meaningful size.
+- The record has addressable parts (top-level sections) the agent can choose among.
+
+## When not to
+
+- **Many rows** → `spillover()`. The document here is one row; spilling rows leaves the per-record size intact.
+- **A capped list** → truncation disclosure.
+- **No meaningful sub-structure** to outline → there's nothing to pick. Return it, or shrink it at the source (drop redundant fields before measuring).

package/templates/AGENTS.md

@@ -13,7 +13,7 @@
 
 ## First Session
 
-This project was just scaffolded with `bunx @cyanheads/mcp-ts-core init`. The framework, skills, and example definitions are in place — the domain isn't. The user's first messages will set direction; wait for them before proceeding.
+This project was just scaffolded with `bunx @cyanheads/mcp-ts-core init`. You're holding a production-grade MCP framework with the hard parts already solved — error handling, telemetry, auth, transport, validation, lifecycle. What's missing is the **domain**. Your job: design the tool, resource, and service surface with the user, then implement it as small pure handlers that throw — the framework catches, classifies, and instruments the rest. Design before code; the user's first messages set direction, so wait for them before scaffolding definitions.
 
 > **Remove this section** from CLAUDE.md / AGENTS.md after completing these steps. The skills and conventions below remain — this block is one-time onboarding only.
 
@@ -138,6 +138,7 @@ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
   apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
+  verboseLogging: z.stringbool().default(false).describe('Enable verbose logging'),
 });
 
 let _config: z.infer<typeof ServerConfigSchema> | undefined;
@@ -145,6 +146,7 @@ export function getServerConfig() {
   _config ??= parseEnvConfig(ServerConfigSchema, {
     apiKey: 'MY_API_KEY',
     maxResults: 'MY_MAX_RESULTS',
+    verboseLogging: 'MY_VERBOSE_LOGGING',
   });
   return _config;
 }
@@ -152,6 +154,8 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
 
+For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
+
 ### Server instructions
 
 `createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
@@ -279,6 +283,7 @@ Available skills:
 | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
 | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
+| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -293,6 +298,8 @@ Available skills:
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
 
+**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
+
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
 ---

package/templates/CLAUDE.md

@@ -13,7 +13,7 @@
 
 ## First Session
 
-This project was just scaffolded with `bunx @cyanheads/mcp-ts-core init`. The framework, skills, and example definitions are in place — the domain isn't. The user's first messages will set direction; wait for them before proceeding.
+This project was just scaffolded with `bunx @cyanheads/mcp-ts-core init`. You're holding a production-grade MCP framework with the hard parts already solved — error handling, telemetry, auth, transport, validation, lifecycle. What's missing is the **domain**. Your job: design the tool, resource, and service surface with the user, then implement it as small pure handlers that throw — the framework catches, classifies, and instruments the rest. Design before code; the user's first messages set direction, so wait for them before scaffolding definitions.
 
 > **Remove this section** from CLAUDE.md / AGENTS.md after completing these steps. The skills and conventions below remain — this block is one-time onboarding only.
 
@@ -138,6 +138,7 @@ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
   apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
+  verboseLogging: z.stringbool().default(false).describe('Enable verbose logging'),
 });
 
 let _config: z.infer<typeof ServerConfigSchema> | undefined;
@@ -145,6 +146,7 @@ export function getServerConfig() {
   _config ??= parseEnvConfig(ServerConfigSchema, {
     apiKey: 'MY_API_KEY',
     maxResults: 'MY_MAX_RESULTS',
+    verboseLogging: 'MY_VERBOSE_LOGGING',
   });
   return _config;
 }
@@ -152,6 +154,8 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
 
+For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
+
 ### Server instructions
 
 `createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
@@ -279,6 +283,7 @@ Available skills:
 | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
 | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
+| `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -293,6 +298,8 @@ Available skills:
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
 
+**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
+
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
 ---

package/templates/Dockerfile

@@ -37,9 +37,12 @@ WORKDIR /usr/src/app
 ENV NODE_ENV=production
 
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+ARG APP_VERSION
 LABEL org.opencontainers.image.title="{{PACKAGE_NAME}}"
 LABEL org.opencontainers.image.description=""
 LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+LABEL org.opencontainers.image.source=""
 
 # Copy dependency manifests
 COPY package.json bun.lock ./