@cyanheads/mcp-ts-core 0.12.9 → 0.13.0

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.13"
+  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/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,90 @@ 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
+### Overview
 
-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.
+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.
 
-**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:
+**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, the hosted endpoint if any). Not a count, and not "an MCP server that…" framing.
 
-- "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."
+**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.
 
-If the tools aren't meaningfully grouped, a single sentence count ("Seven tools for working with Acme data:") is acceptable.
+```markdown
+## Overview
 
-**Summary table:**
+An MCP server 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.
 
-```markdown
-## Tools
+### Tools
 
-Seven tools for working with Acme data:
+| 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 |
 
-| 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. |
-```
+### Resources
 
-**Per-tool subsections:**
+| Resource | Description |
+|:---|:---|
+| `acme://projects/{projectId}` | Project details by ID |
 
-Below the table, add a `### tool_name` subsection for each tool that has meaningful detail beyond its one-line description. Include:
+### Prompts
 
-- 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
+| Prompt | Description |
+|:---|:---|
+| `project_summary` | Summarize a project's status and open tasks |
+```
 
-```markdown
-### `acme_search_projects`
+Derive every row from the actual definitions — real names and descriptions from the Zod schemas.
 
-Search for projects using free-text queries and filters.
+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.
 
-- 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
+### Capability reference
 
-[View detailed examples](./examples/acme_search_projects.md)
+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.
 
----
+**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.
 
-### `acme_get_task`
+```markdown
+## Capability reference
 
-Fetch one or more tasks by ID, with full data or concise summaries.
+### `acme_search_projects` <sub>tool</sub>
 
-- 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
-```
+- 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
 
-Skip the per-tool subsection for simple tools where the table description says everything (e.g., an `acme_get_field_values` lookup tool).
+---
 
-### Resources and Prompts (combined)
+### `acme_get_task` <sub>tool</sub>
 
-**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.
+- 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
 
-```markdown
-## Resources and prompts
+---
 
-| 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 |
-```
+### `acme://projects/{projectId}` <sub>resource</sub>
 
-Use singular ("Resource and prompt") if there's only one of each.
+- Project record as `application/json` — name, status, owners, open task count
+- `projectId` comes from `acme_search_projects`
 
-**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:
+---
 
-```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_summary` <sub>prompt</sub>
 
-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).`
+- Arguments: `projectId` required; `includeClosed` (`"true"` / `"false"`) optional
+- Returns two messages — an assistant framing message and a user message carrying the summary request
+```
 
-Derive all tool/resource/prompt rows directly from the actual definitions. Use the real names and descriptions from the Zod schemas.
+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.
+A one-sentence framework line naming what a user gets from the framework (transports, auth, storage, observability — not how the code is organized; contributor facts belong in the Development guide), then two bullet groups: domain-specific capabilities, then agent-friendly output design.
 
 ```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://www.npmjs.com/package/@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:
 
@@ -483,6 +482,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 +509,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-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.10"
   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
 
@@ -213,7 +213,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 +221,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 +240,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 +255,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 +293,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.8"
   audience: external
   type: workflow
 ---
@@ -207,7 +207,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 +215,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.
+### Use case
 
-Related: #N
-
-## 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 +244,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 +304,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