@cyanheads/mcp-ts-core 0.5.4 → 0.6.0

package/scripts/build-changelog.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Generate CHANGELOG.md as a navigation index from per-version files.
+ *
+ * Source of truth: `changelog/<major.minor>.x/<version>.md` — each file opens with
+ * YAML frontmatter declaring:
+ *   • summary (required)  — ≤250-char headline, no markdown, one line
+ *   • breaking (optional) — `true` flags releases with breaking changes
+ *
+ * The rollup is a thin **index**, not a copy of bodies — each entry is just a
+ * clickable header + one-line summary. Full content stays in the per-version files.
+ *
+ * Rendered rollup entry:
+ *   ## [X.Y.Z](changelog/N.N.x/X.Y.Z.md) — YYYY-MM-DD · ⚠️ Breaking
+ *
+ *   <summary>
+ *
+ * (The `· ⚠️ Breaking` badge only appears when `breaking: true`.)
+ *
+ * Modes:
+ *   • default   → regenerate CHANGELOG.md
+ *   • --check   → exit 1 if CHANGELOG.md differs from what would be generated
+ *
+ * Missing `summary`: warning (not failure) — the entry renders header-only.
+ * Summary > 250 chars, or malformed `breaking`: hard error.
+ *
+ * @module scripts/build-changelog
+ */
+
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+const CHANGELOG_DIR = resolve('changelog');
+const CHANGELOG_PATH = resolve('CHANGELOG.md');
+const EXCLUDED_FILES = new Set(['unreleased.md', 'README.md']);
+const SERIES_PATTERN = /^\d+\.\d+\.x$/;
+const SUMMARY_MAX_LENGTH = 250;
+
+const HEADER = `# Changelog
+
+All notable changes to this project. Each entry links to its full per-version file in [changelog/](changelog/).
+`;
+
+interface VersionEntry {
+  path: string;
+  series: string;
+  version: string;
+}
+
+interface Frontmatter {
+  breaking: boolean;
+  summary: string | null;
+}
+
+/**
+ * Semver descending compare. Final releases rank above their prereleases
+ * (`0.6.0 > 0.6.0-rc.1 > 0.6.0-beta.1`). Prereleases compared lexicographically.
+ */
+function compareSemverDesc(a: string, b: string): number {
+  const parse = (v: string): [number[], string | null] => {
+    const [base, pre = null] = v.split('-', 2) as [string, string | undefined];
+    return [base.split('.').map(Number), pre ?? null];
+  };
+  const [aParts, aPre] = parse(a);
+  const [bParts, bPre] = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (bParts[i] ?? 0) - (aParts[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  if (aPre === bPre) return 0;
+  if (aPre === null) return -1;
+  if (bPre === null) return 1;
+  return bPre.localeCompare(aPre);
+}
+
+/**
+ * Parse minimal YAML frontmatter. Only recognizes `summary` and `breaking` —
+ * other keys are ignored, so the format stays extensible without touching the
+ * parser. Throws on malformed values we actually care about.
+ */
+function parseFrontmatter(content: string, fileLabel: string): Frontmatter {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return { summary: null, breaking: false };
+
+  const block = match[1] as string;
+
+  // summary: quoted or bare, single line
+  let summary: string | null = null;
+  const summaryMatch = block.match(/^summary:\s*(.*)$/m);
+  if (summaryMatch) {
+    let raw = (summaryMatch[1] ?? '').trim();
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+      raw = raw.slice(1, -1);
+    }
+    summary = raw.length > 0 ? raw : null;
+  }
+  if (summary !== null && summary.length > SUMMARY_MAX_LENGTH) {
+    throw new Error(
+      `${fileLabel}: summary is ${summary.length} chars, exceeds cap of ${SUMMARY_MAX_LENGTH}. Keep it tight — headline, not paragraph.`,
+    );
+  }
+
+  // breaking: must be literal true/false if present
+  let breaking = false;
+  const breakingMatch = block.match(/^breaking:\s*(\S+)\s*$/m);
+  if (breakingMatch) {
+    const val = breakingMatch[1];
+    if (val !== 'true' && val !== 'false') {
+      throw new Error(`${fileLabel}: breaking must be 'true' or 'false', got '${val}'.`);
+    }
+    breaking = val === 'true';
+  }
+
+  return { summary, breaking };
+}
+
+/** Extract the release date from the H1 heading. */
+function extractDate(body: string, fileLabel: string): string {
+  const match = body.match(/^#\s+\S+\s+[—–-]\s+(\d{4}-\d{2}-\d{2})/m);
+  if (!match) {
+    throw new Error(
+      `${fileLabel}: H1 heading missing or malformed. Expected '# <version> — YYYY-MM-DD'.`,
+    );
+  }
+  return match[1] as string;
+}
+
+function renderEntry(entry: VersionEntry, fm: Frontmatter, date: string): string {
+  const link = `changelog/${entry.series}/${entry.version}.md`;
+  const breakingBadge = fm.breaking ? ' · ⚠️ Breaking' : '';
+  const header = `## [${entry.version}](${link}) — ${date}${breakingBadge}`;
+  if (fm.summary) {
+    return `${header}\n\n${fm.summary}\n`;
+  }
+  return `${header}\n`;
+}
+
+function collectVersionFiles(): VersionEntry[] {
+  const entries: VersionEntry[] = [];
+  for (const entry of readdirSync(CHANGELOG_DIR, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !SERIES_PATTERN.test(entry.name)) continue;
+    const seriesDir = resolve(CHANGELOG_DIR, entry.name);
+    for (const file of readdirSync(seriesDir)) {
+      if (!file.endsWith('.md') || EXCLUDED_FILES.has(file)) continue;
+      entries.push({
+        version: file.replace(/\.md$/, ''),
+        series: entry.name,
+        path: resolve(seriesDir, file),
+      });
+    }
+  }
+  return entries.sort((a, b) => compareSemverDesc(a.version, b.version));
+}
+
+function buildRollup(): { content: string; missingSummary: string[] } {
+  const entries = collectVersionFiles();
+
+  if (entries.length === 0) {
+    throw new Error(`No per-version changelog files found under ${CHANGELOG_DIR}/<major.minor>.x/`);
+  }
+
+  const missingSummary: string[] = [];
+  const sections: string[] = [];
+
+  for (const entry of entries) {
+    const fileLabel = `changelog/${entry.series}/${entry.version}.md`;
+    const content = readFileSync(entry.path, 'utf-8');
+    const fm = parseFrontmatter(content, fileLabel);
+    const date = extractDate(content, fileLabel);
+
+    if (!fm.summary) {
+      missingSummary.push(fileLabel);
+    }
+
+    sections.push(renderEntry(entry, fm, date));
+  }
+
+  return {
+    content: `${HEADER}\n${sections.join('\n')}`,
+    missingSummary,
+  };
+}
+
+function reportMissingSummaries(missing: string[]): void {
+  if (missing.length === 0) return;
+  const shown = missing.slice(0, 10);
+  const extra = missing.length - shown.length;
+  console.warn(`\nWarning: ${missing.length} file(s) missing 'summary' frontmatter:`);
+  for (const file of shown) console.warn(`  - ${file}`);
+  if (extra > 0) console.warn(`  ... and ${extra} more`);
+  console.warn(`\nBackfill these — see CLAUDE.md § Changelog for the frontmatter format.`);
+}
+
+function main(): void {
+  const checkOnly = process.argv.includes('--check');
+  const { content: generated, missingSummary } = buildRollup();
+
+  if (checkOnly) {
+    let existing = '';
+    try {
+      existing = readFileSync(CHANGELOG_PATH, 'utf-8');
+    } catch {
+      // missing file counts as drift
+    }
+    if (existing === generated) {
+      console.log('CHANGELOG.md is in sync with changelog/ directory.');
+      reportMissingSummaries(missingSummary);
+      process.exit(0);
+    }
+    console.error('CHANGELOG.md is out of sync with changelog/ directory.');
+    console.error('Fix: run `bun run changelog:build` to regenerate.');
+    reportMissingSummaries(missingSummary);
+    process.exit(1);
+  }
+
+  writeFileSync(CHANGELOG_PATH, generated);
+  console.log(`Wrote ${CHANGELOG_PATH} (${generated.split('\n').length - 1} lines).`);
+  reportMissingSummaries(missingSummary);
+}
+
+main();

package/scripts/devcheck.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { type ChildProcess, spawn, spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -421,6 +421,21 @@ const ALL_CHECKS: Check[] = [
     tip: (c) =>
       `Edit both files together, or run ${c.bold('cp CLAUDE.md AGENTS.md')} (or reverse) to resync.`,
   },
+  {
+    name: 'Changelog Sync',
+    flag: '--no-changelog-sync',
+    canFix: false,
+    // --check exits non-zero if CHANGELOG.md drifts from changelog/*.md.
+    // Skipped cleanly when neither CHANGELOG.md nor changelog/ exists (non-mcp-ts-core projects).
+    getCommand: () => {
+      const hasChangelog = existsSync(path.join(ROOT_DIR, 'changelog'));
+      const hasRollup = existsSync(path.join(ROOT_DIR, 'CHANGELOG.md'));
+      if (!hasChangelog && !hasRollup) return null;
+      return ['bun', 'run', 'scripts/build-changelog.ts', '--check'];
+    },
+    tip: (c) =>
+      `Edit the per-version file in ${c.bold('changelog/')} and run ${c.bold('bun run changelog:build')} to regenerate ${c.bold('CHANGELOG.md')}.`,
+  },
   {
     name: 'Biome',
     flag: '--no-lint',

package/scripts/tree.ts

@@ -39,6 +39,9 @@ const DEFAULT_IGNORE_PATTERNS: string[] = [
   'coverage',
   'logs',
   '.husky/_',
+  // Directory-based changelog — keep series dirs visible (0.1.x/, 0.5.x/) for structural
+  // orientation, but collapse out the per-version files. Top-level unreleased.md stays.
+  'changelog/*/*.md',
 ];
 
 interface ParsedArgs {

package/skills/add-app-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold an MCP App tool + UI resource pair. Use when the user asks to add a tool with interactive UI, create an MCP App, or build a visual/interactive tool.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -18,9 +18,7 @@ MCP Apps extend the standard tool pattern with an interactive HTML UI rendered i
 
 Both builders are exported from `@cyanheads/mcp-ts-core`. They handle `_meta.ui.resourceUri`, the compat key (`ui/resourceUri`), and the correct MIME type (`text/html;profile=mcp-app`) automatically.
 
-For the full API, Context interface, and error codes, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full API, Context interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-prompt/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP prompt template. Use when the user asks to add a prompt, create a reusable message template, or define a prompt for LLM interactions.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -15,9 +15,7 @@ Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt li
 
 Prompts are pure message templates — no `Context`, no auth, no side effects.
 
-For the full `prompt()` API, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full `prompt()` API, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-resource/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -15,9 +15,7 @@ Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resou
 
 **Tool coverage.** Not all MCP clients expose resources — many are tool-only (Claude Code, Cursor, most chat UIs). Before adding a resource, verify the same data is reachable via the tool surface — either through a dedicated tool, included in another tool's output, or bundled into a broader tool. A resource whose data has no tool path is invisible to a large share of agents.
 
-For the full `resource()` API, pagination utilities, and `Context` interface, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full `resource()` API, pagination utilities, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
@@ -15,9 +15,7 @@ Services use the init/accessor pattern: initialized once in `createApp`'s `setup
 
 Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
 
-For the full service pattern, `CoreServices`, and `Context` interface, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full service pattern, `CoreServices`, and `Context` interface, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -13,9 +13,7 @@ metadata:
 
 Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix and is registered into `createApp()` in `src/index.ts`. Some larger repos later add `definitions/index.ts` barrels; match the pattern already used by the project you're editing.
 
-For the full `tool()` API, `Context` interface, and error codes, read:
-
-    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+For the full `tool()` API, `Context` interface, and error codes, read `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`.
 
 ## Steps
 
@@ -164,6 +162,8 @@ async handler(input, ctx) {
 },
 ```
 
+**Note on the `try/catch`:** this is the deliberate exception to the "logic throws, framework catches" rule. Per-item isolation is the whole point of partial-success batch tools — one failed item must not abort the batch, and the framework's partial-success telemetry (below) depends on seeing a populated `failed` array. Don't remove it to conform to the handler-level rule.
+
 Single-item tools don't need this — they either succeed or throw. The partial success question only arises with array inputs.
 
 **Telemetry:** The framework automatically detects this pattern — when a handler result contains a non-empty `failed` array, the span gets `mcp.tool.partial_success`, `mcp.tool.batch.succeeded_count`, and `mcp.tool.batch.failed_count` attributes. No manual instrumentation needed.
@@ -242,7 +242,8 @@ import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw serviceUnavailable(`arXiv API returned HTTP ${status}. Retry in a few seconds.`);
 
 // Structured hint for programmatic recovery
-throw new McpError(JsonRpcErrorCode.InvalidParams,
+import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+throw invalidParams(
   `Date range exceeds 90-day API limit. Narrow the range or split into multiple queries.`,
   { maxDays: 90, requestedDays: daysBetween },
 );

package/skills/api-context/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: reference
 ---
@@ -181,7 +181,7 @@ if (ctx.elicit) {
     await produceOutput(result.content?.format as string, result.content?.includeHeaders as boolean);
   } else {
     // 'decline' or 'cancel' — user opted out
-    throw new McpError(JsonRpcErrorCode.InvalidRequest, 'User declined input');
+    throw invalidRequest('User declined input');
   }
 }
 ```

package/skills/api-services/SKILL.md

@@ -4,7 +4,7 @@ description: >
   API reference for built-in service providers (LLM, Speech, Graph). Use when looking up service interfaces, provider capabilities, or integration patterns.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---

package/skills/api-services/references/graph.md

@@ -111,7 +111,7 @@ const path = await graphService.shortestPath('user:alice', 'user:charlie', conte
   algorithm: 'bfs',
   maxLength: 4,
 });
-if (path) console.log(`${path.vertices.length} hops`);
+if (path) context.log.info(`${path.vertices.length} hops`);
 
 // Check reachability
 const connected = await graphService.pathExists('user:alice', 'user:charlie', context, 3);

package/skills/api-utils/SKILL.md

@@ -4,7 +4,7 @@ description: >
   API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
 metadata:
   author: cyanheads
-  version: "2.0"
+  version: "2.1"
   audience: external
   type: reference
 ---

package/skills/api-utils/references/parsing.md

@@ -249,7 +249,7 @@ Matches `--- ... ---` at the very start of the document. An empty `---\n---` blo
 ```ts
 const { frontmatter, content, hasFrontmatter } = await frontmatterParser.parse<SkillMeta>(markdown);
 if (hasFrontmatter) {
-  console.log(frontmatter.name, frontmatter.version);
+  logger.info({ name: frontmatter.name, version: frontmatter.version }, 'parsed frontmatter');
 }
 ```
 

package/skills/api-utils/references/security.md

@@ -147,7 +147,7 @@ rateLimiter.check(`api:${ctx.tenantId}`, ctx);
 // Check status without consuming a request
 const status = rateLimiter.getStatus('api:tenant-123');
 if (status) {
-  console.log(`${status.remaining} requests left, resets at ${new Date(status.resetTime)}`);
+  logger.info(`${status.remaining} requests left, resets at ${new Date(status.resetTime)}`);
 }
 
 // Runtime reconfiguration

package/skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.4"
+  version: "2.5"
   audience: external
   type: workflow
 ---
@@ -271,7 +271,7 @@ throw new Error('Not found');
 "No session working directory set. Please specify a 'path' or use 'git_set_working_dir' first."
 
 // Good — structured hint in error data
-throw new McpError(JsonRpcErrorCode.Forbidden,
+throw forbidden(
   "Cannot perform 'reset --hard' on protected branch 'main' without explicit confirmation.",
   { branch: 'main', operation: 'reset --hard', hint: 'Set the confirmed parameter to true to proceed.' },
 );

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: workflow
 ---
@@ -50,13 +50,18 @@ Do not redo this investigation inline — the `changelog` skill handles tag-form
 
 ### 4. Framework review (`@cyanheads/mcp-ts-core`)
 
-If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. Read:
+If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. The framework ships a **directory-based changelog** grouped by minor series (`.x` semver-wildcard convention) — one file per released version at `node_modules/@cyanheads/mcp-ts-core/changelog/<major.minor>.x/<version>.md`. Read only the files between old and new rather than scanning a monolithic file.
 
-```bash
-node_modules/@cyanheads/mcp-ts-core/CHANGELOG.md
-```
+Example — `0.5.2 → 0.5.4` means reading two new version files:
+
+- `node_modules/@cyanheads/mcp-ts-core/changelog/0.5.x/0.5.3.md`
+- `node_modules/@cyanheads/mcp-ts-core/changelog/0.5.x/0.5.4.md`
+
+Cross-series updates span multiple directories — e.g., `0.4.1 → 0.5.2` reads `0.5.x/0.5.0.md`, `0.5.x/0.5.1.md`, `0.5.x/0.5.2.md`. Enumerate the series directories under `node_modules/@cyanheads/mcp-ts-core/changelog/` to find the relevant files.
 
-Extract entries between the old and new version. Scan specifically for:
+If the per-version directory isn't present (pre-0.5.5 releases, or downstream package that hasn't adopted the convention), fall back to the monolithic rollup at `node_modules/@cyanheads/mcp-ts-core/CHANGELOG.md` and extract the relevant sections manually.
+
+Scan specifically for:
 
 | Area | Adoption Check |
 |:-----|:---------------|
@@ -70,11 +75,7 @@ Extract entries between the old and new version. Scan specifically for:
 
 Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
 
-**Template review.** The framework also ships `templates/CLAUDE.md` and `templates/AGENTS.md` as scaffolding for consumer agent protocol files. The consumer's `CLAUDE.md`/`AGENTS.md` was copied at init time and has since diverged (local customizations, echo replacements, server-specific sections). Read the upstream template fresh:
-
-```bash
-node_modules/@cyanheads/mcp-ts-core/templates/CLAUDE.md
-```
+**Template review.** The framework also ships `templates/CLAUDE.md` and `templates/AGENTS.md` as scaffolding for consumer agent protocol files. The consumer's `CLAUDE.md`/`AGENTS.md` was copied at init time and has since diverged (local customizations, echo replacements, server-specific sections). Read the upstream template fresh at `node_modules/@cyanheads/mcp-ts-core/templates/CLAUDE.md`.
 
 Skip the mechanical diff — consumer customizations create too much noise to filter. Instead, read end-to-end with fresh eyes, mentally comparing against the current `CLAUDE.md`. Look for: new conventions, updated skill references, expanded checklists, new callouts, clearer explanations, restructured sections. Present findings; let the user cherry-pick what to adopt. Never auto-merge — the consumer's file is theirs.
 

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

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "1.4"
+  version: "1.5"
   audience: external
   type: workflow
 ---
@@ -118,22 +118,37 @@ frozenLockfile = false
 bun = true
 ```
 
-### 9. `CHANGELOG.md`
+### 9. Changelog
 
-If `CHANGELOG.md` doesn't exist, create it with an initial entry. If it exists, verify the latest entry reflects the current state:
+Directory-based, grouped by minor series using the `.x` semver-wildcard convention: per-version files live in `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`), work-in-progress in `changelog/unreleased.md` at the top level, and `CHANGELOG.md` is a rollup artifact regenerated by `bun run changelog:build`. Devcheck's `Changelog Sync` step enforces that `CHANGELOG.md` stays in sync.
+
+If `changelog/` doesn't exist, create the structure:
+
+1. Make the `changelog/` directory
+2. Create `changelog/unreleased.md` from the template (H1 `# Unreleased` + empty Added/Changed/Fixed sections)
+3. If the server already has a shipped version (e.g. 0.1.0), create the series directory and initial entry: `changelog/0.1.x/0.1.0.md` with H1 `# 0.1.0 — YYYY-MM-DD`, concrete version and date
+4. Run `bun run changelog:build` to generate `CHANGELOG.md`
+
+Per-version file format:
 
 ```markdown
-# Changelog
+---
+summary: One-line headline for the rollup index — ≤250 chars, no markdown
+breaking: false
+---
+
+# 0.1.0 — YYYY-MM-DD
 
-## 0.1.0 — YYYY-MM-DD
+Optional narrative intro (1-3 sentences).
 
-Initial release.
+## Added
 
-### Added
 - [list tools, resources, prompts, key capabilities]
 ```
 
-Use a concrete version and date. Never `[Unreleased]`.
+**Frontmatter:** `summary` is required (powers the CHANGELOG.md index), `breaking` is optional and defaults to `false` (set `true` for releases requiring consumer code changes).
+
+Never hand-edit `CHANGELOG.md` — it's a build artifact. Never use `[Unreleased]` as a version header in a released file.
 
 ### 10. `LICENSE`
 
@@ -181,7 +196,7 @@ Both must pass clean.
 - [ ] `server.json` matches official MCP schema, versions synced, env vars current
 - [ ] GitHub repo description matches `package.json` description; topics ↔ keywords in sync
 - [ ] `bunfig.toml` present
-- [ ] `CHANGELOG.md` exists with current entry
+- [ ] `changelog/` directory present with per-version files; `CHANGELOG.md` rollup regenerated and in sync
 - [ ] `LICENSE` file present
 - [ ] `Dockerfile` OCI labels and runtime config accurate (if present)
 - [ ] `docs/tree.md` regenerated

package/skills/release/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Verify release readiness and publish. The git wrapup protocol handles version bumps, changelog, README, commits, and tagging during the coding session. This skill verifies nothing was missed, runs final checks, and presents the irreversible publish commands.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.4"
   audience: internal
   type: workflow
 ---
@@ -34,13 +34,27 @@ The wrapup protocol bumps versions, but sometimes a file gets missed. **Search f
 
 Fix any mismatches. A grep for the **old** version is the fastest way to find stragglers.
 
-### 3. Verify CHANGELOG.md
+### 3. Release-ize the Changelog Entry
 
-Confirm the changelog entry:
+The changelog is directory-based, grouped by minor series using the `.x` semver-wildcard convention: per-version files live at `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.5.x/0.5.4.md`), work-in-progress entries go in `changelog/unreleased.md` at the top level, and `CHANGELOG.md` is an auto-generated rollup (`bun run changelog:build`).
 
-- Uses a **concrete version number and date** (never `[Unreleased]`)
-- Groups changes correctly: Added, Changed, Fixed, Removed
-- Accurately reflects what actually shipped — cross-reference with `git log` since the last tag
+If the wrapup already converted `unreleased.md` to the version file, verify it. Otherwise release-ize it now:
+
+1. Determine the series: `0.5.5` → `0.5.x/`. Create the directory if it doesn't exist: `mkdir -p changelog/<series>`
+2. `git mv changelog/unreleased.md changelog/<series>/<version>.md`
+3. Update the H1: `# Unreleased` → `# <version> — <date>` (em-dash, ISO date)
+4. **Fill in the frontmatter** at the top of the file:
+   - `summary:` — one-line headline, ≤250 chars, no markdown. Write it like a GitHub Release title. Required.
+   - `breaking:` — set to `true` if this release requires consumer code changes (API removal, signature change, config rename). Defaults to `false`. Renders `· ⚠️ Breaking` in the rollup when true.
+5. Verify content:
+   - Sections grouped correctly (Added / Changed / Fixed / Removed)
+   - Accurately reflects what shipped — cross-reference with `git log` since the last tag
+   - If this release absorbed pre-release versions (e.g., `0.6.0-beta.1`), confirm their sub-headers are preserved in the final file
+   - **Issue/PR references use full URLs**, not bare `#NN`. GitHub's auto-link only renders inside its own UI; these files are read from `node_modules` too, where bare `#NN` is dead text. Use `[#38](https://github.com/<owner>/<repo>/issues/38)` (or `/pull/NN` for PRs). Only link numbers verified via `gh issue view NN` / `gh pr view NN` — never speculate on future numbers, since GitHub will happily resolve `#42` to whatever unrelated item already owns 42 and pull its title into timeline previews.
+6. Create a fresh empty `changelog/unreleased.md` from the template (frontmatter stub with empty `summary`, `breaking: false`)
+7. Regenerate the rollup: `bun run changelog:build` — warnings about missing summaries are expected during the legacy-file backfill period but should not include this release
+
+Never hand-edit `CHANGELOG.md` — it's a build artifact. Devcheck's `Changelog Sync` step will fail if it drifts.
 
 ### 4. Verify README.md
 
@@ -117,7 +131,7 @@ mcp-publisher publish
 
 - [ ] Version consistent across all files (package.json, server.json ×3, CLAUDE.md, README.md, templates)
 - [ ] No stale old-version references found in repo
-- [ ] CHANGELOG.md has concrete version and date, content matches actual changes
+- [ ] `changelog/<major.minor>.x/<version>.md` has concrete version and date; `changelog/unreleased.md` reset; `CHANGELOG.md` regenerated via `bun run changelog:build`
 - [ ] README.md current — feature counts, badges, descriptions, examples
 - [ ] Modified skill versions bumped in YAML frontmatter
 - [ ] `docs/tree.md` current (if structure changed)