@cyanheads/mcp-ts-core 0.12.9 → 0.13.1

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

@@ -2,6 +2,20 @@
 
 Structure and content guide for creating or updating a README for an MCP server built on `@cyanheads/mcp-ts-core`. If a README already exists, use this as a reference to audit and improve it — don't blindly rewrite sections that are already accurate.
 
+The reference implementation is the `pubmed-mcp-server` README — https://github.com/cyanheads/pubmed-mcp-server/blob/main/README.md. Read it in full before writing, mirror its structure, reuse its non-server-specific content, and treat it as authoritative wherever this file lags behind it.
+
+## Concision
+
+A README is read once by a human deciding whether and how to use the server. It is not the changelog, not the schema, and not a proof that a feature works. Apply these on every pass, including re-runs over a README that is already accurate — accuracy is the floor, not the finish.
+
+**Keep, always:** canonical identifiers (tool, resource, prompt, field, env var, and enum names, exactly as the code spells them); per-call caps and limits; input alternatives and which are required; the fields a caller branches on (discriminators, typed reasons, status values); feature flags and the env var that controls each; anything a caller must know before the first call. Brevity never earns semantic loss — if cutting a clause drops a fact from this list, the clause stays.
+
+**Cut:** narration of how a guarantee is implemented ("so a value stays under the header it belongs to"); restated `.describe()` semantics — the schema carries them at call time; edge-case walkthroughs; the distinction between two similar values when the names already carry it; release-note accretion (a bullet that exists because a version added it, not because a reader needs it); marketing adjectives; a heading's intro sentence that repeats its Overview row.
+
+**The test, per bullet:** would a reader lose a fact they need before their first call? If not, cut or merge. If a bullet needs more than two sentences, it is describing mechanism — keep the contract, drop the mechanism.
+
+**Validate what stays.** Condensing is where wrong facts creep in — a merged bullet can silently combine two tools' limits or promote a default to a rule. Every identifier, cap, enum value, and default that survives the pass is checked against the definition file before the run ends. Never condense from memory of what the tool does; condense from the schema.
+
 ## Structure
 
 Use this section order. Omit sections that don't apply (e.g., skip Docker/Workers if the server doesn't deploy there).
@@ -13,14 +27,15 @@ Install badges                          ← one centered row — Claude Desktop,
 Framework badge                         ← solo spotlight row — `Built on @cyanheads/mcp-ts-core` (cyan-300 #67E8F9)
 [Public hosted callout if present]      ← centered HTML block, directly under the Framework badge
 ---
-## Tools                                ← grouping sentence → summary table → per-tool subsections
-## Resources and prompts (if any)       ← single combined table (Type / Name / Description)
-## Features                             ← framework bullets + domain-specific bullets
+## Overview                             ← short description paragraph → `### Tools` / `### Resources` / `### Prompts` two-column tables
+## Capability reference                 ← one `###` entry per primitive, heading tagged `<sub>tool|resource|prompt</sub>`, contract-shaped bullets
+## Features                             ← one-sentence framework line + domain-specific bullets + agent-friendly output bullets
 ## Getting started                      ← hosted (if any), bunx/npx/docker configs, HTTP one-liner, prerequisites, install
 ## Configuration                        ← env var table + `.env.example` pointer
 ## Running the server                   ← dev, production, Workers/Docker
 ## Project structure                    ← directory/purpose table
 ## Development guide                    ← link to CLAUDE.md/AGENTS.md, key rules
+## Contributing                         ← issues only
 ## License                              ← one line
 ```
 
@@ -108,106 +123,94 @@ If a public hosted instance is available, **promote it to a top-level callout**
 
 Keep the full connection-config JSON block inside a `### Public Hosted Instance` subsection under Getting Started (covered below). This callout is just the visibility pointer.
 
-### Tools
+No hosted instance → omit the callout, the Getting Started subsection, and any hosted mention in the Overview. Never state the absence ("no public hosted instance"); self-hosting is the default a reader already assumes.
 
-This is the most important section — it tells humans and LLMs exactly what the server exposes. Three layers: a **grouping framing sentence**, a summary table, then per-tool subsections for tools with non-trivial behavior.
+### Overview
 
-**Grouping framing sentence:** Lead with one sentence that explains how the tool surface is organized. Richer than a bare count — tells the reader what mental model to apply. Examples:
+The first section after the header rule. Two parts: a short description paragraph, then one two-column table per primitive type. This is what a visitor reads to decide whether the server is for them, so it must scan in one screen.
 
-- "Seventeen tools grouped by shape — workflow helpers orchestrate common flows end-to-end, primitive tools expose fine-grained CRUD, and the instruction tool returns procedural guidance merged with live account state."
-- "Nine tools for working with PubMed and NCBI data:"
-- "Five tools covering project lifecycle — discovery, task CRUD, and team analytics."
+**Description paragraph:** two or three sentences — what the server sits on top of (the upstream APIs), what a user can do with it (the headline workflows, action verbs), and how it runs (transports, plus the hosted endpoint when one exists). Not a count.
 
-If the tools aren't meaningfully grouped, a single sentence count ("Seven tools for working with Acme data:") is acceptable.
+The opening sentence names the subject, not the container. The reader is already on an MCP server's repo page — the `<h1>`, the badge row, and the framework line all say so — so an opener that restates it ("An MCP server over…", "An MCP calculator…", "An MCP server that…") spends the most-read sentence on nothing. Lead with the domain or the upstream as a noun phrase, article optional: "Calculator powered by math.js.", "Seismic data from USGS ComCat and the EMSC SeismicPortal.", "The Acme v2 API — projects, tasks, and team activity.", "Read, write, and search Obsidian vault notes over the Local REST API plugin." The words "MCP server" appear at most once in the paragraph, and never as its first noun.
 
-**Summary table:**
+**Primitive tables:** a `### Tools` table, then `### Resources` and `### Prompts` tables when the server has any. Omit a heading whose table would be empty, but keep a one-row table rather than folding it into another. Two columns, Name/Description, one-line descriptions — the detail lives in the Capability reference.
 
 ```markdown
-## Tools
+## Overview
 
-Seven tools for working with Acme data:
+Project management over the Acme v2 API. Search projects, manage tasks, and track team activity from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
-| Tool Name | Description |
-|:----------|:------------|
-| `acme_search_projects` | Search projects by name, status, or team. |
-| `acme_create_task` | Create a new task in a project. |
-| `acme_get_task` | Fetch one or more tasks by ID, with full or summary data. |
-```
+### Tools
 
-**Per-tool subsections:**
+| Tool | Description |
+|:---|:---|
+| `acme_search_projects` | Search projects by name, status, or team, with pagination and field selection |
+| `acme_get_task` | Fetch one or more tasks by ID, with full or summary data |
 
-Below the table, add a `### tool_name` subsection for each tool that has meaningful detail beyond its one-line description. Include:
+### Resources
 
-- Bullet list of key capabilities (what inputs it accepts, what filtering/pagination it supports, edge cases it handles)
-- Link to example file if one exists: `[View detailed examples](./examples/tool_name.md)`
-- Separate subsections with `---` horizontal rules
+| Resource | Description |
+|:---|:---|
+| `acme://projects/{projectId}` | Project details by ID |
 
-```markdown
-### `acme_search_projects`
+### Prompts
 
-Search for projects using free-text queries and filters.
+| Prompt | Description |
+|:---|:---|
+| `project_summary` | Summarize a project's status and open tasks |
+```
 
-- Full-text search plus typed status/phase filters
-- Geographic proximity filtering by coordinates and distance
-- Pagination (up to 100 per page) and sorting
-- Field selection to limit response size
+Derive every row from the actual definitions — real names and descriptions from the Zod schemas.
 
-[View detailed examples](./examples/acme_search_projects.md)
+If resource data is also reachable through tools, say so in one line under the Resources table; many MCP clients are tool-only and never surface resources. If a prompt has a design doc, link it in one line under the Prompts table.
 
----
+### Capability reference
 
-### `acme_get_task`
+One `###` entry per primitive — every tool, resource, and prompt, in the same order as the Overview tables — with the heading tagged by type in a `<sub>` so a reader scanning headings can tell them apart without a section break. Entries are separated by `---` rules. No intro sentence under the heading — the Overview row already said what it does — go straight to bullets.
 
-Fetch one or more tasks by ID, with full data or concise summaries.
+**Bullet density is contract shape, not changelog narration.** Three to six bullets covering: accepted inputs and per-call caps; the output's discriminating fields; the failure shape (typed reasons, per-item status); the knobs (filters, budgets, feature flags). Behavior a caller discovers from the schema at call time — field-by-field semantics, edge-case handling, the mechanism behind a guarantee — belongs in the definition's `.describe()` text, not here. An entry running past six bullets has started transcribing release notes.
 
-- Batch fetch up to 5 tasks at once
-- Full data includes subtasks, comments, attachments, and history
-- Partial success reporting when some tasks in a batch fail
-```
+```markdown
+## Capability reference
 
-Skip the per-tool subsection for simple tools where the table description says everything (e.g., an `acme_get_field_values` lookup tool).
+### `acme_search_projects` <sub>tool</sub>
 
-### Resources and Prompts (combined)
+- Free-text query plus typed `status` / `phase` filters; up to 100 per page, offset pagination
+- Optional `fields` selection to trim the response
+- Results carry `source` and `fetchedAt` so callers can reason about freshness
 
-**Use a single combined table with a `Type` column** rather than separate `## Resources` and `## Prompts` sections. This is the shipping convention — it scales better when a server has only 1 or 2 of each, and co-locates related content.
+---
 
-```markdown
-## Resources and prompts
+### `acme_get_task` <sub>tool</sub>
 
-| Type | Name | Description |
-|:---|:---|:---|
-| Resource | `acme://projects/{projectId}` | Project details by ID |
-| Resource | `acme://tasks/{taskId}` | Task details by ID |
-| Prompt | `project_summary` | Summarize a project's status and open tasks |
-```
+- Up to 5 task IDs per call; `detail: "full"` adds subtasks, comments, attachments, and history
+- Per-item `status` rows — a partial batch returns the resolved tasks alongside typed errors for the rest
 
-Use singular ("Resource and prompt") if there's only one of each.
+---
 
-**Always include the tool-coverage note** directly under the table. Many MCP clients are tool-only and don't surface resources — this tells both the reader and downstream agents that the data is still reachable:
+### `acme://projects/{projectId}` <sub>resource</sub>
 
-```markdown
-All resource data is also reachable via tools. Large collections (`projects`, `tasks`) are not exposed as resources — use the `list` operation on the corresponding tool instead.
-```
+- Project record as `application/json` — name, status, owners, open task count
+- `projectId` comes from `acme_search_projects`
 
-If a prompt has an associated design doc or reference, link it in the same paragraph: `Design reference for the prompt: [\`docs/email-design-playbook.md\`](./docs/email-design-playbook.md).`
+---
 
-Derive all tool/resource/prompt rows directly from the actual definitions. Use the real names and descriptions from the Zod schemas.
+### `project_summary` <sub>prompt</sub>
+
+- Arguments: `projectId` required; `includeClosed` (`"true"` / `"false"`) optional
+- Returns two messages — an assistant framing message and a user message carrying the summary request
+```
+
+Link an examples file from an entry when one exists: `[View detailed examples](./examples/acme_search_projects.md)`.
 
 ### Features
 
-Three subsection groups: framework capabilities, domain-specific capabilities, then agent-friendly output design. Bullet lists, not prose.
+The framework line below, verbatim — it names what a user gets from the framework (transports, auth, storage, observability), so it replaces any framework-feature bullets; contributor facts about code organization belong in the Development guide. Then two labeled bullet groups, both always present: `<Upstream>-specific:` (3–5 bullets on the server's own integration), then `Agent-friendly output:`.
 
 ```markdown
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
-
-- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
-- Unified error handling — handlers throw, framework catches, classifies, and formats
-- Pluggable auth: `none`, `jwt`, `oauth`
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- STDIO and Streamable HTTP transports
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 Acme-specific:
 
@@ -222,7 +225,7 @@ Agent-friendly output:
 - 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:
+The **Agent-friendly output** subsection documents output-design choices that make the server work well as an AI-agent backend. Always include it, with 2–4 bullets in the "Pattern — concrete detail" form, each naming fields or behavior verified in the server's source — not aspirational framework capabilities. Drop a pattern the server doesn't have (no batch tools → no partial-failure bullet) rather than claiming it. 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)
@@ -435,10 +438,10 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 
 ### Cloudflare Workers
 
-1. **Build the Worker bundle:**
+1. **Run locally under wrangler:**
 
 \`\`\`sh
-bun run build:worker
+bun run deploy:dev
 \`\`\`
 
 2. **Deploy:**
@@ -448,7 +451,7 @@ bun run deploy:prod
 \`\`\`
 ```
 
-Include the Docker or Workers subsection only if the server supports it. The Docker trailing paragraph (log directory, OTEL build arg) is important — it documents Dockerfile behavior that isn't obvious from the build command.
+Include the Docker subsection only if the server ships a Dockerfile, and the Workers subsection only if it ships a `src/worker.ts` entry. The Docker trailing paragraph (log directory, OTEL build arg) is important — it documents Dockerfile behavior that isn't obvious from the build command.
 
 ### Project Structure
 
@@ -483,6 +486,21 @@ See [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) for development guidelines and archit
 - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
 ```
 
+### Contributing
+
+Issues only. Never write "pull requests are welcome" or any PR invitation — contributions arrive as issues, and `.github/CONTRIBUTING.md` says the same.
+
+```markdown
+## Contributing
+
+Issues are welcome. Run checks and tests before submitting:
+
+\`\`\`sh
+bun run devcheck
+bun run test
+\`\`\`
+```
+
 ### License
 
 One line referencing the LICENSE file.
@@ -495,11 +513,13 @@ Apache-2.0 — see [LICENSE](LICENSE) for details.
 
 ## Principles
 
+- **Gold standard first.** The `pubmed-mcp-server` README is the reference implementation; where it and this file disagree, the README wins.
 - **Accuracy over aspiration.** Only document what exists. Don't describe planned features as if they're implemented.
-- **Tools first.** The tool surface is the most important content. Lead with it.
+- **Surface first.** The primitives are the most important content. The Overview leads with them.
 - **Tables over prose** for structured data (tools, config, directories). Scannable and diff-friendly.
-- **Two-layer tool docs.** Grouping sentence + summary table for quick scanning, per-tool subsections for detail. Skip subsections for trivial tools.
-- **Combined resources + prompts.** Single table with a `Type` column, not separate sections.
+- **Overview + reference.** Overview tables for scanning; a Capability reference entry for every primitive, none skipped, with contract-shaped bullets rather than release-note narration.
+- **Concise on every pass.** Re-runs tighten as well as correct; see § *Concision* for what survives a cut and what doesn't, and validate everything that survives.
+- **One two-column table per primitive type.** Tools, resources, and prompts each get a small heading and a Name/Description table, even when a table has one row. No `Type` column — most servers are tool-heavy and many have no resources or prompts.
 - **Promote hosted instances.** If there's a public URL, put it in a top-level callout under the badges — not buried in Getting Started.
 - **Three install configs.** `bunx`, `npx`, `docker run` in that order. Each as a complete MCP-client JSON block.
 - **Real names from code.** Tool names, env vars, and URIs must match the source exactly. Copy from the definitions, don't paraphrase.

package/{skills → framework-skills}/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, fast-forwards `main` when the release rode a release PR, creates the annotated tag on the commit `main` now points at, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit stack — and in release PR mode, the pushed branch and open PR) is already complete — this skill is the post-wrapup merge + tag + publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.16"
+  version: "2.17"
   audience: external
   type: workflow
 ---
@@ -111,12 +111,15 @@ If `--ff-only` refuses, `main` moved underneath the release branch. Halt and rep
 The tag goes on HEAD. In release PR mode that is `main`'s tip after step 3 — the commit the PR's `headRefOid` names — so the tag is created on the branch it stays reachable from.
 
 ```bash
-git tag -a v<version> --cleanup=whitespace -m "<tag message with embedded newlines>"
+cat > /tmp/tag-v<version>.md <<'TAG'
+<tag message>
+TAG
+git tag -a v<version> --cleanup=whitespace -F /tmp/tag-v<version>.md
 ```
 
 If `v<version>` already exists and points at HEAD, a prior run created it — proceed. If it exists and points anywhere else, **halt and report the conflict** with the version string, the existing tag SHA, and HEAD. Never delete or move a tag without explicit authorization.
 
-Use `-m` with embedded newlines in the string (plain `-m` only — no heredoc, no command substitution). The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
+Write the message to a file through a quoted-delimiter heredoc and pass it with `-F`, never inline with `-m`: the body carries backticks, which a double-quoted string runs as command substitution and silently deletes, and apostrophes, which end a single-quoted string. The tag message renders as the GitHub Release body via `--notes-from-tag`. It must be structured markdown, not a flat string.
 
 **Release PR mode: the tag body is the PR body's `## Changes` bullets plus its final changelog link, verbatim** — `gh pr view <N> --json body -q .body` (`<N>` from step 1 — on `main` there is no branch for `gh` to infer it from), take the theme line as the subject, the bullets under `## Changes`, and the last line; drop `## Gates` and the headers. That digest was authored at wrapup and reviewed on the PR; re-authoring it here would publish unreviewed words. The one addition: append ` · release PR #<N>` to that final line, so the GitHub Release points at its audit trail (GitHub autolinks the bare `#<N>`). Without a PR, author it from the changelog entry at `changelog/<major.minor>.x/<version>.md` — every claim in the tag must appear in that file, and the file's `summary:` line is the tag's theme.
 
@@ -193,10 +196,16 @@ Halt on publish error other than "version already exists" (which means this step
 
 Only if `server.json` exists at the repo root (otherwise skip). Note: `server.json` (MCP Registry metadata) and `manifest.json` (MCPB bundle manifest, step 8) are independent — a project may have either, both, or neither.
 
+The registry checks that the npm version exists before it registers, and npm's read endpoint can lag `bun publish` by several minutes. Wait for the version to be served before publishing; a publisher error saying the npm version was not found is this lag, not a terminal failure:
+
 ```bash
+curl -sf --retry 30 --retry-delay 30 --retry-all-errors -o /dev/null \
+  "https://registry.npmjs.org/<package-name>/<version>"
 bun run publish-mcp
 ```
 
+Step 8 depends only on the pushed tag, so it may run while this wait is in progress.
+
 If `publish-mcp` isn't defined in `package.json`, add it permanently (one-time setup, macOS):
 
 ```json

package/{skills → framework-skills}/release-pr-review/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review pass on an open release PR (`release/<version>` → `main`) — the step between `git-wrapup` and `release-and-publish` when a project releases in gated release PR mode. Reads the PR's commit range through the `code-simplifier` lens plus a correctness review, verifies whatever an automated reviewer left on the PR, lands fixes as fixup commits autosquashed back into the stack, force-with-lease pushes the release branch, keeps the PR body in sync with what ships, and leaves one summary comment. The only agent role that both edits and commits — and it never tags, merges, touches `main`, or publishes.
 metadata:
   author: cyanheads
-  version: "1.0"
+  version: "1.1"
   audience: external
   type: workflow
 ---
@@ -35,7 +35,7 @@ git log --oneline main..HEAD                                # the stack: work co
 git diff main...HEAD --stat
 ```
 
-Read `skills/code-simplifier/SKILL.md` in full. Read the changelog entry for this version (`changelog/<major.minor>.x/<version>.md`) — it is the claim the diff has to back.
+Read `framework-skills/code-simplifier/SKILL.md` in full. Read the changelog entry for this version (`changelog/<major.minor>.x/<version>.md`) — it is the claim the diff has to back.
 
 ### 2. Establish the review range
 

package/{skills → framework-skills}/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.9"
+  version: "1.11"
   audience: external
   type: workflow
 ---
@@ -38,7 +38,7 @@ gh api 'repos/cyanheads/mcp-ts-core/issues/<number>/timeline' --paginate \
   --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'
 ```
 
-5. **For documentation- or contract-shaped requests, audit all three doc layers first** — proposals to add reference docs, public-API conventions, attribute/event catalogs, or stability commitments often duplicate surface that already exists. Check `src/` for behavior, `docs/` for human-facing reference, and `skills/` for agent-facing reference. Skill files marked `audience: external` are the framework's public contract — treat them as authoritative when evaluating whether a documentation gap exists. Also verify the constants or types you'd reference aren't already exported from `@cyanheads/mcp-ts-core` or one of its subpaths.
+5. **For documentation- or contract-shaped requests, audit all three doc layers first** — proposals to add reference docs, public-API conventions, attribute/event catalogs, or stability commitments often duplicate surface that already exists. Check `src/` for behavior, `docs/` for human-facing reference, and `framework-skills/` for agent-facing reference. Skill files marked `audience: external` are the framework's public contract — treat them as authoritative when evaluating whether a documentation gap exists. Also verify the constants or types you'd reference aren't already exported from `@cyanheads/mcp-ts-core` or one of its subpaths.
 
 ## Writing Well-Structured Issues
 
@@ -181,6 +181,7 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Fix/feature will break public API; requires a major bump |
+| `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` |
 | `surplus-token-idea` | Worth exploring when token budget allows |
 
 Combine labels: `--label "bug" --label "regression"`.
@@ -213,7 +214,7 @@ gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web
 
 ### CLI (non-interactive)
 
-Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.
+The first three headings are the Feature Request form's own fields, in its order — `Use case` and `Proposed API` are required by the form, so a body without them does not satisfy it. Everything after `Alternatives considered` is supplemental; omit what you don't need — simple requests don't require Flow / Design / Dependencies blocks.
 
 ````bash
 gh issue create -R cyanheads/mcp-ts-core \
@@ -221,16 +222,16 @@ gh issue create -R cyanheads/mcp-ts-core \
   --label "enhancement" \
   --assignee "@me" \
   --body "$(cat <<'ISSUE'
-Concrete statement of what's currently missing or broken in the framework. Name the specific builder, utility, context method, or config field. Two or three sentences — the reader should know the gap before the end of the paragraph.
+### Use case
 
-Related: #N
-
-## Proposal
+One or two sentences: who hits this gap in the framework and why it matters. Name the specific builder, utility, context method, or config field. Kept short on purpose — a field that invites a paragraph gets padded with background and skipped by the next reader.
 
-What you want the framework to do, in one paragraph. Link external libraries on first mention: [lib name](https://github.com/owner/repo). Include a short justification — what this gives us that we don't have today.
+Related: #N
 
 ### Proposed API
 
+What you want the framework to do, then the API as a consumer would call it. Link external libraries on first mention: [lib name](https://github.com/owner/repo).
+
 ```ts
 import { withRetry } from '@cyanheads/mcp-ts-core/utils';
 
@@ -240,18 +241,9 @@ const result = await withRetry(() => fetchExternal(url), {
 });
 ```
 
-### Flow (optional)
-
-Ordered steps — e.g. `trigger → resolve → fetch → degrade`. Useful when the change spans multiple phases or fallbacks.
-
-### Design / Tradeoffs (optional)
-
-Philosophy: **one-line principle in bold.**
+### Alternatives considered
 
-| Option | Strengths | Weaknesses |
-|:---|:---|:---|
-| A | ... | ... |
-| B | ... | ... |
+What you tried or evaluated instead, and why it didn't fit.
 
 ### Scope
 
@@ -264,13 +256,22 @@ Philosophy: **one-line principle in bold.**
 - What we're deliberately not doing
 - Adjacent work that belongs in a separate issue
 
-### Dependencies (optional)
+### Flow (optional)
 
-- Depends on: owner/repo#N
+Ordered steps — e.g. `trigger → resolve → fetch → degrade`. Useful when the change spans multiple phases or fallbacks.
 
-### Alternatives considered
+### Design / Tradeoffs (optional)
 
-What you tried or evaluated instead, and why it didn't fit.
+Philosophy: **one-line principle in bold.**
+
+| Option | Strengths | Weaknesses |
+|:---|:---|:---|
+| A | ... | ... |
+| B | ... | ... |
+
+### Dependencies (optional)
+
+- Depends on: owner/repo#N
 ISSUE
 )"
 ````
@@ -293,8 +294,8 @@ gh issue list -R cyanheads/mcp-ts-core --author @me
 - [ ] Confirmed bug is in `@cyanheads/mcp-ts-core`, not server code
 - [ ] Running latest (or documented) framework version
 - [ ] Searched existing issues — no duplicate found
-- [ ] If documentation or contract enhancement: confirmed `src/`, `docs/`, `skills/`, and public exports don't already cover the surface
+- [ ] If documentation or contract enhancement: confirmed `src/`, `docs/`, `framework-skills/`, and public exports don't already cover the surface
 - [ ] All secrets, credentials, and tokens redacted
 - [ ] 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
+- [ ] If feature: `Use case` and `Proposed API` present (the form's required fields), `Alternatives considered` third; Out of scope defined

package/{skills → framework-skills}/report-issue-local/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.9"
   audience: external
   type: workflow
 ---
@@ -165,8 +165,12 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Change will break public API; requires a major bump |
+| `blocked-by-framework` | Fix requires a released change in `@cyanheads/mcp-ts-core`; pairs with a `Depends on: cyanheads/mcp-ts-core#N` line in the body |
+| `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` |
 | `surplus-token-idea` | Worth exploring when token budget allows |
 
+`blocked-by-framework` comes off when this server adopts the release that ships the fix. An issue blocked on the SDK *through* the framework takes `blocked-by-framework`, not `blocked-by-sdk` — the server's own unblock is still a framework release.
+
 Combine labels: `--label "bug" --label "regression"`.
 
 Secondary labels are not GitHub defaults — if `gh issue create --label "regression"` fails with `label not found`, create it once:
@@ -176,6 +180,8 @@ gh label create regression --color e99695 --description "Worked before, broken a
 gh label create performance --color 5319e7 --description "Memory, CPU, latency, or resource usage"
 gh label create security --color b60205 --description "Vulnerability, CVE, or hardening work"
 gh label create breaking-change --color d93f0b --description "Change will break public API; requires a major bump"
+gh label create blocked-by-framework --color fbca04 --description "Fix requires a released change in @cyanheads/mcp-ts-core"
+gh label create blocked-by-sdk --color c5def5 --description "Fix requires changes in @modelcontextprotocol/sdk"
 gh label create surplus-token-idea --color FF10F0 --description "Worth exploring when token budget allows"
 ```
 
@@ -207,7 +213,7 @@ gh issue create --template "Feature Request" --web
 
 ### CLI (non-interactive)
 
-Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.
+The first three headings are the Feature Request form's own fields, in its order — `Use case` and `Proposed behavior` are required by the form, so a body without them does not satisfy it. Everything after `Alternatives considered` is supplemental; omit what you don't need — simple requests don't require Flow / Design / Dependencies blocks.
 
 ````bash
 gh issue create \
@@ -215,34 +221,23 @@ gh issue create \
   --label "enhancement" \
   --assignee "@me" \
   --body "$(cat <<'ISSUE'
-Concrete statement of what's currently missing or broken. Name the specific tool, service, resource, or domain area. Two or three sentences — the reader should know the gap before the end of the paragraph.
-
-Related: #N
+### Use case
 
-## Proposal
+One or two sentences: who hits this gap and why it matters. Name the specific tool, service, resource, or domain area. Kept short on purpose — a field that invites a paragraph gets padded with background and skipped by the next reader.
 
-What you want the server to do, in one paragraph. Link external libraries or services on first mention: [lib name](https://github.com/owner/repo). Include a short justification — what this gives users that they don't have today.
+Related: #N
 
 ### Proposed behavior
 
-Describe the new behavior or surface. For tool/resource changes, show example input/output or the new schema fields:
+What you want the server to do, then the new behavior or surface. For tool/resource changes, show example input/output or the new schema fields. Link external libraries or services on first mention: [lib name](https://github.com/owner/repo).
 
 ```ts
 // Example: new input field or output shape
 ```
 
-### Flow (optional)
-
-Ordered steps — e.g. `request → lookup → fallback → respond`. Useful when the change spans multiple phases or fallbacks.
-
-### Design / Tradeoffs (optional)
-
-Philosophy: **one-line principle in bold.**
+### Alternatives considered
 
-| Option | Strengths | Weaknesses |
-|:---|:---|:---|
-| A | ... | ... |
-| B | ... | ... |
+What you tried or evaluated instead, and why it didn't fit.
 
 ### Scope
 
@@ -255,14 +250,23 @@ Philosophy: **one-line principle in bold.**
 - What we're deliberately not doing
 - Adjacent work that belongs in a separate issue
 
+### Flow (optional)
+
+Ordered steps — e.g. `request → lookup → fallback → respond`. Useful when the change spans multiple phases or fallbacks.
+
+### Design / Tradeoffs (optional)
+
+Philosophy: **one-line principle in bold.**
+
+| Option | Strengths | Weaknesses |
+|:---|:---|:---|
+| A | ... | ... |
+| B | ... | ... |
+
 ### Dependencies (optional)
 
 - Depends on: cyanheads/mcp-ts-core#N (upstream framework change)
 - Depends on: owner/repo#N (other server work)
-
-### Alternatives considered
-
-What you tried or evaluated instead, and why it didn't fit.
 ISSUE
 )"
 ````
@@ -306,4 +310,4 @@ gh issue close <number> --reason completed --comment "Fixed in <commit or PR>"
 - [ ] 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
+- [ ] If feature: `Use case` and `Proposed behavior` present (the form's required fields), `Alternatives considered` third; Out of scope defined