@cyanheads/mcp-ts-core 0.7.6 → 0.8.1

package/skills/field-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.1"
   audience: external
   type: debug
 ---
@@ -27,14 +27,20 @@ Write the helper to `/tmp/mcp-field-test.sh` once, then source it in every subse
 cat > /tmp/mcp-field-test.sh <<'HELPER_EOF'
 #!/bin/bash
 # Field-test helper: manage an MCP HTTP server + JSON-RPC session across shell calls.
+# Surfaces failures aggressively — field test is for finding things that fail,
+# so the helper auto-tails logs and prints HTTP status/body on errors instead
+# of swallowing them.
 STATE_FILE="/tmp/mcp-field-test.env"
 [ -f "$STATE_FILE" ] && . "$STATE_FILE"
 
 mcp_start() {
   local dir="${1:-$PWD}"
   echo "building $dir ..."
-  (cd "$dir" && bun run rebuild) >/tmp/mcp-build.log 2>&1 \
-    || { echo "BUILD FAILED — see /tmp/mcp-build.log"; return 1; }
+  if ! (cd "$dir" && bun run rebuild) >/tmp/mcp-build.log 2>&1; then
+    echo "BUILD FAILED — last 30 lines of /tmp/mcp-build.log:"
+    tail -30 /tmp/mcp-build.log
+    return 1
+  fi
   echo "starting server ..."
   (cd "$dir" && bun run start:http) >/tmp/mcp-server.log 2>&1 &
   local pid=$!
@@ -45,7 +51,8 @@ mcp_start() {
     sleep 0.25
   done
   if [ -z "$line" ]; then
-    echo "server failed to start — see /tmp/mcp-server.log"
+    echo "server failed to start within 10s — last 30 lines of /tmp/mcp-server.log:"
+    tail -30 /tmp/mcp-server.log
     kill "$pid" 2>/dev/null
     return 1
   fi
@@ -63,12 +70,21 @@ EOF
 mcp_init() {
   [ -z "$MCP_URL" ] && { echo "run mcp_start first"; return 1; }
   local hdr="/tmp/mcp-init-headers.txt"
-  curl -sS -D "$hdr" -X POST "$MCP_URL" \
+  local body_file="/tmp/mcp-init-body.txt"
+  local status
+  status=$(curl -sS -D "$hdr" -o "$body_file" -w '%{http_code}' -X POST "$MCP_URL" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
-    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.0"}}}' >/dev/null
+    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.1"}}}')
   local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
-  [ -z "$sid" ] && { echo "no session id returned"; return 1; }
+  if [ -z "$sid" ]; then
+    echo "init failed — HTTP $status, no Mcp-Session-Id header returned"
+    echo "--- response body ---"
+    cat "$body_file"
+    echo "--- response headers ---"
+    cat "$hdr"
+    return 1
+  fi
   cat > "$STATE_FILE" <<EOF
 export MCP_PID=$MCP_PID
 export MCP_URL=$MCP_URL
@@ -81,11 +97,13 @@ EOF
     -H "Accept: application/json, text/event-stream" \
     -H "Mcp-Session-Id: $sid" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
-  echo "session=$sid"
+  echo "session=$sid (HTTP $status)"
 }
 
 # Usage: mcp_call METHOD [JSON_PARAMS]
-# Prints the JSON-RPC response (SSE framing stripped). Pipe to `jq`.
+# Prints the JSON-RPC response. SSE framing is stripped when present; on
+# non-SSE responses the raw body is printed instead so plain-JSON error
+# replies (HTTP 4xx/5xx) still surface. Pipe to `jq`.
 mcp_call() {
   [ -z "$MCP_SID" ] && { echo "run mcp_init first"; return 1; }
   local method="$1"; local params="${2:-}"
@@ -95,17 +113,57 @@ mcp_call() {
   else
     body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s","params":%s}' "$RANDOM" "$method" "$params")
   fi
-  curl -sS -X POST "$MCP_URL" \
+  local resp_file="/tmp/mcp-call-body.txt"
+  local status
+  status=$(curl -sS -o "$resp_file" -w '%{http_code}' -X POST "$MCP_URL" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Mcp-Session-Id: $MCP_SID" \
-    -d "$body" | sed -n 's/^data: //p'
+    -d "$body")
+  if [ "$status" -ge 400 ]; then
+    echo "HTTP $status from $method — response:" >&2
+    cat "$resp_file" >&2
+    return 1
+  fi
+  local sse; sse=$(sed -n 's/^data: //p' "$resp_file")
+  if [ -n "$sse" ]; then
+    printf '%s\n' "$sse"
+  else
+    cat "$resp_file"
+  fi
+}
+
+# Tail the server log. Useful when a call surprises you — pino startup banner,
+# definition lint diagnostics, request handler errors, upstream calls, and
+# rate-limit warnings live in /tmp/mcp-server.log.
+# Usage: mcp_log [N]   (default: 50 lines)
+mcp_log() {
+  local n="${1:-50}"
+  tail -n "$n" /tmp/mcp-server.log
 }
 
 mcp_stop() {
-  [ -n "$MCP_PID" ] && kill "$MCP_PID" 2>/dev/null
+  if [ -z "$MCP_PID" ]; then
+    rm -f "$STATE_FILE"
+    echo "no PID to stop"
+    return 0
+  fi
+  kill "$MCP_PID" 2>/dev/null
+  for _ in $(seq 1 12); do
+    kill -0 "$MCP_PID" 2>/dev/null || break
+    sleep 0.25
+  done
+  if kill -0 "$MCP_PID" 2>/dev/null; then
+    echo "PID $MCP_PID didn't exit on SIGTERM — sending SIGKILL"
+    kill -9 "$MCP_PID" 2>/dev/null
+    sleep 0.5
+  fi
+  if kill -0 "$MCP_PID" 2>/dev/null; then
+    echo "WARNING: PID $MCP_PID still alive after SIGKILL"
+  else
+    echo "stopped pid=$MCP_PID"
+  fi
   rm -f "$STATE_FILE"
-  echo "stopped"
 }
 HELPER_EOF
 
@@ -132,8 +190,8 @@ Runs `initialize`, captures the session id, sends `notifications/initialized`.
 
 ```bash
 . /tmp/mcp-field-test.sh
-mcp_call tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema}'
-mcp_call resources/list | jq '.result.resources[] | {uri, name, mimeType}'
+mcp_call tools/list     | jq '.result.tools[]     | {name, description, inputSchema, outputSchema, errors: ._meta["mcp-ts-core/errors"]}'
+mcp_call resources/list | jq '.result.resources[] | {uri, name, mimeType, errors: ._meta["mcp-ts-core/errors"]}'
 mcp_call prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
 ```
 
@@ -171,6 +229,8 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 | Hits external API / live upstream | One call that exercises upstream; note rate-limit / timeout / transient-failure behavior |
 | Chained with other tools (search → detail → act) | Run one representative chain end-to-end; does each step return the IDs/cursors the next needs? |
 | `cursor` / `offset` / `limit` params | Pagination: second page, end-of-list |
+| Tool declared an `errors: [...]` contract | Error contract (tool): trigger ≥1 declared failure mode. Verify `result._meta.error.code` matches the contract entry, `result._meta.error.data.reason` is the declared reason (only present when the handler threw an `McpError` — `ctx.fail` always does, plain `throw new Error(...)` does not), and `content[0].text` is actionable. Reasons declared but unreachable from any input are dead contract entries. |
+| Resource declared an `errors: [...]` contract | Error contract (resource): trigger ≥1 declared failure mode by reading a URI that exercises it. Resources re-throw errors at the JSON-RPC level — verify `error.code` matches the contract entry and `error.data.reason` is the declared reason. (Resources don't use the `result.isError` envelope — they fail the request itself.) |
 
 **Resources.** Happy path, not-found URI, `list` if defined, pagination if used.
 **Prompts.** Happy path, defaults omitted, skim message quality.
@@ -188,9 +248,13 @@ Use `TaskCreate` — one task per definition. Mark complete as you go. Don't bat
 
 For each call, capture: input sent, response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
 
+When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/mcp-field-test.sh && mcp_log` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in `/tmp/mcp-server.log` rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone.
+
 **Interpreting responses**
 
 - Tool domain errors return `{result: {content: [...], isError: true}}` — they live in `result`, not `error`. Check `isError`, not the JSON-RPC error field.
+- **Tool error code/reason** rides on `result._meta.error.{code, data.reason}` — inspect that, not just the text. `data` is only spread when the handler threw an `McpError` (or `ZodError`); plain `throw new Error(...)` won't populate `data.reason`. Use `ctx.fail`-thrown errors when the contract reason matters.
+- **Resource errors** are JSON-RPC-level — they appear in the top-level `error.{code, data.reason}` field, not inside `result`. Resource handlers re-throw rather than producing an `isError` envelope.
 - JSON-RPC `error` only appears for protocol issues (bad session, malformed envelope, unknown method).
 - `mcp_call` already strips SSE framing. Pipe to `jq` for readability.
 
@@ -253,6 +317,8 @@ End with:
 - [ ] Catalog surfaced and presented; descriptions audited for leaks (implementation details, meta-coaching, consumer-aware phrasing)
 - [ ] Universal battery run on every definition
 - [ ] Situational categories applied only when triggered
+- [ ] **If a tool declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; `result._meta.error.code` and `data.reason` verified against the contract entry
+- [ ] **If a resource declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; top-level JSON-RPC `error.code` and `error.data.reason` verified against the contract entry
 - [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
 - [ ] Server stopped; state file removed
 - [ ] Report: summary paragraph → grouped findings → numbered options

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -50,6 +50,8 @@ Do not redo this investigation inline — the `changelog` skill handles tag-form
 
 ### 4. Framework review (`@cyanheads/mcp-ts-core`)
 
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`'s `version` exceeds the one running, run Step 5 Phase A first and re-invoke `maintenance` — otherwise feature-adoption rows added in the new version silently don't surface.
+
 If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. The framework ships a **directory-based changelog** grouped by minor series (`.x` semver-wildcard convention) — one file per released version at `node_modules/@cyanheads/mcp-ts-core/changelog/<major.minor>.x/<version>.md`. Read only the files between old and new rather than scanning a monolithic file.
 
 Example — `0.5.2 → 0.5.4` means reading two new version files:
@@ -65,7 +67,8 @@ Scan specifically for:
 
 | Area | Adoption Check |
 |:-----|:---------------|
-| New error factories in `/errors` | Replace ad-hoc `new McpError(...)` with factories where applicable |
+| New `/errors` surface — factories, typed contracts (`errors[]` + `ctx.fail`), `httpErrorFromResponse` | Replace ad-hoc `new McpError(...)` with factories; declare `errors: [...]` on tools that surface domain-specific failure modes; route declared throws through `ctx.fail(reason, …)` so the conformance lint is happy |
+| Existing factory choice — semantic audit | Beyond factory-vs-`new McpError`: audit each `throw factory(...)` against intent. `invalidParams` (-32602) is for malformed JSON-RPC params (wrong-shape post-Zod is rare); semantic post-shape validation should use `validationError` (-32007). `notFound` for missing entities, `conflict` for state collisions, `unauthorized` vs `forbidden` for unauth vs scope-denied. Wrong codes degrade `mcp_error_classified_code` observability and break client retry logic — fix during this pass even if not adopting contracts yet. |
 | New utilities in `/utils` | Identify any that supersede local helper code |
 | New context capabilities | Added `ctx.*` methods worth adopting |
 | Provider/service APIs | Updates to `OpenRouterProvider`, `SpeechService`, `GraphService`, etc. |

package/skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: workflow
 ---
@@ -141,7 +141,7 @@ Format: `bug(<scope>): concise description`
 | `prompt` | Prompt builder, generate, args |
 | `context` | Context, logger, state, progress, elicit, sample |
 | `config` | AppConfig, parseConfig, env parsing |
-| `errors` | McpError, error factories, auto-classification |
+| `errors` | McpError, error factories, typed contracts (`errors[]` / `ctx.fail`), conformance lint, `httpErrorFromResponse`, auto-classification |
 | `auth` | Auth modes, scope checking, JWT/OAuth |
 | `storage` | StorageService, providers |
 | `transport` | stdio/http transport, SSE, session handling |

package/skills/security-pass/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / sampling / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: audit
 ---
@@ -203,10 +203,10 @@ grep -rn "^let " src/services/
 
 What accidentally reaches the LLM, user, or observability sinks.
 
-**Look in:** `throw new McpError(...)` sites, `McpError.data` fields, output schemas, and every logging / telemetry surface — not just `ctx.log`.
+**Look in:** `throw new McpError(...)` and `ctx.fail(reason, msg, data)` sites, error factory calls (`notFound`, `httpErrorFromResponse`, …), `McpError.data` fields (the `data` arg flows through both paths), output schemas, and every logging / telemetry surface — not just `ctx.log`.
 
 ```bash
-grep -rn "new McpError" src/
+grep -rnE "new McpError|ctx\.fail\(|httpErrorFromResponse\(" src/
 grep -rnE "\b(ctx\.log|console\.(log|info|warn|error|debug)|logger\.)" src/
 grep -rnE "(Sentry\.|captureException|setTag|setContext|addBreadcrumb)" src/
 grep -rnE "(setAttribute|setAttributes|span\.)" src/  # OpenTelemetry
@@ -214,7 +214,8 @@ grep -rnE "(setAttribute|setAttributes|span\.)" src/  # OpenTelemetry
 
 **Check:**
 
-- Error `data` fields carry upstream response bodies, auth headers, stack traces?
+- Error `data` fields (whether passed via `ctx.fail(reason, msg, data)`, `new McpError(code, msg, data)`, or factory calls) carry upstream response bodies, auth headers, stack traces?
+- `httpErrorFromResponse` body capture sweeping in too much (default 500-byte cap is fine for most APIs but consider `captureBody: false` when the upstream returns auth-bearing payloads)?
 - Output schemas include token prefixes, internal IDs, session identifiers?
 - `format()` renders fields that shouldn't leave the server?
 - `ctx.log.info(msg, body)` where `body` is the raw request (may contain secrets)?
@@ -222,7 +223,7 @@ grep -rnE "(setAttribute|setAttributes|span\.)" src/  # OpenTelemetry
 - OpenTelemetry span attributes / Sentry breadcrumbs carry tokens, PII, or full request bodies?
 - Secret / token / HMAC comparisons use `===` or `==` instead of constant-time (`timingSafeEqual` / `crypto.timingSafeEqual`) — leaks length and prefix via timing?
 
-**Smell:** `throw new McpError(code, upstream.message, { raw: upstream.body })`. Or: `if (apiKey === expected)` on a request-auth path.
+**Smell:** `throw new McpError(code, upstream.message, { raw: upstream.body })` or `throw ctx.fail('upstream_failed', e.message, { raw: e.response.body })`. Or: `if (apiKey === expected)` on a request-auth path.
 
 #### Axis 8 — Resource bounds
 

package/templates/AGENTS.md

@@ -165,24 +165,39 @@ Handlers receive a unified `ctx` object. Key properties:
 
 ## Errors
 
-Handlers throw — the framework catches, classifies, and formats. Three escalation levels:
+Handlers throw — the framework catches, classifies, and formats.
+
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, retryable? }]` on `tool()` / `resource()` to advertise the failure surface in `tools/list` (under `_meta['mcp-ts-core/errors']`) and receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
-// 1. Plain Error — framework auto-classifies from message patterns
-throw new Error('Item not found');           // → NotFound
-throw new Error('Invalid query format');     // → ValidationError
+errors: [
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query' },
+],
+async handler(input, ctx) {
+  const item = await db.find(input.id);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  return item;
+}
+```
 
-// 2. Error factories — explicit code, concise
-import { notFound, validationError, forbidden, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+**Fallback (no contract entry fits):** throw via factories or plain `Error`.
+
+```ts
+// Error factories — explicit code
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw notFound('Item not found', { itemId });
 throw serviceUnavailable('API unavailable', { url }, { cause: err });
 
-// 3. McpError — full control over code and data
+// Plain Error — framework auto-classifies from message patterns
+throw new Error('Item not found');           // → NotFound
+throw new Error('Invalid query format');     // → ValidationError
+
+// McpError — when no factory exists for the code
 import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
 ```
 
-Plain `Error` is fine for most cases. Use factories when the error code matters. See framework CLAUDE.md for the full auto-classification table and all available factories.
+See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
 
 ---
 

package/templates/CLAUDE.md

@@ -165,24 +165,39 @@ Handlers receive a unified `ctx` object. Key properties:
 
 ## Errors
 
-Handlers throw — the framework catches, classifies, and formats. Three escalation levels:
+Handlers throw — the framework catches, classifies, and formats.
+
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, retryable? }]` on `tool()` / `resource()` to advertise the failure surface in `tools/list` (under `_meta['mcp-ts-core/errors']`) and receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
-// 1. Plain Error — framework auto-classifies from message patterns
-throw new Error('Item not found');           // → NotFound
-throw new Error('Invalid query format');     // → ValidationError
+errors: [
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound, when: 'No item matched the query' },
+],
+async handler(input, ctx) {
+  const item = await db.find(input.id);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  return item;
+}
+```
 
-// 2. Error factories — explicit code, concise
-import { notFound, validationError, forbidden, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+**Fallback (no contract entry fits):** throw via factories or plain `Error`.
+
+```ts
+// Error factories — explicit code
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw notFound('Item not found', { itemId });
 throw serviceUnavailable('API unavailable', { url }, { cause: err });
 
-// 3. McpError — full control over code and data
+// Plain Error — framework auto-classifies from message patterns
+throw new Error('Item not found');           // → NotFound
+throw new Error('Invalid query format');     // → ValidationError
+
+// McpError — when no factory exists for the code
 import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
 ```
 
-Plain `Error` is fine for most cases. Use factories when the error code matters. See framework CLAUDE.md for the full auto-classification table and all available factories.
+See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
 
 ---
 

package/templates/changelog/template.md

@@ -2,7 +2,7 @@
 # FORMAT REFERENCE — this file is never edited, never moved, never renamed.
 #
 # At release time, author a new per-version file at:
-#   changelog/<major.minor>.x/<version>.md   (e.g. changelog/0.1.x/0.1.0.md)
+#   changelog/<major.minor>.x/<version>.md   (e.g. changelog/0.6.x/0.6.6.md)
 # using this file's frontmatter and section layout as the starting point.
 # Set that new file's H1 to `# <version> — YYYY-MM-DD` with a concrete date.
 
@@ -27,16 +27,29 @@ breaking: false
 
   Optional narrative intro — 1-3 sentences framing the release theme. Delete if not needed.
 
+  TONE: terse and fact-dense. 1-2 sentence(s) per bullet where possible —
+  name the symbol, state what changed, stop. Drop "explains how it works" prose;
+  that belongs in JSDoc, AGENTS.md, or the relevant skill. Drop ceremonial
+  framings ("This release introduces…", "fully backwards compatible:" with a
+  paragraph of justification). Prefer code/symbol names over English
+  re-explanations. If a bullet runs more than ~2 lines, split it or cut it.
+
+  WHAT TO INCLUDE: every distinct fact a reader needs to adopt or audit the
+  release — new exports, signatures, lint rule IDs, env vars, breaking
+  changes, version bumps on shipped skills. WHAT TO CUT: mechanism walkthroughs,
+  duplicate prose between Added and Changed, file-by-file test enumerations,
+  internal implementation notes. Trust the reader to read the code or the docs.
+
   Linking issues/PRs: use full URLs so the link works everywhere (GitHub web UI,
   npm/node_modules reads, local editors). GitHub's bare `#NN` auto-link only
   resolves inside its own UI.
 
-    [#12](https://github.com/<owner>/<repo>/issues/12)   ← issue
-    [#17](https://github.com/<owner>/<repo>/pull/17)     ← PR
+    [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+    [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
 
   Only link numbers you've verified exist (via `gh issue view NN` or
-  `gh pr view NN`). Never speculate on a future number — `#17` for "my
-  upcoming PR" will quietly resolve to whatever real item already owns 17,
+  `gh pr view NN`). Never speculate on a future number — `#42` for "my
+  upcoming PR" will quietly resolve to whatever real item already owns 42,
   and GitHub timeline previews will pull in that unrelated item's title.
 -->