@cyanheads/mcp-ts-core 0.9.6 → 0.9.8

package/skills/multi-server-orchestration/references/greenfield-buildout.md

@@ -147,7 +147,7 @@ The big one. One sub-agent per target builds the full implementation from `docs/
 - "No write `git` commands: no `commit`, `push`, `add`, `tag`, `reset`, `restore`, `checkout --`, `clean`, `stash`. Read-only git is allowed — `status`, `diff`, `log` are useful for tracking your own changes."
 - "NEVER `git stash` for any reason. NEVER `git reset --hard`, `git restore .`, `git clean -f`, or `git checkout -- .` — these violate the global protocol."
 - "Do NOT run `field-test`. That's reserved for the user's manual verification later."
-- Orient block — non-negotiable.
+- Orient block — non-negotiable (see `../SKILL.md` for the template).
 
 **Expect context exhaustion on the largest targets.** The agent's work persists to disk even if its session dies, but the agent itself can't continue. Plan Phase 11 as the backstop — not a fallback for failure, a normal next phase.
 
@@ -175,10 +175,28 @@ No commits in this phase.
 
 ### Phase 13: Final wrap-up (fanout, Bash git only)
 
-Run only after the user authorizes. Same shape as Phase 5: per-target sub-agent invokes `git_wrapup_instructions` advice (via Bash git), authors `changelog/0.1.x/<version>.md`, regenerates `CHANGELOG.md` and `docs/tree.md`, version-bumps `package.json` and `server.json`, commits with a conventional subject, creates an annotated tag, pushes.
+Run only after the user authorizes. One sub-agent per target reads and executes the standalone `git-wrapup` skill (`skills/git-wrapup/SKILL.md`). All git calls use Bash, not git-mcp-server. After the local wrap-up, the agent pushes commits and tags to origin.
 
 Version bumps live with the change that warrants them per the global protocol's git rules — don't manufacture extra commits.
 
+## Recommended additional phases
+
+The 13-phase pattern above covers scaffold-to-ship. Experience from multi-server pipeline runs surfaces additional phases that earn their cost. Orchestrators building a prescriptive pipeline layer on top of this reference should consider inserting these:
+
+**Design gate (after Phase 3).** A third agent per target reads ONLY `docs/design.md` (no idea.md, no skill) and gives a pass/fail verdict. The point is cold-read validation: does the design make sense on its own? Filter out noise — only flag genuine structural issues, not style preferences. If all pass, proceed to build. If any fail, spawn focused fix agents.
+
+**Test quality review (after Phase 11/12).** Dedicated agents that audit test coverage and quality: are all tools tested? Are error paths exercised? Are edge cases covered? Build agents write tests as a secondary concern; dedicated test agents treat it as primary.
+
+**Field test (after test quality review).** Run the `field-test` skill per target — exercise tools with real inputs, report issues. May be blocked by API key requirements or rate limits. If blocked, note it and skip. If field tests surface issues, spawn fix agents and re-field-test.
+
+**Pre-launch sweep (before final wrap-up).** Singular-purpose verification agents per target:
+1. **Metadata sync** — descriptions aligned across package.json, manifest.json, server.json (100-char condensed), README header, GH repo description. Keywords/topics include baseline MCP terms. Versions consistent.
+2. **README accuracy** — README matches current code (tool names, parameter lists, examples, config table, feature list).
+3. **PII/secrets sweep** — no hardcoded credentials, API keys, personal emails, internal paths, or sensitive context in tracked files.
+4. **Error code semantic audit** — InvalidParams only for malformed JSON-RPC params shape; ValidationError for domain validation; NotFound for missing entities.
+
+These agents fix, not just report. Re-run devcheck + test after each.
+
 ## Gotchas specific to greenfield build-out
 
 | # | Gotcha | Mitigation |
@@ -190,6 +208,11 @@ Version bumps live with the change that warrants them per the global protocol's
 | 5 | `init` defaults package name to the cwd; if the project was scaffolded inside an outer dir, the name is wrong | Verify in Phase 4 prompt: "Check the substituted package name in `package.json`, `server.json`, and the agent protocol matches the intended server name." |
 | 6 | Sub-agent creates GH repo public by default if `gh repo create` omits `--private` | Restate the scenario hard rule in every fanout that touches `gh`: "Repo must be private before any push." |
 | 7 | Wrap-up agents have been observed reporting "pushed" while the remote ref didn't actually land — the push only succeeded on a subsequent op | Verify after every Bash-git fanout: `git ls-remote --tags origin` and `gh repo view --json defaultBranchRef` per target |
+| 8 | LICENSE file missing from scaffolded projects despite package.json declaring Apache-2.0 | Copy from `node_modules/@cyanheads/mcp-ts-core/LICENSE` during scaffold phase (run `bun install` first if `node_modules` isn't present) |
+| 9 | Description drift across surfaces — agents set descriptions independently, creating inconsistencies across package.json, manifest.json, server.json, README, and GH repo description | Pre-launch sweep phase catches this; or define the canonical description once in docs/design.md and have agents reference it |
+| 10 | `server.json` `isRequired` flags set without verifying upstream API reality | Pre-launch sweep should verify each env var's `isRequired` against actual API behavior (does it work without the key?) |
+| 11 | Build agents exhaust context and leave tests half-written — finish agents inherit the gap but don't prioritize test coverage | Dedicated test quality review phase after build/finish is the backstop |
+| 12 | Field-test agents can't run if the API requires a key the user hasn't provided | Check API key requirements before spawning field-test agents; skip with a note if blocked |
 
 ## Checklist
 
@@ -202,15 +225,22 @@ The orchestrator's checklist for a full N-target greenfield build:
 - [ ] Phase 1 — `docs/idea.md` authored per target
 - [ ] Phase 2 — design fanout — `docs/design.md` with Decisions Log per target
 - [ ] Phase 3 — critical review fanout — `docs/design.md` hardened per target
+- [ ] **Recommended: design gate — cold-read pass/fail per target**
 - [ ] Phase 4 — setup + repo fanout — repos created private, working tree unstaged, no commits
+- [ ] Phase 4 — package name verified in `package.json`, `server.json`, and agent protocol per target
+- [ ] Phase 4 — LICENSE file present in each target
 - [ ] Phase 5 — v0.1.0 wrap-up fanout (Bash git only) — commits + annotated tags + pushes; verified via `git log` and `git ls-remote --tags origin`
 - [ ] Phase 6 — polish docs/meta fanout against named gold-standard
 - [ ] Phase 7 — normalization — divergent conventions aligned
 - [ ] **If extension applicable:** Phase 8 — design extension fanout (e.g., DataCanvas for tabular servers)
 - [ ] **If Phases 6–8 produced doc changes the build should start from:** Phase 9 — interim wrap-up fanout (Bash git only) after user authorizes
 - [ ] Phase 10 — build fanout — implementation + tests + green devcheck per target
+- [ ] **If any Phase 10 agent didn't finish:** Phase 10 state documented per incomplete target (tool count, error count, missing tests) for Phase 11 prompt
 - [ ] **If any Phase 10 agent didn't finish:** Phase 11 — narrow-scope finish fanout per incomplete target
 - [ ] Phase 12 — simplify fanout — `code-simplifier` pass per target
+- [ ] **Recommended: test quality review — dedicated test coverage and quality audit**
+- [ ] **Recommended: field test — `field-test` skill per target (skip if API key blocker)**
+- [ ] **Recommended: pre-launch sweep — metadata sync, README accuracy, PII sweep, error code audit**
 - [ ] All targets: green `bun run devcheck` and `bun run test`
 - [ ] Phase 13 — final wrap-up fanout (Bash git only) — version bump, changelog file, regenerated rollup, commit + annotated tag + push; verified
 - [ ] Final read-only verification: tags pushed, repos still private, no stray uncommitted work

package/skills/multi-server-orchestration/references/maintenance-pass.md

@@ -59,7 +59,7 @@ One sub-agent per target. Each agent runs the `maintenance` skill end-to-end in
 > 3. Invoke the `changelog` skill for each updated package
 > 4. If `@cyanheads/mcp-ts-core` updated, do the deeper framework review from Step 4 of the maintenance skill
 > 5. Run Step 5 skill/script sync (Phase A: package → project `skills/`; Phase B: project `skills/` → agent dirs; Phase C: package scripts + pristine refs → project)
-> 6. Adopt changes per Step 6 — **framework changes are auto-adopt every applicable site in this pass**, no scope/effort/marginal-benefit deferrals; third-party libs are cost/benefit
+> 6. Adopt changes per Step 6 — **framework changes are auto-adopt every applicable site in this pass** (the maintenance skill's Step 6 defines "applicable site" — follow its guidance; don't infer scope from this summary), no scope/effort/marginal-benefit deferrals; third-party libs are cost/benefit
 > 7. `bun run rebuild` → `bun run devcheck` → `bun run test`
 > 8. Produce the Step 8 numbered summary (Updated packages, Breaking changes handled, Features adopted, Skills synced, New/changed skills available, Open decisions, Status)
 >
@@ -67,7 +67,7 @@ One sub-agent per target. Each agent runs the `maintenance` skill end-to-end in
 > - **No write git commands** — no `commit`, `push`, `tag`, `branch`, `merge`, `rebase`, `cherry-pick`, `add`, `reset`, `restore`, `checkout --`, `clean`, `stash`. Leave the working tree dirty for orchestrator review.
 > - Read-only git is allowed and expected — `status`, `diff`, `log`, `show`, `blame`. The maintenance skill's Step 5 Phase A explicitly requires `git diff skills/` after sync to surface adoption signal; do that.
 > - NEVER `git stash` for any reason. NEVER `git reset --hard`, `git restore .`, `git clean -f`, or `git checkout -- .` — these violate the global protocol.
-> - Halt and report if `bun run devcheck` can't be made green after adoption. `bun run test` is skip-not-halt: if the project has no `test` script in `package.json`, note it and continue.
+> - Halt and report if `bun run devcheck` can't be made green after adoption. `bun audit` failures from devcheck are note-not-halt if the advisory is in a transitive dep with no available patch — surface it in the Step 8 summary under Open decisions. `bun run test` is skip-not-halt: if the project has no `test` script in `package.json`, note it and continue.
 > - Output the Step 8 summary verbatim at the end of your run — the orchestrator parses it.
 >
 > If the `maintenance` skill's own version increased in Phase A of the skill sync (skill-version paradox), re-read the synced `skills/maintenance/SKILL.md` and continue from Step 5 onward with the new version.
@@ -94,6 +94,8 @@ Independent maintenance agents diverge on incidental choices and miss adoption s
 - **Content accuracy** — `isRequired` flags in `server.json` match the upstream API's actual requirement; `manifest.json` `name` doesn't include the npm scope prefix; `user_config` entries have required `title` and `type` fields
 - **Cross-target consistency** — if a feature shows up in 3 of 5 Step 8 summaries, the other 2 likely missed it
 
+Phase 3.5 agents operate under the same no-write-git constraint as Phase 2 agents — leave fixes in the working tree for Phase 4.
+
 These agents should **fix, not just report** — analysis-only agents create unnecessary follow-up. After fixing, re-run `bun run rebuild && bun run devcheck && bun run test`.
 
 Use a lighter model (e.g. Sonnet) for this pass — it's verification and targeted fixes, not deep adoption work.
@@ -104,7 +106,7 @@ Run only after explicit user authorization. Per-target commit decisions are driv
 
 - **Pure third-party dependency update** — `chore(deps): update dependencies` (or per-package if the diff is concentrated)
 - **Framework upgrade with adoption changes** — `chore(framework): mcp-ts-core <old> → <new>, adopt <pattern>`
-- **Mixed** — split into atomic commits per the global git rules ("Related changes ship together; unrelated changes split")
+- **Mixed** — split into atomic commits per the global git rules ("Related changes ship together; unrelated changes split"). Example: `package.json` + `bun.lock` + adoption code ship together in the framework adoption commit; unrelated third-party-only deps ship in a separate `chore(deps)` commit
 
 One sub-agent per target. Each agent:
 
@@ -114,6 +116,10 @@ One sub-agent per target. Each agent:
 
 If the maintenance pass should drive a version bump (breaking framework upgrade, or follow-on release intent), see the `release-and-publish` skill — the orchestrator may chain a release scenario as a separate run.
 
+## Orchestrator-driven updates
+
+If the orchestrator runs `bun update --latest` centrally before spawning sub-agents (e.g. to batch the network I/O or to run changelog investigation itself), pass the resolved version deltas (`package old → new`) into each sub-agent's prompt. This lets the agent skip re-discovery and jump straight to changelog review / framework adoption with concrete versions in hand.
+
 ## Gotchas specific to maintenance
 
 | # | Gotcha | Mitigation |
@@ -133,8 +139,10 @@ If the maintenance pass should drive a version bump (breaking framework upgrade,
 
 - [ ] Pre-flight: target list confirmed, clean working trees verified, `list-skills` presence noted per target, `maintenance` skill availability noted per target, `publish-mcp` and `manifest.json` presence noted, auth scope clarified with user
 - [ ] Phase 2: maintenance fanout spawned; each sub-agent returned a Step 8 summary
+- [ ] Phase 2 integrity: `git log --oneline -1` per target confirms no new commits written by sub-agents
 - [ ] All targets: green `bun run devcheck` and `bun run test` post-adoption
 - [ ] Phase 3: consolidated roll-up presented to user with per-target headlines, cross-target patterns, open decisions, outliers
+- [ ] Phase 3.5: double-check pass completed; adoption gaps fixed, audience compliance verified, `manifest.json` name/`user_config` validated; devcheck + test green per target after fixes
 - [ ] **User authorization captured for wrap-up if proceeding to Phase 4**
 - [ ] Phase 4: per-target commits via Bash git, pushed to origin
 - [ ] Final read-only verification: `git log --oneline -3` and `git ls-remote` per target — commits landed, no stray uncommitted work

package/skills/multi-server-orchestration/references/release-and-publish-pass.md

@@ -70,7 +70,7 @@ One sub-agent per target. Quick verification gate before any version bump or wra
 
 > Run `bun run devcheck`. Then run `bun run test:all` if it exists in `package.json` scripts, otherwise `bun run test`. Both must pass green. Halt and report the failing step's verbatim output if anything fails — do not attempt fixes from inside this phase. If neither `test:all` nor `test` exists in `package.json` scripts, note it and continue — devcheck-only is acceptable (though uncommon for a project shipping a release).
 
-Any red target halts the orchestration. The user fixes locally and re-invokes from Phase 2.
+Any red target halts the orchestration for that target. The user fixes locally and re-invokes Phase 2 for the failing target(s) only — other targets that passed don't need to re-run.
 
 ### Phase 3: README review fanout
 
@@ -80,7 +80,7 @@ One sub-agent per target reads the full README plus key adjacent docs, identifie
 
 > Read `README.md` from front to back. Identify content stale relative to the current code: tool/resource counts, version badges, feature lists, configuration tables, version mentions in install snippets. Fold updates in naturally — don't rewrite sections that are already accurate. Do NOT commit. Leave changes in the working tree for the next phase.
 >
-> If `polish-docs-meta` skill is available and the change spans more than just the README (e.g., new env vars, new tools), invoke that skill instead — it handles README plus `server.json`, `package.json`, agent protocol, and `.env.example` in one pass.
+> If `polish-docs-meta` skill is available (`skills/polish-docs-meta/SKILL.md`) and the change spans more than just the README (e.g., new env vars, new tools), invoke that skill instead — it handles README plus `server.json`, `package.json`, agent protocol, and `.env.example` in one pass.
 >
 > If the README is already accurate, report "no changes needed" and exit cleanly.
 
@@ -88,32 +88,20 @@ For a small patch bump, this phase is often a no-op. That's fine.
 
 ### Phase 4: Wrap-up fanout (Bash git only)
 
-Run only after user authorizes commits.
+Runs on the authorization captured in Pre-flight Step 5 — no separate authorization needed for wrap-up.
 
-One sub-agent per target. The agent executes the wrapup steps via Bash git — the same workflow `git_wrapup_instructions` walks through, but per-target absolute paths instead of session state.
+One sub-agent per target. The agent reads and executes the standalone `git-wrapup` skill (`skills/git-wrapup/SKILL.md`) — the skill contains the complete protocol for version bump, changelog, verification, commit, and annotated tag.
 
 **Task body:**
 
-> Run the version-bump wrapup via Bash `git` (no `git-mcp-server` tools — see the orchestration skill's Hard Rule 1).
+> Read and follow the `git-wrapup` skill — check `skills/git-wrapup/SKILL.md` first; fall back to `.claude/skills/git-wrapup/SKILL.md` if not found. Apply a `[patch/minor/major]` version bump.
 >
-> 1. **Inspect state:** `git status`, `git log --oneline -5`, `git diff --stat` on the working tree.
-> 2. **Determine the new version:** start from the current `package.json` `version`, apply the bump intent (`[patch/minor/major or explicit string]`). For a patch, e.g., `0.1.1 → 0.1.2`.
-> 3. **Author the changelog:** create `changelog/<major.minor>.x/<version>.md` per the directory-based convention. YAML frontmatter (`summary:` required, ≤350 chars, no markdown; `breaking:` and `security:` optional, default false). Grouped sections: Added / Changed / Fixed / Removed. Use the format reference at `changelog/template.md` — never edit, rename, or move that file.
-> 4. **Regenerate:** `bun run changelog:build` (rebuilds `CHANGELOG.md` rollup) and `bun run tree` (regenerates `docs/tree.md`).
-> 5. **Bump every version-bearing file:** `package.json` `version`, `server.json` `version` at the top level AND every `packages[].version` entry, any README badge that references the version. Use `grep -rn "<current-version>"` to find any you missed; resolve case by case.
-> 6. **Stage and commit.** Conventional Commits subject. Per the global protocol: version bumps ride with the change that warrants them — for a focused patch this is one commit. Subject style: `feat: <version> — <one-line theme>` or `chore(release): v<version> — <theme>`. Plain `-m` only, no heredoc, no `Co-authored-by` or `Generated with` trailers.
-> 7. **Annotated tag** `v<version>` (`-a`, NOT lightweight): terse message with release theme, notable changes, and dep arrows in `pkg ^old → ^new` form if applicable. Not a CHANGELOG copy.
+> Additional constraints for orchestrated runs:
+> - **Bash `git` only.** Do not use `git-mcp-server` (`mcp__git-mcp-server__*`) tools — session state leaks across parallel agents in the same orchestrator session.
+> - **Do NOT push.** Phase 5 handles the push as part of `release-and-publish`.
+> - If `v<version>` already exists as a tag, **halt and surface the conflict** to the orchestrator. Do NOT `git tag -d` without authorization.
 >
-> **Do NOT push.** Phase 5 handles the push as part of `release-and-publish`'s verification gate flow.
->
-> **Verify state at the end:**
-> ```bash
-> git log --oneline -1
-> git show v<version> --stat | head -20
-> git status   # should be clean
-> ```
->
-> Constraints: Bash git only. NEVER `git stash`. NEVER `reset --hard` / `restore .` / `clean -f` / `checkout -- .`. No marketing adjectives ("comprehensive", "robust", "enhanced", "seamless", "improved") in commit or tag messages. Be concise and accurate.
+> Output for the orchestrator: commit SHA, tag name, tag annotation subject.
 
 After this fanout, each target has a clean working tree with the wrap-up commit + annotated tag locally; nothing has been pushed.
 
@@ -132,7 +120,7 @@ Each target invokes the `release-and-publish` skill end-to-end. Execution mode d
 
 > Read `skills/release-and-publish/SKILL.md` (or `.claude/skills/release-and-publish/SKILL.md`). Run it end-to-end:
 >
-> 1. Sanity-check wrapup outputs (working tree clean, HEAD tagged `v<version>` from Phase 4)
+> 1. Sanity-check wrapup outputs (working tree clean, HEAD tagged `v<version>` from Phase 4). If either check fails, halt and report to the orchestrator — do not re-run Phase 4 from inside Phase 5
 > 2. Verification gate: `bun run devcheck`, `bun run rebuild`, `bun run test:all` (or `test`)
 > 3. Push commits and tags to origin via Bash git
 > 4. `bun publish --access public` (npm — uses the configured bypass token)
@@ -143,7 +131,7 @@ Each target invokes the `release-and-publish` skill end-to-end. Execution mode d
 >
 > Honor the skill's retry/halt protocol — transient network errors retry up to 2× with backoff; idempotent-success signals ("version already exists", "cannot publish duplicate version") are treated as success and proceed. Bash git for all git ops. Never skip the verification gate.
 
-**Serial mode:** the orchestrator runs `release-and-publish` against each target sequentially in its own session, handling OTP prompts interactively as they appear.
+**Serial mode:** the orchestrator spawns one sub-agent at a time per target — each runs `release-and-publish` end-to-end, completing before the next target starts. This prevents OTP prompt interleaving.
 
 After Phase 5, collect per-target status: which destinations succeeded, which (if any) halted with partial state. The user re-invokes Phase 5 for any failed targets only — completed destinations hit the idempotent-success signal and skip naturally.
 
@@ -178,7 +166,7 @@ Skip Phase 6 for any target whose Phase 5 didn't complete — there's nothing to
 | 9 | Sub-agent uses `git-mcp-server` instead of Bash git in Phase 4 or 5 | Hard Rule 1 restated explicitly in every fanout prompt that touches git |
 | 10 | Failed publish leaves a tag pushed but no npm package — looks shipped, isn't | Collect per-destination status per target in Phase 5 roll-up; surface partial-state targets explicitly to the user before Phase 6 |
 | 11 | `gh release create --notes-from-tag` fails with `--repo` flag | `gh` CLI limitation. Always `cd` into the target repo dir for `gh release` commands instead of using `--repo` |
-| 12 | Post-version doc changes (install badges, description fixes) land after the version commit — tag points at stale content | Move the tag forward: delete remote release, delete remote+local tag, recreate tag at new HEAD with same annotation, re-push, recreate release with `.mcpb`. This is authorized within the pipeline for same-day follow-ups |
+| 12 | Post-version doc changes (install badges, description fixes) land after the version commit — tag points at stale content | Move the tag forward: delete remote release, delete remote+local tag, recreate tag at new HEAD with same annotation, re-push, recreate release with `.mcpb`. This requires explicit user confirmation before executing — ask at runtime |
 | 13 | `mcpb pack` fails because `manifest.json` `user_config` entries are missing `title`/`type` fields | Verify `manifest.json` `user_config` entries during Phase 3 or a pre-Phase-5 check; the `polish-docs-meta` skill's cross-file consistency section covers this |
 
 ## Checklist
@@ -189,6 +177,7 @@ Skip Phase 6 for any target whose Phase 5 didn't complete — there's nothing to
 - [ ] Phase 3: README review fanout — updates folded, no commits
 - [ ] Phase 4: wrap-up fanout (Bash git only) — version bumped, changelog authored, rollup regenerated, commit + annotated tag per target — **NOT pushed**
 - [ ] Working tree clean per target; `git show v<version>` succeeds per target
+- [ ] Version-bearing files consistent across `package.json`, `server.json`, README badge, and `Dockerfile` OCI labels per target — no doc changes pending after the tag
 - [ ] Phase 5: release publish — completed per target via `release-and-publish` (parallel or serial based on 2FA mode); per-target status captured
 - [ ] All targets: deployed artifact URLs reported (npm / MCP Registry / GHCR as applicable)
 - [ ] **If GH issue map captured:** Phase 6: issue closure fanout — relevant issues commented and closed per target whose Phase 5 succeeded

package/skills/multi-server-orchestration/references/wrapup-pass.md

@@ -4,7 +4,7 @@ description: >
   Multi-server-orchestration reference for git wrap-up passes — distilled from `git-mcp-server`'s `git_wrapup_instructions` protocol. Drives parallel verification → optional doc review → wrap-up (version bump, changelog, commit, annotated tag — Bash git, local only, no push) → roll-up across N MCP server projects. Stops at "committed and tagged locally". No push, no publish — those are separate, separately-authorized workflows.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: internal
   type: reference
 ---
@@ -62,6 +62,8 @@ Phase 3 is optional — skip when the change is small enough that the README/doc
 
 ## Phase details
 
+> **Orient block:** the standard preamble instructing sub-agents to read `~/.claude/CLAUDE.md`, workspace `CLAUDE.md`, project `CLAUDE.md`, and run `bun run list-skills` — defined in `../SKILL.md`. Every sub-agent prompt starts with this block before the task body.
+
 ### Phase 2: Verification fanout
 
 One sub-agent per target. Quick verification gate before any version bump or wrap-up.
@@ -80,53 +82,27 @@ One sub-agent per target reads the README plus adjacent docs, identifies stale c
 
 > Read `README.md` from front to back. Identify content stale relative to the current code: tool/resource counts, version badges, feature lists, configuration tables, version mentions in install snippets. Fold updates in naturally — don't rewrite sections that are already accurate. Do NOT commit. Leave changes in the working tree for the next phase.
 >
-> If `polish-docs-meta` skill is available and the change spans more than just the README (e.g., new env vars, new tools), invoke that skill instead — it handles README plus `server.json`, `package.json`, agent protocol, and `.env.example` in one pass.
+> If `polish-docs-meta` skill is available (`skills/polish-docs-meta/SKILL.md`) and the change spans more than just the README (e.g., new env vars, new tools), invoke that skill instead — it handles README plus `server.json`, `package.json`, agent protocol, and `.env.example` in one pass.
 >
 > If the README is already accurate, report "no changes needed" and exit cleanly.
 
-For a small patch, this phase is often a no-op. That's fine — skip it entirely if pre-flight confirmed no user-facing change.
+For a small patch, this phase is often a no-op. Skip Phase 3 when the diff introduces no new tools, resources, env vars, or behavior changes visible to the user.
 
 ### Phase 4: Wrap-up fanout (Bash git only)
 
-Run only after user authorizes commits.
+Runs on the authorization captured in Pre-flight Step 4 — no separate authorization needed for wrap-up.
 
-One sub-agent per target. The agent executes the seven acceptance criteria via Bash `git` — no `git-mcp-server` (per the parent SKILL.md's Hard Rule 1, the MCP server's session state leaks across parallel agents).
+One sub-agent per target. The agent reads and executes the standalone `git-wrapup` skill (`skills/git-wrapup/SKILL.md`) — the skill contains the complete protocol for version bump, changelog, verification, commit, and annotated tag.
 
 **Task body:**
 
-> Execute the wrap-up protocol against this target. Acceptance criteria — strict on goals, generic on mechanism — but for `@cyanheads/mcp-ts-core` consumers, mechanism is concrete:
->
-> 1. **Diff reviewed.** `git status`, `git log v<latest-tag>..HEAD --oneline`, `git diff --stat`. Understand what's about to ship.
-> 2. **Version bump.** Start from current `package.json` `version`; apply the bump intent (`[patch/minor/major or explicit string]`). Bump every place version is declared:
->    - `package.json` `version`
->    - `server.json` `version` at the top level AND every `packages[].version` entry
->    - `manifest.json` (if present) `version`. Also verify `name` doesn't include the npm scope prefix — it should be the bare package name (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`)
->    - README version badge and any hero pinning
->    - Dockerfile OCI labels (if pinned to version)
->    - Any agent-instruction file (`CLAUDE.md`, `AGENTS.md`) that pins the version
->    
->    Run `grep -rn "<current-version>" .` to catch stragglers; resolve case by case (some hits are historical changelog entries — leave those).
-> 3. **Changelog authored.** Create `changelog/<major.minor>.x/<version>.md` per the directory-based convention. YAML frontmatter (`summary:` required, ≤350 chars, no markdown; `breaking:` and `security:` optional, default false). Section order (Keep a Changelog): Added / Changed / Deprecated / Removed / Fixed / Security. Include only sections with entries. Use `changelog/template.md` as the format reference — never edit, rename, or move it.
-> 4. **Regenerate derived artifacts.** `bun run changelog:build` (rebuilds `CHANGELOG.md` rollup from per-version files); `bun run tree` (regenerates `docs/tree.md` if the file structure changed).
-> 5. **Verification gate.** `bun run devcheck` must pass against the tree being committed. `bun run test:all` if it exists, otherwise `bun run test`. Both green. Halt if not green — do NOT bypass.
-> 6. **Atomic Conventional Commits.** Version bumps ride with the change that warrants them. For a focused patch, this is ONE commit covering the work + the version bump + changelog + regenerated artifacts. Subject form: `feat: <version> — <one-line theme>` or `chore(release): v<version> — <theme>`. Plain `-m` only — no heredoc, no `Co-authored-by`, no `Generated with` trailers. No marketing adjectives.
-> 7. **Annotated tag** `v<version>` (`-a`, NOT lightweight) with terse message: release theme, notable changes, dep arrows in `pkg ^old → ^new` form if applicable. Not a CHANGELOG copy. Length is earned.
+> Read and follow the `git-wrapup` skill — check `skills/git-wrapup/SKILL.md` first; fall back to `.claude/skills/git-wrapup/SKILL.md` if not found. Apply a `[patch/minor/major]` version bump.
 >
-> Constraints:
+> Additional constraints for orchestrated runs:
 > - **Bash `git` only.** Do not use `git-mcp-server` (`mcp__git-mcp-server__*`) tools — session state leaks across parallel agents in the same orchestrator session.
-> - **Do NOT push.** Wrap-up is local only. Push is a separate authorized step (`release-and-publish-pass.md` Phase 5, or the standalone `release-and-publish` skill).
-> - NEVER `git stash`. NEVER `git reset --hard`, `git restore .`, `git clean -f`, or `git checkout -- .` — these violate the global protocol.
-> - No marketing adjectives ("comprehensive", "robust", "enhanced", "seamless", "improved") in commit or tag messages. State the change.
-> - If `v<version>` already exists as a tag, **halt and surface the conflict**. Do NOT `git tag -d` without orchestrator authorization.
+> - If `v<version>` already exists as a tag, **halt and surface the conflict** to the orchestrator. Do NOT `git tag -d` without authorization.
 >
-> **Verify state at the end:**
-> ```bash
-> git log --oneline -1
-> git show v<version> --stat | head -20
-> git status   # should be clean
-> ```
->
-> Output for the orchestrator: commit SHA, tag name, tag annotation subject. The orchestrator parses these for Phase 5.
+> Output for the orchestrator: commit SHA, tag name, tag annotation subject.
 
 ### Phase 5: Roll-up (orchestrator)
 
@@ -139,6 +115,8 @@ for d in <target paths>; do
 done
 ```
 
+Spot-check commit and tag quality: `git log --format='%s%n%b' -1` for marketing adjectives in commit messages, `git show v<version>` for tag annotation structure.
+
 Then produces a consolidated report:
 
 1. **Per-target headline** — target → new version → tag annotation subject → commit SHA
@@ -152,7 +130,7 @@ Then produces a consolidated report:
 | 1 | Sub-agent pushes prematurely despite "local only" instruction | Restate "Do NOT push" in the Phase 4 prompt verbatim; verify post-fanout that `git log @{u}..HEAD` shows the wrap-up commit (i.e., still ahead of origin) |
 | 2 | Version bump skipped a file (`server.json`'s per-package entries, README badge, Dockerfile OCI labels, `manifest.json`) | Phase 4 prompt enumerates every version-bearing file; the `grep -rn "<current-version>"` step catches stragglers |
 | 3 | Tag at `v<version>` already exists (leftover from failed prior run, or two orchestrator runs against the same target) | Sub-agent halts and surfaces conflict; never `git tag -d` without orchestrator authorization. Inspect with `git tag -l "v<version>"` and `git show v<version>` |
-| 4 | Annotated tag message bloats into a CHANGELOG copy | Restate in Phase 4 prompt: terse theme + notable changes + dep arrows in `pkg ^old → ^new` form. Length is earned |
+| 4 | Annotated tag message bloats into a CHANGELOG copy, or collapses into a flat comma-separated string | Phase 4 prompt has explicit structured format: subject, prose intro, sectioned bullets, dep arrows, test footer. Both extremes (too long, too flat) are format violations |
 | 5 | Marketing adjectives slip into commit/tag messages | Restate the no-marketing rule in the prompt body; orchestrator spot-checks during Phase 5 (`git log --format='%s%n%b' -1`, `git show v<version>`) |
 | 6 | Sub-agent uses `git-mcp-server` instead of Bash git | Phase 4 prompt restates Hard Rule 1 from parent SKILL.md; session-state leak across parallel agents is real |
 | 7 | Verification gate skipped because "the change is small" | Restate "Halt if not green — do NOT bypass" in the prompt; the wrap-up protocol forbids bypass and the orchestrator confirms green status in Phase 5 |
@@ -169,3 +147,4 @@ Then produces a consolidated report:
 - [ ] Tags exist locally; nothing pushed to remotes
 - [ ] Phase 5: orchestrator verification — `git log --oneline -1`, `git tag --points-at HEAD`, `git status --short` per target
 - [ ] Consolidated report presented to user with per-target headlines, outliers, next steps
+- [ ] Orchestrator has NOT advanced to push, publish, or any remote operation — wrap-up is complete

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

@@ -72,7 +72,9 @@ Compare `.env.example` against the server config Zod schema. Add any missing ser
 
 Check for empty or placeholder metadata fields. Read `references/package-meta.md` for which fields matter and why. Fill in anything still missing — skip fields that are already correct.
 
-Key fields: `description`, `repository`, `author`, `homepage`, `bugs`, `keywords`.
+Key fields: `name`, `description`, `repository`, `author`, `homepage`, `bugs`, `keywords`.
+
+**`name` must communicate the server's domain at a glance.** See `references/package-meta.md` for the naming convention — ambiguous abbreviations and acronym-only names fail the scannability test for humans and agents alike.
 
 **`description` is the canonical source.** Every other surface (README header, `server.json`, Dockerfile OCI label, GitHub repo description) derives from it. Write it here first, then propagate.
 

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

@@ -6,7 +6,7 @@ Fields that may still be empty or generic from scaffolding. Check each one and f
 
 | Field | Default / Scaffolded | What It Should Be |
 |:------|:---------------------|:------------------|
-| `name` | `{{PACKAGE_NAME}}` (substituted by init) | Verify it's correct. Use scoped name if publishing (`@org/my-server`). |
+| `name` | `{{PACKAGE_NAME}}` (substituted by init) | Verify it communicates the server's domain at a glance. A human or agent scanning a list should know what this server does from the name alone. Prefer full names over ambiguous abbreviations (`libofcongress` not `loc`, `federal-reserve` not `fred`). Non-obvious acronyms get a descriptive suffix (`eia-energy`, `bls-labor`). Use scoped name if publishing (`@org/my-server`). |
 | `version` | `0.1.0` | Keep for initial development. Bump via the `release-and-publish` skill. |
 | `mcpName` | _(often missing)_ | Reverse-domain identifier: `"io.github.{owner}/{repo}"`. Used in `server.json` `name` field and Dockerfile OCI labels. |
 | `description` | `""` (empty) | One **action-first** sentence — lead with the actions/workflows, end with `via MCP. STDIO or Streamable HTTP.` (or the transports that apply). Example: `"Search projects, manage tasks, track teams via MCP. STDIO or Streamable HTTP."` Avoid `"MCP server for/that …"` framings. Appears on npm and in `npm search`; the README header tagline and `server.json` `description` derive from this (server.json drops the `via MCP …` suffix). |

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

@@ -182,7 +182,7 @@ Derive all tool/resource/prompt rows directly from the actual definitions. Use t
 
 ### Features
 
-Two subsection groups: framework capabilities, then domain-specific capabilities. Bullet lists, not prose.
+Three subsection groups: framework capabilities, domain-specific capabilities, then agent-friendly output design. Bullet lists, not prose.
 
 ```markdown
 ## Features
@@ -201,8 +201,21 @@ Acme-specific:
 - Type-safe client for the Acme v2 API
 - Automatic cleaning and simplification of API responses for agent consumption
 - Workflow tools parallelize related sub-requests under a configurable concurrency limit
+
+Agent-friendly output:
+
+- Provenance on every response — source labels, effective-query echo, and confidence/coverage caveats so agents can reason about trust
+- Graceful partial failure — batch tools return per-item success/error rows instead of failing the request, with structured status codes and actionable next-step text
+- Discriminated output contracts — typed status and source fields let callers branch on data, not string parsing
 ```
 
+The **Agent-friendly output** subsection documents output-design choices that make the server work well as an AI-agent backend. Include it when the server exhibits at least two of these patterns. Write bullets grounded in the server's actual behavior — not aspirational framework capabilities. Examples of what fits:
+
+- Provenance: source labels (`viaSource`, `source`), license/access-level fields, effective-query echo, best-effort warnings on lossy tiers
+- Partial failure: per-item status in batch operations, structured error rows alongside successes, recovery hints ("Next Step" text)
+- Discriminated outputs: union types on `source` or `status` fields, typed `unavailable` reasons, per-tier outcome traces (`triedTiers`)
+- Response shaping: stripping upstream noise, normalizing inconsistent schemas, deduplicating nested structures
+
 ### Getting Started
 
 Lead with the lowest-friction option. If a public hosted instance exists, show that first. Then the **three standard install configs in order — `bunx`, `npx`, `docker run`** — followed by the HTTP one-liner quickstart, then prerequisites and install steps.

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

@@ -73,7 +73,7 @@ If working tree is dirty or HEAD isn't on `v<version>`, halt.
 
 ### 2. Run the verification gate
 
-All three must succeed. Use `test:all` if the script exists in `package.json`, otherwise fall back to `test`:
+All three must succeed. Check `package.json` `scripts` for `test:all`; if absent, fall back to `test`:
 
 ```bash
 bun run devcheck
@@ -85,7 +85,7 @@ Any non-zero exit → halt with the failing command's output.
 
 ### 3. Push to origin
 
-Use your git tools to push commits and tags to origin. If the remote rejects either push, halt.
+Use your git tools to push the branch commits first, then push tags to origin. If the remote rejects either push, halt.
 
 ### 4. Publish to npm
 
@@ -106,13 +106,13 @@ Halt on publish error other than "version already exists" (which means this step
 
 ### 5. Publish to MCP Registry
 
-Only if `server.json` exists at the repo root (otherwise skip).
+Only if `server.json` exists at the repo root (otherwise skip). Note: `server.json` (MCP Registry metadata) and `manifest.json` (MCPB bundle manifest, step 6) are independent — a project may have either, both, or neither.
 
 ```bash
 bun run publish-mcp
 ```
 
-If `publish-mcp` isn't defined in `package.json`, add it (macOS):
+If `publish-mcp` isn't defined in `package.json`, add it permanently (one-time setup, macOS):
 
 ```json
 "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
@@ -171,22 +171,33 @@ docker buildx build --platform linux/amd64,linux/arm64 \
   --push .
 ```
 
-If the project uses a non-GHCR registry or a custom image name, respect the project's convention. Halt on build or push failure.
+If the project uses a non-GHCR registry or a custom image name, respect the project's convention. If push fails with a 401/403, prompt the user to authenticate (`echo $GITHUB_TOKEN | docker login ghcr.io -u <OWNER> --password-stdin`) and retry. Halt on build failure or non-auth push failure.
 
 ### 8. Report the deployed artifacts
 
 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=<package.json#mcpName>`
+- 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`)
 - GitHub Release: `https://github.com/<OWNER>/<REPO>/releases/tag/v<VERSION>` (with `.mcpb` asset attached)
 - GHCR: `ghcr.io/<OWNER>/<REPO>:<VERSION>`
 
 Skip any destination that was skipped in its step.
 
+### 9. Verify artifacts are reachable
+
+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`)
+- **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
+
+If any check fails, halt and report which destination is unreachable. A successful `docker push` or `bun publish` exit code does not guarantee the artifact is queryable — registry propagation delays, auth scoping, and partial failures all exist.
+
 ## Checklist
 
-- [ ] Working tree clean; HEAD tagged `v<version>`
+- [ ] Working tree clean; HEAD tagged `v<version>`; current branch name noted for push
 - [ ] `bun run devcheck` passes
 - [ ] `bun run rebuild` succeeds
 - [ ] `bun run test:all` (or `test`) passes
@@ -196,4 +207,6 @@ Skip any destination that was skipped in its step.
 - [ ] `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)
 - [ ] 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
 - [ ] Deployed artifact URLs reported to the user

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

@@ -180,12 +180,12 @@ Combine labels: `--label "bug" --label "regression"`.
 
 ### Attaching logs or stack traces
 
-For long output, write to a file and attach:
+For long output, write to a file and attach. Note: `--body-file` replaces the entire body — it does not supplement a `--body` flag. For structured bugs with logs, either embed the log content in the `Additional context` section of a normal `--body`, or file the issue first and add the log as a comment:
 
 ```bash
 bun run rebuild && bun run start:stdio 2>&1 | head -100 > /tmp/mcp-error.log
 
-# As part of a new issue
+# As part of a new issue (the log becomes the entire body — no template fields)
 gh issue create -R cyanheads/mcp-ts-core \
   --title "bug(transport): stdio crashes on large payload" \
   --label "bug" \
@@ -287,4 +287,6 @@ gh issue list -R cyanheads/mcp-ts-core --author @me
 - [ ] Running latest (or documented) framework version
 - [ ] Searched existing issues — no duplicate found
 - [ ] All secrets, credentials, and tokens redacted
-- [ ] Issue filed with: version, runtime, repro code, actual vs expected behavior
+- [ ] Primary label assigned (`bug` / `enhancement` / `documentation`)
+- [ ] If bug: version, runtime, repro code, actual vs expected behavior included
+- [ ] If feature: Proposal and Scope sections present; Out of scope defined

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

@@ -32,7 +32,7 @@ For general `gh` CLI workflows outside issue filing (PRs, workflows, API access)
 gh repo view --json nameWithOwner -q '.nameWithOwner'
 ```
 
-2. **Search existing issues**:
+2. **Search existing issues** — if a close match exists (same symptom, different tool; same tool, different symptom; closed issue that might cover the new case), add a comment on that issue instead of filing a new one — unless the symptom or scope is distinct enough to warrant separate tracking:
 
 ```bash
 gh issue list --search "your error message or keyword"
@@ -176,17 +176,19 @@ gh label create surplus-token-idea --color FF10F0 --description "Worth exploring
 
 ### Attaching logs or large output
 
+Note: `--body-file` replaces the entire body — it does not supplement a `--body` flag. For structured bugs with logs, either embed the log content in the `Additional context` section of a normal `--body`, or file the issue first and add the log as a comment:
+
 ```bash
 bun run rebuild && bun run start:stdio 2>&1 | head -200 > /tmp/server-error.log
 
-# As part of a new issue
+# As part of a new issue (the log becomes the entire body — no template fields)
 gh issue create \
   --title "bug(ingest): crashes on large payload" \
   --label "bug" \
   --assignee "@me" \
   --body-file /tmp/server-error.log
 
-# Or as a comment on an existing issue
+# Or as a comment on an existing issue (preferred — keeps the structured body intact)
 gh issue comment <number> --body-file /tmp/server-error.log
 ```
 
@@ -294,6 +296,9 @@ gh issue close <number> --reason completed --comment "Fixed in <commit or PR>"
 ## Checklist
 
 - [ ] Confirmed bug is in server code, not the framework
-- [ ] Searched existing issues — no duplicate found
+- [ ] Searched existing issues — no duplicate found; close matches commented instead of duplicated
 - [ ] All secrets, credentials, and tokens redacted
-- [ ] Issue filed with: version, runtime, repro steps, actual vs expected behavior
+- [ ] Title follows `type(scope): description` format
+- [ ] Primary label assigned (`bug` / `enhancement` / `documentation`)
+- [ ] If bug: version, runtime, repro steps, actual vs expected behavior included
+- [ ] If feature: Proposal and Scope sections present; Out of scope defined

package/skills/setup/SKILL.md

@@ -17,8 +17,8 @@ This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. Th
 
 The init CLI generates both `CLAUDE.md` and `AGENTS.md` with the same purpose. Keep one authoritative file for the agent you actually use:
 
-- **Claude Code** — keep `CLAUDE.md`, discard `AGENTS.md`
-- **All other agents** (Codex, Cursor, Windsurf, etc.) — keep `AGENTS.md`, discard `CLAUDE.md`
+- **Claude Code** — keep `CLAUDE.md`, delete `AGENTS.md`
+- **All other agents** (Codex, Cursor, Windsurf, etc.) — keep `AGENTS.md`, delete `CLAUDE.md`
 
 Both files serve the same purpose: project-specific agent instructions. Prefer committing one authoritative copy rather than trying to keep both in sync by hand.
 
@@ -94,7 +94,7 @@ After init:
 
 1. **Clean up what you don't need.** If your server has no prompts, delete the echo prompt and its registration in `src/index.ts`. Same for resources, or the app-tool pair if you're not targeting UI-capable clients.
 2. **Rename and replace what you keep.** The echo definitions and their tests show the pattern — swap them out for your real tools/resources/prompts.
-3. **Definitions register directly in `src/index.ts`.** No barrel files, just import and add to the `tools` / `resources` / `prompts` arrays.
+3. **Definitions register directly in `src/index.ts`.** The init scaffold uses direct imports — no barrel files yet. As the definition count grows, the `add-tool`/`add-resource`/`add-prompt` skills introduce `definitions/index.ts` barrels per the framework convention.
 
 See the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt`, `add-service`, and `add-test` skills for the scaffolding patterns when you start adding real definitions.
 
@@ -126,11 +126,13 @@ This step is the **bootstrap** — it creates the agent directory. From then on,
 
 ## Project Scaffolding
 
-After `bun install`, complete these one-time setup tasks:
+Complete these one-time setup tasks:
 
-1. **Update dependencies to latest** — `bun update --latest`. The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
-2. **Initialize git** — use your git tools: init the repo, stage all files, and commit with message `chore: scaffold from @cyanheads/mcp-ts-core`
-3. **Verify the substituted server name** — when `init` runs without a `[name]` argument, the package name defaults to the cwd directory name. If that's not what you want as the published server name, update `package.json`, `CLAUDE.md`/`AGENTS.md`, and `server.json` to your actual server name.
+1. **Install dependencies** — `bun install`
+2. **Update dependencies to latest** — `bun update --latest`. The scaffolded `package.json` pins minimum versions from when the framework was published; updating ensures you start with the latest compatible releases.
+3. **Initialize git** — use your git tools: init the repo, stage all files, and commit with message `chore: scaffold from @cyanheads/mcp-ts-core`
+4. **Verify the substituted server name** — when `init` runs without a `[name]` argument, the package name defaults to the cwd directory name. If that's not what you want as the published server name, update `package.json`, `CLAUDE.md`/`AGENTS.md`, and `server.json` to your actual server name.
+5. **Verify the scaffold builds clean** — `bun run devcheck`. Fix any issues before starting real work.
 
 ## Changelog Convention
 
@@ -153,7 +155,10 @@ Skip or reorder as the project calls for it. The agent protocol's "What's Next?"
 
 ## Checklist
 
-- [ ] Agent protocol file selected — keep one authoritative file (`CLAUDE.md` or `AGENTS.md`)
+- [ ] Agent protocol file selected — one authoritative file kept (`CLAUDE.md` or `AGENTS.md`), the other deleted
+- [ ] `bun install` run
+- [ ] Dependencies updated (`bun update --latest`)
+- [ ] Git repo initialized and initial commit made (`chore: scaffold from @cyanheads/mcp-ts-core`)
 - [ ] Substituted server name verified in `package.json`, agent protocol file, and `server.json`
 - [ ] Framework docs read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
 - [ ] Unused echo definitions cleaned up (and unregistered from `src/index.ts`)