@cyanheads/mcp-ts-core 0.9.6 → 0.9.8

package/skills/api-workers/SKILL.md

@@ -59,7 +59,7 @@ Fresh scaffolds register definitions directly in the entry point as shown above.
 
 - **Per-request `McpServer` factory**: a new server instance is created for each request. Required by SDK security advisory GHSA-345p-7cg4-v4c7.
 - **Env bindings refreshed per-request**: Cloudflare may rotate binding object references between requests; the handler re-injects them on every call.
-- **`ctx.waitUntil()` is documented but not yet called by the framework**: the `ExecutionContext` is received and passed through to `app.fetch` and `onScheduled`, but the framework does not currently call `ctx.waitUntil()` for telemetry flush. Spans complete synchronously within the request lifecycle.
+- **OTel NodeSDK is disabled in Workers** — `canUseNodeSDK()` returns `false` for V8 isolates, so no OTLP spans or metrics are emitted. Structured logs via `ctx.log` still work. `OTEL_ENABLED=true` has no effect in Workers. `ctx.waitUntil()` is received and passed through to `app.fetch` and `onScheduled` but not called by the framework (nothing to flush asynchronously).
 - **Singleton app promise with retry-on-failure**: the framework init runs once; if it fails, the next request retries rather than leaving the Worker in a permanently broken state.
 
 ---
@@ -130,7 +130,7 @@ In Workers, only these storage providers are allowed:
 `filesystem`, `supabase`, and unknown provider types are not on the whitelist:
 
 - **`filesystem`** and unknown types throw `ConfigurationError` in serverless environments.
-- **`supabase`** does **not** silently fall back. The framework may validate Supabase credentials first, but Worker startup still fails with `ConfigurationError` because Supabase storage is not a supported serverless provider. Do not set `STORAGE_PROVIDER_TYPE=supabase` in a Worker.
+- **`supabase`** does **not** silently fall back. The serverless provider whitelist check fires immediately at the top of `createStorageProvider()` — Supabase credentials are never validated. Worker startup fails with `ConfigurationError` because Supabase is not on the serverless whitelist. Do not set `STORAGE_PROVIDER_TYPE=supabase` in a Worker.
 
 Set `STORAGE_PROVIDER_TYPE` to one of the four whitelisted values to avoid unexpected behavior.
 
@@ -142,17 +142,24 @@ Set `STORAGE_PROVIDER_TYPE` to one of the four whitelisted values to avoid unexp
 compatibility_flags = ["nodejs_compat"]
 compatibility_date = "2025-09-01"  # must be >= 2025-09-01
 
+# Built-in storage providers require these exact binding names:
 [[kv_namespaces]]
-binding = "MY_CUSTOM_KV"
+binding = "KV_NAMESPACE"       # required for cloudflare-kv storage
 id = "..."
 
 [[r2_buckets]]
-binding = "MY_R2_BUCKET"
+binding = "R2_BUCKET"          # required for cloudflare-r2 storage
 bucket_name = "..."
+
+[[d1_databases]]
+binding = "DB"                 # required for cloudflare-d1 storage
+database_id = "..."
 ```
 
 `nodejs_compat` is required for Node.js API shims (e.g., `process.env`, `Buffer`, `crypto`). The minimum `compatibility_date` activates the required shim set.
 
+**Binding names for core storage are hardcoded** — the storage factory looks for `KV_NAMESPACE`, `R2_BUCKET`, and `DB` on `globalThis`. Using different binding names will cause a `ConfigurationError`. For custom (non-storage) bindings, use `extraObjectBindings` to map arbitrary binding names to `globalThis` keys.
+
 ---
 
 ## Workers-specific warnings
@@ -190,4 +197,4 @@ export function getServerConfig() {
 
 > `DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.`
 
-Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check `if (!ctx.core.canvas) { ... }` and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference.
+Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check the module-level accessor (`if (!getCanvas()) { ... }`) and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference and setup wiring pattern.

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

@@ -29,6 +29,14 @@ 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 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?
+
+- **Use the canonical platform/brand name, not abbreviations.** `libofcongress-mcp-server` not `loc-mcp-server` ("loc" reads as lines-of-code or location). `federal-reserve-mcp-server` not `fred-mcp-server` ("fred" reads as a person's name).
+- **Add a descriptive suffix when the base name is a non-obvious acronym.** Pattern: `{acronym}-{domain}-mcp-server` — e.g., `eia-energy-mcp-server`, `bls-labor-mcp-server`, `nhtsa-vehicle-safety-mcp-server`. Skip when the name is already self-descriptive (`earthquake-mcp-server`, `wikidata-mcp-server`).
+- **The name becomes the tool prefix.** Every tool is `{prefix}_{verb}_{noun}`, so the server name shows up in every tool call an agent sees. A descriptive name gives agents domain context without reading the server's instructions.
+
 ## Steps
 
 ### 1. Research External Dependencies
@@ -53,6 +61,8 @@ When research is genuinely parallelizable (multiple independent APIs, several SD
 - **Pagination behavior** — verify token format, page size limits, and what happens when results exceed one page.
 - **Error shapes** — trigger real 400/404/429 responses to see the actual error format, not just what docs claim.
 
+**Stopping condition:** at minimum, probe one list/search endpoint, one single-item GET, and one error case (force a 404 or 400). For large APIs with many resource types, add one probe per major noun. Stop when the response shapes and error envelope are confirmed.
+
 This step prevents building a service layer against assumed response shapes that don't match reality.
 
 ### 2. Map User Goals, Then Domain Operations
@@ -74,7 +84,7 @@ Then enumerate the underlying **domain operations** the system supports, grouped
 | Task | list (by project), get, create, update status, assign, comment |
 | User | list, get current |
 
-The user-goal list shapes the tool surface; the operation list fills in the gaps. Not every operation becomes a tool.
+The user-goal list shapes the tool surface; the operation list fills in the gaps. Not every operation becomes a tool — an operation stays as raw material (not its own tool) when it's already fully covered by an existing tool's output, or when the only agents who'd use it are in scenarios outside this server's stated purpose.
 
 ### 3. Classify into MCP Primitives
 
@@ -482,12 +492,12 @@ What this server does, what system it wraps, who it's for.
 
 Each step is independently testable.
 
-<!-- Optional sections for API-wrapping servers: -->
-## Domain Mapping          <!-- nouns × operations → API endpoints -->
-## Workflow Analysis        <!-- how tools chain for real tasks -->
-## Design Decisions         <!-- rationale for consolidation, naming, tradeoffs -->
-## Known Limitations        <!-- inherent API/data constraints the server can't solve -->
-## API Reference            <!-- query language, pagination, rate limits -->
+<!-- Optional sections — include when the trigger fires: -->
+## Domain Mapping          <!-- nouns × operations → API endpoints; include when ≥3 nouns each with ≥3 operations -->
+## Workflow Analysis        <!-- how tools chain for real tasks; include when any tool makes ≥3 upstream calls -->
+## Design Decisions         <!-- rationale for consolidation, naming, tradeoffs; include when a choice would otherwise be opaque -->
+## Known Limitations        <!-- inherent API/data constraints the server can't solve; include when a constraint visibly caps utility -->
+## API Reference            <!-- query language, pagination, rate limits; include when worth documenting -->
 ```
 
 Keep it concise. The design doc is a working reference, not a spec document — enough to orient a developer (or agent) implementing the server, not more.
@@ -512,7 +522,7 @@ The table surfaces design questions early: should the elicit happen before or af
 
 ### 9. Confirm and Proceed
 
-If the user has already authorized implementation (e.g., "build me a ___ server"), proceed directly to scaffolding using the design doc as the plan. Otherwise, present the design doc to the user for review before implementing.
+If the user has already authorized implementation — any message that contains both a design request and a build/implement verb in the same clause (e.g., "build me a ___ server", "design and implement a ___") — proceed directly to scaffolding using the design doc as the plan. Otherwise, present the design doc to the user for review before implementing.
 
 ## After Design
 
@@ -530,6 +540,7 @@ 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.
 
 - [ ] 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
 - [ ] Each operation classified as tool, resource, prompt, or excluded
 - [ ] Catastrophically irreversible operations excluded from the tool surface (stay in vendor UI) — not just `destructiveHint`
@@ -553,6 +564,7 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If a parameter determines blast radius:** safe default set (e.g., `mode: 'preview'`, `dryRun: true`, `confirmCount` required)
 - [ ] **App tools default to no.** If one was proposed, verified there's a real human-in-the-loop in an MCP Apps-capable client justifying the iframe/CSP/`format()`-twin maintenance cost — otherwise dropped in favor of a standard tool
 - [ ] **If the server exposes resources:** URIs use `{param}` templates, pagination planned for large lists
+- [ ] **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 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

package/skills/field-test/SKILL.md

@@ -19,7 +19,7 @@ Unit tests (`add-test` skill) verify handler logic with mocked context. Field te
 
 This skill drives an HTTP server because curl + JSON-RPC is the most reliable harness for shell-based agents. The same handlers run on both transports — only the framing differs — so HTTP exercises the full functional surface.
 
-**Stdio coverage is a boot check only.** Run `bun run rebuild && bun run start:stdio`, confirm the startup logs look clean (banner, expected tool/resource counts, no errors/warnings, no missing-config gripes), then kill it. Pino logs go to stderr in stdio mode (stdout is reserved for JSON-RPC), so they print straight to the terminal when you run interactively. No need to call tools over stdio — the HTTP pass already covered handler behavior.
+**Stdio coverage is a boot check only — run this before Step 1.** Run `bun run rebuild && bun run start:stdio`, confirm the startup logs look clean (banner, expected tool/resource counts, no errors/warnings, no missing-config gripes), then kill it. Pino logs go to stderr in stdio mode (stdout is reserved for JSON-RPC), so they print straight to the terminal when you run interactively. No need to call tools over stdio — the HTTP pass already covered handler behavior.
 
 ---
 
@@ -193,7 +193,7 @@ Capture `pid`, `url`, `port`, `log` from the `mcp_start` output — every later
 
 - `MCP_HTTP_PORT` is a *starting* port — the server auto-increments if taken. Helper parses the real URL from the log (`HTTP transport listening at ...`).
 - If `bun run rebuild` fails, stop. Don't field-test broken code — fix the build first.
-- If a server is already listening on the project's port (`lsof -i :<port>`), confirm with the user before killing it; it may be their own session.
+- If a server is already listening on the project's port (`lsof -i :<port>`), confirm with the user before killing it; it may be their own session. If the user isn't available to confirm, abort the field test and surface the port conflict in your response.
 
 ### 2. Initialize the session
 
@@ -251,7 +251,7 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 | Resource declared an `errors: [...]` contract | Error contract (resource): trigger ≥1 declared failure mode by reading a URI that exercises it. Resources re-throw errors at the JSON-RPC level — verify `error.code` matches the contract entry and `error.data.reason` is the declared reason. (Resources don't use the `result.isError` envelope — they fail the request itself.) |
 | Mutator (write/update/delete/append/patch verbs, or `destructiveHint: true`) | Mutator response observability: run an intentionally-ambiguous input (typo path, wrong ID, already-deleted target). Confirm the response carries enough state (pre/post values, state-change discriminator) for the agent to detect intent-effect divergence without re-fetching. |
 
-**Resources.** Happy path, not-found URI, `list` if defined, pagination if used.
+**Resources.** Happy path, not-found URI (use a syntactically valid but non-existent ID — e.g., substitute a fake ID into the URI template), `list` if defined, pagination if used.
 **Prompts.** Happy path, defaults omitted, skim message quality.
 
 **Sampling for large servers.** If more than 15 tools, run the universal battery on all, but pick roughly 30–40% for situational testing. Weight toward: write-shaped tools, complex schemas, external deps. List which ones you skipped in the report.
@@ -285,7 +285,7 @@ mcp_stop <pid> <log>
 rm -f /tmp/<project-name>-field-test-<ID>.sh
 ```
 
-Kills the background server, removes the server log, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session.
+Kills the background server, removes the server log, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session. If `mcp_stop` warns the PID is still alive after SIGKILL, note it in the report and proceed — don't block on a zombie process.
 
 ### 7. Report
 
@@ -332,13 +332,15 @@ End with:
 
 ## Checklist
 
-- [ ] Server built and started; real port parsed from log
+- [ ] Stdio boot check completed — `bun run rebuild && bun run start:stdio` shows clean startup (banner, expected counts, no errors)
+- [ ] HTTP server built and started; real port parsed from log
 - [ ] Session initialized; `notifications/initialized` sent
 - [ ] Catalog surfaced and presented; descriptions audited for leaks (implementation details, meta-coaching, consumer-aware phrasing)
-- [ ] Universal battery run on every definition
+- [ ] Universal battery run on every definition (happy path, parity, input error)
 - [ ] Situational categories applied only when triggered
+- [ ] **If >15 tools:** sampled 30–40% for situational testing; skipped definitions listed in report
 - [ ] **If a tool declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; `result.structuredContent.error.code` and `data.reason` verified against the contract entry
 - [ ] **If a resource declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; top-level JSON-RPC `error.code` and `error.data.reason` verified against the contract entry
 - [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
-- [ ] Server stopped; state file removed
+- [ ] Server stopped; server log and helper script removed
 - [ ] Report: summary paragraph → grouped findings → numbered options

package/skills/git-wrapup/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: git-wrapup
+description: >
+  Land working-tree changes as a versioned release commit with an annotated tag — version bump, changelog, regenerate derived artifacts, verify, commit, tag. Stops at "committed and tagged locally" — no push, no publish. The release-and-publish skill picks up from here. Distilled from the git_wrapup_instructions protocol.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: workflow
+---
+
+## When to use
+
+Working-tree or staged changes are ready to ship as a new version. This skill lands them as a single atomic commit with an annotated tag. It does NOT push or publish — that's a separate step (`release-and-publish`).
+
+Common triggers:
+- Feature work, bug fixes, or dependency updates are done and tested
+- A maintenance or polish pass left changes in the working tree
+- An orchestrator says "wrapup this project"
+
+## Pre-wrapup gate checklist
+
+Every item must be true before starting wrapup. Committing means releasing — a commit only happens when the work is ready to ship, not just "the edits are done." Each item is a goal to verify.
+
+- [ ] **Changes exist** — uncommitted files or commits since the last tag
+- [ ] **Work is complete** — no half-finished features, no "I'll add the test later," no TODO placeholders. The diff represents a shippable unit.
+- [ ] **Code simplified** — if the diff spans more than ~50 changed lines or touches 3+ source files, the `code-simplifier` skill has been run across the changes
+- [ ] **`bun run devcheck` passes** — typecheck + lint clean
+- [ ] **`bun run rebuild` succeeds** — full clean build from scratch
+- [ ] **All tests pass** — `bun run test:all` (or `bun run test`). New tests and regression tests added as needed for the changes being shipped.
+- [ ] **Fixes verified** — bug fixes validated, generally via `bun run rebuild` and field-testing. Not just written — confirmed to resolve the described behavior.
+- [ ] **No known regressions** — the changes don't break existing functionality
+- [ ] **GH issues updated** — issues addressed by this work commented with what landed and any follow-ups needed. Concise. Backlinked as needed.
+- [ ] **Docs updated** — surgical updates to existing docs as needed. New docs for new features. No large rewrites for documentation that's still accurate.
+
+If any gate is red, fix it before proceeding. This skill re-verifies build + tests in step 6, but starting wrapup on a broken tree wastes the version number and creates a revert-or-amend situation.
+
+After all gates pass, spawn dedicated agents to handle the wrapup (this skill) and publish (`release-and-publish`). These are separate agents from the ones that did the editing work.
+
+## Steps
+
+### 1. Review the diff
+
+Understand what's about to ship before touching version numbers:
+
+```bash
+git status
+git log v<latest-tag>..HEAD --oneline    # commits since last release
+git diff --stat                           # uncommitted changes
+git diff                                  # review the actual content
+```
+
+If the working tree is clean AND there are no commits since the last tag, halt — nothing to wrap up.
+
+### 2. Determine the new version
+
+Read the current version from `package.json`. Apply the intended bump:
+
+| Bump | When |
+|:-----|:-----|
+| **patch** | Bug fixes, dependency updates, metadata changes, docs |
+| **minor** | New tools, new features, new env vars, behavioral changes |
+| **major** | Breaking changes to tool schemas, removed tools, incompatible config |
+
+Default to **patch** unless the diff clearly warrants minor or major.
+
+### 3. Bump version everywhere
+
+Every file that declares a version must be updated. Skip any file that doesn't exist in the project. For `@cyanheads/mcp-ts-core` projects:
+
+- `package.json` — `version`
+- `server.json` — top-level `version` AND every `packages[].version` entry
+- `manifest.json` (if present) — `version`. Verify `name` is the bare package name (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`)
+- `README.md` — version badge
+- `CLAUDE.md` / `AGENTS.md` — if they pin a version string
+- `Dockerfile` — OCI labels if they pin the version
+
+Catch stragglers (replace the placeholder with the actual current version string, e.g. `0.9.7`):
+
+```bash
+grep -rn "0.9.7" . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=changelog
+```
+
+Resolve hits case by case — historical changelog entries are correct as-is; everything else should match the new version.
+
+### 4. Author the changelog
+
+Create `changelog/<major.minor>.x/<version>.md`. Use `changelog/template.md` as the format reference — never edit, rename, or move that file.
+
+**Frontmatter (required):**
+
+```yaml
+---
+summary: "<one-line headline, ≤350 chars, no markdown>"
+breaking: false    # true if consumers must change code to upgrade
+security: false    # true if this release contains a security fix
+---
+```
+
+**Body:** Section order follows Keep a Changelog — Added / Changed / Deprecated / Removed / Fixed / Security. Include only sections with entries. Delete empty sections.
+
+**Tone:** Terse, fact-dense. Lead each bullet with the symbol or concept in **bold**. One sentence per bullet by default. See the authoring guide in `changelog/template.md` for full conventions.
+
+### 5. Regenerate derived artifacts
+
+```bash
+bun run changelog:build    # rebuilds CHANGELOG.md rollup from per-version files
+bun run tree               # regenerates docs/tree.md — run when files were added, removed, or moved in src/
+```
+
+Both scripts are idempotent — safe to run even if nothing changed.
+
+### 6. Run the verification gate
+
+The tree being committed must pass verification. Both must succeed:
+
+```bash
+bun run devcheck
+bun run test:all           # or `bun run test` if no test:all script exists
+```
+
+**If either fails, halt.** Do not bypass verification to land the commit. Fix the issue first, then re-run from step 6.
+
+### 7. Commit
+
+Stage everything and create ONE atomic commit. Version bumps ride with the change that warrants them — the version bump is not a separate commit.
+
+```bash
+git add -A
+git commit -m "<subject>"
+```
+
+**Subject format:** Conventional Commits. Examples:
+- `feat: 0.1.5 — hosted server endpoint`
+- `fix: 0.2.1 — handle empty SPARQL result sets`
+- `chore(deps): 0.3.2 — mcp-ts-core ^0.9.1 → ^0.9.6`
+
+**Rules:**
+- Plain `-m` flag only — no heredoc, no command substitution
+- No `Co-authored-by` or `Generated with` trailers
+- No marketing adjectives ("comprehensive", "robust", "enhanced", "seamless", "improved")
+- The commit message must stand alone for someone reading `git log` — no references to chat context, option numbers, or "as discussed"
+
+**When to split into multiple commits:** Only when the working tree contains genuinely independent concerns (e.g., two unrelated bug fixes in unrelated files). NEVER split a single file's changes across commits.
+
+### 8. Create an annotated tag
+
+```bash
+git tag -a v<version> -m "<tag message with embedded newlines>"
+```
+
+Use `-m` with embedded newlines in the string (the commit `-m`-only constraint applies here too — no heredoc). The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string. Format:
+
+```
+<theme — omit version number, GitHub prepends v<VERSION>:>
+
+<1-2 sentence context: what this release does>
+
+<Sections — Keep a Changelog names, only those with entries>
+
+Added:
+
+- <bullet>
+
+Changed:
+
+- <bullet>
+
+<dep arrows if applicable>
+
+Dependency bumps:
+
+- `pkg` ^old → ^new
+
+<N> tests pass; `bun run devcheck` clean.
+```
+
+**Rules:**
+- Subject line omits the version number (GitHub prepends `v<VERSION>:` to the release title)
+- Not a CHANGELOG copy — terse, scannable
+- No marketing adjectives
+- Length is earned — two-line tags are fine for small patches
+
+### 9. Verify end state
+
+```bash
+git log --oneline -1              # confirm commit subject
+git show v<version> --stat | head -20   # confirm tag points at HEAD
+git status                        # must be clean
+```
+
+If the working tree isn't clean or the tag doesn't point at HEAD, something went wrong — investigate before proceeding.
+
+**Do NOT push.** This skill stops here. Use the `release-and-publish` skill for the push + publish workflow.
+
+## Constraints
+
+- **Local only.** No `git push`, no remote operations
+- **Never stash.** Not for quick checks, not for testing, not for any reason
+- **Never destructive.** No `git reset --hard`, `git restore .`, `git clean -f`, `git checkout -- .`
+- **Bash git only** when running inside orchestrated sub-agents (git-mcp-server session state leaks across parallel agents)
+- If `v<version>` already exists as a tag, **halt and report the conflict** — include the version string, existing tag SHA, and current HEAD SHA so the caller can resolve it. Do not delete or move tags without explicit authorization
+
+## Checklist
+
+- [ ] Diff reviewed end-to-end before version bump
+- [ ] Version bumped in every declaring file (`package.json`, `server.json`, `manifest.json`, README badge, `CLAUDE.md`/`AGENTS.md` if they pin a version)
+- [ ] GH issues addressed by this work commented with what landed (if working from GH issues)
+- [ ] Docs updated for any new or changed features
+- [ ] Changelog authored at `changelog/<major.minor>.x/<version>.md`
+- [ ] `CHANGELOG.md` rollup regenerated (`bun run changelog:build`)
+- [ ] `docs/tree.md` regenerated if structure changed (`bun run tree`)
+- [ ] `bun run devcheck` passes
+- [ ] `bun run test:all` (or `test`) passes
+- [ ] One atomic commit in Conventional Commits format
+- [ ] Annotated tag `v<version>` with structured markdown message
+- [ ] Working tree clean
+- [ ] Nothing pushed — local only

package/skills/maintenance/SKILL.md

@@ -48,11 +48,11 @@ Capture the `↑ package old → new` lines from stdout — these feed Step 3. A
 
 Invoke the **`changelog`** skill with the captured list of updated packages. It resolves each repo, fetches release notes (or CHANGELOG entries) between old and new versions, and cross-references changes against actual imports in `src/`. Output per package: what changed, impact on this project, action items.
 
-Do not redo this investigation inline — the `changelog` skill handles tag-format detection, monorepo patterns, and fallbacks.
+Do not redo this investigation inline — the `changelog` skill handles tag-format detection, monorepo patterns, and fallbacks. If the skill cannot resolve a package (private repo, no tags, no CHANGELOG), note it in Step 8 under "Open decisions" and proceed.
 
 ### 4. Framework review (`@cyanheads/mcp-ts-core`)
 
-**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`'s `version` exceeds the one running, run Step 5 Phase A first and re-invoke `maintenance` — otherwise feature-adoption rows added in the new version silently don't surface.
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`'s `version` exceeds the one running, run Step 5 Phase A first and re-invoke `maintenance` — otherwise feature-adoption rows added in the new version silently don't surface. After Phase A, confirm the running skill version matches the package before continuing. If the session still has the old skill loaded, exit and restart.
 
 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.
 
@@ -84,7 +84,7 @@ Cross-reference each finding against the server's code. Collect adoption opportu
 
 **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`.
 
-Read the upstream template end-to-end, mentally comparing against the current `CLAUDE.md`/`AGENTS.md`. Apply framework-authored updates directly — new skill references in the skills table, new entries in the "What's Next?" section, updated convention callouts, clarified patterns. These are factual updates, not taste decisions; the consumer's agent protocol file is meant to track the framework's. Only surface a decision when a template change conflicts with a section the consumer has intentionally customized (server-specific domain context, bespoke checklists, etc.) — in that case, note the conflict and ask.
+Read the upstream template end-to-end, mentally comparing against the current `CLAUDE.md`/`AGENTS.md`. Apply framework-authored updates directly — new skill references in the skills table, new entries in the "What's Next?" section, updated convention callouts, clarified patterns. These are factual updates, not taste decisions; the consumer's agent protocol file is meant to track the framework's. Only surface a decision when a template change conflicts with a section the consumer has intentionally customized — a section is "intentionally customized" when it contains server-specific domain context, bespoke checklists, or content that doesn't originate from the template. In that case, note the conflict and ask.
 
 ### 5. Sync project skills and scripts
 
@@ -205,7 +205,7 @@ bun run test
 
 `rebuild` (clean + build) catches API surface and type-alignment issues that `devcheck` alone may miss — module resolution, path aliases, post-build processing. `devcheck` includes `bun audit` and `bun outdated`, so no separate audit step is needed.
 
-In **Mode B**, the user already ran rebuild + test before invoking this skill, but run them again here — Step 6 made code changes that need verification.
+In **Mode B**, the user already ran rebuild + test before invoking this skill, but run them again here — Step 6 made code changes that need re-verification.
 
 Fix anything that fails. Re-run until clean.
 
@@ -226,13 +226,15 @@ Present a concise numbered summary to the user:
 ## Checklist
 
 - [ ] Update applied (`bun update --latest`) — Mode A, or already done by user — Mode B
+- [ ] Skill-version paradox checked — if package maintenance skill version > running version, Phase A run first and skill re-invoked
 - [ ] `changelog` skill invoked for each updated package
 - [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
-- [ ] Every applicable framework adoption opportunity applied in this pass — no scope/effort/marginal-benefit deferrals; third-party adoptions evaluated on cost/benefit
+- [ ] Framework `CLAUDE.md`/`AGENTS.md` template reviewed; applicable updates applied or conflicts surfaced
+- [ ] Step 6 complete — all applicable framework adoption sites updated; third-party adoption decisions recorded
 - [ ] 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/` 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 rebuild` succeeds (re-run after Step 6, even in Mode B)
 - [ ] `bun run devcheck` passes (includes audit + outdated)
 - [ ] `bun run test` passes
 - [ ] Numbered summary presented to user

package/skills/migrate-mcp-ts-template/SKILL.md

@@ -20,7 +20,7 @@ For the full exports catalog, see `CLAUDE.md` → Exports Reference.
 ## Steps
 
 1. **Install the package**: `bun add @cyanheads/mcp-ts-core`
-2. **Search for all `@/` imports** across `src/` that reference framework internals
+2. **Search for all `@/` imports** across `src/` that reference framework internals: `grep -rn "from '@/" src/`
 3. **Rewrite each import** using the mapping table below
 4. **Identify framework source files** now provided by the package (see candidates below) — review each for server-specific additions before cleaning up
 5. **Update entry point** (`src/index.ts`) to use `createApp()` from the package and the project's chosen registration pattern (fresh scaffold default: direct imports in `src/index.ts`)
@@ -52,9 +52,9 @@ These are the actual `@/` import paths used in framework source. Rewrite any tha
 
 | Old `@/` import | New package import |
 |:----------------|:-------------------|
-| `@/mcp-server/tools/utils/toolDefinition.js` | `@cyanheads/mcp-ts-core/tools` or `@cyanheads/mcp-ts-core` (for `tool()` builder) |
-| `@/mcp-server/resources/utils/resourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` or `@cyanheads/mcp-ts-core` (for `resource()` builder) |
-| `@/mcp-server/prompts/utils/promptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` or `@cyanheads/mcp-ts-core` (for `prompt()` builder) |
+| `@/mcp-server/tools/utils/toolDefinition.js` | `@cyanheads/mcp-ts-core/tools` (types only: `ToolDefinition`, `AnyToolDefinition`) or `@cyanheads/mcp-ts-core` (for the `tool()` builder) |
+| `@/mcp-server/resources/utils/resourceDefinition.js` | `@cyanheads/mcp-ts-core/resources` (types only: `ResourceDefinition`, `AnyResourceDefinition`) or `@cyanheads/mcp-ts-core` (for the `resource()` builder) |
+| `@/mcp-server/prompts/utils/promptDefinition.js` | `@cyanheads/mcp-ts-core/prompts` (types only: `PromptDefinition`) or `@cyanheads/mcp-ts-core` (for the `prompt()` builder) |
 | `@/mcp-server/tasks/utils/taskToolDefinition.js` | `@cyanheads/mcp-ts-core/tasks` |
 
 ### Utils
@@ -90,7 +90,9 @@ After rewriting imports, these directories and files are candidates for cleanup
 
 **Preserve:** server-specific code under `mcp-server/tools/definitions/`, `mcp-server/resources/definitions/`, `mcp-server/prompts/definitions/`, the server's own `services/`, and `config/server-config.ts`.
 
-Framework directories (typically safe to clean up in full — verify no server-specific files were added):
+A file is server-specific if it doesn't appear in the `mcp-ts-template` repo at its path. Modified framework files should be extracted to a server-specific location (e.g., `src/utils/my-project/`) before deletion.
+
+Framework directories (typically safe to remove in full — verify no server-specific files were added):
 
 - `src/core/` (app, context, worker)
 - `src/cli/`
@@ -113,7 +115,7 @@ Framework files within directories that contain server code:
 
 ## Entry point rewrite
 
-Replace the fork's `src/index.ts` with the scaffold-default direct-registration pattern:
+Rewrite the `createApp()` call and its surrounding imports to use the package. Preserve the project's existing barrel structure and registration pattern if present:
 
 ```ts
 #!/usr/bin/env node
@@ -153,6 +155,8 @@ If the migrated project already has `definitions/index.ts` barrels and you want
 - [ ] `tsconfig.json` extends `@cyanheads/mcp-ts-core/tsconfig.base.json`
 - [ ] `biome.json` extends `@cyanheads/mcp-ts-core/biome`
 - [ ] `vitest.config.ts` spreads from `@cyanheads/mcp-ts-core/vitest.config`
-- [ ] Framework source files cleaned up from `src/`
+- [ ] Framework-only directories removed (`src/core/`, `src/cli/`, `src/types-global/`, `src/storage/`, `src/utils/`, `src/testing/`, framework service subdirs)
+- [ ] Framework files within mixed directories removed (`server.ts`, `transports/`, `roots/`, tasks infra, `*/utils/` dirs, `*-registration.ts` files)
+- [ ] `vitest.config.ts` includes `@/` alias: `resolve: { alias: { '@/': new URL('./src/', import.meta.url).pathname } }`
 - [ ] Server-specific `@/` imports (own tools, services) still work
 - [ ] `bun run devcheck` passes

package/skills/multi-server-orchestration/SKILL.md

@@ -28,11 +28,11 @@ Read this SKILL.md end-to-end first — the concepts, orient block, and hard rul
    |:----------------|:---------------------------|
    | **Greenfield build-out** | Echo definitions still present in `src/mcp-server/{tools,resources,prompts}/definitions/`, no real services in `src/services/`, no released changelog files under `changelog/<minor>.x/`, `package.json` version is `0.0.0` or unset |
    | **Maintenance pass** | Real tool/resource definitions present, framework deps installed, `bun outdated` reports updates available, at least one prior release tagged |
-   | **Release pass** | Working tree has uncommitted/staged work, OR `git log v<latest-tag>..HEAD` shows commits since the last release that warrant a new version, OR the user explicitly asks to "ship", "release", or do a version bump |
+   | **Wrap-up / release pass** | Working tree has uncommitted/staged work, OR `git log v<latest-tag>..HEAD` shows commits since the last release that warrant a new version, OR the user explicitly asks to "ship", "release", or do a version bump. If the user explicitly wants to publish to npm/registries → release-and-publish pass; if local-only → wrap-up pass |
    | **Neither** | None of the above match cleanly — surface the state to the user, ask what they want |
 
 3. **Pick the reference** from the References table below. Each reference contains its scenario's phase pattern, per-sub-agent prompt bodies, scenario-specific gotchas, and checklist.
-4. **Surface the plan to the user** before kicking off the first fanout: scenario, target list, phase summary, gotchas in play. Get explicit authorization before any phase that commits, tags, pushes, or creates remote resources.
+4. **Surface the plan to the user** before kicking off the first fanout: scenario, target list, phase summary, gotchas in play. Get explicit authorization before any phase that commits, tags, pushes, or creates remote resources. Non-destructive phases (read, analyze, write files, devcheck) proceed without additional check-ins after the initial plan approval.
 
 ## References
 
@@ -40,8 +40,8 @@ Read this SKILL.md end-to-end first — the concepts, orient block, and hard rul
 |:---------|:----------|:-----|
 | **Greenfield build-out** | `references/greenfield-buildout.md` | New server(s) from `bunx @cyanheads/mcp-ts-core init` driven through design → build → first release |
 | **Maintenance pass** | `references/maintenance-pass.md` | Existing server(s) need `bun update --latest`, changelog investigation, framework adoption, and verification — optionally followed by a commit/push |
-| **Wrap-up pass** | `references/wrapup-pass.md` | Existing server(s) with committed/staged work to land locally as a new commit + annotated tag — verification → optional doc review → wrap-up (version + changelog + commit + tag) — **local only, no push**. Distilled from `git_wrapup_instructions` |
-| **Release-and-publish pass** | `references/release-and-publish-pass.md` | Existing server(s) have committed/staged work that needs to ship as a new version end-to-end — verification → README polish → wrap-up (version + changelog + commit + tag) → publish (npm / MCP Registry / GHCR via the `release-and-publish` skill) → optional GH issue closure. Disambiguated from the standalone `release-and-publish` skill, which is the single-target publish step this reference invokes per target |
+| **Wrap-up pass** | `references/wrapup-pass.md` | Existing server(s) with committed/staged work to land locally as a new commit + annotated tag — verification → optional doc review → wrap-up (version + changelog + commit + tag) — **local only, no push**. Sub-agents execute the standalone `git-wrapup` skill per target |
+| **Release-and-publish pass** | `references/release-and-publish-pass.md` | Existing server(s) have committed/staged work that needs to ship as a new version end-to-end — verification → README polish → wrap-up → publish → optional GH issue closure. Sub-agents execute the standalone `git-wrapup` then `release-and-publish` skills per target |
 
 **Mental model — scenarios are related but never auto-chain.** A maintenance pass often produces work worth wrapping up; a wrap-up commonly precedes a release; a greenfield build-out ends with what's effectively a release. Useful for orienting around what comes next conceptually — but **each scenario requires its own explicit user authorization to invoke**. The orchestrator never advances from one to the next on its own. Pick the reference for the current scope; if more work follows, wait for the user to direct it.
 
@@ -122,4 +122,16 @@ These commonly bite across all scenarios. Scenario-specific gotchas live in thei
 
 ## Extending the pattern
 
-When a new scenario emerges that's worth codifying (security-pass fanout across N servers, framework-wide migration, etc.), author a new reference at `references/<scenario>.md` and add a row to the table above. The reference should follow the shape of the existing two: scope, pre-flight, phase table, phase details, scenario-specific gotchas, checklist. The concepts/orient/rules/gotchas in this SKILL.md don't need to be restated — the reference assumes the reader started here.
+When a new scenario emerges that's worth codifying (security-pass fanout across N servers, framework-wide migration, etc.), author a new reference at `references/<scenario>.md` and add a row to the table above. The reference should follow the shape of the existing references (e.g., `greenfield-buildout.md`): scope, pre-flight, phase table, phase details, scenario-specific gotchas, checklist. The concepts/orient/rules/gotchas in this SKILL.md don't need to be restated — the reference assumes the reader started here.
+
+## Pre-flight Checklist
+
+Applies to all scenarios — verify before picking a reference and kicking off the first fanout.
+
+- [ ] Target list captured with absolute paths and per-target metadata
+- [ ] Scenario identified from intent + state; confirmed with user if ambiguous
+- [ ] Reference selected from the table above
+- [ ] `scripts/list-skills.ts` + `list-skills` package script present in each target
+- [ ] Plan surfaced to user: scenario, targets, phase summary, active gotchas
+- [ ] User authorization captured for any phase that commits, tags, pushes, or creates remote resources
+- [ ] Scenario reference read in full before first fanout