@cyanheads/mcp-ts-core 0.4.1 → 0.5.2

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

@@ -7,42 +7,47 @@ Structure and content guide for creating or updating a README for an MCP server
 Use this section order. Omit sections that don't apply (e.g., skip Docker/Workers if the server doesn't deploy there).
 
 ```text
-# {Server Name}                        ← centered HTML block
-Badges row                             ← npm, Docker, Version, MCP Spec, SDK, License, Status, TS, Bun, Coverage
+# {Server Name}                         ← centered HTML block
+[Public hosted callout if present]      ← centered HTML block, directly under badges
+Badges row                              ← npm, Docker, Version, Framework, MCP SDK, License, TS, Bun, Coverage
 ---
-## Tools                               ← summary table, then per-tool subsections
-## Resources (if any)                  ← summary table
-## Prompts (if any)                    ← summary table
-## Features                            ← framework + domain-specific bullets
-## Getting Started                     ← hosted instance (if any), MCP client config, prerequisites, install
-## Configuration                       ← env var table
-## Running the Server                  ← dev, production, Workers/Docker
-## Project Structure                   ← directory/purpose table
-## Development Guide                   ← link to CLAUDE.md, key rules
-## Contributing                        ← brief
-## License                             ← one line
+## 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
+## 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, key rules
+## Contributing                         ← brief
+## License                              ← one line
 ```
 
 ## Section Guide
 
 ### Title Block
 
-Centered HTML. The `<h1>` is the server name — use the scoped package name if published under a scope (e.g., `@cyanheads/my-mcp-server`). The `<p>` is a bold one-liner: what the server wraps, key capabilities, transport/deployment options. Follow with a count line summarizing the MCP surface (tools, resources, prompts) separated by ` · `, then a badge row.
+Centered HTML. The `<h1>` is the server name — use the scoped package name if published under a scope (e.g., `@cyanheads/my-mcp-server`). The `<p>` is a bold one-liner: what the server wraps, key capabilities, transport/deployment options. **Nest the surface count as a `<div>` inside the same `<p>`**, separated by `•` (U+2022 bullet) — not as a second `<p>`. This matches the shipping convention across `@cyanheads/*` servers.
 
 ```html
 <div align="center">
   <h1>@cyanheads/my-mcp-server</h1>
-  <p><b>MCP server for the Acme API. Search projects, manage tasks, track teams. STDIO & Streamable HTTP</b></p>
-  <p><b>7 Tools · 2 Resources · 1 Prompt</b></p>
+  <p><b>MCP server for the Acme API — search projects, manage tasks, track teams. STDIO or Streamable HTTP.</b>
+  <div>7 Tools • 2 Resources • 1 Prompt</div>
+  </p>
 </div>
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/my-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/my-mcp-server) [![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![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) [![Version](https://img.shields.io/badge/Version-1.0.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![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.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 ```
 
+The header tagline must match the `package.json` `description`.
+
 **Badge selection:** All badges use `style=flat-square`. Include what applies — don't add badges for things the server doesn't have:
 
 | Badge | When to include |
@@ -51,19 +56,41 @@ Centered HTML. The `<h1>` is the server name — use the scoped package name if
 | Docker | Published to ghcr.io or Docker Hub |
 | Version | Always — link to CHANGELOG.md |
 | Framework | Always — links to `@cyanheads/mcp-ts-core` on npm |
-| MCP Spec | Always — link to the spec version implemented |
 | MCP SDK | Always — show the `@modelcontextprotocol/sdk` version |
 | License | Always |
-| Status | Optional — Stable, Beta, etc. |
 | TypeScript | Always |
-| Bun | If using Bun |
+| Bun | If using Bun (standard for this framework) |
+| MCP Spec | Optional — rarely included; the SDK badge usually suffices |
+| Status | Optional — Stable, Beta, etc. |
 | Code Coverage | If coverage is tracked |
 
 Add a `---` horizontal rule after the badge block.
 
+### Public Hosted Callout (if present)
+
+If a public hosted instance is available, **promote it to a top-level callout** immediately below the badge block — don't bury it inside Getting Started. This is the highest-value piece of information for a visitor who wants to try the server with zero install.
+
+```html
+<div align="center">
+
+**Public Hosted Server:** [https://my-server.example.com/mcp](https://my-server.example.com/mcp)
+
+</div>
+```
+
+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
 
-This is the most important section — it tells humans and LLMs exactly what the server exposes. Two layers: summary table, then per-tool subsections for tools with non-trivial behavior.
+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.
+
+**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:
+
+- "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."
+
+If the tools aren't meaningfully grouped, a single sentence count ("Seven tools for working with Acme data:") is acceptable.
 
 **Summary table:**
 
@@ -79,8 +106,6 @@ Seven tools for working with Acme data:
 | `get_task` | Fetch one or more tasks by ID, with full or summary data. |
 ```
 
-Lead with a one-line count: "Seven tools for working with X data:" (or "Three tools", etc.).
-
 **Per-tool subsections:**
 
 Below the table, add a `### tool_name` subsection for each tool that has meaningful detail beyond its one-line description. Include:
@@ -110,34 +135,35 @@ Fetch one or more tasks by ID, with full data or concise summaries.
 - 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
-
-[View detailed examples](./examples/get_task.md)
 ```
 
 Skip the per-tool subsection for simple tools where the table description says everything (e.g., a `get_field_values` lookup tool).
 
-### Resources (if any)
+### Resources and Prompts (combined)
+
+**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
+## Resources and prompts
 
-| URI Pattern | Description |
-|:------------|:------------|
-| `acme://projects/{projectId}` | Project details by ID |
-| `acme://tasks/{taskId}` | Task details by ID |
+| 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 |
 ```
 
-### Prompts (if any)
+Use singular ("Resource and prompt") if there's only one of each.
 
-```markdown
-## Prompts
+**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:
 
-| Prompt | Description |
-|:-------|:------------|
-| `project_summary` | Summarize a project's status and open tasks |
+```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.
 ```
 
-Derive all tool/resource/prompt tables directly from the actual definitions. Use the real names and descriptions from the Zod schemas.
+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.
 
 ### Features
 
@@ -146,90 +172,166 @@ Two subsection groups: framework capabilities, then domain-specific capabilities
 ```markdown
 ## Features
 
-Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
 
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling across all tools
-- Pluggable auth (`none`, `jwt`, `oauth`)
+- 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
-- Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase
+- STDIO and Streamable HTTP transports
 
 Acme-specific:
 
 - Type-safe client for the Acme v2 API
 - Automatic cleaning and simplification of API responses for agent consumption
+- Workflow tools parallelize related sub-requests under a configurable concurrency limit
 ```
 
 ### Getting Started
 
-Lead with the lowest-friction option. If a public hosted instance exists, show that first. Then self-hosted via `bunx`/`npx`. Then manual clone/install.
+Lead with the lowest-friction option. If a public hosted instance exists, show that first. Then the **three standard install configs in order — `bunx`, `npx`, `docker run`** — followed by the HTTP one-liner quickstart, then prerequisites and install steps.
 
-```markdown
-## Getting Started
+**Standard three-block pattern** (the house style across shipping `@cyanheads/*` servers):
 
-### Public Hosted Instance
+```markdown
+## Getting started
 
-A public instance is available at `https://my-server.example.com/mcp` — no installation required:
+Add the following to your MCP client configuration file. See [`docs/api-key.md`](./docs/api-key.md) for how to generate an API key.
 
 \`\`\`json
 {
   "mcpServers": {
     "my-server": {
-      "type": "streamable-http",
-      "url": "https://my-server.example.com/mcp"
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@cyanheads/my-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info",
+        "ACME_API_KEY": "your-api-key"
+      }
     }
   }
 }
 \`\`\`
 
-### Self-Hosted / Local
-
-Add to your MCP client config (e.g., `claude_desktop_config.json`):
+Or with npx (no Bun required):
 
 \`\`\`json
 {
   "mcpServers": {
-    "my-mcp-server": {
+    "my-server": {
       "type": "stdio",
-      "command": "bunx",
-      "args": ["my-mcp-server@latest"],
+      "command": "npx",
+      "args": ["-y", "@cyanheads/my-mcp-server@latest"],
       "env": {
-        "ACME_API_KEY": "your-api-key",
-        "MCP_TRANSPORT_TYPE": "stdio"
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info",
+        "ACME_API_KEY": "your-api-key"
       }
     }
   }
 }
 \`\`\`
 
+Or with Docker:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "-e", "ACME_API_KEY=your-api-key",
+        "ghcr.io/cyanheads/my-mcp-server:latest"
+      ]
+    }
+  }
+}
+\`\`\`
+
+For Streamable HTTP, set the transport and start the server:
+
+\`\`\`sh
+MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 ACME_API_KEY=... bun run start:http
+# Server listens at http://localhost:3010/mcp
+\`\`\`
+```
+
+Refer to "your MCP client configuration file" generically — don't prescribe `claude_desktop_config.json` by name. Different clients use different config paths and the server isn't client-specific.
+
+**If a public hosted instance exists**, precede the three-block pattern with a `### Public Hosted Instance` subsection and wrap the local configs in a `### Self-Hosted / Local` subsection:
+
+```markdown
+### Public Hosted Instance
+
+A public instance is available at `https://my-server.example.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "streamable-http",
+      "url": "https://my-server.example.com/mcp"
+    }
+  }
+}
+\`\`\`
+
+### Self-Hosted / Local
+
+[bunx / npx / docker blocks here]
+```
+
+**Prerequisites:** Include a Bun version line and any domain-specific setup (API key format, rate-limit tiers, required accounts). Don't just list Bun — readers need to know what else to prepare.
+
+```markdown
 ### Prerequisites
 
-- [Bun v1.2.0](https://bun.sh/) or higher.
+- [Bun v1.3.2](https://bun.sh/) or higher (or Node.js v22+).
+- An Acme API key — see [`docs/api-key.md`](./docs/api-key.md) for how to generate one.
+```
+
+**Installation:** Standard four steps (clone, cd, install, configure env):
 
+```markdown
 ### Installation
 
 1. **Clone the repository:**
+
 \`\`\`sh
 git clone https://github.com/cyanheads/my-mcp-server.git
 \`\`\`
 
 2. **Navigate into the directory:**
+
 \`\`\`sh
 cd my-mcp-server
 \`\`\`
 
 3. **Install dependencies:**
+
 \`\`\`sh
 bun install
 \`\`\`
+
+4. **Configure environment:**
+
+\`\`\`sh
+cp .env.example .env
+# edit .env and set required vars
+\`\`\`
 ```
 
-Omit the hosted instance subsection if there isn't one. Omit the clone/install steps if the server is npm-only (not meant to be cloned).
+Omit the clone/install steps if the server is npm-only (not meant to be cloned).
 
 ### Configuration
 
-Table of environment variables. Include framework vars only if the server uses non-default values.
+Table of environment variables. Include framework vars only if the server uses non-default values. Mark required vars with bold **Required.** in the description rather than a separate column. **Close with a pointer to `.env.example`** for the full list of optional overrides.
 
 ```markdown
 ## Configuration
@@ -238,6 +340,7 @@ Table of environment variables. Include framework vars only if the server uses n
 |:---------|:------------|:--------|
 | `ACME_API_KEY` | **Required.** API key for the Acme service. | — |
 | `ACME_BASE_URL` | API base URL. | `https://api.acme.com` |
+| `ACME_TIMEOUT_MS` | Per-request timeout in milliseconds. | `60000` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
@@ -245,74 +348,105 @@ Table of environment variables. Include framework vars only if the server uses n
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
 | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
+
+See [`.env.example`](./.env.example) for the full list of optional overrides.
 ```
 
-Source from the server config Zod schema and `.env.example`. Mark required vars with bold **Required.** in the description rather than a separate column.
+Source from the server config Zod schema and `.env.example`.
 
 ### Running the Server
 
-Separate from Getting Started. Show build + run commands, and Workers/Docker deployment if applicable.
+Separate from Getting Started. Show dev, build + run, and Workers/Docker deployment if applicable.
 
 ```markdown
-## Running the Server
+## Running the server
+
+### Local development
 
-### Local Development
+- **Hot-reload dev mode:**
+
+  \`\`\`sh
+  bun run dev:stdio
+  bun run dev:http
+  \`\`\`
 
 - **Build and run the production version:**
+
   \`\`\`sh
-  bun run build
-  bun run start:http   # or start:stdio
+  # One-time build
+  bun run rebuild
+
+  # Run the built server
+  bun run start:stdio
+  # or
+  bun run start:http
   \`\`\`
 
 - **Run checks and tests:**
+
   \`\`\`sh
-  bun run devcheck     # Lints, formats, type-checks
-  bun run test         # Runs test suite
+  bun run devcheck   # Lint, format, typecheck, security
+  bun run test       # Vitest test suite
+  bun run lint:mcp   # Validate MCP definitions against spec
   \`\`\`
 
+### Docker
+
+\`\`\`sh
+docker build -t my-mcp-server .
+docker run --rm -e ACME_API_KEY=your-key -p 3010:3010 my-mcp-server
+\`\`\`
+
+The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/my-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
+
 ### Cloudflare Workers
 
 1. **Build the Worker bundle:**
+
 \`\`\`sh
 bun run build:worker
 \`\`\`
 
 2. **Deploy:**
+
 \`\`\`sh
 bun run deploy:prod
 \`\`\`
 ```
 
-Include the Docker or Workers subsection only if the server supports it.
+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.
 
 ### Project Structure
 
 Directory/purpose table orienting contributors to the codebase.
 
 ```markdown
-## Project Structure
+## Project structure
 
 | Directory | Purpose |
 |:----------|:--------|
+| `src/index.ts` | `createApp()` entry point — registers tools/resources/prompts and inits services. |
+| `src/config` | Server-specific environment variable parsing and validation with Zod. |
 | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |
 | `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |
+| `src/mcp-server/prompts` | Prompt definitions (`*.prompt.ts`). |
 | `src/services` | Domain service integrations. |
-| `src/config` | Environment variable parsing and validation with Zod. |
 | `tests/` | Unit and integration tests mirroring `src/`. |
 ```
 
 ### Development Guide
 
-Brief — link to CLAUDE.md for full details. State 2-3 key rules.
+Brief — link to CLAUDE.md for full details. State 3-4 key rules. **Include the "validate → normalize → never fabricate" bullet** — it's the canonical anti-hallucination convention for external API wrappers and reinforces the framework's `no fabricated signal` principle.
 
 ```markdown
-## Development Guide
+## Development guide
 
 See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
-- Use `ctx.log` for domain-specific logging, `ctx.state` for storage
-- Register new tools and resources in the `index.ts` barrel files
+- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage
+- Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`
+- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
 ```
 
 ### Contributing
@@ -320,7 +454,7 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
 ```markdown
 ## Contributing
 
-Issues and pull requests are welcome. Run checks before submitting:
+Issues and pull requests are welcome. Run checks and tests before submitting:
 
 \`\`\`sh
 bun run devcheck
@@ -343,8 +477,12 @@ Apache-2.0 — see [LICENSE](LICENSE) for details.
 - **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.
 - **Tables over prose** for structured data (tools, config, directories). Scannable and diff-friendly.
-- **Two-layer tool docs.** Summary table for quick scanning, per-tool subsections for detail. Skip subsections for trivial tools.
+- **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.
+- **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.
-- **Lowest friction first.** In Getting Started, lead with the easiest option (hosted instance > bunx > clone).
+- **Lowest friction first.** Hosted instance > bunx > npx > docker > clone.
 - **No badges unless publishing.** Badges for unpublished packages are noise.
+- **Client-agnostic framing.** Say "your MCP client configuration file", not `claude_desktop_config.json`.
 - **Keep it current.** Update the README whenever tools are added or removed.

package/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.2"
+  version: "1.3"
   audience: external
   type: workflow
 ---
 
 ## Context
 
-This skill assumes `@cyanheads/mcp-ts-core init` 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 `npx @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.
 
 ## Agent Protocol File
 
@@ -91,7 +91,7 @@ mkdir -p .claude/skills && cp -R skills/* .claude/skills/
 
 **For other agents** (Codex, Cursor, Windsurf, etc.) — copy to the equivalent directory (e.g., `.codex/skills/`, `.cursor/skills/`).
 
-After the initial copy, use the `maintenance` skill to keep them in sync after package updates.
+This step is the **bootstrap** — it creates the agent directory. From then on, use the `maintenance` skill to refresh it after package updates (Phase B). Maintenance only refreshes directories that already exist; it won't create a new agent directory on your behalf.
 
 ## Project Scaffolding
 

package/templates/AGENTS.md

@@ -14,8 +14,7 @@
 
 1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
 2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-3. **Check for Bun** — run `bun --version`. If [Bun](https://bun.sh) is available, it's the recommended runtime: update `package.json` scripts to use `bun` instead of `tsx` (e.g., `"devcheck": "bun scripts/devcheck.ts"`), prefer `bun run` over `npm run` for all commands, and update the Commands table and Checklist in this file to match.
-4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
@@ -25,13 +24,13 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
-3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
 4. **Add services** — scaffold domain service integrations using the `add-service` skill
 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
 7. **Run `devcheck`** — lint, format, typecheck, and security audit
 8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+9. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
 
 Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
 
@@ -77,6 +76,7 @@ export const searchItems = tool('search_items', {
 
   // format() populates content[] — the only field most LLM clients forward to
   // the model. Render all data the LLM needs, not just a count or title.
+  // Enforced at lint time: every field in `output` must appear in the rendered text.
   format: (result) => [{
     type: 'text',
     text: result.items.map(i => `**${i.id}**: ${i.name}`).join('\n'),
@@ -122,20 +122,26 @@ export const reviewCode = prompt('review_code', {
 
 ```ts
 // src/config/server-config.ts — lazy-parsed, separate from framework config
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+
 const ServerConfigSchema = z.object({
-  myApiKey: z.string().describe('External API key'),
+  apiKey: z.string().describe('External API key'),
   maxResults: z.coerce.number().default(100),
 });
+
 let _config: z.infer<typeof ServerConfigSchema> | undefined;
 export function getServerConfig() {
-  _config ??= ServerConfigSchema.parse({
-    myApiKey: process.env.MY_API_KEY,
-    maxResults: process.env.MY_MAX_RESULTS,
+  _config ??= parseEnvConfig(ServerConfigSchema, {
+    apiKey: 'MY_API_KEY',
+    maxResults: 'MY_MAX_RESULTS',
   });
   return _config;
 }
 ```
 
+`parseEnvConfig` maps Zod schema paths → env var names so validation errors name the actual variable (`MY_API_KEY`) rather than the internal path (`apiKey`). It throws a `ConfigurationError` the framework catches and prints as a clean startup banner.
+
 ---
 
 ## Context
@@ -215,7 +221,7 @@ src/
 
 Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, re-copy to pick up changes.
+**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
 
 Available skills:
 
@@ -232,7 +238,7 @@ Available skills:
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Sync skills and dependencies after updates |
+| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -250,6 +256,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
+**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. Use whichever package manager you have; `bun` is slightly faster for invoking scripts but not required.
+
 | Command | Purpose |
 |:--------|:--------|
 | `npm run build` | Compile TypeScript |
@@ -281,7 +289,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
 - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage