@cyanheads/mcp-ts-core 0.8.18 → 0.8.19

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: "2.0"
+  version: "2.1"
   audience: external
   type: workflow
 ---
@@ -120,9 +120,11 @@ For each agent directory that exists:
 
 If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.
 
-**Phase C — Package scripts → Project `scripts/`**
+**Phase C — Package framework files → Project**
 
-The `init` CLI scaffolds a fixed set of framework scripts into consumer projects — these underpin `bun run build`, `bun run devcheck`, `bun run lint:mcp`, `bun run tree`, and the changelog build. They drift silently when the framework updates them. Compare by content hash and overwrite on mismatch:
+Two categories of framework-authored files ship into consumer projects and drift silently as the framework updates them. Both follow the same hash-compare-and-overwrite mechanic.
+
+**Scripts** — `init` scaffolds a fixed set that underpin `bun run build`, `bun run devcheck`, `bun run lint:mcp`, `bun run tree`, and the changelog build. Iterate the package's shipped scripts directory:
 
 ```bash
 for src in node_modules/@cyanheads/mcp-ts-core/scripts/*.ts; do
@@ -140,9 +142,17 @@ done
 
 Scripts in `scripts/` that aren't present in the package directory are project-specific (custom deploy, codegen, etc.) — leave them alone. The package's `files:` field gates what ships into `node_modules/.../scripts/`, so enumerating that directory is the canonical "shipped scripts" set.
 
-If the consumer customized a framework script, the overwrite discards those changes. After the sync runs, diff `scripts/` to surface replacements — review before committing. If a specific local customization needs to be preserved, revert that file using your git tools.
+**Pristine reference files** — files explicitly documented as "never edit, rename, or move." The framework keeps the authoritative copy under `templates/`; the consumer's copy must track upstream as the format evolves (new frontmatter fields, section reorderings, etc.). Fixed src→dst mapping:
+
+| Source (in package) | Destination (in project) |
+|:--|:--|
+| `templates/changelog/template.md` | `changelog/template.md` |
+
+Apply the same compare-and-overwrite logic. Add new entries here only when a template is explicitly documented as pristine in the framework's CLAUDE.md or its own header.
+
+If the consumer customized a framework script or pristine reference (against guidance), the overwrite discards those changes. After the sync runs, diff `scripts/` and the affected template paths to surface replacements — review before committing. If a specific local customization needs to be preserved, revert that file using your git tools.
 
-**Report** which skills were added/updated in Phase A (with version deltas), which agent directories were refreshed in Phase B, and which scripts were resynced in Phase C. The user needs to know what new guidance and tooling is now in play.
+**Report** which skills were added/updated in Phase A (with version deltas), which agent directories were refreshed in Phase B, and which scripts and pristine reference files were resynced in Phase C. The user needs to know what new guidance and tooling is now in play.
 
 ### 6. Adopt changes in the codebase
 
@@ -212,7 +222,7 @@ Present a concise numbered summary to the user:
 - [ ] Every applicable framework adoption opportunity applied in this pass — no scope/effort/marginal-benefit deferrals; third-party adoptions evaluated on cost/benefit
 - [ ] Project `skills/` synced from package (Phase A), with a change report
 - [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
-- [ ] Framework `scripts/` resynced from package via content-hash compare (Phase C), with a change report; `scripts/` diff reviewed before committing
+- [ ] Framework `scripts/` and pristine reference files resynced from package via content-hash compare (Phase C), with a change report; diffs reviewed before committing
 - [ ] `bun run rebuild` succeeds
 - [ ] `bun run devcheck` passes (includes audit + outdated)
 - [ ] `bun run test` passes

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/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/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"