@cyanheads/mcp-ts-core 0.10.13 → 0.10.15

package/skills/orchestrations/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: workflow
 ---
@@ -189,7 +189,7 @@ Sub-agent self-reports describe intent, not always reality. After every phase th
 - **GitHub** — `gh repo view --json visibility`, `gh release view v<VERSION>`, `gh issue list`, `gh issue view <N> --comments` to confirm the fix comment landed
 - **npm / registries** — `npm view <pkg>@<version>`, registry-specific checks
 - **Build state** — re-run `bun run devcheck` if the previous phase was supposed to land green
-- **Quality** — tag annotation reads as structured markdown (not flat string), subject omits the version number, no marketing adjectives, dep arrows present where applicable, issue backlinks where applicable
+- **Quality** — tag annotation is a headline digest covering every change (flat bullets — notable ones named, minor ones in one grouped bullet; no changelog section headers, deps ≤1 line, no gates line), subject omits the version number, no marketing adjectives, issue backlinks where applicable, changelog link as final line
 
 If verification disagrees with the sub-agent's report, that's the signal to re-spawn with the actual state and the unmet goal in the prompt — not to trust the report. The goal hasn't changed; only the path needs to.
 

package/skills/orchestrations/workflows/field-test-fix.md

@@ -137,7 +137,7 @@ Each sub-agent reads both `skills/git-wrapup/SKILL.md` and `skills/release-and-p
 4. Release commit on top — version bump + changelog + regenerated artifacts as `chore(release): v<version>`
 5. Tag the release commit
 
-The tag annotation and changelog cover ALL fixes — the commit split is about git history, not release notes.
+The changelog carries the depth; the tag annotation covers every change at headline granularity — notable ones named, minor ones in one grouped bullet (per git-wrapup step 8). The commit split is about git history, not release notes.
 
 **Version bump.** Default **patch** for field-test fix releases. **Minor** when enhancements are bundled in.
 

package/skills/orchestrations/workflows/fix-wrapup-release.md

@@ -123,7 +123,7 @@ Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-p
 4. Release commit on top: `chore(release): v<version>` — version bump + changelog + regenerated artifacts
 5. Tag the release commit
 
-The tag annotation and changelog cover ALL fixes — the commit split is about git history, not release notes.
+The changelog carries the depth; the tag annotation covers every change at headline granularity — notable ones named, minor ones in one grouped bullet (per git-wrapup step 8). The commit split is about git history, not release notes.
 
 **Version bump.** Default **patch** for bug-fix releases. **Minor** when enhancements are included.
 
@@ -134,7 +134,7 @@ The tag annotation and changelog cover ALL fixes — the commit split is about g
 | Private / in-development | Version bump → changelog → commit → tag → mcpb bundle → push → `gh release create`. Skip `bun publish`, Docker, MCP Registry. |
 | Public / launched | Full `release-and-publish`: push + `bun publish` + `publish-mcp` + bundle + GH release + Docker (if Dockerfile). |
 
-**Tag annotations** are for end users — internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in commit bodies, not the tag annotation.
+**Tag annotations** are for end users — every changelog-worthy change stays visible in the tag, with minor/internal items (build config, repo hygiene, metadata) grouped into ONE compact bullet; only non-changelog churn (lockfile refreshes, lint fixes) stays in commit bodies alone.
 
 ### Phase 4: Issue cleanup
 Close issues that shipped — only those. Skipped issues stay open.

package/skills/orchestrations/workflows/maintenance-release.md

@@ -119,7 +119,7 @@ If a target's diff suggests minor-or-above, **pause that target and surface to t
 ### Phase 4: Wrap-up + release
 Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-publish/SKILL.md`. Runs wrap-up (version bump, changelog authoring, commit, annotated tag), then release (push, npm publish, MCP Registry, GH release, Docker).
 
-**Framework changelog reading.** When `mcp-ts-core` was updated, the sub-agent must read the framework's changelog files for the version delta (e.g. `node_modules/@cyanheads/mcp-ts-core/changelog/0.9.x/0.9.2.md` through `0.9.6.md`) and distill user-facing changes relevant to this server into the changelog entry and tag annotation. "Picks up upstream fixes" is not acceptable — name what changed.
+**Framework changelog reading.** When `mcp-ts-core` was updated, the sub-agent must read the framework's changelog files for the version delta (e.g. `node_modules/@cyanheads/mcp-ts-core/changelog/0.9.x/0.9.2.md` through `0.9.6.md`) and distill user-facing changes relevant to this server into the changelog entry; the tag annotation carries at most a one-line framework mention with the version arrow. "Picks up upstream fixes" is not acceptable in the changelog — name what changed.
 
 **Wrap-up scope.** Determined by repo visibility (`gh repo view --json visibility`):
 
@@ -135,7 +135,7 @@ Each sub-agent reads BOTH `skills/git-wrapup/SKILL.md` AND `skills/release-and-p
 
 **Commit structure.** Group the work by concern, then land the release artifacts (version bumps + changelog + regenerated `docs/tree.md`/`server.json`/`manifest.json`) as a `chore(release): <version> — <theme>` commit on top — same model as `git-wrapup` Step 7. A single-concern pass (just dep updates, or one framework adoption) is one work commit plus the release commit; a pass spanning multiple distinct concerns splits into per-concern work commits with the release commit last. Regenerated meta-drift is release-artifact-shaped — it rides in the release commit, never carved out as its own.
 
-**Tag annotations are for end users.** Internal dev cleanup (lockfile refreshes, linter fixes, build config) belongs in the commit body, not the tag annotation.
+**Tag annotations are for end users.** Every changelog-worthy change stays visible in the tag, with minor/internal items (build config, repo hygiene, metadata) grouped into ONE compact bullet; only non-changelog churn (lockfile refreshes, lint fixes) stays in commit bodies alone.
 
 **Tag-moving protocol.** If post-version doc changes land after the version commit, move the tag to HEAD: delete remote release, delete remote + local tag, recreate tag at new HEAD with same annotation, re-push, recreate release with `.mcpb`. Authorized within the workflow — same-day forward move.
 

package/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, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit, annotated tag) is already complete — this skill is the post-wrapup 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.10"
+  version: "2.11"
   audience: external
   type: workflow
 ---
@@ -202,7 +202,7 @@ Confirm each published artifact is actually live — don't rely on a successful
 - **npm**: `npm view <package.json#name>@<version> version` — must return the version string
 - **MCP Registry**: `curl -s "https://registry.modelcontextprotocol.io/v0.1/servers/<mcpName>/versions/<version>"` — must return HTTP 200 with `server.version` matching `<version>` (`mcpName` is the `name` field from `server.json`; URL-encode `/` as `%2F`). The search endpoint (`/v0.1/servers?search=`) paginates and may not include the latest version for packages with many releases — always use the direct version lookup.
 - **GitHub Release**: `gh release view v<VERSION> -R <OWNER>/<REPO> --json assets --jq '.assets[].name'` — must list the `.mcpb` file
-- **GHCR**: fetch an anonymous bearer token, then `curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $TOKEN" "https://ghcr.io/v2/<OWNER>/<REPO>/manifests/<VERSION>"` — must return HTTP 200
+- **GHCR**: `docker manifest inspect ghcr.io/<OWNER>/<REPO>:<VERSION>` — must exit 0 (resolves multi-arch OCI indexes directly with the correct media types; exits non-zero when the tag is genuinely absent)
 
 If any check fails, halt and report which destination is unreachable. A successful `docker push` or `bun publish` exit code does not guarantee the artifact is queryable — registry propagation delays, auth scoping, and partial failures all exist.
 

package/skills/techniques/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Catalog of reusable response- and data-shaping techniques for MCP servers built on `@cyanheads/mcp-ts-core` — overflow handling, payload shaping, retrieval patterns. Use when a tool's payload is too large, awkwardly shaped, or expensive to retrieve and you want a proven pattern instead of inventing one. Each technique has a self-contained reference under `references/`.
 metadata:
   author: cyanheads
-  version: "0.1"
+  version: "0.2"
   audience: external
   type: reference
 ---
@@ -13,7 +13,7 @@ metadata:
 
 A directory of cross-cutting techniques for shaping what a handler returns and how a client retrieves it — patterns that don't belong to a single API surface. Each entry is a self-contained reference under `references/`: the problem it solves, when to reach for it (and when not to), and how to apply it with current framework primitives.
 
-These are **patterns, not new primitives** — they compose `tool()`, discriminated-union `output`, `ctx.state`, and the existing helpers. Where a technique has (or will have) a dedicated helper, its reference says so and links the tracking issue.
+These are **patterns, not new primitives** — they compose `tool()`, `output`/`format()` shaping, `ctx.state`, and the existing helpers. Where a technique has (or will have) a dedicated helper, its reference says so and links the tracking issue.
 
 ## Techniques
 

package/skills/techniques/references/outline-on-overflow.md

@@ -20,9 +20,9 @@ This is distinct from the other two overflow shapes:
 
 **Never truncate to fit a budget.** When a payload is too big, return a complete, honest outline of what's available plus how to retrieve it — identically on `content[]` and `structuredContent`.
 
-## The shape — a discriminated-union `output`
+## The shape — a flat `output` with a `kind` discriminator
 
-The outline is the payload the agent acts on, so it lands in the **main body** (`structuredContent` + `content[]`), as a variant of the tool's own `output`. Not the enrichment block — enrichment is *additive* (`output.extend(...)` merged after `output.parse(result)`), so it can add fields to the fat document but never replace it. Not a post-hoc framework swap either — that would emit a `structuredContent` shape the advertised `outputSchema` (`tools/list`) doesn't describe. A discriminated-union variant is the only placement that replaces the payload, is advertised honestly, and gets `format()`-parity for free.
+The outline is the payload the agent acts on, so it lands in the **main body** (`structuredContent` + `content[]`), as a variant of the tool's own `output`. Not the enrichment block — enrichment is *additive* (`output.extend(...)` merged after `output.parse(result)`), so it can add fields to the fat document but never replace it. Not a post-hoc framework swap either — that would emit a `structuredContent` shape the advertised `outputSchema` (`tools/list`) doesn't describe. A single `output` object carrying both modes — a `kind` discriminator plus presence-based optional arms — is the placement that replaces the payload, is advertised honestly, and holds `format()`-parity. (`tool()` requires `output` to be a `ZodObject`: the `schema-is-object` lint rule and the enrichment `.extend()` are both object-only, so a `z.discriminatedUnion` output is rejected — model the two modes as optional arms of one object, not union branches.)
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
@@ -44,11 +44,17 @@ export const getLabel = tool('get_label', {
       .optional()
       .describe('Sections to return. Omit for the full label (or an outline if it overflows).'),
   }),
-  output: z.discriminatedUnion('kind', [
-    FullLabel.extend({ kind: z.literal('full') }),
-    OUTLINE_VARIANT,
-  ]),
-  format: (r) => (r.kind === 'outline' ? formatOutline(r) : renderLabel(r)),
+  output: z.object({
+    kind: z.enum(['full', 'outline']),
+    ...FullLabel.partial().shape,                         // full arm — every field optional
+    sections: OUTLINE_VARIANT.shape.sections.optional(),  // outline arm
+    notice: OUTLINE_VARIANT.shape.notice.optional(),
+  }),
+  // Render each arm on field presence, independently — never branch on `kind` (see below).
+  format: (r) => [
+    ...(r.id ? renderLabel(r) : []),  // full arm — key on a full-only field
+    ...(r.sections ? formatOutline({ kind: 'outline', sections: r.sections, notice: r.notice ?? '' }) : []),
+  ],
   async handler(input) {
     const doc = await fetchLabel(input.query); // deterministic from query
     if (input.sections?.length) {
@@ -60,7 +66,7 @@ export const getLabel = tool('get_label', {
 });
 ```
 
-`format()`-parity is enforced **per branch** — the linter walks each discriminated-union arm separately, so both `full` and `outline` must render. `formatOutline` is the shipped renderer for the `outline` arm; you supply the `full` renderer. That keeps the two client surfaces in lockstep with no extra work.
+`format()`-parity holds because every terminal field in `output` must appear in the rendered text. With a flat object the linter builds **one** synthetic sample with every optional field populated at once, so render each arm on field presence, independently — a mutually-exclusive `if (kind === 'outline') … else …` renders only one arm against that all-fields sample and fails parity for the other. `formatOutline` is the shipped renderer for the `outline` arm; you supply the `full` renderer. That keeps the two client surfaces in lockstep.
 
 ## The helper
 
@@ -69,7 +75,7 @@ export const getLabel = tool('get_label', {
 | Export | Purpose |
 |:--|:--|
 | `outlineOnOverflow(doc, options?)` | Returns `{ kind: 'full', ...doc }` under budget (or with `< 2` sections), else `{ kind: 'outline', sections, notice }`. |
-| `OUTLINE_VARIANT` | The reusable `outline`-arm Zod schema for your discriminated-union `output`. |
+| `OUTLINE_VARIANT` | The reusable `outline`-arm Zod schema; fold `.shape.sections` / `.shape.notice` into your flat `output` object as optional arms. |
 | `selectSections(doc, want, { alwaysKeep })` | Projects the document to requested keys plus always-kept metadata. The selection-path counterpart. |
 | `formatOutline(outline)` | Renders the outline to `content[]` for `format()`. |
 | `DEFAULT_OUTLINE_BUDGET_BYTES` | The default budget (`24_000`) when `options.budget` is omitted. |

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

@@ -1,10 +1,10 @@
 ---
 name: tool-defs-analysis
 description: >
-  Read-only audit of MCP definition language across an existing surface — tools, resources, prompts. Walks every definition file and checks 12 categories the LLM reads to decide whether and how to call: voice & tense, internal leaks, audience leaks, defaults, recovery hints, output descriptions, cross-references, sparsity, examples, structure, mutator observability, unit-bearing numeric names. 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).
+  Read-only audit of MCP definition language across an existing surface — tools, resources, prompts, server instructions. Walks every definition file and checks 15 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 — 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.3"
+  version: "1.4"
   audience: external
   type: audit
 ---
@@ -22,7 +22,7 @@ This skill is the **review-time pass** for that drift. Read each definition the
 | `security-pass` | Injection, scopes, input sinks |
 | `tool-defs-analysis` (this) | LLM-facing language across the existing surface |
 
-`field-test` already audits descriptions for implementation leaks, meta-coaching, and consumer-aware phrasing during its catalog step — that's a fast shallow pass alongside live tool calls. This skill is the deeper review: 12 categories, every field, every recovery hint, every default value, with file:line citations.
+`field-test` already audits descriptions for implementation leaks, meta-coaching, and consumer-aware phrasing during its catalog step — that's a fast shallow pass alongside live tool calls. This skill is the deeper review: 15 categories, every field, every recovery hint, every default value, with file:line citations — plus a cross-surface pass for the drift no single file shows.
 
 **Read-only.** This skill produces a report; the maintainer applies fixes. While running it, do not run git, do not stage or commit, do not update the changelog, do not run `devcheck`, do not invoke wrapup or release workflows. Fixes flow through the normal authoring path (edit the definition, then re-run this skill if you want to verify).
 
@@ -53,11 +53,11 @@ find src/mcp-server/resources/definitions -type f -name "*resource.ts" 2>/dev/nu
 find src/mcp-server/prompts/definitions   -type f -name "*.prompt.ts"  2>/dev/null | sort
 ```
 
-The `*tool.ts` / `*resource.ts` patterns also catch `*.app-tool.ts` / `*.app-resource.ts`. If the server's definitions live elsewhere (`examples/`, a packages workspace, …), audit those paths too.
+The `*tool.ts` / `*resource.ts` patterns also catch `*.app-tool.ts` / `*.app-resource.ts`. If the server's definitions live elsewhere (`examples/`, a packages workspace, …), audit those paths too. Also locate the server-level `instructions` string if the server sets one (the `createApp` option — `grep -rn "instructions" src/ --include="*.ts"`); it's audited in the cross-surface pass.
 
 Use `TaskCreate` — one task per file. Mark each complete after its findings are captured.
 
-### 2. Walk the 12 categories per file
+### 2. Walk the 15 categories per file
 
 Read each definition file in full. Apply every category — most files trip more than one. Capture each hit with `file:line`, the offending excerpt, and a one-line fix.
 
@@ -79,8 +79,6 @@ Read each definition file in full. Apply every category — most files trip more
 
 **Smell:** "/api/v2/by-state", "Adds a second API call", "API requires `two_year_period`", "(deprecated; use bar_v2)", "TODO: support batch mode", "Used internally by FooService".
 
-Prior art: #25.
-
 #### 3. Audience leaks
 
 **Look in:** every `description` and `.describe()`.
@@ -89,7 +87,7 @@ Prior art: #25.
 
 **Smell:** "suitable for LLM consumption", "Treat the returned ID as the canonical Y", "Agents should…", "Callers should…", "When you call this tool…", any reference to "LLM", "agent", "Claude", "the model".
 
-Prior art: #74. Field-test catches this in its leak audit; this skill is the more thorough pass.
+Field-test catches this in its leak audit; this skill is the more thorough pass.
 
 #### 4. Defaults
 
@@ -107,19 +105,21 @@ Prior art: #74. Field-test catches this in its leak audit; this skill is the mor
 
 **Smell:** "Check the logs", "See documentation", "Contact admin", "Try again later" (with no condition), generic non-actionable text, hints that name internal classes or files.
 
-#### 6. Output descriptions
+#### 6. Field descriptions
 
-**Look in:** every field `.describe()` inside `output: z.object({ ... })`.
+**Look in:** every field in `input` and `output` schemas; resource URI template variables.
 
-**Check:** the description tells the agent what the *value* is — not just the field name restated, not silent on dynamic shapes.
+**Check:** every field carries a `.describe()`, and it tells the agent what the *value* is — not just the field name restated, not silent on dynamic shapes. Enum variants — especially operation discriminators — are explained.
 
 **Smell:**
 
+- An input field with no `.describe()` at all
 - `name: z.string().describe('Name')` — tautology
-- `description: z.string().describe('Description.')` — tautology
+- `operation: z.enum([...])` whose variants are never explained
 - `metadata: z.record(z.string(), z.unknown()).describe('Metadata')` — opaque dynamic shape with no hint about keys/values
 - Optional fields with no note on when they're absent
-- Enum fields with no `.describe()` on the variants
+- Paging fields (`total`, `hasMore`, `nextCursor`) with semantics unstated — or a `limit` param that doesn't say whether it caps the page or the whole result
+- A URI template variable (`{cid}`) never described anywhere
 
 #### 7. Cross-references
 
@@ -157,8 +157,6 @@ Prior art: #74. Field-test catches this in its leak audit; this skill is the mor
 
 **Smell:** blank lines (`\n\n`) inside a description string, `- bullet` lines, `## Header` lines, "Operations:\n- foo: …" duplicating an enum's `.describe()` text.
 
-Prior art: #33.
-
 #### 11. Mutator observability
 
 **Look in:** mutator tools — any tool that writes, updates, deletes, appends, or patches (i.e., definitions without `annotations.readOnlyHint: true`).
@@ -171,11 +169,51 @@ Prior art: #33.
 
 **Look in:** every `z.number()` field in `output` schemas.
 
-**Check:** the field name carries a unit when not pinned by context — `sizeInBytes`, `durationInMs`, `priceInCents`, `latencyInMs`. The `.describe()` drops in summarization or gets truncated; the field name persists into the JSON the agent reads.
+**Check:** the field name carries a unit when not pinned by context — `sizeInBytes`, `durationInMs`, `priceInCents`, `latencyInMs`. The `.describe()` drops in summarization or gets truncated; the field name persists into the JSON the agent reads. Scores, ratios, and percentages carry their range the same way — in the name or as the first thing in the describe (`0–1`).
+
+**Smell:** `size`, `duration`, `price`, `latency` — bare names that force the agent to guess units; `score`/`confidence` with no stated range (0.87 and 87 both pass the schema). Exempt: `index`, `position`, `page`, `offset`, `limit`, `totalCount`, `itemCount` (dimensionless).
+
+#### 13. Constraints in validators
+
+**Look in:** input schemas — every field whose `.describe()` states a format, range, length, or pattern.
+
+**Check:** stated constraints are machine-enforced in the schema (`.regex()`, `.min()`/`.max()`, `.int()`, `.length()`, an enum) so they emit into the JSON Schema the client renders — a constraint living only in prose reaches a weaker model unreliably and burns retries on malformed input. Opaque-ID params also say how to *obtain* the value (which sibling tool returns it), not just its shape.
+
+**Smell:** `.describe('Date in YYYY-MM-DD format')` on a bare `z.string()`; "max 100" in prose with no `.max(100)`; an ID param whose describe gives the format but never the tool that produces it.
+
+#### 14. Annotations truthfulness
+
+**Look in:** the `annotations` block on every tool.
+
+**Check:** hints match what the handler actually does — clients gate confirmation prompts and retry policy on them. A purely-read tool carries `readOnlyHint: true`; deletes and overwrites aren't marked `destructiveHint: false`; retry-safe mutators carry `idempotentHint: true`; tools calling external services carry `openWorldHint: true`. If `annotations.title` is set, it still matches the tool's current name and behavior.
+
+**Smell:** `readOnlyHint: true` on anything that writes; a read-only tool with no `readOnlyHint` (clients assume it can mutate); `destructiveHint: false` on a delete; a stale `title` surviving a rename.
 
-**Smell:** `size`, `duration`, `price`, `latency` — bare names that force the agent to guess units or rely on description text. Exempt: `index`, `position`, `totalCount`, `itemCount` (dimensionless).
+#### 15. Single-line strings
 
-### 3. Report
+**Look in:** every `description`, `.describe()`, and error `recovery` / `when` string in a definition file.
+
+**Check:** each is a single-line string literal. NEVER split one across lines with `+` concatenation (`'part one ' + 'part two'`), and never line-wrap a description into a `\n`-bearing template literal. The formatter does not break string literals, so a long single-line string passes formatting untouched — the line-width limit is not a reason to concatenate.
+
+**Why it's not cosmetic:** `+`-concatenation forces every fragment to hand-carry its boundary whitespace, and a dropped trailing space silently fuses two words in the rendered schema the model reads (`'…table_name. ' + 'Columns…'` renders as `table_name.Columns`). Correct output is byte-identical to the single-line form, so the concatenation buys nothing and adds a class of silent contract corruption.
+
+**Smell:** a string literal ending in `' +` or `" +` at end of line; a `description:` value spanning multiple quoted fragments; a multi-line template literal inside a description (also a Structure finding, #10).
+
+**Fix:** collapse to one single-line string literal.
+
+### 3. Cross-surface pass
+
+The per-file walk misses drift that only shows between files. After it, sweep the whole surface:
+
+- **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.
+- **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).
+
+### 4. Report
 
 Three sections.
 
@@ -194,6 +232,8 @@ Issue: <one line: what's wrong>
 Fix: <one line: what to change to>
 ```
 
+Excerpts are verbatim copy-paste from the file as read, line numbers from that read — re-verify any finding written from memory before it enters the report.
+
 Two-level severity:
 
 - **material** — affects agent decisions (will mis-select tool, mis-fill input, mis-handle output, swallow an irrecoverable error)
@@ -219,10 +259,11 @@ End with:
 
 - [ ] Scope confirmed (whole server / module / specific files)
 - [ ] Severity floor applied — nits suppressed if user requested
-- [ ] Inventory built — every `*.tool.ts`, `*.app-tool.ts`, `*.resource.ts`, `*.app-resource.ts`, `*.prompt.ts` listed
-- [ ] Each file walked through all 12 categories (per-file, not 12 separate passes)
+- [ ] Inventory built — every `*.tool.ts`, `*.app-tool.ts`, `*.resource.ts`, `*.app-resource.ts`, `*.prompt.ts` listed; server `instructions` located if set
+- [ ] Each file walked through all 15 categories (per-file, not 15 separate passes)
+- [ ] Cross-surface pass run — naming taxonomy, parameter vocabulary, tool overlap, instructions drift, length outliers
 - [ ] **Read-only:** no git, no commits, no changelog edits, no `devcheck`, no wrapup invoked during the audit
-- [ ] Findings carry file:line citation, excerpt, issue, fix
+- [ ] Findings carry file:line citation, excerpt, issue, fix — excerpts verbatim, line numbers verified
 - [ ] Report: summary → grouped-by-category findings → numbered options
-- [ ] Options section produced — numbered, one-per-file, severity tagged, cherry-pickable
+- [ ] Options section produced — numbered, each single-file-scoped, severity tagged, cherry-pickable
 - [ ] If no findings: summary states "no findings"; Findings and Options sections omitted

package/templates/Dockerfile

@@ -14,7 +14,7 @@ COPY package.json bun.lock ./
 # Install all dependencies (including dev dependencies for building).
 # The BuildKit cache mount persists Bun's global package cache across builds.
 RUN --mount=type=cache,target=/root/.bun/install/cache \
-    bun install --frozen-lockfile
+    bun install --frozen-lockfile --ignore-scripts
 
 # Copy the rest of the source code
 COPY . .

package/templates/package.json

@@ -64,9 +64,9 @@
     "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.2",
+    "@biomejs/biome": "2.5.4",
     "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@types/node": "26.1.0",
+    "@types/node": "26.1.1",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",
     "tsc-alias": "^1.9.0",