@cyanheads/whois-mcp-server 0.1.3 → 0.1.5

package/Dockerfile

@@ -4,15 +4,17 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1.3 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
 
 WORKDIR /usr/src/app
 
 # Copy dependency manifests for optimized layer caching
 COPY package.json bun.lock ./
 
-# Install all dependencies (including dev dependencies for building)
-RUN bun install --frozen-lockfile
+# Install all dependencies (including dev dependencies for building).
+# The BuildKit cache mount persists Bun's global package cache across builds.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --ignore-scripts
 
 # Copy the rest of the source code
 COPY . .
@@ -28,7 +30,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.3-slim AS production
+FROM oven/bun:1.4.0-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -49,14 +51,21 @@ COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
-RUN bun install --production --frozen-lockfile --ignore-scripts
+# `--omit=peer` drops the framework's optional peer tiers (test runner, service
+# SDKs, parsers) that Bun would otherwise auto-install. Anything this server
+# actually imports belongs in its own `dependencies`, so nothing needed at
+# runtime is lost. The OTEL step below carries the same flag — without it, that
+# install re-resolves the graph and pulls every optional peer back in.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
 # with: docker build --build-arg OTEL_ENABLED=true
 ARG OTEL_ENABLED=true
-RUN if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add @hono/otel \
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    if [ "$OTEL_ENABLED" = "true" ]; then \
+      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \

package/LICENSE

@@ -186,7 +186,7 @@ Apache License
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Casey Hand @cyanheads
+   Copyright 2026 Casey Hand @cyanheads
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/whois-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/whois-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/whois-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.1.5-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/whois-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/whois-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/whois-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -21,9 +21,11 @@
 
 ---
 
-## Tools
+## Overview
 
-Six tools covering domain intelligence, DNS, and IP/ASN resolution:
+Domain and network intelligence via RDAP and DNS-over-HTTPS. Look up domain registrations, check availability, fetch DNS records, and resolve IPs and ASNs to their registries — all via public, keyless data sources. Runs as a stdio process or a local Streamable HTTP server.
+
+### Tools
 
 | Tool | Description |
 |:-----|:------------|
@@ -34,97 +36,84 @@ Six tools covering domain intelligence, DNS, and IP/ASN resolution:
 | `whois_lookup_asn` | Resolve an ASN to its org name, country, and RIR source |
 | `whois_get_dossier` | One-call domain triage — registration + DNS in parallel, normalized into a single record with factual signals |
 
-### `whois_lookup_domain`
+---
+
+## Capability reference
 
-Look up a domain's full RDAP registration record.
+### `whois_lookup_domain` <sub>tool</sub>
 
 - RDAP-first via IANA auto-bootstrap — automatically selects the correct registry RDAP server per TLD
-- Returns registrar, creation/expiry dates, nameservers, EPP status codes, DNSSEC delegation flag
-- Surfaces `registrant_redacted: true` explicitly when privacy redaction is in effect (standard post-GDPR for gTLDs)
-- Returns `rdap_coverage: false` for TLDs without RDAP coverage rather than silently failing
-- Includes `last_update_of_rdap_db` event timestamp for data freshness transparency
+- Returns registrar, creation/expiry dates, nameservers, EPP status codes, and DNSSEC delegation flag
+- Surfaces `registrant_redacted: true` when privacy redaction is in effect (standard post-GDPR for gTLDs)
+- Throws `rdap_no_coverage` when the TLD has no RDAP server in the IANA bootstrap — use `whois_check_availability` instead
+- Throws `domain_not_found` on an RDAP 404 (domain not registered) — use `whois_check_availability` to confirm
 
 ---
 
-### `whois_check_availability`
+### `whois_check_availability` <sub>tool</sub>
 
-Check whether a domain name is registered or available to register.
-
-- RDAP 404 = available (`available: true`) — exploits the RDAP spec's intended behavior
-- Returns `available: false` with `registrar` and `expiry_date` when registered
-- Returns `available: null` with `rdap_coverage: false` for TLDs without RDAP — cannot determine availability
-- Optimized for bulk name sweeps — thin response, no unnecessary fields
+- RDAP 404 response maps to `available: true`
+- Registered domains return `available: false` with `registrar` and `expiry_date`
+- `available: null` with `rdap_coverage: false` when the TLD has no RDAP coverage — availability cannot be determined
+- Thin response optimized for bulk name sweeps — no extra fields
 
 ---
 
-### `whois_get_dns`
-
-Fetch DNS records via DNS-over-HTTPS.
+### `whois_get_dns` <sub>tool</sub>
 
-- Cloudflare `1.1.1.1` primary, Google `8.8.8.8` fallback (used for CAA records where Cloudflare returns raw hex)
-- Supports A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR — multiple types in one call
-- Returns records with TTLs and the resolving source (`cloudflare` or `google`)
-- `nxdomain: true` in result (not an error) when the domain doesn't exist in DNS
+- Supports A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR; multiple types fetched in parallel; defaults to A, AAAA, MX, TXT, NS when `types` is omitted
+- Cloudflare primary, NextDNS fallback per type (CAA always uses NextDNS — Cloudflare returns raw hex wire format for it)
+- Returns records with TTLs and the resolving `source` (`cloudflare` or `nextdns`)
+- `nxdomain: true` in the result (not an error) when the domain doesn't exist in DNS
 
 ---
 
-### `whois_lookup_ip`
+### `whois_lookup_ip` <sub>tool</sub>
 
-Look up an IP address or CIDR block via RIR RDAP.
-
-- Auto-routes to the correct RIR (ARIN, RIPE, APNIC, LACNIC, AFRINIC) via IANA IP bootstrap
+- Accepts an IPv4/IPv6 address or CIDR block; auto-routes to the correct RIR (ARIN, RIPE, APNIC, LACNIC, AFRINIC) via IANA IP bootstrap
 - Returns netblock CIDR, org name, country, abuse contact email
 - Fetches PTR (reverse DNS) via DoH as a best-effort step — `ptr: null` on failure, not an error
-- Validates and rejects private/reserved ranges (RFC 1918, loopback, link-local) with a clear error
+- Throws `private_range` for RFC 1918, loopback, and link-local addresses — no RIR RDAP record exists for them
+- Throws `ip_not_found` on an RIR RDAP 404
 
 ---
 
-### `whois_lookup_asn`
-
-Resolve an ASN to its org name, country, and RIR.
+### `whois_lookup_asn` <sub>tool</sub>
 
 - Accepts `AS15169` or bare integer `15169` format
 - Routes to the correct RIR RDAP endpoint via IANA ASN bootstrap
-- Returns `name`, `org`, `country`, `rir`, `start_autnum`, `end_autnum`
+- Returns `name`, `org_name`, `country`, `rir`, `start_autnum`, `end_autnum`
+- Throws `asn_not_found` on an RIR RDAP 404
 
 ---
 
-### `whois_get_dossier`
-
-One-call domain triage aggregating registration and DNS data in parallel.
+### `whois_get_dossier` <sub>tool</sub>
 
 - Runs RDAP domain lookup and DoH (A, MX, NS, TXT) in parallel via `Promise.allSettled`
 - Inferred signals: `age_days`, `privacy_redacted`, `registrar`, `ns_provider` (from NS records), `mx_provider` (from MX records)
 - No synthesized risk scores — factual signals only; the agent decides the verdict
-- Partial results surfaced when one leg fails (`source_error` on the failed leg)
-- Both-legs-fail throws `ServiceUnavailable`; individual leg failures are data, not errors
+- Partial results surfaced when one leg fails (`rdap_source_error` / `dns_source_error` on the failed leg)
+- Throws `both_legs_failed` only when both RDAP and DNS fail; individual leg failures are data, not errors
 
 ---
 
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
-
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling — handlers throw, framework catches, classifies, and formats
-- Pluggable auth: `none`, `jwt`, `oauth`
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- STDIO and Streamable HTTP transports
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
-Domain and network intelligence:
+RDAP / DNS-specific:
 
-- RDAP over HTTPS — no port-43 TCP dependency, runs on Node, Bun, and Cloudflare Workers
-- IANA bootstrap auto-selection — correct registry RDAP server picked per TLD, RIR, or ASN range; bootstrap JSON cached (TTL 24h) in tenant state
-- DNS-over-HTTPS via Cloudflare and Google — resilient dual-provider with per-type routing (Google for CAA; Cloudflare for all others)
-- No API keys required — all sources (IANA, registry RDAP endpoints, RIR RDAP, Cloudflare DoH, Google DoH) are public and keyless
+- RDAP over HTTPS — no port-43 TCP dependency
+- IANA bootstrap auto-selection — correct registry RDAP server picked per TLD, RIR, or ASN range; bootstrap JSON cached in-memory for 24h
+- DNS-over-HTTPS via Cloudflare and NextDNS — dual-provider with per-type routing (NextDNS for CAA; Cloudflare for all others) and automatic fallback
+- No API keys required — all sources (IANA, registry RDAP endpoints, RIR RDAP, Cloudflare DoH, NextDNS DoH) are public and keyless
 
 Agent-friendly output:
 
-- Explicit coverage signals — `rdap_coverage: false` tells the agent the TLD lacks RDAP rather than returning a confusing error
+- Coverage signaled two ways — `rdap_coverage: false` returned as data by `whois_check_availability` and `whois_get_dossier`, while `whois_lookup_domain` throws `rdap_no_coverage` for the same case
 - Privacy redaction surfaced as a field — `registrant_redacted: true` rather than silently absent contact data
-- Partial failure model — `whois_get_dossier` marks individual legs with `source_error` and continues; only both-legs-fail escalates to an error
-- Factual signals, not scores — `age_days`, `privacy_redacted`, `ns_provider`, `mx_provider` are real data; agents chain into threat-intel or risk servers for enrichment
+- Partial failure model — `whois_get_dossier` marks individual legs with a `source_error` field and continues; only both-legs-fail escalates to an error
+- Factual signals, not scores — `age_days`, `privacy_redacted`, `ns_provider`, `mx_provider` are real data, not synthesized risk scores
 
 ---
 
@@ -279,10 +268,11 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 
 | Path | Purpose |
 |:-----|:--------|
-| `src/index.ts` | `createApp()` entry point — registers tools and inits services. |
+| `src/index.ts` | Entry point — starts the app. |
+| `src/app.ts` | `createApp()` options — registers tools, inits services, declares the session mode. |
 | `src/config/` | Server-specific environment variable parsing and validation (Zod). |
 | `src/services/rdap/` | RDAP client — IANA bootstrap cache, domain/IP/ASN lookup, retry. |
-| `src/services/doh/` | DNS-over-HTTPS client — Cloudflare primary, Google fallback. |
+| `src/services/doh/` | DNS-over-HTTPS client — Cloudflare primary, NextDNS fallback. |
 | `src/mcp-server/tools/` | Tool definitions (`*.tool.ts`). |
 | `tests/` | Vitest tests mirroring `src/`. |
 | `docs/` | Design and API reference documents. |
@@ -294,15 +284,15 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
-- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage (IANA bootstrap cache)
-- Register new tools via `src/index.ts` tools array
+- Use `ctx.log` for request-scoped logging
+- Register new tools via `src/app.ts`'s `tools` array
 - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
 
 ---
 
 ## Contributing
 
-Issues and pull requests are welcome. Run checks and tests before submitting:
+Issues are welcome. Run checks and tests before submitting:
 
 ```sh
 bun run devcheck

package/changelog/0.1.x/0.1.4.md

@@ -0,0 +1,38 @@
+---
+summary: "Adopt mcp-ts-core 0.12.3 (SDK v2 era) — strict tool inputs, error-envelope output schemas; IP/ASN RDAP 404s now reject as NotFound with recovery hints; supply-chain install guard"
+breaking: false
+security: false
+---
+
+# 0.1.4 — 2026-08-21
+
+## Added
+
+- **Supply-chain install guard** — `bunfig.toml` holds freshly published versions for 3 days (`minimumReleaseAge`, framework excluded) and runs the Socket security scanner on every install.
+- **RDAP 404 service tests** — four cases pinning the NotFound conversion and no-retry behavior across domain, availability, IP, and ASN lookups against a mocked RDAP endpoint.
+- **Community health files** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` (contact: casey@caseyjhand.com), plus `.gitattributes` line-ending normalization.
+
+## Changed
+
+- **Framework `@cyanheads/mcp-ts-core` `^0.10.6` → `^0.12.3`** (SDK v2 era) — tool inputs are strict (an unrecognized argument key is rejected by name), the advertised `outputSchema` declares the error envelope so schema-validating clients stop rejecting error results with -32602, JSON Schema advertises as 2020-12, and HTTP serves protocol revision 2026-07-28 alongside the 2025 revisions.
+- **Framework diagnostics and retry behavior** — input-validation failures read as flat `path: message` sentences instead of a `ZodIssue[]` blob; `ctx.log` lines mirror to the client as `notifications/message`; `withRetry` honors upstream `Retry-After` headers; fetch timeouts classify as `Timeout`, and a stalled response body can no longer hold a request open past its deadline.
+- **Toolchain** — TypeScript `^7.0.2`, Biome `^2.5.9`, Vitest `^4.1.11`, `@types/node` `^26`, Bun `1.4.0` (`packageManager` and both Dockerfile stages).
+- **Docker image hardening** — `BUILDPLATFORM` on the build stage restores multi-arch builds; BuildKit cache mounts for Bun installs; `--ignore-scripts` on the build install; `--omit=peer` on production installs so optional framework peer tiers stay out of the runtime image.
+- **`.mcpb` bundles are portable** — platform-specific native bindings are stripped after pack, so the bundle no longer carries the build host's platform slice.
+
+## Fixed
+
+- **IP and ASN lookups returning RDAP 404 now reject as `NotFound`** with `ip_not_found` / `asn_not_found` reasons and recovery hints, matching domain lookup — previously the 404 surfaced as a transient network error and burned retries. 404 responses no longer retry or log at error level.
+- **DoH provider docs corrected** — the fallback is NextDNS, not Google (docs only; CAA records always resolve via NextDNS because Cloudflare returns raw hex wire format for them). The result `source` field reads `cloudflare` | `nextdns`.
+- **Plugin marketplace manifests** carry the bare machine name in identity fields (`name`, server key) with the full npm name on the `npx -y` install arg, and a populated `longDescription`.
+
+## Dependency bumps
+
+- `@cyanheads/mcp-ts-core` `^0.10.6` → `^0.12.3`
+- `typescript` `^6.0.3` → `^7.0.2`
+- `@biomejs/biome` `^2.4.16` → `^2.5.9`
+- `@types/node` `25.9.3` → `^26`
+- `vitest` `^4.1.8` → `^4.1.11`
+- `tsc-alias` `^1.8.17` → `^1.9.2`
+- `ignore` `^7.0.5` → `^7.0.6`
+- Added `@socketsecurity/bun-security-scanner` `^1.1.2` (dev)

package/changelog/0.1.x/0.1.5.md

@@ -0,0 +1,35 @@
+---
+summary: "Adopt mcp-ts-core 0.13.6 — the server resolves to a stateless session posture however it is launched, and an out-of-schema argument fails as InvalidParams (-32602) with a Recovery line instead of ValidationError (-32007). The Bun floor rises to 1.4.0."
+breaking: true
+security: false
+---
+
+# 0.1.5 — 2026-09-20
+
+## Added
+
+- **`.github/FUNDING.yml`** — GitHub Sponsors and Buy Me a Coffee.
+- **`bun run audit:fix`** — `bun audit fix`, the first response to a transitive advisory, ahead of `audit:refresh`.
+- **`devcheck.config.json` `lint` block** — where `lint.truncationAllowlist` now lives, in place of a per-script `MCP_LINT_TRUNCATION_ALLOWLIST` env var.
+- **`tests/app.test.ts`** — asserts the resolved session posture and the registered tool surface against a live `createApp()`.
+
+## Changed
+
+- **The session mode is `stateless` however the server is launched** ([#11](https://github.com/cyanheads/whois-mcp-server/issues/11)). `src/app.ts` declares `createApp({ sessionMode: 'stateless' })` and `.env.example` sets the variable actively, so the `Dockerfile` line restates the posture rather than overriding it; previously only the container was stateless and a `bunx`, `npm start`, or from-source run resolved to `stateful`. No tool holds per-session state or calls `ctx.requestInput`.
+- **An out-of-schema argument now fails as `InvalidParams` (`-32602`), not `ValidationError` (`-32007`).** The rejection carries `data.reason: "invalid_arguments"` and its text ends with a `Recovery: …` line naming the field to fix. A client branching on the old code needs updating.
+- **Tool error text closes with `(reason <reason> · not retryable)`** whenever the error carries a `reason` or a boolean `retryable`. `structuredContent` is unchanged.
+- **A caller that disconnects mid-call classifies as `RequestCancelled` (`-32011`)** rather than `InternalError`, and logs at `info`. An upstream 500 on a DNS-over-HTTPS query now retries instead of failing on the first attempt.
+- **Bun engines floor `>=1.3.0` → `>=1.4.0`**, required by the framework.
+- **`whois_lookup_ip` and `whois_lookup_asn` mark their service-thrown contract entries `thrownBy: 'service'`** — `private_range`, `ip_not_found`, `invalid_asn`, `asn_not_found` (lint-only metadata; the advertised error surface is unchanged).
+- **The framework skill tree moved from `skills/` to `framework-skills/`** — Claude Code and Codex auto-load a plugin's root `skills/`, so this server's plugin manifests no longer hand its development skills to every agent that installs it.
+- **`createApp()` options live in `src/app.ts` as `appOptions`**; `src/index.ts` is the entry point that starts them.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.13.6`
+- `zod` `^4.4.3` → `^4.6.5`
+- `vitest` (dev) `^4.1.11` → `^5.0.1`
+- `@biomejs/biome` (dev) `^2.5.9` → `^2.5.14`
+- `@types/node` (dev) `^26` → `^26.6.1`
+- `ignore` (dev) `^7.0.6` → `^7.0.9`
+- `tsc-alias` (dev) `^1.9.2` → `^1.9.5`

package/changelog/template.md

@@ -4,10 +4,11 @@
 # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
 # with a concrete date.
 
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
 # Set `true` when consumers must change code to upgrade: API removals,
@@ -15,16 +16,19 @@ summary: ""
 # usage. Flagged as `Breaking` in the rollup.
 breaking: false
 
-# Set `true` if this release contains any security fix. Pairs with the
-# `## Security` section below. Flagged as `Security` in the rollup so
-# users can triage upgrade urgency at a glance.
+# Set `true` ONLY for a security fix in THIS project's own source code — a
+# vulnerability or hardening in code you ship. A dependency or transitive CVE
+# bump is routine maintenance, NOT a security release: record it under
+# `## Dependencies` (with the advisory ID) and leave this `false`. When true,
+# pairs with the `## Security` section below and flags `Security` in the rollup.
 security: false
 
 # Optional free-form notes for maintenance agents processing this release.
 # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
-# downstream servers. Use for adoption instructions that don't fit the
-# human-facing sections: new files to create, fields to populate, one-time
-# migration steps. Omit the field entirely when there's nothing to say.
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
 # agent-notes: |
 #   <instructions for downstream maintenance agents>
 ---
@@ -39,17 +43,54 @@ security: false
   each bullet with the symbol or concept name in **bold** so they can skip
   what's irrelevant and zoom in on what's not.
 
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
 
   Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
 
   Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
   Fixed, Security. Include only sections with entries; delete the rest
@@ -76,30 +117,13 @@ security: false
   in that unrelated item's metadata.
 
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
-  via `gh release create --notes-from-tag`. The tag is a derivative of this
-  changelog entry — a condensed, scannable version, not a copy. Format:
-
-    <theme — omit version number, GitHub prepends it>
-                                                          ← blank line
-    <1-2 sentence context: what this release does>
-                                                          ← blank line
-    Dependency bumps:                                     ← section header
-                                                          ← blank line
-    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
-                                                          ← blank line
-    Changed:                                              ← only sections with entries
-                                                          ← blank line
-    - `format()` output includes `query` in text mode
-                                                          ← blank line
-    Added:
-                                                          ← blank line
-    - `manifest.json` scaffolded for MCPB bundle support
-    - Install badges (Claude Desktop, Cursor, VS Code)
-                                                          ← blank line
-    <N> tests pass; `bun run devcheck` clean.             ← footer
-
-  Never a flat comma-separated string. Always structured markdown with
-  sections. The tag must scan well as a rendered GitHub Release page.
+  via `gh release create --notes-from-tag`. It is a condensed digest of this
+  entry, never a copy, and its format is owned by the `release-and-publish`
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added