@cyanheads/mcp-ts-core 0.13.2 → 0.13.4

package/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.11"
+  version: "1.12"
   audience: external
   type: workflow
 ---
@@ -42,18 +42,16 @@ gh api 'repos/cyanheads/mcp-ts-core/issues/<number>/timeline' --paginate \
 
 ## Writing Well-Structured Issues
 
-Good issues are scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
+Good issues are terse and fact-dense. **Budget: a bug reads in ~150 words, a feature in ~250, code and logs excluded.** Every section past the form's required fields must earn its place — a section you could delete without changing the fix is noise. One or two sentences per bullet; if a bullet runs long, split it or cut it.
 
+- **Cut what dilutes the signal.** Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), restated context the reader already has, and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
 - **Lead with specifics.** Name the tool, function, module, or symptom. "Currently `createApp()` throws `ConfigurationError` when `MCP_HTTP_PORT` is set to `0`" beats "There's a problem with the config." A reader should know what's broken or missing before the end of the first sentence.
 - **Embed library/service links on first mention.** `[Hono](https://hono.dev/)`, `[linkedom](https://github.com/WebReflection/linkedom)`. Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
 - **Use `owner/repo#N` for cross-repo issue references.** GitHub auto-renders them as linked references (e.g. `cyanheads/pubmed-mcp-server#34`). Bare `#N` only works for same-repo issues.
 - **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
 - **Cite cross-references once per body.** Link an issue/PR in `Related:`, the description, or Additional context — not all three. The reader sees them all; redundant linking dilutes signal.
-- **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **fail fast on config errors, degrade gracefully on runtime errors.**" Establishes the lens for the rest of the section.
 - **Prefer Markdown tables for comparisons.** When showing options, tiers, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
-- **Separate `### Scope` from `### Out of scope`.** The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
 - **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on another issue landing first.
-- **Cut what dilutes the signal.** Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
 - **Skip collaborator-framing sign-offs.** Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.
 
 ## Redact Before Posting
@@ -72,7 +70,7 @@ gh issue create -R cyanheads/mcp-ts-core --template "Bug Report" --web
 
 ### CLI (non-interactive)
 
-Structure the `--body` to match the template's form fields:
+Structure the `--body` to match the template's form fields. Description is two or three sentences; the reproduction is the minimal code and the observed output, nothing else. Add `### Additional context` only when it changes the fix (a workaround, a related issue, the one log line that matters) — omitted by default.
 
 ````bash
 gh issue create -R cyanheads/mcp-ts-core \
@@ -131,10 +129,6 @@ Error: Output validation failed: ...
 ### Expected behavior
 
 Omitting an optional output field should pass validation.
-
-### Additional context
-
-Any workarounds, related issues, or observations.
 ISSUE
 )"
 ````
@@ -214,7 +208,7 @@ gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web
 
 ### CLI (non-interactive)
 
-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.
+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. `Out of scope` is one or two lines. Nothing else by default: a `Scope`, `Flow`, `Design / Tradeoffs`, or `Depends on` block is added only when the reader cannot act without it, and each stays to a few lines.
 
 ````bash
 gh issue create -R cyanheads/mcp-ts-core \
@@ -245,33 +239,9 @@ const result = await withRetry(() => fetchExternal(url), {
 
 What you tried or evaluated instead, and why it didn't fit.
 
-### Scope
-
-- Files or modules touched
-- New exports, env vars, or config keys
-- Tier (Tier 1 core / Tier 2 standard / Tier 3 optional peer dep)
-
 ### Out of scope
 
-- What we're deliberately not doing
 - Adjacent work that belongs in a separate issue
-
-### 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.**
-
-| Option | Strengths | Weaknesses |
-|:---|:---|:---|
-| A | ... | ... |
-| B | ... | ... |
-
-### Dependencies (optional)
-
-- Depends on: owner/repo#N
 ISSUE
 )"
 ````
@@ -299,3 +269,4 @@ gh issue list -R cyanheads/mcp-ts-core --author @me
 - [ ] Primary label assigned (`bug` / `enhancement` / `documentation`)
 - [ ] If bug: version, runtime, repro code, actual vs expected behavior included
 - [ ] If feature: `Use case` and `Proposed API` present (the form's required fields), `Alternatives considered` third; Out of scope defined
+- [ ] Inside the budget — ~150 words for a bug, ~250 for a feature, code and logs excluded — and every section past the form's fields earns its place

package/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.9"
+  version: "1.10"
   audience: external
   type: workflow
 ---
@@ -49,18 +49,16 @@ gh api 'repos/{owner}/{repo}/issues/<number>/timeline' --paginate \
 
 ## Writing Well-Structured Issues
 
-Good issues are scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
+Good issues are terse and fact-dense. **Budget: a bug reads in ~150 words, a feature in ~250, code and logs excluded.** Every section past the form's required fields must earn its place — a section you could delete without changing the fix is noise. One or two sentences per bullet; if a bullet runs long, split it or cut it.
 
+- **Cut what dilutes the signal.** Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), restated context the reader already has, and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
 - **Lead with specifics.** Name the tool, service, resource, or symptom. "Currently `search_docs` returns an empty array for queries containing `&`" beats "Search is broken." A reader should know what's wrong before the end of the first sentence.
 - **Embed library/service links on first mention.** `[Hono](https://hono.dev/)`, `[Supabase](https://supabase.com/)`. Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
 - **Use `owner/repo#N` for cross-repo issue references.** GitHub auto-renders them as linked references (e.g. `cyanheads/mcp-ts-core#46`). Bare `#N` only works for same-repo issues — useful when the bug depends on or relates to a framework issue.
 - **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
 - **Cite cross-references once per body.** Link an issue/PR in `Related:`, the description, or Additional context — not all three. The reader sees them all; redundant linking dilutes signal.
-- **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **return best-effort data, don't fail the tool call on parsing edge cases.**" Establishes the lens for the rest of the section.
 - **Prefer Markdown tables for comparisons.** When showing options, data sources, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
-- **Separate `### Scope` from `### Out of scope`.** The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
 - **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on an upstream framework change or another issue landing first.
-- **Cut what dilutes the signal.** Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
 - **Skip collaborator-framing sign-offs.** Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.
 
 ## Redact Before Posting
@@ -79,7 +77,7 @@ gh issue create --template "Bug Report" --web
 
 ### CLI (non-interactive)
 
-Structure the `--body` to match the template's form fields:
+Structure the `--body` to match the template's form fields. Description is two or three sentences; the reproduction is the exact input and the observed output, nothing else. Add `### Additional context` only when it changes the fix (a workaround, a related issue, the one log line that matters) — omitted by default.
 
 ````bash
 gh issue create \
@@ -125,10 +123,6 @@ Error or incorrect output here
 ### Expected behavior
 
 What should have happened.
-
-### Additional context
-
-Relevant `ctx.log` output, stack traces, or telemetry spans.
 ISSUE
 )"
 ````
@@ -213,7 +207,7 @@ gh issue create --template "Feature Request" --web
 
 ### CLI (non-interactive)
 
-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.
+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. `Out of scope` is one or two lines. Nothing else by default: a `Scope`, `Flow`, `Design / Tradeoffs`, or `Depends on` block is added only when the reader cannot act without it, and each stays to a few lines.
 
 ````bash
 gh issue create \
@@ -239,34 +233,9 @@ What you want the server to do, then the new behavior or surface. For tool/resou
 
 What you tried or evaluated instead, and why it didn't fit.
 
-### Scope
-
-- Files or modules touched
-- New env vars, config keys, or service integrations
-- New or modified tools / resources / prompts
-
 ### Out of scope
 
-- 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)
 ISSUE
 )"
 ````
@@ -311,3 +280,4 @@ gh issue close <number> --reason completed --comment "Fixed in <commit or PR>"
 - [ ] Primary label assigned (`bug` / `enhancement` / `documentation`)
 - [ ] If bug: version, runtime, repro steps, actual vs expected behavior included
 - [ ] If feature: `Use case` and `Proposed behavior` present (the form's required fields), `Alternatives considered` third; Out of scope defined
+- [ ] Inside the budget — ~150 words for a bug, ~250 for a feature, code and logs excluded — and every section past the form's fields earns its place

package/framework-skills/tool-defs-analysis/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Read-only audit of MCP definition language across an existing surface — tools, resources, prompts, server instructions. Walks every definition file and checks 16 categories the LLM reads to decide whether and how to call: voice & tense, internal leaks, audience leaks, defaults, recovery hints, field descriptions, cross-references, sparsity, examples, structure, mutator observability, unit-bearing numeric names, validator-enforced constraints, annotations truthfulness, single-line strings, exclusive modes in the schema — then a cross-surface pass: naming taxonomy, parameter vocabulary, tool overlap, instructions drift, length outliers. Produces grouped findings with file:line citations and a numbered options list. Use during polish, after a refactor, or before a release. Complements `field-test` (behavior testing) and `security-pass` (security audit).
 metadata:
   author: cyanheads
-  version: "1.5"
+  version: "1.6"
   audience: external
   type: audit
 ---
@@ -153,9 +153,9 @@ Field-test catches this in its leak audit; this skill is the more thorough pass.
 
 **Look in:** tool / resource / prompt `description`.
 
-**Check:** single cohesive paragraph. No bullet lists, no blank-line-separated sections, no markdown headers inside the description.
+**Check:** single cohesive paragraph, written as one string literal in source. No bullet lists, no blank-line-separated sections, no markdown headers inside the description; no `+`-joined fragments in the file — a description assembled one sentence per line reads as a list of disconnected claims and grows a line at a time until it is several times its siblings' length.
 
-**Smell:** blank lines (`\n\n`) inside a description string, `- bullet` lines, `## Header` lines, "Operations:\n- foo: …" duplicating an enum's `.describe()` text.
+**Smell:** blank lines (`\n\n`) inside a description string, `- bullet` lines, `## Header` lines, "Operations:\n- foo: …" duplicating an enum's `.describe()` text, `'…' +` continuation lines under `description:`.
 
 #### 11. Mutator observability
 
@@ -218,7 +218,7 @@ The per-file walk misses drift that only shows between files. After it, sweep th
 - **Naming taxonomy** — verb prefixes mean one thing each across the surface (`search_` / `find_` / `get_` / `list_` / `lookup_`); the same verb carrying different semantics on different tools is a finding.
 - **Parameter vocabulary** — one name per concept everywhere: `query` vs `q`, `limit` vs `maxResults`, `nctId` vs `nct_id` on sibling tools is a finding.
 - **Tool overlap** — for any pair with adjacent scope, the two descriptions alone must answer "when X vs Y." If an agent can't pick, that's material.
-- **Instructions drift** — if the server sets `instructions`: every tool it names exists, workflow guidance reflects the current surface (new tools that belong in it, renamed or removed ones purged), and nothing contradicts a per-tool description.
+- **Instructions drift** — if the server sets `instructions`: every tool it names exists, workflow guidance reflects the current surface (new tools that belong in it, renamed or removed ones purged), and nothing contradicts a per-tool description. Shape is a finding too: two to three cohesive sentences in one string literal (no `+`-joined fragments, no one-line-per-tool inventory — the catalog already carries that), written for the calling agent only. Operator configuration (`*_BASE_URL`, API keys, ports) belongs in the README and `.env.example`, not here — the agent cannot act on it.
 - **Length outliers** — a description several times longer than its siblings (attention drag), or a one-liner that underspecifies (selection risk).
 
 Cross-surface findings use the same finding format, cited at the file:line you'd change (the `instructions` string is a citable location).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -200,7 +200,7 @@
     "@biomejs/biome": "2.5.13",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
     "@cloudflare/workers-types": "5.20260910.1",
-    "@duckdb/node-api": "^1.5.5-r.4",
+    "@duckdb/node-api": "^1.5.5-r.5",
     "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
@@ -228,10 +228,10 @@
     "depcheck": "^1.4.7",
     "diff": "^9.0.0",
     "execa": "^10.0.1",
-    "fast-check": "^4.9.0",
+    "fast-check": "^4.10.0",
     "fast-xml-parser": "^5.11.1",
     "ignore": "^7.0.9",
-    "js-yaml": "^5.4.1",
+    "js-yaml": "^5.4.2",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
     "openai": "^7.15.0",
@@ -241,7 +241,7 @@
     "pino-pretty": "^13.1.3",
     "repomix": "^1.18.0",
     "sanitize-html": "^2.17.7",
-    "tsc-alias": "^1.9.4",
+    "tsc-alias": "^1.9.5",
     "typedoc": "^0.28.20",
     "typescript": "^7.0.2",
     "typescript-v6": "npm:typescript@^6.0.3",
@@ -306,10 +306,10 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.1",
     "dotenv": "^17.4.2",
-    "hono": "^4.13.7",
+    "hono": "^4.13.8",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
-    "zod": "^4.6.2"
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",

package/templates/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -76,7 +76,7 @@ body:
     id: description
     attributes:
       label: Description
-      description: What happened and what you expected instead.
+      description: What happened and what you expected instead — two or three sentences.
     validations:
       required: true
 
@@ -112,6 +112,6 @@ body:
     id: context
     attributes:
       label: Additional context
-      description: Workarounds, related issues, logs, or anything else relevant.
+      description: Only what changes the fix — a workaround, a related issue, the one log line that matters.
     validations:
       required: false

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -17,7 +17,7 @@ body:
     id: use-case
     attributes:
       label: Use case
-      description: What problem does this solve? Who benefits?
+      description: What problem does this solve? Who benefits? Two or three sentences.
     validations:
       required: true
 
@@ -42,6 +42,6 @@ body:
     id: context
     attributes:
       label: Additional context
-      description: Related issues, prior art, links, or anything else relevant.
+      description: Only what the reader needs to act — related issues, prior art, a link.
     validations:
       required: false

package/templates/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+# CodeQL static analysis — the one workflow every server carries.
+# Verification (typecheck, lint, tests) is local; this file exists because CodeQL
+# is GitHub-owned end to end and a workflow file is visible in the repo where a
+# repo-level "default setup" is not. Default setup must be OFF for this to run.
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '30 6 * * 1'
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      security-events: write
+      contents: read
+      actions: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: javascript-typescript, actions
+          build-mode: none
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4

package/templates/AGENTS.md

@@ -311,7 +311,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
-| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixup commits autosquashed into the stack, PR body kept in sync. Release PR mode only |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
@@ -362,6 +362,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling

package/templates/CLAUDE.md

@@ -311,7 +311,7 @@ Available skills:
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern, release commit on top. No tag, no push to main; opens the release PR when the project declares release PR mode |
-| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixup commits autosquashed into the stack, PR body kept in sync. Release PR mode only |
+| `release-pr-review` | Review pass on an open release PR — simplifier + correctness review, fixes as ordinary commits on top of the stack, PR body kept in sync. Release PR mode only |
 | `release-and-publish` | Fast-forward merge (release PR mode) + tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
@@ -362,6 +362,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
+**CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
+
 ---
 
 ## Bundling

package/templates/changelog/template.md

@@ -6,8 +6,8 @@
 
 # Required. One-line GitHub Release-style headline. 350 character cap — a
 # ceiling, not a target. Default short and scannable. Don't pad, don't stitch
-# unrelated changes with commas/semicolons into an inventory — pick the
-# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# unrelated changes with commas/semicolons into an inventory — pick the one
+# headline the release is about. Quotes required: unquoted YAML treats
 # `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
@@ -119,11 +119,11 @@ security: false
   TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
   via `gh release create --notes-from-tag`. It is a condensed digest of this
   entry, never a copy, and its format is owned by the `release-and-publish`
-  skill (step 4, "Create the annotated tag"): the entry's `summary:` as the
-  theme line without the version, flat headline bullets — no Keep-a-Changelog
-  section headers, no gates line — at most one deps line, issue backlinks,
-  and the changelog link last. In release-PR mode the `git-wrapup` skill
-  authors that digest as the PR body's `## Changes` and the tag copies it.
+  skill (step 4, "Create the annotated tag"): a short subject line without the
+  version, flat headline bullets — no Keep-a-Changelog section headers, no
+  gates line — at most one deps line, issue backlinks, and the changelog link
+  last. In release-PR mode the `git-wrapup` skill authors those bullets as the
+  PR body's `## Changes` and the tag copies them.
 -->
 
 ## Added

package/templates/package.json

@@ -72,8 +72,8 @@
     "@vitest/coverage-istanbul": "4.1.11",
     "depcheck": "^1.4.7",
     "fast-check": "^4.9.0",
-    "ignore": "^7.0.7",
-    "tsc-alias": "^1.9.2",
+    "ignore": "^7.0.9",
+    "tsc-alias": "^1.9.5",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   }

package/templates/src/index.ts

@@ -17,9 +17,10 @@ await createApp({
   tools: [echoTool, echoAppTool],
   resources: [echoResource, echoAppUiResource],
   prompts: [echoPrompt],
-  // instructions: 'Server-level orientation forwarded to the model on every initialize.\n' +
-  //   '- Use shortcut `X` for the most common case\n' +
-  //   '- Tools require auth via the `inventory:read` scope',
+  // Server-level orientation forwarded to the model on every initialize: two to three
+  // cohesive sentences in one string literal, written for the calling agent (which tool
+  // opens a workflow, what chains into what). Operator configuration stays in the README.
+  // instructions: 'Resolve a name to an id with example_search, then pass that id to example_get for the full record. Results are paged; follow nextOffset until it is absent.',
 
   // Session posture in code rather than in a Dockerfile. MCP_SESSION_MODE still
   // wins when it is set. Add `require: 'stateful'` — `{ default: 'stateful',