@cyanheads/mcp-ts-core 0.8.18 → 0.8.20

package/skills/polish-docs-meta/references/package-meta.md

@@ -27,7 +27,7 @@ These are set by `init` and generally don't need changes. Verify they're present
 | `main` | `"dist/index.js"` | Entry point after build |
 | `types` | `"dist/index.d.ts"` | TypeScript declarations |
 | `files` | `["dist/"]` | What npm publishes |
-| `engines` | `{ "node": ">=22.0.0" }` | Add `"bun": ">=1.2.0"` alongside Node |
+| `engines` | `{ "node": ">=24.0.0" }` | Add `"bun": ">=1.3.0"` alongside Node |
 | `packageManager` | _(often missing)_ | `"bun@1.3.2"` (or current Bun version). Signals the intended package manager. |
 | `scripts` | _(various)_ | Build, dev, test scripts |
 | `dependencies` | `@cyanheads/mcp-ts-core` | Core framework |

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.5"
+  version: "1.6"
   audience: external
   type: workflow
 ---
@@ -35,16 +35,18 @@ gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
 
 ## Writing Well-Structured Issues
 
-Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
+Good issues are scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
 
 - **Lead with specifics.** Name the tool, function, module, or symptom. "Currently `createApp()` throws `ConfigurationError` when `MCP_HTTP_PORT` is set to `0`" beats "There's a problem with the config." A reader should know what's broken or missing before the end of the first sentence.
 - **Embed library/service links on first mention.** `[Hono](https://hono.dev/)`, `[linkedom](https://github.com/WebReflection/linkedom)`. Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
 - **Use `owner/repo#N` for cross-repo issue references.** GitHub auto-renders them as linked references (e.g. `cyanheads/pubmed-mcp-server#34`). Bare `#N` only works for same-repo issues.
 - **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
+- **Cite cross-references once per body.** Link an issue/PR in `Related:`, the description, or Additional context — not all three. The reader sees them all; redundant linking dilutes signal.
 - **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **fail fast on config errors, degrade gracefully on runtime errors.**" Establishes the lens for the rest of the section.
 - **Prefer Markdown tables for comparisons.** When showing options, tiers, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
 - **Separate `### Scope` from `### Out of scope`.** The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
 - **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on another issue landing first.
+- **Cut what dilutes the signal.** Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
 - **Skip collaborator-framing sign-offs.** Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.
 
 ## Redact Before Posting
@@ -81,7 +83,7 @@ Bun
 
 ### Runtime version
 
-Bun 1.2.x
+Bun 1.3.x
 
 ### Transport
 

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

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: workflow
 ---
@@ -44,16 +44,18 @@ gh issue list --search "your error message or keyword"
 
 ## Writing Well-Structured Issues
 
-Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
+Good issues are scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
 
 - **Lead with specifics.** Name the tool, service, resource, or symptom. "Currently `search_docs` returns an empty array for queries containing `&`" beats "Search is broken." A reader should know what's wrong before the end of the first sentence.
 - **Embed library/service links on first mention.** `[Hono](https://hono.dev/)`, `[Supabase](https://supabase.com/)`. Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
 - **Use `owner/repo#N` for cross-repo issue references.** GitHub auto-renders them as linked references (e.g. `cyanheads/mcp-ts-core#46`). Bare `#N` only works for same-repo issues — useful when the bug depends on or relates to a framework issue.
 - **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
+- **Cite cross-references once per body.** Link an issue/PR in `Related:`, the description, or Additional context — not all three. The reader sees them all; redundant linking dilutes signal.
 - **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **return best-effort data, don't fail the tool call on parsing edge cases.**" Establishes the lens for the rest of the section.
 - **Prefer Markdown tables for comparisons.** When showing options, data sources, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
 - **Separate `### Scope` from `### Out of scope`.** The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
 - **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on an upstream framework change or another issue landing first.
+- **Cut what dilutes the signal.** Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
 - **Skip collaborator-framing sign-offs.** Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.
 
 ## Redact Before Posting
@@ -94,7 +96,7 @@ Bun
 
 ### Runtime version
 
-Bun 1.2.x
+Bun 1.3.x
 
 ### Transport
 

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.3"
+  version: "1.4"
   audience: external
   type: audit
 ---
@@ -104,8 +104,9 @@ grep -rn "auth: \[" src/mcp-server/tools/definitions/
 - Tools with `['admin']`, `['*']`, or `[]`?
 - A single scope covering two capabilities that should be separated (read vs write)?
 - Read-only tools never require write scopes?
+- `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` set in production? When on, both `withRequiredScopes` and `checkScopes` early-return — every authenticated user gets every tool, and runtime tenant patterns like `team:${input.teamId}:write` no longer guard. Acceptable only when paired with a real server-side ACL (path filter, allowlist, upstream API enforcement).
 
-**Smell:** every tool shares the same scope string.
+**Smell:** every tool shares the same scope string. Or: `MCP_AUTH_DISABLE_SCOPE_CHECKS=true` set without a documented compensating ACL — confirm the deployment relies on a meaningful access control layer below the framework before approving.
 
 #### Axis 3 — Destructive ops without elicit
 

package/skills/setup/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: workflow
 ---
 
 ## Context
 
-This skill assumes `npx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
+This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
 
 ## Agent Protocol File
 
@@ -22,7 +22,7 @@ The init CLI generates both `CLAUDE.md` and `AGENTS.md` with the same purpose. K
 
 Both files serve the same purpose: project-specific agent instructions. Prefer committing one authoritative copy rather than trying to keep both in sync by hand.
 
-For the full framework API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
+For the full framework docs, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` once per session. It contains the exports catalog, tool/resource/prompt contracts, error codes, context API, and common import patterns.
 
 ## Project Structure
 
@@ -96,7 +96,7 @@ After init:
 2. **Rename and replace what you keep.** The echo definitions and their tests show the pattern — swap them out for your real tools/resources/prompts.
 3. **Definitions register directly in `src/index.ts`.** No barrel files, just import and add to the `tools` / `resources` / `prompts` arrays.
 
-See the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt`, and `add-test` skills for the scaffolding patterns when you start adding real definitions.
+See the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt`, `add-service`, and `add-test` skills for the scaffolding patterns when you start adding real definitions.
 
 ## Conventions
 
@@ -130,11 +130,11 @@ After `bun install`, complete these one-time setup tasks:
 
 1. **Update dependencies to latest** — `bun update --latest`. The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
 2. **Initialize git** — use your git tools: init the repo, stage all files, and commit with message `chore: scaffold from @cyanheads/mcp-ts-core`
-3. **Verify agent protocol placeholders** — if the `init` CLI was run without a `[name]` argument, `{{PACKAGE_NAME}}` may remain as a literal in `CLAUDE.md`/`AGENTS.md` and `package.json`. Replace it with the actual server name.
+3. **Verify the substituted server name** — when `init` runs without a `[name]` argument, the package name defaults to the cwd directory name. If that's not what you want as the published server name, update `package.json`, `CLAUDE.md`/`AGENTS.md`, and `server.json` to your actual server name.
 
 ## Changelog Convention
 
-`changelog/template.md` ships as a **format reference** — never edit, rename, or move it. For each release, author a per-version file at `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) with YAML frontmatter (`summary:` + optional `breaking:`) and grouped sections (Added / Changed / Fixed / Removed). Then regenerate the rollup with `bun run changelog:build` — `CHANGELOG.md` is an auto-generated navigation index, never hand-edited. See the `release-and-publish` skill for the full release flow.
+`changelog/template.md` ships as a **format reference** — never edit, rename, or move it. For each release, author a per-version file at `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) with YAML frontmatter (`summary:` + optional `breaking:` / `security:`) and grouped sections (Added / Changed / Fixed / Removed). Then regenerate the rollup with `bun run changelog:build` — `CHANGELOG.md` is an auto-generated navigation index, never hand-edited. See the `release-and-publish` skill for the full release flow.
 
 ## Next Steps
 
@@ -146,15 +146,16 @@ The included skills form a rough progression — not a rigid sequence, but the t
 4. **`field-test`** — exercise the built surface with real and adversarial inputs; produces a report of issues and pain points
 5. **`security-pass`** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
 6. **`polish-docs-meta`** — finalize README, metadata, and agent protocol before shipping
-7. **`maintenance`** — after `bun update --latest`, investigate upstream changelogs and re-sync skills
+7. **`release-and-publish`** — post-wrapup ship workflow: verification gate, push commits and tags, publish to npm/MCP Registry/GHCR
+8. **`maintenance`** — after `bun update --latest`, investigate upstream changelogs and re-sync skills
 
 Skip or reorder as the project calls for it. The agent protocol's "What's Next?" section is the authoritative map once the first session is over.
 
 ## Checklist
 
 - [ ] Agent protocol file selected — keep one authoritative file (`CLAUDE.md` or `AGENTS.md`)
-- [ ] `{{PACKAGE_NAME}}` placeholders replaced in agent protocol file (if not auto-substituted by init)
-- [ ] Core framework CLAUDE.md read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
+- [ ] Substituted server name verified in `package.json`, agent protocol file, and `server.json`
+- [ ] Framework docs read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
 - [ ] Unused echo definitions cleaned up (and unregistered from `src/index.ts`)
 - [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)

package/skills/tool-defs-analysis/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Read-only audit of MCP definition language across an existing surface — tools, resources, prompts. Walks every definition file and checks 10 categories the LLM reads to decide whether and how to call: voice & tense, internal leaks, audience leaks, defaults, recovery hints, output descriptions, cross-references, sparsity, examples, structure. Produces grouped findings with file:line citations and a numbered options list. Use during polish, after a refactor, or before a release. Complements `field-test` (behavior testing) and `security-pass` (security audit).
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: audit
 ---
@@ -105,7 +105,7 @@ Prior art: #74. Field-test catches this in its leak audit; this skill is the mor
 
 **Check:** the hint directs the *agent* to its next action, not the developer to debugging. "Call `pubmed_search` with a narrower query" beats "Verify the configuration is correct" or "Internal error".
 
-**Smell:** "Check the logs", "See documentation", "Contact admin", "Try again later" (with no condition), generic non-actionable text, hints that name internal classes, files, or env vars.
+**Smell:** "Check the logs", "See documentation", "Contact admin", "Try again later" (with no condition), generic non-actionable text, hints that name internal classes or files.
 
 #### 6. Output descriptions
 

package/templates/AGENTS.md

@@ -1,8 +1,11 @@
-# Agent Protocol
+# Developer Protocol
 
 **Server:** {{PACKAGE_NAME}}
 **Version:** 0.1.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^{{FRAMEWORK_VERSION}}`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/sdk` {{MCP_SDK_VERSION}}
+**Zod:** {{ZOD_VERSION}}
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -10,17 +13,20 @@
 
 ## 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.
+
 > **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.
 
-1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
-2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+1. **Get your bearings.** Take stock of your current environment — think through the project tree, the skills in `skills/`, and the tools/MCP servers you have available. Light tool use is fine if something isn't already in context; you're building a mental map for later, not committing to anything yet.
+2. **Read the framework docs** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` (builders, Context, errors, exports, conventions)
+3. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
+4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
 ## What's Next?
 
-When the user asks what to do next, what's left, or needs direction, suggest relevant options based on the current project state:
+When the user asks what to do next, what's left, or needs direction, you can suggest relevant options based on the current project state. Some common next steps:
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
@@ -271,7 +277,8 @@ Available skills:
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
-| `api-utils` | Formatting, parsing, security, pagination, scheduling |
+| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
+| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
@@ -306,15 +313,18 @@ Each per-version file opens with YAML frontmatter:
 
 ```markdown
 ---
-summary: One-line headline, ≤250 chars  # required — powers the rollup index
-breaking: false                          # optional — true flags breaking changes
+summary: "One-line headline, ≤250 chars"  # required — powers the rollup index
+breaking: false                            # optional — true flags breaking changes
+security: false                            # optional — true flags security fixes
 ---
 
 # 0.1.0 — YYYY-MM-DD
 ...
 ```
 
-`breaking: true` renders a `· ⚠️ Breaking` badge in the rollup — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames).
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+
+**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 ---
 

package/templates/CLAUDE.md

@@ -1,8 +1,11 @@
-# Agent Protocol
+# Developer Protocol
 
 **Server:** {{PACKAGE_NAME}}
 **Version:** 0.1.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^{{FRAMEWORK_VERSION}}`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/sdk` {{MCP_SDK_VERSION}}
+**Zod:** {{ZOD_VERSION}}
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -10,17 +13,20 @@
 
 ## 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.
+
 > **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.
 
-1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
-2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+1. **Get your bearings.** Take stock of your current environment — think through the project tree, the skills in `skills/`, and the tools/MCP servers you have available. Light tool use is fine if something isn't already in context; you're building a mental map for later, not committing to anything yet.
+2. **Read the framework docs** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` (builders, Context, errors, exports, conventions)
+3. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
+4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
 ## What's Next?
 
-When the user asks what to do next, what's left, or needs direction, suggest relevant options based on the current project state:
+When the user asks what to do next, what's left, or needs direction, you can suggest relevant options based on the current project state. Some common next steps:
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
@@ -271,7 +277,8 @@ Available skills:
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
-| `api-utils` | Formatting, parsing, security, pagination, scheduling |
+| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
+| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
@@ -306,15 +313,18 @@ Each per-version file opens with YAML frontmatter:
 
 ```markdown
 ---
-summary: One-line headline, ≤250 chars  # required — powers the rollup index
-breaking: false                          # optional — true flags breaking changes
+summary: "One-line headline, ≤250 chars"  # required — powers the rollup index
+breaking: false                            # optional — true flags breaking changes
+security: false                            # optional — true flags security fixes
 ---
 
 # 0.1.0 — YYYY-MM-DD
 ...
 ```
 
-`breaking: true` renders a `· ⚠️ Breaking` badge in the rollup — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames).
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+
+**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 ---
 

package/templates/Dockerfile

@@ -4,7 +4,7 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1 AS build
+FROM oven/bun:1.3 AS build
 
 WORKDIR /usr/src/app
 
@@ -28,7 +28,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1-slim AS production
+FROM oven/bun:1.3-slim AS production
 
 WORKDIR /usr/src/app
 

package/templates/changelog/template.md

@@ -1,56 +1,71 @@
 ---
-# 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.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.
-
-# Required. One-line headline describing the release. Max 250 chars. No markdown.
-# This line is what the CHANGELOG.md rollup shows — write it like a GitHub Release title.
-# Keep the double quotes around the value — unquoted YAML treats `:` (colon-space)
-# inside the string as a key separator, which fails GitHub's strict YAML parser.
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# 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. ~250 character soft 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.
 summary: ""
 
-# Set to `true` only if this release has breaking changes (API removals, signature
-# changes, config renames, anything that requires consumer code changes on update).
-# Flagged as ⚠️ Breaking in the rollup.
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# 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.
+security: false
 ---
 
 # <version> — YYYY-MM-DD
 
 <!--
-  FORMAT REFERENCE — do not edit this file. It exists so the per-version file
-  structure has a single copy-source. Create new release notes at
-  `changelog/<major.minor>.x/<version>.md` using this layout.
-
-  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.
-
-    [#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 — `#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.
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  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, 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.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  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. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
 -->
 
 ## Added
@@ -61,6 +76,18 @@ breaking: false
 
 -
 
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
 ## Fixed
 
 -
+
+<!-- ## Security
+
+- -->

package/templates/package.json

@@ -44,8 +44,8 @@
   },
   "license": "Apache-2.0",
   "engines": {
-    "bun": ">=1.2.0",
-    "node": ">=22.0.0"
+    "bun": ">=1.3.0",
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"