@cyanheads/mcp-ts-core 0.9.8 → 0.9.10

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.11"
+  version: "2.12"
   audience: external
   type: workflow
 ---
@@ -29,6 +29,23 @@ Gather before designing. Ask the user if not obvious from context:
 
 If the domain has a public API, read its docs before designing. For internal-only servers, skip API research and go straight to user goals. Don't design from vibes either way.
 
+### Server scope and audience
+
+Before committing to a server boundary, answer: **what workflow does this server serve, and who is the audience?**
+
+The unit of a server is a *user workflow*, not an API. A single rich API can earn its own server when the audience is large and the API surface supports a full workflow (PubMed for literature research, SEC EDGAR for financial analysis, Shodan for internet-wide device intelligence). Multiple APIs should collapse into one server when they serve the same workflow from different angles — a "threat intelligence" server that aggregates VirusTotal, AbuseIPDB, and GreyNoise is more useful than three separate servers because the user's goal is "assess this indicator," not "query VirusTotal."
+
+**Don't default to one-API-one-server.** That's the right call when the API is deep enough and the audience is large enough, but it's not the starting point. The starting point is the workflow:
+
+| Signal | Server boundary |
+|:-------|:----------------|
+| Single API with rich surface, large audience | Standalone server named for the platform (`pubmed-mcp-server`, `secedgar-mcp-server`) |
+| Multiple APIs serving the same workflow | One server named for the workflow (`threat-intel-mcp-server`), APIs are internal sources |
+| Domain with distinct sub-audiences | Consider splitting — a pentester and a SOC analyst have different workflows even in the same domain |
+| Pure computation, no external deps | Standalone server named for the capability (`calculator-mcp-server`, `redteam-mcp-server`) |
+
+When multiple APIs collapse into one server, the tool surface is organized around what the user is doing, not which API gets called. The agent says "investigate this domain" and the server routes to the best available source internally. Individual APIs become service-layer implementation details, not tool-surface identities.
+
 ## Server Naming
 
 The server name (repo name, npm package, public identity) must communicate what it does at a glance. The test: can a human or agent scanning a server list tell what this server does from the name alone?
@@ -141,6 +158,56 @@ const findStudies = tool('clinicaltrials_find_studies', {
 
 > **Tip — mode consolidation.** When a tool has several related operations on the same noun, you can consolidate them under one tool with a `mode`/`operation` enum. This affects both naming (noun-led, e.g., `github_pull_request`) and handler design (dispatch by mode). Use when it tightens the surface; skip when ops diverge enough to warrant separate tools.
 
+#### Multi-source tools and fallback chains
+
+**Applies when:** a server aggregates multiple data sources for the same workflow, and the "best" source varies by input type, availability, or coverage. Skip for single-API servers.
+
+When a tool's goal can be served by multiple sources, design it as a **multi-source tool** — the agent calls one tool, the handler routes to the best source (or fans out to several) internally. This is the difference between a "PubMed wrapper" and a "literature research server": `pubmed_search_articles` tries PubMed first, falls back to EuropePMC for broader coverage, then Unpaywall for open access. The agent doesn't choose which API to hit — the server makes that decision based on what works.
+
+Two patterns:
+
+**Source fallback chains** — try sources in priority order, fall through on failure or empty results. Best when sources cover the same data with different depth or availability. The output should indicate which source provided the data so the agent (and human) can assess provenance.
+
+```ts
+// Handler pseudocode — not a real implementation
+async handler(input, ctx) {
+  // Primary: PubMed E-utilities (authoritative, best metadata)
+  const result = await pubmedService.search(input.query);
+  if (result.items.length > 0) return { ...result, source: 'pubmed' };
+
+  // Fallback: EuropePMC (broader coverage, includes preprints)
+  const epmcResult = await epmcService.search(input.query);
+  if (epmcResult.items.length > 0) return { ...epmcResult, source: 'europepmc' };
+
+  return { items: [], source: 'none', message: 'No results from any source.' };
+}
+```
+
+**Multi-source fan-out** — query multiple sources in parallel, merge results. Best when sources provide complementary data about the same entity. Use `Promise.allSettled` so one failing source doesn't tank the whole call.
+
+```ts
+// Handler pseudocode — indicator enrichment across threat intel sources
+async handler(input, ctx) {
+  const [vt, abuse, greynoise] = await Promise.allSettled([
+    vtService.lookup(input.indicator),
+    abuseIpService.check(input.indicator),
+    greynoiseService.query(input.indicator),
+  ]);
+  return {
+    indicator: input.indicator,
+    sources: {
+      virustotal: vt.status === 'fulfilled' ? vt.value : { error: vt.reason.message },
+      abuseipdb: abuse.status === 'fulfilled' ? abuse.value : { error: abuse.reason.message },
+      greynoise: greynoise.status === 'fulfilled' ? greynoise.value : { error: greynoise.reason.message },
+    },
+    // Server synthesizes a verdict from available data — the agent gets a conclusion, not raw API dumps
+    assessment: synthesizeVerdict(vt, abuse, greynoise),
+  };
+}
+```
+
+In both patterns, the tool surface is organized around what the user is doing. Sources are service-layer details — the agent sees `threat_enrich_indicator`, not `virustotal_lookup` + `abuseipdb_check` + `greynoise_query`. Mode-based dispatch by input type (e.g., `indicator_type: 'ip' | 'domain' | 'hash'`) naturally routes to different source chains per mode, since different sources cover different indicator types.
+
 There is no fixed ceiling on tool count — tools need to earn their keep, but don't artificially limit the surface. If the domain genuinely has 20 distinct workflows, expose 20 tools.
 
 #### Cut the surface
@@ -416,7 +483,7 @@ Skip for purely data/action-oriented servers.
 
 ### 7. Plan Services and Config
 
-**Services** — one per external dependency. Init/accessor pattern. Skip if all tools are thin wrappers with no shared state.
+**Services** — one per external dependency (or per source, for multi-source servers). Init/accessor pattern. Skip if all tools are thin wrappers with no shared state. For multi-source servers, each upstream API gets its own service with its own auth, rate limits, and retry config — tools compose across services internally, agents never see the service boundary.
 
 **Server-as-service.** When the server IS the source of truth (knowledge graph, in-memory task tracker, local scratchpad, embedded inference wrapper), the resilience table below doesn't apply — there's no upstream to retry. The design questions shift to state management: what's tenant-scoped vs. global, what TTLs apply, what survives a restart, what the storage backend is. Plan persistence via `ctx.state` for tenant-scoped KV (auto-namespaced by `tenantId`), or use a `StorageService` provider directly when data must cross tenants. Service init still happens in `setup()`, accessed via `getMyService()` at request time. Calls within the server are local and synchronous-ish — the API-efficiency table below also doesn't apply.
 
@@ -539,6 +606,8 @@ Execute the plan using the scaffolding skills:
 
 Items without an `If …:` prefix apply to every design. Conditional items only apply when the trigger fires — otherwise skip them.
 
+- [ ] Server scope decided — workflow identified, audience sized, boundary drawn (standalone single-API vs. multi-source aggregation vs. internal-only)
+- [ ] **If multi-source:** tool surface organized around user workflows, not API identity. Sources are service-layer details.
 - [ ] External APIs/dependencies researched and verified (docs fetched, SDKs identified)
 - [ ] **If wrapping an external API:** live API probed (at minimum: one list/search, one single-item GET, one error case)
 - [ ] User goals enumerated first (3–10 outcomes agents will accomplish, scaled to domain size), then domain operations mapped as raw material
@@ -567,5 +636,6 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If the server is itself the source of truth (no external API):** state lifecycle planned — tenant-scoped vs. global, TTLs, what survives restart, storage backend chosen
 - [ ] **If the server has external deps or shared state:** service layer planned (or explicitly skipped with reasoning)
 - [ ] **If services wrap external APIs:** resilience planned (retry boundary, backoff, parse classification)
+- [ ] **If multi-source server:** each source has its own service with independent auth/retry/rate-limit config. Fallback chains or fan-out strategy documented per tool. Output includes source provenance.
 - [ ] **If exposing a SQL/analytical workspace over tabular data is in scope:** DataCanvas considered (`api-canvas` skill) as one option before designing custom analytical state — register / query / export tools accepting an optional `canvas_id`, with `ctx.core.canvas?` reads
 - [ ] **If the server needs runtime config:** env vars identified in `server-config.ts`

package/skills/git-wrapup/SKILL.md

@@ -180,6 +180,7 @@ Dependency bumps:
 - Not a CHANGELOG copy — terse, scannable
 - No marketing adjectives
 - Length is earned — two-line tags are fine for small patches
+- **Issue backlinks:** when changes address GitHub issues, include `(#N)` references in the relevant bullets — same as the changelog entry. The backlinks render as clickable links in the GitHub Release body.
 
 ### 9. Verify end state
 

package/skills/maintenance/SKILL.md

@@ -78,7 +78,8 @@ Scan specifically for:
 | Config changes | New env vars, renamed keys, changed defaults |
 | Linter rules | New definition-lint rules that may now flag existing tools/resources |
 | New or materially-changed skills | Note new skills or workflow changes (renamed steps, new checklist items) worth surfacing at end-of-run. Don't auto-invoke — some skills (e.g. `security-pass`) are user-triggered. The per-version changelog entries (e.g. 0.6.14 calling out `skills/security-pass/ (v1.0)`) name what changed. |
-| New template-scaffolded files | Compare `templates/` in the package against the project root. Files that `init` would create for a new project but don't exist in this project are adoption candidates — create them with project-specific values (version, name, description, env vars from `server.json`). Examples: `manifest.json`, `.mcpbignore`. Skip files the project has intentionally opted out of (documented in CLAUDE.md or a code comment). |
+| New template-scaffolded files | Compare `templates/` in the package against the project root. Files that `init` would create for a new project but don't exist in this project are adoption candidates — create them with project-specific values (version, name, description, env vars from `server.json`). Examples: `manifest.json`, `.mcpbignore`, `.codex-plugin/`, `.claude-plugin/`. Skip files the project has intentionally opted out of (documented in CLAUDE.md or a code comment). |
+| Changelog `agent-notes` | Read `agent-notes` frontmatter from each new per-version changelog file — these carry release-specific adoption instructions for downstream consumers (new files to create, fields to populate, one-time migration steps). Apply them alongside other adoption work in Step 6. |
 
 Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
 

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

@@ -165,7 +165,24 @@ Never hand-edit `CHANGELOG.md` when using this pattern — it's a build artifact
 
 **Monolithic** — maintain `CHANGELOG.md` directly in [Keep a Changelog](https://keepachangelog.com/) format. To collapse from the template default: delete the `changelog/` directory, remove `changelog:build` and `changelog:check` from `package.json` scripts (and from `devcheck.config.json` if referenced), and drop `"changelog/"` from the `files` array. The `release` skill's directory-specific steps then don't apply — just edit `CHANGELOG.md` and bump version at release time.
 
-### 10. MCPB Bundling Artifacts
+### 10. Plugin Metadata (Codex / Claude Code)
+
+If `.codex-plugin/plugin.json` exists, verify it's populated and in sync with `package.json` and `server.json`:
+
+- `name` matches `package.json` `name`
+- `version` matches `package.json` `version`
+- `description` matches `package.json` `description`
+- `repository` matches `package.json` `repository.url`
+- `license` matches `package.json` `license`
+- `interface.displayName` = `package.json` `name`
+- `interface.shortDescription` matches `package.json` `description`
+- `interface.category` is set to a meaningful category
+
+If `.codex-plugin/mcp.json` exists, verify the server name key matches `package.json` `name` and env vars include any required API keys from the server config schema.
+
+If `.claude-plugin/plugin.json` exists, apply the same checks: `name`, `version`, `description`, `repository`, `license` from `package.json`. Verify the inline `mcpServers` entry key matches `package.json` `name` and env vars include any required API keys.
+
+### 11. MCPB Bundling Artifacts
 
 If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifest.json` at the project root), verify the full artifact set is present and consistent. If the project doesn't ship `.mcpb` bundles, skip this step.
 
@@ -196,11 +213,11 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - See `references/readme.md` for badge format and config generation commands
 - See the **Bundling** section of `templates/CLAUDE.md` for `base64` / `encodeURIComponent` generation
 
-### 11. `LICENSE`
+### 12. `LICENSE`
 
 Confirm a license file exists. If not, ask the user which license to use (default: Apache-2.0, matching the scaffolded `package.json`). Create the file.
 
-### 12. `Dockerfile`
+### 13. `Dockerfile`
 
 If a `Dockerfile` exists, verify the OCI labels and runtime config match the actual server:
 
@@ -211,7 +228,7 @@ If a `Dockerfile` exists, verify the OCI labels and runtime config match the act
 
 If no `Dockerfile` exists and the server is deployed via HTTP transport, consider scaffolding one — the template is available via `npx @cyanheads/mcp-ts-core init`.
 
-### 13. `docs/tree.md`
+### 14. `docs/tree.md`
 
 Regenerate the directory structure:
 
@@ -221,7 +238,7 @@ bun run tree
 
 Review the output for anything unexpected (leftover files, missing directories).
 
-### 14. Final Verification
+### 15. Final Verification
 
 Run the full check suite one last time:
 
@@ -243,6 +260,9 @@ Both must pass clean.
 - [ ] GitHub repo description matches `package.json` description; topics ↔ keywords in sync
 - [ ] `bunfig.toml` present
 - [ ] Changelog current — either monolithic `CHANGELOG.md` (hand-edited, Keep a Changelog) or directory-based (`changelog/<minor>.x/<version>.md` + rollup regenerated and in sync)
+- [ ] `.codex-plugin/plugin.json` populated and in sync with `package.json` (if present)
+- [ ] `.codex-plugin/mcp.json` server name and env vars current (if present)
+- [ ] `.claude-plugin/plugin.json` populated and in sync with `package.json` (if present)
 - [ ] MCPB artifacts consistent (if `manifest.json` present) — version synced, env vars match `server.json`, `bundle` + `lint:packaging` scripts exist, README install badges present
 - [ ] `LICENSE` file present
 - [ ] `Dockerfile` OCI labels and runtime config accurate (if present)

package/skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.5"
+  version: "2.7"
   audience: external
   type: workflow
 ---
@@ -131,11 +131,12 @@ Halt on any publisher error other than "cannot publish duplicate version".
 
 Only if `manifest.json` exists at the repo root (otherwise skip).
 
-Build the bundle, then create a Release on the existing annotated tag and attach the `.mcpb`. The Release sits on top of the tag from wrapup — `--verify-tag` enforces that the tag already exists on the remote and prevents `gh` from creating a lightweight tag that would shadow the annotated one. `--notes-from-tag` pulls release notes directly from the annotated tag message (no duplication). Note: GitHub prepends `v<VERSION>:` to the release title, so the tag annotation subject must omit the version number to avoid stutter.
+Build the bundle, then create a Release on the existing annotated tag and attach the `.mcpb`. The Release sits on top of the tag from wrapup — `--verify-tag` enforces that the tag already exists on the remote and prevents `gh` from creating a lightweight tag that would shadow the annotated one. `--notes-from-tag` pulls the tag annotation body as release notes. `--title` sets the release title from the tag subject — `--notes-from-tag` alone does NOT set the title (it defaults to the bare tag name, e.g. "v0.1.8" with no theme). The tag subject already omits the version number per the git-wrapup skill, so prepending `v<VERSION>:` produces the correct display title.
 
 ```bash
 bun run bundle              # produces dist/<name>.mcpb (stable filename, no version)
-gh release create v<VERSION> --verify-tag --notes-from-tag dist/*.mcpb
+SUBJECT=$(git tag -l --format='%(contents:subject)' v<VERSION>)
+gh release create v<VERSION> --verify-tag --notes-from-tag --title "v<VERSION>: $SUBJECT" dist/*.mcpb
 ```
 
 The stable filename matters: it lets the README "Install in Claude Desktop" badge point at `releases/latest/download/<name>.mcpb` and always resolve to the most recent release. The `bundle` script in the templates outputs `dist/{{PACKAGE_NAME}}.mcpb` for this reason.
@@ -178,7 +179,7 @@ If the project uses a non-GHCR registry or a custom image name, respect the proj
 Print clickable URLs for every destination that succeeded:
 
 - npm: `https://www.npmjs.com/package/<package.json#name>/v/<version>`
-- MCP Registry: `https://registry.modelcontextprotocol.io/v0/servers?search=<mcpName>` — `mcpName` is the `name` field from `server.json` (the unscoped server name, e.g. `bls-mcp-server`)
+- MCP Registry: `https://registry.modelcontextprotocol.io/v0.1/servers/<mcpName>/versions/<version>` — `mcpName` is the `name` field from `server.json` (URL-encode the `/` as `%2F`)
 - GitHub Release: `https://github.com/<OWNER>/<REPO>/releases/tag/v<VERSION>` (with `.mcpb` asset attached)
 - GHCR: `ghcr.io/<OWNER>/<REPO>:<VERSION>`
 
@@ -189,7 +190,7 @@ Skip any destination that was skipped in its step.
 Confirm each published artifact is actually live — don't rely on a successful push exit code alone. For each destination that succeeded:
 
 - **npm**: `npm view <package.json#name>@<version> version` — must return the version string
-- **MCP Registry**: `curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=<mcpName>"` — response must include `<version>` (`mcpName` is the `name` field from `server.json`)
+- **MCP Registry**: `curl -s "https://registry.modelcontextprotocol.io/v0.1/servers/<mcpName>/versions/<version>"` — must return HTTP 200 with `server.version` matching `<version>` (`mcpName` is the `name` field from `server.json`; URL-encode `/` as `%2F`). The search endpoint (`/v0.1/servers?search=`) paginates and may not include the latest version for packages with many releases — always use the direct version lookup.
 - **GitHub Release**: `gh release view v<VERSION> -R <OWNER>/<REPO> --json assets --jq '.assets[].name'` — must list the `.mcpb` file
 - **GHCR**: fetch an anonymous bearer token, then `curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $TOKEN" "https://ghcr.io/v2/<OWNER>/<REPO>/manifests/<VERSION>"` — must return HTTP 200
 
@@ -205,7 +206,7 @@ If any check fails, halt and report which destination is unreachable. A successf
 - [ ] Tags pushed to origin
 - [ ] `bun publish --access public` succeeds
 - [ ] `bun run publish-mcp` succeeds (if `server.json` present)
-- [ ] `bun run bundle` + `gh release create --verify-tag --notes-from-tag` succeeds (if `manifest.json` present)
+- [ ] `bun run bundle` + `gh release create --verify-tag --notes-from-tag --title` succeeds (if `manifest.json` present)
 - [ ] Docker buildx multi-arch push succeeds (if `Dockerfile` present)
 - [ ] All published artifacts verified reachable (npm, MCP Registry, GH Release asset, GHCR manifest)
 - [ ] On re-invocation: idempotent-success signals recognized for already-published destinations

package/templates/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "",
+  "author": {
+    "name": ""
+  },
+  "homepage": "",
+  "repository": "",
+  "license": "Apache-2.0",
+  "mcpServers": {
+    "{{PACKAGE_NAME}}": {
+      "command": "npx",
+      "args": ["-y", "{{PACKAGE_NAME}}"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio"
+      }
+    }
+  }
+}

package/templates/.codex-plugin/mcp.json

@@ -0,0 +1,9 @@
+{
+  "{{PACKAGE_NAME}}": {
+    "command": "npx",
+    "args": ["-y", "{{PACKAGE_NAME}}"],
+    "env": {
+      "MCP_TRANSPORT_TYPE": "stdio"
+    }
+  }
+}

package/templates/.codex-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "",
+  "author": {
+    "name": "",
+    "email": "",
+    "url": ""
+  },
+  "homepage": "",
+  "repository": "",
+  "license": "Apache-2.0",
+  "keywords": ["mcp", "mcp-server", "model-context-protocol"],
+  "mcpServers": "./.codex-plugin/mcp.json",
+  "interface": {
+    "displayName": "{{PACKAGE_NAME}}",
+    "shortDescription": "",
+    "longDescription": "",
+    "developerName": "",
+    "category": "",
+    "capabilities": ["Read"],
+    "websiteURL": "",
+    "defaultPrompt": []
+  }
+}

package/templates/AGENTS.md

@@ -369,6 +369,8 @@ security: false                            # optional — true flags security fi
 
 `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`.
 
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
 **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
@@ -401,4 +403,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
 - [ ] `npm run devcheck` passes

package/templates/CLAUDE.md

@@ -50,6 +50,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
 - **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
 ---
 
@@ -369,6 +370,8 @@ security: false                            # optional — true flags security fi
 
 `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`.
 
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
 **Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
 
 **Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
@@ -401,4 +404,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
 - [ ] `npm run devcheck` passes

package/templates/changelog/template.md

@@ -19,6 +19,14 @@ breaking: false
 # `## Security` section below. Flagged as `Security` in the rollup so
 # users can triage upgrade urgency at a glance.
 security: false
+
+# Optional free-form notes for maintenance agents processing this release.
+# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
+# downstream servers. Use for adoption instructions that don't fit the
+# human-facing sections: new files to create, fields to populate, one-time
+# migration steps. Omit the field entirely when there's nothing to say.
+# agent-notes: |
+#   <instructions for downstream maintenance agents>
 ---
 
 # <version> — YYYY-MM-DD

package/scripts/split-changelog.ts

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-/**
- * @fileoverview One-shot migration: split the monolithic CHANGELOG.md into
- * per-version files under `changelog/<major.minor>.x/<version>.md`.
- *
- * After the initial migration, this script is no longer needed — the
- * per-version files become the source of truth and `scripts/build-changelog.ts`
- * regenerates CHANGELOG.md from them. Keep this around only long enough to
- * verify the round-trip (split → build → diff).
- *
- * Behavior:
- *   • Reads CHANGELOG.md, splits on `## [X.Y.Z] - YYYY-MM-DD` headers
- *   • Groups by minor series: 0.1.4 → changelog/0.1.x/0.1.4.md
- *   • Writes each version block with an H1 heading
- *   • Creates changelog/template.md template if missing
- *   • Overwrites existing per-version files (idempotent)
- *   • Drops the preamble (title + description) — that's handled by the build script
- *
- * Usage: bun run scripts/split-changelog.ts
- *
- * @module scripts/split-changelog
- */
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-const CHANGELOG_PATH = resolve('CHANGELOG.md');
-const CHANGELOG_DIR = resolve('changelog');
-const TEMPLATE_PATH = resolve(CHANGELOG_DIR, 'template.md');
-
-const TEMPLATE_CONTENT = `# <version> — YYYY-MM-DD
-
-<!-- Brief summary of the upcoming release — delete this comment when filled in. -->
-
-## Added
-
--
-
-## Changed
-
--
-
-## Fixed
-
--
-`;
-
-interface Section {
-  body: string;
-  date: string;
-  version: string;
-}
-
-function extractSections(content: string): Section[] {
-  const regex = /^## \[([^\]]+)\] - (\d{4}-\d{2}-\d{2})$/gm;
-  const matches = [...content.matchAll(regex)];
-  if (matches.length === 0) {
-    throw new Error('No version sections found in CHANGELOG.md (expected ## [X.Y.Z] - YYYY-MM-DD)');
-  }
-
-  const sections: Section[] = [];
-  for (let i = 0; i < matches.length; i++) {
-    const match = matches[i] as RegExpMatchArray & { index: number };
-    const next = matches[i + 1] as (RegExpMatchArray & { index: number }) | undefined;
-    const start = match.index + match[0].length;
-    const end = next ? next.index : content.length;
-
-    let body = content.slice(start, end);
-    body = body.replace(/^\n+/, '');
-    body = body.replace(/\n+---\n*$/, '\n');
-    body = body.replace(/\n*$/, '\n');
-
-    sections.push({
-      version: match[1] as string,
-      date: match[2] as string,
-      body,
-    });
-  }
-  return sections;
-}
-
-/**
- * Promote heading levels by stripping one `#` from H2+ lines. Assumes no H1
- * or H2 in section bodies (the version H2 was already stripped); the existing
- * CHANGELOG.md uses H3 for Added/Changed/Fixed etc., which become H2 here.
- */
-function promoteHeadings(body: string): string {
-  return body.replace(/^(#{2,6}) /gm, (_, hashes: string) => `${hashes.slice(1)} `);
-}
-
-function toPerVersionFile(section: Section): string {
-  return `# ${section.version} — ${section.date}\n\n${promoteHeadings(section.body)}`;
-}
-
-/** Extract the `major.minor.x` series directory for a version string. */
-function seriesOf(version: string): string {
-  const [major, minor] = version.split('.');
-  if (!major || !minor) throw new Error(`Cannot derive series from version: ${version}`);
-  return `${major}.${minor}.x`;
-}
-
-function main(): void {
-  const content = readFileSync(CHANGELOG_PATH, 'utf-8');
-  const sections = extractSections(content);
-
-  mkdirSync(CHANGELOG_DIR, { recursive: true });
-
-  const seriesCounts = new Map<string, number>();
-
-  for (const section of sections) {
-    const series = seriesOf(section.version);
-    const seriesDir = resolve(CHANGELOG_DIR, series);
-    mkdirSync(seriesDir, { recursive: true });
-    const path = resolve(seriesDir, `${section.version}.md`);
-    writeFileSync(path, toPerVersionFile(section));
-    seriesCounts.set(series, (seriesCounts.get(series) ?? 0) + 1);
-  }
-
-  for (const [series, count] of [...seriesCounts.entries()].sort()) {
-    console.log(`  + changelog/${series}/ (${count} file${count === 1 ? '' : 's'})`);
-  }
-
-  if (!existsSync(TEMPLATE_PATH)) {
-    writeFileSync(TEMPLATE_PATH, TEMPLATE_CONTENT);
-    console.log('  + changelog/template.md (format reference)');
-  }
-
-  console.log(`\nSplit ${sections.length} versions into ${seriesCounts.size} series.`);
-  console.log('Next: `bun run scripts/build-changelog.ts` to regenerate CHANGELOG.md,');
-  console.log('      then `diff` against the original to verify byte-equality.');
-}
-
-main();