@cyanheads/mcp-ts-core 0.12.8 → 0.13.0

package/{skills → framework-skills}/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "2.6"
+  version: "2.7"
   audience: external
   type: workflow
 ---
@@ -52,7 +52,7 @@ Do not redo this investigation inline — the `changelog` skill handles tag-form
 
 ### 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. 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.
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/framework-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.
 
@@ -77,8 +77,8 @@ Scan specifically for:
 | Deprecations | Migrate now, before the next breaking release |
 | Config changes | New env vars, renamed keys, changed defaults |
 | Linter rules | New definition-lint rules that may now flag existing tools/resources |
-| New or materially-changed skills | Note new skills or workflow changes (renamed steps, new checklist items) worth surfacing at end-of-run. Don't auto-invoke — some skills (e.g. `security-pass`) are user-triggered. The per-version changelog entries (e.g. 0.6.14 calling out `skills/security-pass/ (v1.0)`) name what changed. |
-| New template-scaffolded files | Compare `templates/` in the package against the project root. Files that `init` would create for a new project but don't exist in this project are adoption candidates — create them with project-specific values (version, name, description, env vars from `server.json`). Examples: `manifest.json`, `.mcpbignore`, `.codex-plugin/`, `.claude-plugin/`. Skip files the project has intentionally opted out of (documented in CLAUDE.md/AGENTS.md or a code comment). |
+| New or materially-changed skills | Note new skills or workflow changes (renamed steps, new checklist items) worth surfacing at end-of-run. Don't auto-invoke — some skills (e.g. `security-pass`) are user-triggered. The per-version changelog entries (e.g. one calling out `security-pass` v1.0) name what changed. |
+| New template-scaffolded files | Compare `templates/` in the package against the project root. Files that `init` would create for a new project but don't exist in this project are adoption candidates — create them with project-specific values (version, name, description; user-supplied variables from `server.json` go into `userConfig` + `${user_config.<option>}` for `.claude-plugin/` and into `env_vars` for `.codex-plugin/mcp.json`, never as `""` in `env`). Examples: `manifest.json`, `.mcpbignore`, `.codex-plugin/`, `.claude-plugin/`. Skip files the project has intentionally opted out of (documented in CLAUDE.md/AGENTS.md or a code comment). |
 | Changelog `agent-notes` | Read `agent-notes` frontmatter from each new per-version changelog file — these carry release-specific adoption instructions for downstream consumers (new files to create, fields to populate, one-time migration steps). Apply them alongside other adoption work in Step 6. |
 
 Cross-reference each finding against the server's code. Collect adoption opportunities for Step 6.
@@ -89,29 +89,31 @@ Read the upstream template end-to-end, mentally comparing against the current `C
 
 ### 5. Sync project skills and scripts
 
-Skills flow in two hops: package → project `skills/` → agent directories. Framework scripts flow in one: package → project `scripts/`. Both drift silently unless resynced.
+Skills flow in two hops: package → project `framework-skills/` → agent directories. Framework scripts flow in one: package → project `scripts/`. Both drift silently unless resynced.
 
-**Phase A — Package → Project `skills/`**
+**Phase A — Package → Project `framework-skills/`**
 
-1. **Package** — `node_modules/@cyanheads/mcp-ts-core/skills/` (canonical source)
-2. **Project** — `skills/` at project root (working copy; may contain local overrides or server-specific skills)
+1. **Package** — `node_modules/@cyanheads/mcp-ts-core/framework-skills/` (canonical source)
+2. **Project** — `framework-skills/` at project root (working copy; may contain local overrides or server-specific skills)
+
+**One-time migration from `skills/` (framework 0.13.0).** Earlier releases scaffolded this tree at `skills/`. Claude Code and Codex auto-load a plugin's root `skills/`, so a server shipping `.claude-plugin/` or `.codex-plugin/` handed its development skills to every agent that installed it. If the project has `skills/` and no `framework-skills/`: `git mv skills framework-skills`, then update every path reference — `CLAUDE.md`/`AGENTS.md`, `.mcpbignore` (`/skills/` → `/framework-skills/`), `.github/CONTRIBUTING.md` — regenerate `docs/tree.md`, and continue below. `bun run devcheck` reports an unmigrated tree until this is done. The agent mirrors (`.claude/skills/`, `.agents/skills/`) keep their names; plugin hosts do not scan them.
 
 Procedure:
 
-1. List all skill directories in `node_modules/@cyanheads/mcp-ts-core/skills/`
+1. List all skill directories in `node_modules/@cyanheads/mcp-ts-core/framework-skills/`
 2. For each skill with `metadata.audience: external` in its `SKILL.md` frontmatter:
-   - If missing in project `skills/`, copy the full directory
+   - If missing in project `framework-skills/`, copy the full directory
    - If present, compare `metadata.version` — replace if the package version is newer
    - If the local version is equal or newer, skip (local override)
    - **Report every skip.** List each skipped skill with both versions in the pass output. The rule trusts a downstream stamp it cannot verify, so a stamp that ever moves backwards upstream makes the skip permanent and silent — the local copy outranks the package copy forever and no future edit reaches it. A skip you can see is a skip you can question; compare the two bodies whenever one looks unexpected.
-3. Leave skills in `skills/` that lack `metadata.audience: external` untouched — they're server-specific or sourced elsewhere, not framework-managed.
-4. **Prune framework skills deleted upstream.** A skill in `skills/` that *carries* `metadata.audience: external` but is **absent** from the package was removed upstream (e.g. `migrate-mcp-ts-template`, removed in 0.9.12) and lingers because sync was previously add/update-only. Delete it from `skills/` (and from the agent mirrors in Phase B). The `audience: external` marker is the provenance: it scopes the prune to framework-managed skills, so a server's own skills — which never carry it — are never touched. Before deleting, scan the skill for local edits worth keeping; if any exist, reconcile or surface them rather than discarding silently.
+3. Leave skills in `framework-skills/` that lack `metadata.audience: external` untouched — they're server-specific or sourced elsewhere, not framework-managed.
+4. **Prune framework skills deleted upstream.** A skill in `framework-skills/` that *carries* `metadata.audience: external` but is **absent** from the package was removed upstream (e.g. `migrate-mcp-ts-template`, removed in 0.9.12) and lingers because sync was previously add/update-only. Delete it from `framework-skills/` (and from the agent mirrors in Phase B). The `audience: external` marker is the provenance: it scopes the prune to framework-managed skills, so a server's own skills — which never carry it — are never touched. Before deleting, scan the skill for local edits worth keeping; if any exist, reconcile or surface them rather than discarding silently.
 
-**Skill diffs are adoption signal, not just sync output.** After replacing files in `skills/`, run `git diff skills/` to read what changed. Updated skill bodies describe new patterns, refined workflows, or new conventions — apply them to the codebase in Step 6 the same way you'd apply a framework API addition. The file copy is the *trigger*, not the work. The work is what the updated skill now says to do.
+**Skill diffs are adoption signal, not just sync output.** After replacing files in `framework-skills/`, run `git diff framework-skills/` to read what changed. Updated skill bodies describe new patterns, refined workflows, or new conventions — apply them to the codebase in Step 6 the same way you'd apply a framework API addition. The file copy is the *trigger*, not the work. The work is what the updated skill now says to do.
 
-**Phase B — Project `skills/` → Agent directories**
+**Phase B — Project `framework-skills/` → Agent directories**
 
-The `setup` skill instructs consumers to copy `skills/*` into their agent's skill directory at init time. Those copies go stale unless re-synced. Detect which agent directories exist and propagate:
+The `setup` skill instructs consumers to copy `framework-skills/*` into their agent's skill directory at init time. Those copies go stale unless re-synced. Detect which agent directories exist and propagate:
 
 | Agent | Directory |
 |:------|:----------|
@@ -123,8 +125,8 @@ The `setup` skill instructs consumers to copy `skills/*` into their agent's skil
 
 For each agent directory that exists:
 
-1. For every directory in project `skills/`, copy it into the agent dir (overwrite on match, add if missing)
-2. Do **not** delete skills in the agent dir that aren't in project `skills/` — they may be general-purpose skills sourced elsewhere (e.g., `code-security`, `cloudflare`, `changelog`). **Exception:** a framework skill pruned in Phase A step 4 — delete that same-named directory from each agent dir too. Match by the specific name you just removed, never by a blanket "absent from `skills/`" sweep (which would catch the externally-sourced skills above).
+1. For every directory in project `framework-skills/`, copy it into the agent dir (overwrite on match, add if missing)
+2. Do **not** delete skills in the agent dir that aren't in project `framework-skills/` — they may be general-purpose skills sourced elsewhere (e.g., `code-security`, `cloudflare`, `changelog`). **Exception:** a framework skill pruned in Phase A step 4 — delete that same-named directory from each agent dir too. Match by the specific name you just removed, never by a blanket "absent from `framework-skills/`" sweep (which would catch the externally-sourced skills above).
 
 If no agent directory exists, skip Phase B — the project hasn't opted in to per-agent skill copies.
 
@@ -170,7 +172,7 @@ Apply the findings from Steps 3 and 4. Framework changes and third-party library
 
 The consumer opted into the framework; its templates, skills, scripts, linter rules, conventions, and new APIs that supersede local code are authoritative. Adopt them now — not as a follow-up.
 
-- **Synced skill content from Phase A** — `git diff skills/` for every skill that was updated. Each updated body is new framework guidance; apply it to matching surfaces in this server. Examples: `add-tool` gains a section on output formatting → audit existing tool definitions against that section; `api-errors` documents a new contract pattern → adopt across error surfaces; `security-pass` adds a new check → run it against the surface. Skill updates aren't metadata.
+- **Synced skill content from Phase A** — `git diff framework-skills/` for every skill that was updated. Each updated body is new framework guidance; apply it to matching surfaces in this server. Examples: `add-tool` gains a section on output formatting → audit existing tool definitions against that section; `api-errors` documents a new contract pattern → adopt across error surfaces; `security-pass` adds a new check → run it against the surface. Skill updates aren't metadata.
 - **Breaking changes** — fix call sites. Not optional.
 - **Deprecations** — migrate now, while context is fresh.
 - **New linter rules** — if the rule now flags existing code, fix the code; don't silence the rule.
@@ -212,7 +214,14 @@ In **Mode B**, the user already ran rebuild + test before invoking this skill, b
 
 Fix anything that fails. Re-run until clean.
 
-**Transitive advisory triage.** If `bun audit` (inside devcheck) reports a vulnerability in a transitive dep, run `bun run audit:refresh` before treating it as real. Bun's `bun update` is sticky on transitive resolutions — it keeps lockfile entries even when a parent's range allows a newer patched version. `audit:refresh` deletes `bun.lock`, reinstalls, and re-audits; if the advisory disappears, it was a stale-lockfile false positive (commit the refreshed lockfile). If it survives, it's real — patch via `package.json` `overrides` or nudge upstream.
+**Transitive advisory triage.** When `bun audit` (inside devcheck) reports a vulnerability in a transitive dependency, fix it in place, most surgical option first:
+
+1. `bun run audit:fix` (`bun audit fix`) — upgrades the vulnerable package to the lowest safe version that still satisfies every dependent's range; `package.json` changes only when an exact pin has to move. `bun audit fix --dry-run` previews; `--latest` also applies fixes the declared ranges exclude and rewrites `package.json` — the escalation, not the default.
+2. `bun update <name>` — bumps that one package wherever it appears in the lockfile, transitive entries included, when the advisory names a version `audit fix` left alone.
+3. `bun dedupe` — collapses duplicate versions of a package in the lockfile without touching `package.json` (`bun dedupe --check` lists them); the fix when the advisory sits on a stale extra copy rather than on the version the ranges resolve to.
+4. `bun run audit:refresh` — deletes `bun.lock` and reinstalls. Last resort only: every `^`-ranged dependency re-resolves to latest-in-range, so an advisory check becomes an unreviewed dependency bump, and on Bun 1.4 the fresh lockfile is written as `lockfileVersion: 2`.
+
+If the advisory survives all four, it is real — pin the patched version in `package.json` `overrides` or nudge upstream.
 
 ### 8. Summary
 
@@ -234,8 +243,8 @@ Present a concise numbered summary to the user:
 - [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
 - [ ] 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)
+- [ ] Project `framework-skills/` synced from package (Phase A), with a change report
+- [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `framework-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 (re-run after Step 6, even in Mode B)
 - [ ] `bun run devcheck` passes (includes audit + outdated)

package/{skills → framework-skills}/orchestrations/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -28,7 +28,7 @@ Single-skill work — running just `maintenance`, just `git-wrapup`, just `relea
 | **2** | Orchestration workflows | The four files under `workflows/` | Orchestrator only |
 | **3** | Router | This `SKILL.md` | Orchestrator only |
 
-Workflows in Tier 2 sequence Tier 1 skills with gates and verification. They never duplicate Tier 1 content — they direct to it. A workflow file says "Phase N: agent reads and runs `skills/git-wrapup/SKILL.md`," not "here's how to wrap up a release."
+Workflows in Tier 2 sequence Tier 1 skills with gates and verification. They never duplicate Tier 1 content — they direct to it. A workflow file says "Phase N: agent reads and runs `framework-skills/git-wrapup/SKILL.md`," not "here's how to wrap up a release."
 
 The orchestrator is the agent driving the workflow — the one reading this SKILL.md. Sub-agents the orchestrator spawns receive prompts pointing at Tier 1 skills directly; they do not receive this skill or the workflow file. That boundary prevents recursive sub-agent spawning.
 

package/{skills → framework-skills}/orchestrations/workflows/field-test-fix.md

@@ -25,13 +25,13 @@ For known work (issues already tracked, handoff documents) where the discovery p
 
 | Phase | Tier 1 skill(s) |
 |:---|:---|
-| Field-test | `skills/field-test/SKILL.md` |
-| Issue filing | `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
-| Tool definition quality (informs field-test framing) | `skills/tool-defs-analysis/SKILL.md` |
+| Field-test | `framework-skills/field-test/SKILL.md` |
+| Issue filing | `framework-skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
+| Tool definition quality (informs field-test framing) | `framework-skills/tool-defs-analysis/SKILL.md` |
 | Fix | (No single skill — sub-agent reads issues, validates, fixes) |
-| Code simplify (optional) | `skills/code-simplifier/SKILL.md` |
-| Wrap-up | `skills/git-wrapup/SKILL.md` |
-| Release | `skills/release-and-publish/SKILL.md` |
+| Code simplify (optional) | `framework-skills/code-simplifier/SKILL.md` |
+| Wrap-up | `framework-skills/git-wrapup/SKILL.md` |
+| Release | `framework-skills/release-and-publish/SKILL.md` |
 
 ## Pre-flight
 
@@ -83,7 +83,7 @@ Phase 6 is optional — stop earlier if release isn't authorized. Phase 7 only r
 - **Do NOT file against `@cyanheads/mcp-ts-core`** unless the bug is clearly in the framework — file against the server's own repo
 - **Redact secrets** — API keys, tokens, etc.
 
-Sub-agent reads `skills/tool-defs-analysis/SKILL.md` as a primer — field-testing evaluates the agent-facing surface during live use, not just statically.
+Sub-agent reads `framework-skills/tool-defs-analysis/SKILL.md` as a primer — field-testing evaluates the agent-facing surface during live use, not just statically.
 
 ### Phase 2: Issue triage
 Orchestrator verifies filed issues exist via `gh issue list -R <owner>/<repo>` per target. Reconciles sub-agent reports against actual GH state (sub-agents sometimes report filing but hit errors). Produces a per-target issue count and severity breakdown. If all sub-agents found 0 issues, skip to Phase 6 (or end the workflow if no release authorized).
@@ -128,7 +128,7 @@ The orchestrator makes this call based on evidence — don't defer when the data
 If looping: respawn Phase 1 + Phase 3 for targets that had fixes applied; skip targets that passed clean. Diminishing returns after 2 cycles.
 
 ### Phase 6: Wrap-up + release (optional)
-Each sub-agent reads both `skills/git-wrapup/SKILL.md` and `skills/release-and-publish/SKILL.md`.
+Each sub-agent reads both `framework-skills/git-wrapup/SKILL.md` and `framework-skills/release-and-publish/SKILL.md`.
 
 **Release PR mode.** When the target declares it (see "Release PR mode" in `../SKILL.md`), Phase 6 runs as three serial sub-agents — wrap-up (halts at the open PR) → `release-pr-review` → release — with an orchestrator check of the PR between each. Everything below is unchanged; the PR wraps it.
 

package/{skills → framework-skills}/orchestrations/workflows/fix-wrapup-release.md

@@ -37,11 +37,11 @@ For unsourced QA — where the bugs are unknown until you test — use `field-te
 
 | Phase | Tier 1 skill(s) |
 |:---|:---|
-| Validate (handoff input only) | `skills/field-test/SKILL.md` + `skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
+| Validate (handoff input only) | `framework-skills/field-test/SKILL.md` + `framework-skills/report-issue-local/SKILL.md` + `.github/ISSUE_TEMPLATE/` |
 | Fix | (No single skill — sub-agent reads issues, validates, fixes) |
-| Verify | `skills/field-test/SKILL.md` (live verification) + `skills/code-simplifier/SKILL.md` (optional) |
-| Wrap-up | `skills/git-wrapup/SKILL.md` |
-| Release | `skills/release-and-publish/SKILL.md` |
+| Verify | `framework-skills/field-test/SKILL.md` (live verification) + `framework-skills/code-simplifier/SKILL.md` (optional) |
+| Wrap-up | `framework-skills/git-wrapup/SKILL.md` |
+| Release | `framework-skills/release-and-publish/SKILL.md` |
 
 ## Pre-flight
 
@@ -112,7 +112,7 @@ Fresh sub-agent per target, reads the full `git diff` cold. Two passes:
 Exit gate: `bun run devcheck && bun run rebuild && bun run test`.
 
 ### Phase 3: Wrap-up + release
-Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`.
+Each sub-agent reads BOTH `framework-skills/git-wrapup/SKILL.md` AND `framework-skills/release-and-publish/SKILL.md`.
 
 **Release PR mode.** When the target declares it (see "Release PR mode" in `../SKILL.md`), Phase 3 runs as three serial sub-agents — wrap-up (halts at the open PR) → `release-pr-review` → release — with an orchestrator check of the PR between each. The commit structure, version bump, and tag rules below are unchanged; the PR wraps them.
 

package/{skills → framework-skills}/orchestrations/workflows/greenfield-build.md

@@ -35,18 +35,18 @@ Everything stays at **v0.1.0** through the build. Intermediate commits don't bum
 
 | Phase | Tier 1 skill(s) |
 |:---|:---|
-| Scaffold (1) | `skills/setup/SKILL.md` |
-| Initial commit, design commit, build commit, pre-launch commit (2, 5, 10, 16) | `skills/git-wrapup/SKILL.md` (commit + tag, no push) |
-| Design + validation (3, 4) | `skills/design-mcp-server/SKILL.md` |
-| Build (6) | `skills/add-tool/SKILL.md`, `skills/add-app-tool/SKILL.md`, `skills/add-resource/SKILL.md`, `skills/add-prompt/SKILL.md`, `skills/add-service/SKILL.md` |
-| Tool-def audit (7) | `skills/tool-defs-analysis/SKILL.md` |
-| Test coverage (8) | `skills/add-test/SKILL.md` |
+| Scaffold (1) | `framework-skills/setup/SKILL.md` |
+| Initial commit, design commit, build commit, pre-launch commit (2, 5, 10, 16) | `framework-skills/git-wrapup/SKILL.md` (commit + tag, no push) |
+| Design + validation (3, 4) | `framework-skills/design-mcp-server/SKILL.md` |
+| Build (6) | `framework-skills/add-tool/SKILL.md`, `framework-skills/add-app-tool/SKILL.md`, `framework-skills/add-resource/SKILL.md`, `framework-skills/add-prompt/SKILL.md`, `framework-skills/add-service/SKILL.md` |
+| Tool-def audit (7) | `framework-skills/tool-defs-analysis/SKILL.md` |
+| Test coverage (8) | `framework-skills/add-test/SKILL.md` |
 | Field-test loop (11) | → `workflows/field-test-fix.md` as a sub-loop (see Phase 11 note) |
-| Simplify (12) | `skills/code-simplifier/SKILL.md` |
-| Polish docs/meta (13) | `skills/polish-docs-meta/SKILL.md` |
-| Security pass (14) | `skills/security-pass/SKILL.md` |
-| Final wrap-up (17) | `skills/git-wrapup/SKILL.md` |
-| Release (18) | `skills/release-and-publish/SKILL.md` |
+| Simplify (12) | `framework-skills/code-simplifier/SKILL.md` |
+| Polish docs/meta (13) | `framework-skills/polish-docs-meta/SKILL.md` |
+| Security pass (14) | `framework-skills/security-pass/SKILL.md` |
+| Final wrap-up (17) | `framework-skills/git-wrapup/SKILL.md` |
+| Release (18) | `framework-skills/release-and-publish/SKILL.md` |
 
 ## Phases
 

package/{skills → framework-skills}/orchestrations/workflows/maintenance-release.md

@@ -25,10 +25,10 @@ Use after reading `../SKILL.md`. Drives maintenance, adoption verification, wrap
 
 | Phase | Tier 1 skill(s) |
 |:---|:---|
-| Maintenance | `skills/maintenance/SKILL.md` |
-| Double-check | `skills/polish-docs-meta/SKILL.md` (the cross-file consistency reference is the most commonly missed surface) |
-| Wrap-up | `skills/git-wrapup/SKILL.md` |
-| Release | `skills/release-and-publish/SKILL.md` |
+| Maintenance | `framework-skills/maintenance/SKILL.md` |
+| Double-check | `framework-skills/polish-docs-meta/SKILL.md` (the cross-file consistency reference is the most commonly missed surface) |
+| Wrap-up | `framework-skills/git-wrapup/SKILL.md` |
+| Release | `framework-skills/release-and-publish/SKILL.md` |
 
 ## Pre-flight
 
@@ -58,25 +58,25 @@ Phase 4 combines wrap-up and release in one sub-agent because the work is sequen
 ## Phase notes
 
 ### Phase 1: Maintenance
-Each sub-agent runs `skills/maintenance/SKILL.md` Mode A — the full flow from `bun outdated` through verification.
+Each sub-agent runs `framework-skills/maintenance/SKILL.md` Mode A — the full flow from `bun outdated` through verification.
 
 **Prompt phrasing matters.** Generic "run the maintenance skill" prompts cause sub-agents to stop at changelog analysis without executing. Include explicit steps in the prompt body:
 1. `bun outdated` — capture the list
 2. `bun update --latest` — apply, capturing the `↑ package old → new` lines for Step 3
 3. Invoke the `changelog` skill for each updated package (or read `node_modules/<pkg>/CHANGELOG.md` directly if the skill isn't synced yet)
 4. If `@cyanheads/mcp-ts-core` updated, do the deeper framework review per the maintenance skill's Step 4
-5. Run Step 5 skill/script sync — Phase A (package → project `skills/`), Phase B (project `skills/` → agent dirs), Phase C (package scripts + pristine references → project)
+5. Run Step 5 skill/script sync — Phase A (package → project `framework-skills/`), Phase B (project `framework-skills/` → agent dirs), Phase C (package scripts + pristine references → project)
 6. Adopt changes per Step 6 — framework changes are auto-adopt at every applicable site in this pass; third-party libs are cost/benefit
 7. `bun run rebuild` → `bun run devcheck` → `bun run test`
 8. Produce the Step 8 numbered summary
 
-**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md` version is newer than the synced project copy, feature-adoption rows added in the new version don't surface. Sub-agent prompt instructs: after Phase A sync completes, re-read the synced `maintenance` SKILL.md and continue from Step 5 with the new version.
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/framework-skills/maintenance/SKILL.md` version is newer than the synced project copy, feature-adoption rows added in the new version don't surface. Sub-agent prompt instructs: after Phase A sync completes, re-read the synced `maintenance` SKILL.md and continue from Step 5 with the new version.
 
-**Skill audience compliance.** Only sync skills with `metadata.audience: external` into project `skills/`. Sub-agents miss this under context pressure — restate explicitly.
+**Skill audience compliance.** Only sync skills with `metadata.audience: external` into project `framework-skills/`. Sub-agents miss this under context pressure — restate explicitly.
 
 **Constraints to restate verbatim:**
 - No commits, tags, pushes — leave working tree dirty for orchestrator review
-- Read-only git allowed and expected — `git diff skills/` after Phase A surfaces adoption signal
+- Read-only git allowed and expected — `git diff framework-skills/` after Phase A surfaces adoption signal
 - Halt and report verbatim if `bun run devcheck` can't be made green; `bun audit` failures from a transitive dep with no patch are note-not-halt
 - Output the Step 8 numbered summary at the end — the orchestrator parses it
 
@@ -88,7 +88,7 @@ Independent maintenance sub-agents diverge on incidental choices and miss adopti
 Audit categories (sub-agent prompt enumerates):
 
 - **Adoption gaps** — features the updated skills say to do that weren't applied (error code semantic audit, missing scaffolding files like `manifest.json`/`.mcpbignore`, `publish-mcp` script)
-- **Audience compliance** — only skills with `metadata.audience: external` belong in project `skills/`; agents sometimes sync `internal`-audience skills
+- **Audience compliance** — only skills with `metadata.audience: external` belong in project `framework-skills/`; agents sometimes sync `internal`-audience skills
 - **Content accuracy** — `isRequired` flags in `server.json` match the upstream API's reality (does the API work without the key?); `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 Phase 1 summaries, the other 2 likely missed it
 - **Error code semantics** — `InvalidParams` only for malformed JSON-RPC params shape; `ValidationError` for domain validation; `NotFound` for missing entities
@@ -117,7 +117,7 @@ The orchestrator collects Phase 1 + Phase 2 reports and produces:
 If a target's diff suggests minor-or-above, **pause that target and surface to the user during roll-up** — unaffected targets proceed to Phase 4 at patch.
 
 ### Phase 4: Wrap-up + release
-Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`. Runs wrap-up (version bump, changelog authoring, commit stack), then release (annotated tag, push, npm publish, MCP Registry, GH release, Docker).
+Each sub-agent reads BOTH `framework-skills/git-wrapup/SKILL.md` AND `framework-skills/release-and-publish/SKILL.md`. Runs wrap-up (version bump, changelog authoring, commit stack), then release (annotated tag, push, npm publish, MCP Registry, GH release, Docker).
 
 **Release PR mode.** When the target declares it (see "Release PR mode" in `../SKILL.md`), Phase 4 runs as three serial sub-agents — wrap-up (halts at the open PR) → `release-pr-review` → release — with an orchestrator check of the PR between each. Everything below is unchanged; the PR wraps it.
 
@@ -153,7 +153,7 @@ For targets with hosted instances behind an auto-pull tool, trigger the refresh
 | 3 | Per-target adoption divergence is expected — projects on different starting framework versions adopt different things | Don't try to normalize. Surface divergence as informational in Phase 3 roll-up. |
 | 4 | The `changelog` skill may not exist in a target's skill directory yet | Sub-agent falls back to direct `node_modules/<pkg>/CHANGELOG.md` reading |
 | 5 | Sub-agent runs write git commands despite instruction | Restate the no-write-git list + no-`stash` rule in prompt body; verify via `git log --oneline -1` per target after Phase 1 — should show no new commits |
-| 6 | Sub-agent syncs `internal`-audience skills into project `skills/` | Restate "Only sync skills with `metadata.audience: external`" — sub-agents miss this under context pressure |
+| 6 | Sub-agent syncs `internal`-audience skills into project `framework-skills/` | Restate "Only sync skills with `metadata.audience: external`" — sub-agents miss this under context pressure |
 | 7 | `manifest.json` scaffolded with scoped name from `package.json` (e.g. `@scope/server-name`) — renders in mcpb install dialog | Phase 2 verifies `manifest.json` `name` doesn't contain `/` |
 | 8 | `manifest.json` `user_config` entries missing required `title`/`type` — `mcpb pack` fails at release time | Phase 2 verifies required fields |
 | 9 | `server.json` `isRequired` doesn't match upstream API reality | Phase 2 verifies against actual API behavior |

package/{skills → framework-skills}/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.12"
+  version: "2.15"
   audience: external
   type: workflow
 ---
@@ -48,13 +48,17 @@ Capture: tool count, resource count, prompt count, service count, required env v
 
 ### 2. README.md
 
-Read `references/readme.md` for structure and conventions. If `README.md` doesn't exist, create it from scratch. If it exists, diff the current content against the audit — update tool/resource/prompt tables, env var lists, and descriptions to match the actual surface area. Don't rewrite sections that are already accurate.
+**Read the gold standard first: the `pubmed-mcp-server` README** — https://github.com/cyanheads/pubmed-mcp-server/blob/main/README.md (or `../pubmed-mcp-server/README.md` when that repo is checked out beside this one). Mirror its structure, section order, heading forms, and density. Reuse its non-server-specific content as-is — the framework line under Features, and the Getting started / Configuration / Running the server / Development guide / Contributing boilerplate — and tune only what is server-specific: the header, the Overview description, the primitives and their Capability reference entries, the domain-specific and agent-friendly bullets, env vars, project structure. Then read `references/readme.md` for the conventions spelled out; where it and the pubmed README disagree, the README wins — note the discrepancy in your report rather than editing the reference.
+
+If `README.md` doesn't exist, create it from scratch. If it exists, diff the current content against the audit — update tool/resource/prompt tables, env var lists, and descriptions to match the actual surface area. Don't restructure sections that are already accurate and already in the gold-standard shape.
+
+**Every run is also a concision pass.** READMEs accrete: each release adds a bullet, and nobody removes one. Accurate is not the same as done — on every run, tighten what is already there, especially the Capability reference. Read `references/readme.md` § *Concision* for what to keep and what to cut. The bar is natural prose a human reads once, that still carries every fact a caller needs before the first call, and where every retained claim has been checked against the definition it describes.
 
 The bold header tagline (the `<b>` text inside the first `<p>`) must match the `package.json` `description`. The surface count is a nested `<div>` inside the same `<p>`, separated by `•`.
 
 ### 3. Agent Protocol (CLAUDE.md / AGENTS.md)
 
-Update the project's agent protocol file to reflect the actual server. Scope is the project-root `CLAUDE.md` / `AGENTS.md` only — **do not edit `skills/*/SKILL.md` or their `references/` files**. Those are external skill files synced from `@cyanheads/mcp-ts-core` and get overwritten on the next `maintenance` refresh.
+Update the project's agent protocol file to reflect the actual server. Scope is the project-root `CLAUDE.md` / `AGENTS.md` only — **do not edit `framework-skills/*/SKILL.md` or their `references/` files**. Those are external skill files synced from `@cyanheads/mcp-ts-core` and get overwritten on the next `maintenance` refresh.
 
 Read `references/agent-protocol.md` for the full update checklist, then review the current file and address what's stale or missing:
 
@@ -169,7 +173,9 @@ Never hand-edit `CHANGELOG.md` when using this pattern — it's a build artifact
 
 ### 10. Plugin Metadata (Codex / Claude Code)
 
-`lint:packaging` (run by `devcheck`) now enforces the high-value subset automatically when these manifests are present: non-empty descriptions, and identity/install correctness — display fields (`name`, server key, `interface.displayName`) must be the **unscoped** machine name, while the `npx -y` install arg must be the full `package.json` `name` (scoped if scoped). Opt out per project with `"packaging": { "pluginManifests": false }` in `devcheck.config.json`. The checks below cover the fields the gate doesn't (version / repository / license sync, category, env vars).
+`lint:packaging` (run by `devcheck`) now enforces the high-value subset automatically when these manifests are present: non-empty descriptions, identity/install correctness — display fields (`name`, server key, `interface.displayName`) must be the **unscoped** machine name, while the `npx -y` install arg must be the full `package.json` `name` (scoped if scoped) — and the env contract below (no `""` values; every `${user_config.*}` reference declared). Opt out per project with `"packaging": { "pluginManifests": false }` in `devcheck.config.json`. The checks below cover the fields the gate doesn't (version / repository / license sync, category, the wording of each option).
+
+**How user-supplied values reach the server.** Neither client passes the user's shell environment through untouched, so an env entry of `"KEY": ""` is not a hint — it is the value the server receives, and the framework reads an empty string as unset. Claude Code prompts for values declared under `userConfig` at enable time and substitutes `${user_config.<option>}` into `env` (sensitive values go to the Keychain). Codex starts stdio servers with a whitelisted environment and forwards only the host variables named in `env_vars`. Mirror `manifest.json`'s `user_config` block: same options, same titles and descriptions.
 
 If `.codex-plugin/plugin.json` exists, verify it's populated and in sync with `package.json` and `server.json`:
 
@@ -182,9 +188,9 @@ If `.codex-plugin/plugin.json` exists, verify it's populated and in sync with `p
 - `interface.shortDescription` matches `package.json` `description`
 - `interface.category` is set to a meaningful category
 
-If `.codex-plugin/mcp.json` exists, verify the server-name key is the unscoped `package.json` `name`, the `npx -y` install arg is the full `package.json` `name`, and env vars include any required API keys from the server config schema.
+If `.codex-plugin/mcp.json` exists, verify the server-name key is the unscoped `package.json` `name`, the `npx -y` install arg is the full `package.json` `name`, `env` carries only fixed values (`MCP_TRANSPORT_TYPE`), and `env_vars` lists every user-supplied variable from the server config schema (API keys, contact emails, instance URLs) so Codex forwards it from the user's environment.
 
-If `.claude-plugin/plugin.json` exists, apply the same checks: `name` (unscoped), `version`, `description`, `repository`, `license` from `package.json`. Verify the inline `mcpServers` entry key is the unscoped name, its `npx -y` install arg is the full `package.json` `name`, and env vars include any required API keys.
+If `.claude-plugin/plugin.json` exists, apply the same checks: `name` (unscoped), `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`, `$schema` set to `https://json.schemastore.org/claude-code-plugin-manifest.json`. Verify the inline `mcpServers` entry key is the unscoped name and its `npx -y` install arg is the full `package.json` `name`. Every user-supplied variable is declared under `userConfig` — `type: "string"`, `title`, `description`, `sensitive: true` for keys and tokens, and either `required: true` or `default: ""` so a blank answer reaches the server as empty rather than as the literal placeholder — and referenced from `env` as `"KEY": "${user_config.<option>}"`. Run `claude plugin validate .` after editing; the CLAUDE.md-at-root warning is expected, anything else is not.
 
 ### 11. MCPB Bundling Artifacts
 
@@ -207,7 +213,8 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 - `manifest.json` `name` matches `package.json` name **without the npm scope prefix** (e.g. `bls-mcp-server`, not `@cyanheads/bls-mcp-server`); `description` matches `package.json`
 - `manifest.json` `author` is the full person object — `{ "name", "email", "url" }` — carrying the same identity as `package.json` `author` (name matches the LICENSE copyright holder, url is the author's site)
 - `manifest.json` `user_config` entries must include `title` and `type` fields — `mcpb pack` validates these
-- For each `user_config` entry referenced as `${user_config.X}` in `mcp_config.env`: if it's not `required: true`, set `"default": ""`. MCPB hosts (Claude Desktop included) pass the literal placeholder string through to the process when an optional field is left blank without a default — strict consumer validators (`z.email()`, `z.url()`, `.regex()`) then crash at lazy config load, exiting silently after `initialize`. Server-side: pair every optional env-backed strict-validator field with a `z.preprocess` that strips `${...}` placeholders to `undefined`.
+- Every `user_config` entry is referenced from `mcp_config.env` as `"X": "${user_config.X}"`, and `mcp_config` carries no other `${…}` besides MCPB's own path placeholders (`${__dirname}`, `${HOME}`, …). The host substitutes nothing else: a declared option that is never referenced is collected and dropped, and `"X": "${X}"` reaches the server as that literal string. `lint:packaging` enforces both
+- For each `user_config` entry referenced as `${user_config.X}` in `mcp_config.env`: if it's not `required: true`, set `"default": ""`. MCPB hosts (Claude Desktop included) pass the literal placeholder string through to the process when an optional field is left blank without a default — the `default` keeps that string out of the process. Server-side, the framework already treats a whole-value `${…}` placeholder the same as an empty string — unset — in both its own config and `parseEnvConfig`, so an optional field falls through to its default and a required one fails as missing rather than as a format error; a per-field `z.preprocess` guard for placeholders is redundant and can be dropped.
 - `server.json` env var `isRequired` must match the upstream API's actual requirement — if the API works without the value (rate-limited, DEMO_KEY fallback, polite pool), mark `isRequired: false` and describe the tradeoff in the description
 - Server description aligned across all surfaces: `package.json`, `manifest.json`, `server.json` (condensed, hard 100-char limit), README header `<p><b>`, and GitHub repo description (`gh repo edit --description`)
 - `package.json` `keywords` include baseline terms: `mcp`, `mcp-server`, `model-context-protocol`, `typescript`, `bun`, `stdio`, `streamable-http`, plus data-domain terms. GitHub repo topics (`gh repo edit --add-topic`) should match.
@@ -257,7 +264,8 @@ Both must pass clean.
 ## Checklist
 
 - [ ] Surface area audited — tool/resource/prompt/service inventory built
-- [ ] `README.md` accurate — tool/resource tables, config, descriptions match actual code
+- [ ] `README.md` accurate — mirrors the `pubmed-mcp-server` gold-standard structure; Overview tables, Capability reference entries, config, and descriptions match actual code
+- [ ] `README.md` concise — Capability reference entries are contract-shaped and within the bullet budget; nothing narrates mechanism the schema already carries; every retained claim verified against its definition
 - [ ] Agent protocol file accurate — no stale template content, real examples, structure matches reality
 - [ ] `.env.example` in sync with server config schema
 - [ ] `package.json` metadata complete (`description`, `mcpName`, `repository`, `author`, `keywords`, `engines`, `packageManager`)
@@ -266,8 +274,8 @@ Both must pass clean.
 - [ ] `bunfig.toml` present
 - [ ] Changelog current — either monolithic `CHANGELOG.md` (hand-edited, Keep a Changelog) or directory-based (`changelog/<minor>.x/<version>.md` + rollup regenerated and in sync)
 - [ ] `.codex-plugin/plugin.json` populated and in sync with `package.json` (if present)
-- [ ] `.codex-plugin/mcp.json` server name and env vars current (if present)
-- [ ] `.claude-plugin/plugin.json` populated and in sync with `package.json` (if present)
+- [ ] `.codex-plugin/mcp.json` server name current; user-supplied variables in `env_vars`, none as `""` in `env` (if present)
+- [ ] `.claude-plugin/plugin.json` populated and in sync with `package.json`; every user-supplied variable declared in `userConfig` and referenced as `${user_config.<option>}`, none as `""` in `env` (if present)
 - [ ] MCPB artifacts consistent (if `manifest.json` present) — version synced, env vars match `server.json`, `bundle` + `lint:packaging` scripts exist, README install badges present
 - [ ] `LICENSE` file present
 - [ ] `Dockerfile` OCI labels and runtime config accurate (if present)

package/{skills → framework-skills}/polish-docs-meta/references/agent-protocol.md

@@ -54,7 +54,7 @@ If the server has a `server-config.ts`, check whether the Patterns section still
 
 ### 6. Update the Skills Table
 
-Check for server-specific skills added to `skills/` that aren't in the table yet. Add any missing entries. Remove framework skills the server doesn't use (rare — most are useful).
+Check for server-specific skills added to `framework-skills/` that aren't in the table yet. Add any missing entries. Remove framework skills the server doesn't use (rare — most are useful).
 
 ### 7. Update the Commands Table
 

package/{skills → framework-skills}/polish-docs-meta/references/package-meta.md

@@ -27,7 +27,7 @@ These are set by `init` and generally don't need changes. Verify they're present
 | `main` | `"dist/index.js"` | Entry point after build |
 | `types` | `"dist/index.d.ts"` | TypeScript declarations |
 | `files` | `["dist/"]` | What npm publishes |
-| `engines` | `{ "node": ">=24.0.0", "bun": ">=1.3.0" }` | Node runs the built `dist/`; Bun is the dev floor |
+| `engines` | `{ "node": ">=24.0.0", "bun": ">=1.4.0" }` | Node runs the built `dist/`; Bun is the dev floor |
 | `packageManager` | `"bun@1.4.0"` | Pins the dev package manager; keep current with the framework's Bun version |
 | `scripts` | _(various)_ | Build, dev, test scripts |
 | `dependencies` | `@cyanheads/mcp-ts-core` | Core framework |