@cyanheads/mcp-ts-core 0.12.8 → 0.13.0

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
 ```
 
@@ -40,7 +55,7 @@ Centered HTML. The `<h1>` is the server name — use the scoped package name if
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/my-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/my-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/my-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/my-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -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:
 
@@ -333,7 +332,7 @@ A public instance is available at `https://my-server.example.com/mcp` — no ins
 ```markdown
 ### Prerequisites
 
-- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
 - An Acme API key — see [`docs/api-key.md`](./docs/api-key.md) for how to generate one.
 ```
 
@@ -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-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.14"
+  version: "2.16"
   audience: external
   type: workflow
 ---
@@ -138,6 +138,7 @@ Format — a **headline digest**, never a section-by-section changelog mirror:
 (` · release PR #<N>` only in release PR mode; without a PR the line ends at the changelog link.)
 
 **Rules:**
+- **Subject line is ONE short theme, at most ~60 characters, no semicolons, no clauses** — it becomes the GitHub Release title after `v<VERSION>: `. The digest lives in the bullets; a subject that summarizes each change is wrong even when every word is accurate. In release PR mode the PR body's opening paragraph is NOT the subject — write the theme fresh (the release commit's subject after the version and dash is usually it)
 - Subject line omits the version number (GitHub prepends `v<VERSION>:` to the release title)
 - **Flat bullets only — never Keep-a-Changelog section headers.** `Added:`/`Changed:`/`Fixed:`/`Dependency bumps:` belong in the changelog file; a tag that mirrors the changelog's structure is wrong even when every line is accurate
 - **Complete at headline granularity** — every changelog-worthy change stays visible: notable changes get their own bullet, minor/internal items (build config, repo hygiene, metadata) share ONE grouped compact bullet. Nothing silently dropped, nothing expanded — the changelog carries the depth, the tag carries the existence
@@ -171,6 +172,8 @@ Push `main` first, then the tag. If the remote rejects either push, halt.
 
 ### 6. Publish to npm
 
+Before publishing, inspect `bun publish --dry-run`. A resumed run may leave `dist/*.mcpb` in a package whose `files` allowlist includes `dist/`, adding the desktop bundle and its dependencies to npm. If listed, move the bundle outside the package directory, publish npm, then restore the bundle for the GitHub Release.
+
 ```bash
 bun publish --access public
 ```

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

package/{skills → framework-skills}/security-pass/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: audit
 ---
@@ -257,7 +257,7 @@ grep -rn "JSON.parse\b" src/
 
 DataCanvas is opt-in and deliberately trades isolation for cross-agent token-shareable working sets — designed for public-data tabular servers (BrAPI, OpenAlex, etc.) where session-pinning isn't desired. The trade only holds when the deployment matches that assumption. Skip this axis entirely when canvas is disabled (`CANVAS_PROVIDER_TYPE=none`, the default).
 
-**Look in:** `src/config/server-config.ts`, every tool reading `ctx.core.canvas?`, deployment config (wrangler / Dockerfile / proxy).
+**Look in:** `src/config/server-config.ts`, the `setCanvas(core.canvas)` wiring in `setup()` and every tool reading the canvas accessor, deployment config (wrangler / Dockerfile / proxy).
 
 **Check:**
 

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

@@ -4,14 +4,14 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: workflow
 ---
 
 ## Context
 
-This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
+This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `framework-skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
 
 ## Agent Protocol File
 
@@ -41,7 +41,7 @@ Dockerfile                                      # Starter multi-stage image
 server.json                                     # MCP Registry publishing metadata
 changelog/template.md                           # Format reference for per-version changelog files
 scripts/                                        # build, clean, devcheck, lint-mcp, list-skills, build-changelog, tree, check-docs-sync
-skills/                                         # External skills copied from the package (source of truth)
+framework-skills/                               # External skills copied from the package (source of truth)
 src/
   index.ts                                      # createApp() entry point
   mcp-server/
@@ -108,14 +108,14 @@ See the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt`, `add-service`,
 
 ## Skill Sync
 
-Copy all project skills into your agent's skill directory so they're available as context. `skills/` is the source of truth.
+Copy all project skills into your agent's skill directory so they're available as context. `framework-skills/` is the source of truth. It is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, and these are development skills, not skills for the agents that install the server — leave `skills/` for those.
 
-**Don't edit `skills/*/SKILL.md` or `skills/*/references/*`.** These are external skill files synced from `@cyanheads/mcp-ts-core` — the `maintenance` skill overwrites them on package updates, so local edits get lost. Project-specific agent context belongs in `CLAUDE.md` / `AGENTS.md`.
+**Don't edit `framework-skills/*/SKILL.md` or `framework-skills/*/references/*`.** These are external skill files synced from `@cyanheads/mcp-ts-core` — the `maintenance` skill overwrites them on package updates, so local edits get lost. Project-specific agent context belongs in `CLAUDE.md` / `AGENTS.md`.
 
 **For Claude Code:**
 
 ```bash
-mkdir -p .claude/skills && cp -R skills/* .claude/skills/
+mkdir -p .claude/skills && cp -R framework-skills/* .claude/skills/
 ```
 
 **For other agents** (Codex, Cursor, Windsurf, etc.) — copy to the equivalent directory (e.g., `.codex/skills/`, `.cursor/skills/`).
@@ -138,7 +138,9 @@ Complete these one-time setup tasks:
    | `.claude-plugin/plugin.json` | `description` | `lint:packaging` |
    | `.codex-plugin/plugin.json` | `description`, `interface.shortDescription`, `interface.longDescription` | `lint:packaging` |
 
-   Fill the rest of the same blocks while you are in them — `package.json` `description` and `repository.url`, both plugin manifests' `author` / `homepage` / `repository`, the Codex manifest's `interface.developerName` / `category` / `websiteURL`, and `manifest.json` `description` / `author.name`. Nothing gates them, and every install surface reads them.
+   Fill the rest of the same blocks while you are in them — `package.json` `description` and `repository.url`, both plugin manifests' `author` / `homepage` / `repository` / `keywords`, the Codex manifest's `interface.developerName` / `category` / `websiteURL`, and `manifest.json` `description` / `author.name`. Nothing gates them, and every install surface reads them.
+
+   When the server takes a user-supplied value (an API key, a contact email, an instance URL), wire it into the plugin manifests the way each client delivers it — never as `"KEY": ""` in `env`, which `lint:packaging` rejects because the empty value replaces the user's exported key and is read as unset. In `.claude-plugin/plugin.json`, declare the option under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and set `"KEY": "${user_config.<option>}"` in `env`. In `.codex-plugin/mcp.json`, list the variable name in `env_vars`. Mirror the `user_config` block you write in `manifest.json`.
 
    A server that will never be published or installed as a plugin can drop the plugin-manifest gate instead — set `"packaging": { "pluginManifests": false }` in `devcheck.config.json`.
 6. **Verify the scaffold builds clean** — `bun run devcheck`. Fix any issues before starting real work.
@@ -172,7 +174,7 @@ Skip or reorder as the project calls for it. The agent protocol's "What's Next?"
 - [ ] Publishing identity populated (`server.json`, `package.json`, plugin manifests, `manifest.json`) — or the plugin-manifest gate opted out
 - [ ] Framework docs read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` or `AGENTS.md`)
 - [ ] Unused echo definitions cleaned up (and unregistered from `src/index.ts`)
-- [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
+- [ ] Skills copied to agent directory (`cp -R framework-skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)
 - [ ] `bun run devcheck` passes
 - [ ] Next: if new server, move on to `design-mcp-server` to plan the tool surface