@cyanheads/mcp-ts-core 0.13.7 → 0.13.8

package/framework-skills/api-utils/references/security.md

@@ -21,7 +21,7 @@ Pre-constructed singleton of `Sanitization`. Tier 3 peer: `sanitize-html` (HTML
 | `sanitizePath` | **no** | Node.js only | `(input, options?) -> SanitizedPathInfo` |
 | `sanitizeJson` | **no** | none | `<T>(input, maxSize?) -> T` |
 | `sanitizeForLogging` | **no** | none | `(input) -> unknown` |
-| `redactSensitiveFields` | **no** | none | `(data, fields?, ctx?) -> unknown` |
+| `serializeForLogging` | **no** | none | `(value, maxBytes) -> { text: string; truncated: boolean }` |
 | `getSensitivePinoFields` | **no** | none | `() -> string[]` |
 
 ### Option types
@@ -65,6 +65,8 @@ interface SanitizedPathInfo {
 - `sanitizeJson`: `maxSize` is bytes (UTF-8); uses `Buffer.byteLength` / `TextEncoder` / `string.length` fallback chain
 - `sanitizeNumber`: `NaN`/`Infinity` always rejected; out-of-range values silently clamped with debug log
 - `sanitizeForLogging`: deep clones via `structuredClone`; returns `'[Log Sanitization Failed]'` on clone error
+- **Rejection reasons.** Every `ValidationError` carries `data.reason`, and a `data.recovery.hint` wherever the caller can change the input: `invalid_url` (`sanitizeUrl`; the hint names the allowed schemes), `invalid_path` / `path_traversal` / `absolute_path_disallowed` (`sanitizePath`), `invalid_json` / `json_too_large` (`sanitizeJson`; the latter names the byte cap), `invalid_number` (`sanitizeNumber`), and `unsupported_sanitize_context` (`sanitizeString`'s `'javascript'` context, which has no hint — it is a server-code choice)
+- `serializeForLogging`: `sanitizeForLogging`, then `JSON.stringify`, then a cut to at most `maxBytes` UTF-8 bytes on a character boundary — redaction first, so a cut never keeps part of a secret. A truncated `text` is a prefix of the whole serialization and no longer valid JSON; `truncated` says so. Returns a string so a deep payload survives the logger's four-level field depth. A value `JSON.stringify` rejects (a `bigint`) yields `'[Log Serialization Failed]'`. Backs the failed-call payload record (`LOG_TOOL_FAILURE_PAYLOADS`)
 
 ### Sensitive fields
 
@@ -191,10 +193,10 @@ interface IdGenerationOptions {
 | Method | Signature | Notes |
 |:-------|:----------|:------|
 | `generate` | `(prefix?, options?) -> string` | `PREFIX_XXXXXX` or just `XXXXXX` if no prefix |
-| `generateForEntity` | `(entityType, options?) -> string` | Uses registered prefix; throws `McpError(ValidationError)` if type unknown |
-| `generateRandomString` | `(length?, charset?) -> string` | Raw random string; defaults: length 6, charset `A-Z0-9` |
+| `generateForEntity` | `(entityType, options?) -> string` | Uses registered prefix; throws `McpError(ValidationError)` with `data.reason: 'unknown_entity_type'` if type unknown |
+| `generateRandomString` | `(length?, charset?) -> string` | Raw random string; defaults: length 6, charset `A-Z0-9`. A charset outside 1–256 characters throws `ValidationError` with `data.reason: 'invalid_charset'` |
 | `isValid` | `(id, entityType, options?) -> boolean` | Regex-validates format against prefix + separator + charset{length} |
-| `getEntityType` | `(id, separator?) -> string` | Resolves entity type from prefix; throws `McpError(ValidationError)` if unknown |
+| `getEntityType` | `(id, separator?) -> string` | Resolves entity type from prefix; throws `McpError(ValidationError)` — `data.reason: 'invalid_id_format'` when the ID has no `PREFIX<sep>` part, `'unknown_entity_type'` when the prefix is unregistered, each with a `recovery.hint` (the latter lists the registered prefixes) |
 | `normalize` | `(id, separator?) -> string` | Canonical prefix casing + uppercase random part |
 | `stripPrefix` | `(id, separator?) -> string` | Returns random part; returns original if separator not found |
 | `setEntityPrefixes` | `(config) -> void` | Replaces all prefixes and rebuilds reverse lookup |

package/framework-skills/git-wrapup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Land working-tree changes as logical commits — the work grouped by concern, topped by a release commit (version bump, changelog, regenerated artifacts). The work commits land first, then the version bump, verification, and the release commit on top. Stops at "committed locally on main" — or, when the project releases through a release PR, at "release branch pushed, PR open". No tag, no push to main, no publish: the release-and-publish skill merges, tags, and ships from here. Distilled from the git_wrapup_instructions protocol.
 metadata:
   author: cyanheads
-  version: "1.25"
+  version: "1.26"
   audience: external
   type: workflow
 ---
@@ -105,7 +105,9 @@ git commit --only <paths-for-this-concern> -m "<subject>" -m "<body>"
 
 **The file is the atomic boundary:** NEVER split a single file's working-tree changes across commits, regardless of mechanism — not `git add -p`, not an index-only patch (`git apply --cached`), not editing the file between commits to remove-then-re-add a hunk. When one file serves two concerns, it ships whole in the commit of its dominant concern; a later commit may touch the file again only for changes made AFTER the first commit (the version bump applied in step 4).
 
-**Every commit builds on its own.** When a concern changes an exported contract — a service method's return type, a shared helper's signature — the files that consume it ride in the same commit, even when they also carry other concerns. Grouping the contract change into one commit and each consumer into its own later commit leaves pushed commits that fail typecheck alone, and pushed history is never rewritten to repair them.
+**Every commit builds and passes its tests on its own.** When a concern changes an exported contract — a service method's return type, a shared helper's signature, a renamed export, a changed query or behavior a consumer's tests assert — the files that consume it AND their tests ride in the same commit, even when they also carry other concerns. Grouping the contract change into one commit and each consumer into its own later commit leaves pushed commits that fail typecheck or the suite alone, and pushed history is never rewritten to repair them. A snapshot can typecheck and still be red: before pushing, check out each work commit's tree (`git stash` is not the tool — extract it with `git archive <sha> | tar -x -C <scratch>`, symlink the project's `node_modules` into it) and run the test script there; merge groups whose snapshot fails.
+
+**A dependency bump lands before the commits that use it.** When any later commit in the stack uses something the new versions introduce — a new framework export, a new `tool()` option, a changed signature — `chore(deps)` is the first work commit. It builds on its own: `package.json`, the lockfile, and any source change the upgrade itself forces (a renamed import, a removed option) ride in it, so the commits above it compile against the versions they were written for. Ordered the other way, the adopting commit and every commit up to the bump fail typecheck at their own SHA.
 
 **Subject format:** Conventional Commits, no version in the subject — `feat: hosted server endpoint`, `fix: handle empty SPARQL result sets`, `feat(linter): enrichment contract rules`, `docs: document the enrichment block`, `chore(deps): refresh dev dependencies`.
 
@@ -307,6 +309,7 @@ If the working tree isn't clean or the release commit isn't at HEAD, something w
 - [ ] `bun run test:package` passes, when the project defines it — it guards the public-export manifest and `test:all` does not run it
 - [ ] Release PR mode: stack committed on `release/<version>`, never on `main`
 - [ ] Work grouped into logical commits (large features split by layer); release artifacts (version + changelog + tree) committed separately on top, subject leading with the version
+- [ ] `chore(deps)` is the first work commit whenever a later commit uses what the new versions introduce, and it builds on its own — carrying `package.json`, the lockfile, and any source change the upgrade forces
 - [ ] A gate failure after the work is committed landed as a new commit on the stack — nothing amended, rebased, or otherwise rewritten
 - [ ] Every commit carries a body, and every body is one or two lines — none subject-only, none a paragraph
 - [ ] Release PR mode: branch pushed, PR open — title = release commit subject; body = theme line, `## Changes` in tag rules, `## Gates`, changelog link last (via `--body-file`, no closing keywords)

package/framework-skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "2.9"
+  version: "2.10"
   audience: external
   type: workflow
 ---
@@ -177,7 +177,7 @@ The consumer opted into the framework; its templates, skills, scripts, linter ru
 - **Deprecations** — migrate now, while context is fresh.
 - **New linter rules** — if the rule now flags existing code, fix the code; don't silence the rule.
 - **New utilities that supersede local code** — swap them in. The point of the framework is to centralize. This applies even when the local helper has richer messages or branch handling — port the domain detail onto the framework path; don't leave the local helper as-is. (E.g., `httpErrorFromResponse` replacing a project-local `throwForStatus`: keep the per-route message map, but route it through the framework utility.)
-- **New conventions** (template changes, new config keys, renamed env vars) — adopt and update `.env.example`, server config schema, `server.json`, and README if user-facing.
+- **New conventions** (template changes, new config keys, renamed env vars) — adopt and update `.env.example`, server config schema, `server.json`, and README if user-facing. A new Bun pin (the template's `packageManager`) moves three places together: `package.json` `packageManager`, the Dockerfile `oven/bun` base tags, and the README Bun badge.
 - **New patterns that match existing surfaces** — refactor *every* matching site in this pass. Examples: typed error contracts (`errors[]` + `ctx.fail`) on tools that already throw domain-specific failures; factory adoption (`notFound()`, `validationError()`, …) replacing ad-hoc `new McpError(...)`; new logging/observability hooks supplanting bespoke logging. If the framework added a pattern that fits N tools/services, do all N — partial adoption fragments the surface and rots faster.
 - **New framework features that don't match existing use cases** — skip. These are for future features, not retroactive refactors. "Don't match" means *the surface doesn't exist in this server* (e.g., a new Speech API in a non-speech server) — not "I'd have to touch a few files."
 

package/framework-skills/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.18"
+  version: "2.19"
   audience: external
   type: workflow
 ---

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

@@ -390,6 +390,7 @@ Table of environment variables. Include framework vars only if the server uses n
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
+| `LOG_TOOL_FAILURE_PAYLOADS` | Log each failed tool call's arguments and result, redacted by key name and capped at `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` (default `16384`). A secret inside a free-form value is not redacted. | `false` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
 | `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |
 

package/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.20"
+  version: "2.21"
   audience: external
   type: workflow
 ---
@@ -175,7 +175,7 @@ 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.
+A `dist/*.mcpb` already built for step 8 stays out of the tarball: the `files` allowlist carries `"!dist/*.mcpb"`, and `lint:packaging` fails a project with `manifest.json` that lacks it.
 
 ```bash
 bun publish --access public

package/framework-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.3"
+  version: "0.4"
   audience: external
   type: reference
 ---

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

@@ -45,9 +45,12 @@ export const getLabel = tool('get_label', {
       .describe('Sections to return. Omit for the full label (or an outline if it overflows).'),
   }),
   output: z.object({
-    kind: z.enum(['full', 'outline']),
+    kind: z.enum(['full', 'outline']).describe('Whether the full label or a section outline was returned'),
     ...FullLabel.partial().shape,                         // full arm — every field optional
-    sections: OUTLINE_VARIANT.shape.sections.optional(),  // outline arm
+    sections: z                                           // outline arm
+      .array(OUTLINE_VARIANT.shape.sections.element.describe('One section of the label'))
+      .optional()
+      .describe('Available sections, largest first'),
     notice: OUTLINE_VARIANT.shape.notice.optional(),
   }),
   // Render each arm on field presence, independently — never branch on `kind` (see below).
@@ -66,6 +69,8 @@ export const getLabel = tool('get_label', {
 });
 ```
 
+The shape lints clean as written. The section item is described in place (`.element.describe(…)`, then the array re-described) because `describe-on-fields` asks every array-of-object element for a description and `OUTLINE_VARIANT`'s item carries none; folding `OUTLINE_VARIANT.shape.sections` in directly warns on `output.sections[]`. The `notice` beside a `sections` array is exempt from `enrichment-prefer-block` — it is the re-call instruction, main-body payload by design.
+
 `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
@@ -75,9 +80,9 @@ 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; 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()`. |
+| `OUTLINE_VARIANT` | The reusable `outline`-arm Zod schema; fold `.shape.sections` (item described in place, as above) / `.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. A requested name that is not a key of `doc` throws `InvalidParams`; the message names the unmatched names and the available keys, and `data` carries both (`unmatched`, `available`). An `alwaysKeep` key absent from `doc` is ignored. |
+| `formatOutline(outline)` | Renders the outline to `content[]` for `format()`. Each section name is a code span sized past any backtick in it, so the name reads back exactly as the caller must pass it in `sections`. |
 | `DEFAULT_OUTLINE_BUDGET_BYTES` | The default budget (`24_000`) when `options.budget` is omitted. |
 
 `outlineOnOverflow` options:
@@ -93,14 +98,14 @@ The flow:
 3. **Over budget, ≥ 2 sections** → the outline (sections sorted largest-first). The agent re-calls with `sections: [...]`.
 4. **Over budget, < 2 sections** → `full` anyway (nothing to pick between). A single section that *alone* exceeds budget is a known limitation — sub-section outlining is out of scope.
 
-The budget bounds the **disclosure**, not the selection. `selectSections` returns whatever the agent named, so a selection over several sections — or one section larger than the budget — comes back whole. That is deliberate: the agent asked for those sections by name, and truncating the answer is the thing this technique exists to avoid. The default notice reports each example's size so the selection can be sized before it is made.
+The budget bounds the **disclosure**, not the selection. `selectSections` returns whatever the agent named, so a selection over several sections — or one section larger than the budget — comes back whole. That is deliberate: the agent asked for those sections by name, and truncating the answer is the thing this technique exists to avoid. The default notice reports each example's size so the selection can be sized before it is made. The selection is not lenient about names, though: a name the document does not carry is rejected with the valid names, not dropped, so a stale or mistyped section never comes back as a quietly smaller answer.
 
 ## Re-retrieval — why the selection call is stateless
 
 The re-call is **self-contained**, so nothing is stored between the outline call and the selection call:
 
 - The selection call sends the **same input** as the outline call, plus `sections: [...]`.
-- The handler **re-fetches** the document — input-minus-`sections` is identical and the upstream query is deterministic, so it reproduces the exact same record — then applies `selectSections` (a pure projection: requested keys + `alwaysKeep` metadata).
+- The handler **re-fetches** the document — input-minus-`sections` is identical and the upstream query is deterministic, so it reproduces the exact same record — then applies `selectSections` (a pure projection: requested keys + `alwaysKeep` metadata; an unknown requested name throws `InvalidParams` naming the available keys).
 - You **reconstruct rather than remember**. The agent holds the continuity (it passes `sections`); the upstream holds the document.
 
 The only cost is the redundant fetch. For a **rate-limited or expensive upstream**, trade it for an optional cache:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.7",
+  "version": "0.13.8",
   "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": [
@@ -202,17 +202,20 @@
     "@duckdb/node-api": "^1.5.5-r.5",
     "@hono/otel": "^1.1.2",
     "@modelcontextprotocol/client": "^2.0.0",
+    "@opentelemetry/api-logs": "^0.222.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
     "@opentelemetry/instrumentation-http": "^0.222.0",
     "@opentelemetry/instrumentation-pino": "^0.68.0",
     "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.11.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
-    "@supabase/supabase-js": "^2.117.0",
+    "@supabase/supabase-js": "^2.117.1",
     "@types/bun": "^1.4.2",
     "@types/node": "26.6.2",
     "@types/papaparse": "^5.5.2",
@@ -232,7 +235,7 @@
     "js-yaml": "^5.4.2",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
-    "openai": "^7.21.0",
+    "openai": "^7.23.0",
     "papaparse": "^5.7.0",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
@@ -297,11 +300,14 @@
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",
     "@hono/otel": "^1.1.2",
+    "@opentelemetry/api-logs": "^0.222.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
     "@opentelemetry/instrumentation-http": "^0.222.0",
     "@opentelemetry/instrumentation-pino": "^0.68.0",
     "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.10.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "@opentelemetry/sdk-trace-node": "^2.10.0",
@@ -332,6 +338,12 @@
     "@hono/otel": {
       "optional": true
     },
+    "@opentelemetry/api-logs": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-logs-otlp-http": {
+      "optional": true
+    },
     "@opentelemetry/instrumentation-http": {
       "optional": true
     },
@@ -347,6 +359,9 @@
     "@opentelemetry/resources": {
       "optional": true
     },
+    "@opentelemetry/sdk-logs": {
+      "optional": true
+    },
     "@opentelemetry/sdk-metrics": {
       "optional": true
     },

package/scripts/check-skill-versions.ts

@@ -20,10 +20,19 @@
  *
  * A bare name (`add-tool`) and the file path (`add-tool/SKILL.md`) both match.
  *
- * Diffing against `HEAD` keeps the per-release-cycle carve-out automatic: once the
- * version line is bumped, later commits in the same cycle no longer re-trigger.
+ * In the framework repo, a skill whose version already moved since the last `v*`
+ * release tag — or that is new since it — is covered: a later body edit in the
+ * same cycle shares that bump instead of needing another.
+ *
+ * The inverse also holds: a skill moves at most one step per release. In the
+ * framework repo itself, each skill's version is compared with its version at the
+ * last `v*` release tag, and anything past the next minor (`1.4` → `1.5`) or the
+ * next major (`1.4` → `2.0`) is a violation — repeated edits in one cycle share a
+ * single bump. Consumer repos skip this: a skill sync can legitimately jump
+ * several framework releases at once.
+ *
  * Severity mirrors `check-skills-sync.ts` — exits 1, demoted to a warning by
- * devcheck. New skills (no `HEAD` version) and non-git trees are skipped.
+ * devcheck. New skills (no prior version) and non-git trees are skipped.
  *
  * Runs standalone (`bun run scripts/check-skill-versions.ts`) and as a devcheck step.
  *
@@ -36,6 +45,7 @@ import process from 'node:process';
 
 const ROOT = resolve('.');
 const SKILL_MD_RE = /^framework-skills\/[^/]+\/SKILL\.md$/;
+const FRAMEWORK_PACKAGE = '@cyanheads/mcp-ts-core';
 
 interface DevcheckConfig {
   skillVersions?: { ignore?: string[] };
@@ -60,10 +70,10 @@ function isIgnored(relPath: string, patterns: string[]): boolean {
   );
 }
 
-/** Skill `SKILL.md` files that differ from `HEAD` (staged + unstaged). */
-function changedSkillFiles(): string[] {
-  const result = spawnSync('git', ['diff', '--name-only', 'HEAD', '--'], { encoding: 'utf-8' });
-  if (result.status !== 0) return []; // not a git repo / no HEAD commit
+/** Skill `SKILL.md` files that differ from `ref` in the working tree (staged + unstaged). */
+function changedSkillFiles(ref: string): string[] {
+  const result = spawnSync('git', ['diff', '--name-only', ref, '--'], { encoding: 'utf-8' });
+  if (result.status !== 0) return []; // not a git repo / no such ref
   return result.stdout
     .trim()
     .split('\n')
@@ -71,18 +81,50 @@ function changedSkillFiles(): string[] {
 }
 
 /**
- * Content of a path at `HEAD`, or null when it didn't exist there (new file).
- * A tree renamed from the pre-0.13 `skills/` reads its `HEAD` copy from the old
+ * Content of a path at `ref`, or null when it didn't exist there (new file).
+ * A tree renamed from the pre-0.13 `skills/` reads its old copy from the old
  * path, so the release that carries the rename still checks every body edit.
  */
-function headContent(relPath: string): string | null {
-  const show = (p: string) => spawnSync('git', ['show', `HEAD:${p}`], { encoding: 'utf-8' });
+function contentAt(ref: string, relPath: string): string | null {
+  const show = (p: string) => spawnSync('git', ['show', `${ref}:${p}`], { encoding: 'utf-8' });
   const result = show(relPath);
   if (result.status === 0) return result.stdout;
   const legacy = show(relPath.replace(/^framework-skills\//, 'skills/'));
   return legacy.status === 0 ? legacy.stdout : null;
 }
 
+/** True when this tree is the framework itself, where skill versions are authored. */
+function isFrameworkRepo(): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')) as {
+      name?: string;
+    };
+    return pkg.name === FRAMEWORK_PACKAGE;
+  } catch {
+    return false;
+  }
+}
+
+/** The latest `v*` release tag reachable from `HEAD`, or null when there is none. */
+function lastReleaseTag(): string | null {
+  const result = spawnSync('git', ['describe', '--tags', '--abbrev=0', '--match', 'v*'], {
+    encoding: 'utf-8',
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+/** True when `to` is `from`, its next minor, or its next major at `.0`. */
+function withinOneStep(from: string, to: string): boolean {
+  const [fromMajor, fromMinor] = from.split('.').map(Number);
+  const [toMajor, toMinor] = to.split('.').map(Number);
+  if ([fromMajor, fromMinor, toMajor, toMinor].some((n) => n === undefined || Number.isNaN(n))) {
+    return true; // not `X.Y` — out of this check's scope
+  }
+  if (from === to) return true;
+  if (toMajor === fromMajor) return toMinor === (fromMinor as number) + 1;
+  return toMajor === (fromMajor as number) + 1 && toMinor === 0;
+}
+
 /** `metadata.version` from skill frontmatter, or null when absent/unparseable. */
 function extractVersion(content: string): string | null {
   const block = content.match(/^---\n([\s\S]*?)\n---/)?.[1];
@@ -108,11 +150,24 @@ if (!existsSync(resolve(ROOT, 'framework-skills'))) {
 }
 
 const ignore = loadIgnorePatterns();
-const changed = changedSkillFiles().filter((f) => !isIgnored(f, ignore));
+const tag = isFrameworkRepo() ? lastReleaseTag() : null;
 
-const violations: { file: string; version: string }[] = [];
-for (const file of changed) {
-  const oldContent = headContent(file);
+/**
+ * True when the skill's current version already differs from its version at the
+ * release tag — or the skill is new since it — so this cycle's one step is taken
+ * and a further body edit shares it rather than needing another bump.
+ */
+function bumpedThisRelease(file: string, version: string | null): boolean {
+  if (tag === null) return false;
+  const released = contentAt(tag, file);
+  if (released === null) return true;
+  const releasedVersion = extractVersion(released);
+  return releasedVersion !== null && releasedVersion !== version;
+}
+
+const missing: { file: string; version: string }[] = [];
+for (const file of changedSkillFiles('HEAD').filter((f) => !isIgnored(f, ignore))) {
+  const oldContent = contentAt('HEAD', file);
   if (oldContent === null) continue; // new skill — no prior version to compare
   if (!existsSync(resolve(ROOT, file))) continue; // deleted in worktree — no body to compare, can't violate
   const newContent = readFileSync(resolve(ROOT, file), 'utf-8');
@@ -121,25 +176,51 @@ for (const file of changed) {
 
   const oldVersion = extractVersion(oldContent);
   const newVersion = extractVersion(newContent);
-  if (oldVersion !== null && oldVersion === newVersion) {
-    violations.push({ file, version: oldVersion });
+  if (oldVersion !== null && oldVersion === newVersion && !bumpedThisRelease(file, newVersion)) {
+    missing.push({ file, version: oldVersion });
   }
 }
 
-if (violations.length === 0) {
+const overshot: { file: string; tag: string; released: string; version: string }[] = [];
+if (tag !== null) {
+  for (const file of changedSkillFiles(tag)) {
+    const released = contentAt(tag, file);
+    if (released === null || !existsSync(resolve(ROOT, file))) continue;
+    const releasedVersion = extractVersion(released);
+    const version = extractVersion(readFileSync(resolve(ROOT, file), 'utf-8'));
+    if (releasedVersion === null || version === null) continue;
+    if (!withinOneStep(releasedVersion, version)) {
+      overshot.push({ file, tag, released: releasedVersion, version });
+    }
+  }
+}
+
+const count = missing.length + overshot.length;
+if (count === 0) {
   console.log('Skill versions are in step with body changes.');
   process.exit(0);
 }
 
 const lines = [
-  `${violations.length} skill${violations.length === 1 ? '' : 's'} changed body without a metadata.version bump:`,
+  `${count} skill${count === 1 ? '' : 's'} out of step with the versioning policy:`,
   '',
 ];
-for (const v of violations) {
+for (const v of missing) {
   lines.push(`  - ${v.file} body changed but metadata.version is still "${v.version}"`);
 }
+for (const v of overshot) {
+  lines.push(
+    `  - ${v.file} is "${v.version}", more than one step past "${v.released}" at ${v.tag}`,
+  );
+}
 lines.push('');
-lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
-lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+if (missing.length > 0) {
+  lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
+  lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+}
+if (overshot.length > 0) {
+  lines.push('Fix: set metadata.version to one step past the release tag — edits in one');
+  lines.push('     release cycle share a single bump.');
+}
 console.log(lines.join('\n'));
 process.exit(1);

package/scripts/devcheck.ts

@@ -811,7 +811,8 @@ const ALL_CHECKS: Check[] = [
     flag: '--no-skill-versions',
     canFix: false,
     // Flags framework-skills/<name>/SKILL.md body changes (vs HEAD) that lack a metadata.version
-    // bump (#99). Skipped when framework-skills/ is absent. Drift is demoted to a warning via
+    // bump (#99), and, in the framework repo, a skill bumped more than one step past the last
+    // release tag. Skipped when framework-skills/ is absent. Drift is demoted to a warning via
     // isSuccess — the typo/whitespace carve-out lives in devcheck.config.json
     // `skillVersions.ignore`.
     getCommand: () => {
@@ -821,11 +822,11 @@ const ALL_CHECKS: Check[] = [
     isSuccess: (result) => {
       if (result.exitCode === 0) return true;
       const firstLine =
-        result.stdout.split('\n')[0]?.trim() || 'Skill bodies changed without a version bump.';
+        result.stdout.split('\n')[0]?.trim() || 'Skill versions are out of step with the policy.';
       return { success: true, warning: firstLine };
     },
     tip: (c) =>
-      `Bump ${c.bold('metadata.version')} in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
+      `Bump ${c.bold('metadata.version')} once per release in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
   },
   {
     name: 'Changelog Sync',

package/scripts/lint-packaging.ts

@@ -59,6 +59,12 @@
  *      package's headline version on GitHub and npmjs.com and ships in the
  *      tarball, so a half-finished bump is publicly visible. Skipped when the
  *      README, the badge, or the package version is absent (issue #418).
+ *  13. npm `files` excludes the built bundle: when `manifest.json` exists and
+ *      `package.json` `files` covers `dist/` wholesale, it must also carry
+ *      `"!dist/*.mcpb"`. The `bundle` script writes the `.mcpb` into `dist/`,
+ *      so without the entry a release that bundles before publishing ships the
+ *      server and its production dependencies inside the npm tarball
+ *      (issue #469). Skipped when `manifest.json` or `files` is absent.
  *
  * Every check skips cleanly when its input is absent — consumers who deleted
  * `manifest.json` for an HTTP-only deploy, or who haven't built a bundle,
@@ -742,6 +748,33 @@ export function checkReadmeVersionBadge(readme: string, packageVersion?: string)
   ];
 }
 
+/** The `files` entry that keeps the `bundle` script's `dist/<name>.mcpb` out of the npm tarball. */
+const BUNDLE_EXCLUSION = '!dist/*.mcpb';
+
+/**
+ * Check 13: a `files` allowlist that covers `dist/` wholesale must exclude the
+ * `.mcpb` the `bundle` script writes there. npm and Bun both honor `!` entries
+ * in `files`, and both ignore `.npmignore` once `files` is set, so the entry is
+ * the only place the exclusion can live. The caller runs this only when
+ * `manifest.json` exists — a project without one never builds a bundle.
+ */
+export function checkBundleExcludedFromFiles(files: unknown): string[] {
+  if (!Array.isArray(files)) return [];
+  const entries = files.filter((entry): entry is string => typeof entry === 'string');
+
+  const coversDist = entries.some(
+    (entry) => entry.replace(/^\.\//, '').replace(/\/(?:\*\*(?:\/\*)?|\*)?$/, '') === 'dist',
+  );
+  if (!coversDist) return [];
+  if (entries.includes(BUNDLE_EXCLUSION) || entries.includes('!dist/**/*.mcpb')) return [];
+
+  return [
+    `package.json "files" covers dist/ without "${BUNDLE_EXCLUSION}" — the bundle script writes ` +
+      `dist/<name>.mcpb, so a release that bundles before publishing ships it in the npm tarball; ` +
+      `add "${BUNDLE_EXCLUSION}" to "files"`,
+  ];
+}
+
 /** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
 function pluginManifestsEnabled(): boolean {
   const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
@@ -755,7 +788,9 @@ async function main(): Promise<void> {
   const warnings: string[] = [];
   const notes: string[] = [];
 
-  const pkg = tryReadJson<{ name?: string; version?: string }>(resolve('package.json'));
+  const pkg = tryReadJson<{ files?: unknown; name?: string; version?: string }>(
+    resolve('package.json'),
+  );
   const unscopedName = pkg?.name?.split('/').pop();
 
   // ── Manifest-dependent checks (1–4 + manifest identity) ──
@@ -826,6 +861,8 @@ async function main(): Promise<void> {
     if (unscopedName) {
       errors.push(...checkManifestIdentity(manifest, unscopedName));
     }
+
+    errors.push(...checkBundleExcludedFromFiles(pkg?.files));
   } else {
     notes.push('No manifest.json — skipping manifest/server.json alignment checks.');
   }

package/templates/.env.example

@@ -31,12 +31,16 @@ MCP_SESSION_MODE=stateless          # stateful | stateless | auto. Set here, not
 # MCP_LOG_LEVEL=info                # debug | info | notice | warning | error
 # MCP_LOG_RATE_LIMIT_THRESHOLD=10   # Max emissions per level+message per window; 0 disables
 # MCP_LOG_RATE_LIMIT_WINDOW_MS=60000
+# LOG_TOOL_FAILURE_PAYLOADS=false            # Log failed tool calls' arguments + result (key-name redaction only;
+                                             # secrets in free-form values are kept). Reaches stderr, files, and OTLP
+# LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES=16384   # Per-payload cap, UTF-8 bytes
 
 # ── Telemetry ─────────────────────────────────────────────────────────
 # OTEL_ENABLED=false                          # Enable OpenTelemetry (default: false)
 # OTEL_EXPORTER_OTLP_ENDPOINT=               # OTLP base URL (e.g., http://localhost:4318); traces → /v1/traces, metrics → /v1/metrics
 # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=        # Overrides the base for traces; used as-is
 # OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=       # Overrides the base for metrics; used as-is
+# OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=          # Opt-in log export (e.g., http://localhost:4318/v1/logs); the base never enables it
 
 # ── Server-specific ──────────────────────────────────────────────────
 # Add your server's environment variables below

package/templates/Dockerfile

@@ -56,8 +56,15 @@ LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
 LABEL org.opencontainers.image.source=""
 
-# Copy dependency manifests
-COPY package.json bun.lock ./
+# Copy dependency manifests. `bunfig.toml` rides along so every install below
+# passes its release-age gate and security scanner, as a local install does.
+COPY package.json bun.lock bunfig.toml ./
+
+# The scanner bunfig.toml names is a devDependency, and Bun installs a missing
+# scanner through the same production-filtered install, which omits it and
+# aborts. Seed it from the build stage's full install instead. Remove this line
+# together with the scanner if bunfig.toml stops naming one.
+COPY --from=build /usr/src/app/node_modules/@socketsecurity/bun-security-scanner ./node_modules/@socketsecurity/bun-security-scanner
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
@@ -72,19 +79,33 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # Installed by default. Omit them for a leaner image at build time
 # with: docker build --build-arg OTEL_ENABLED=false
+# Each package is requested at the range the installed framework declares in
+# `peerDependencies`, so the resolution stays inside the framework's tested
+# peer range; a name with no declared range fails the build.
 ARG OTEL_ENABLED=true
 RUN --mount=type=cache,target=/root/.bun/install/cache \
     if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
-        @opentelemetry/instrumentation-http \
+      specs=$(bun -e ' \
+        const { peerDependencies: peers } = await Bun.file("node_modules/@cyanheads/mcp-ts-core/package.json").json(); \
+        const names = process.argv.slice(1); \
+        const missing = names.filter((name) => !peers?.[name]); \
+        if (missing.length > 0) throw new Error(`no peerDependencies range for ${missing.join(", ")}`); \
+        console.log(names.map((name) => `${name}@${peers[name]}`).join(" ")); \
+      ' \
+        @hono/otel \
+        @opentelemetry/api-logs \
+        @opentelemetry/exporter-logs-otlp-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \
+        @opentelemetry/instrumentation-http \
         @opentelemetry/instrumentation-pino \
         @opentelemetry/resources \
+        @opentelemetry/sdk-logs \
         @opentelemetry/sdk-metrics \
         @opentelemetry/sdk-node \
         @opentelemetry/sdk-trace-node \
-        @opentelemetry/semantic-conventions; \
+        @opentelemetry/semantic-conventions) \
+      && bun add --omit=dev --omit=peer --ignore-scripts $specs; \
     fi
 
 # Copy the compiled application code from the build stage
@@ -128,7 +149,6 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/{{PACKAGE_NAME}}"
-ENV MCP_FORCE_CONSOLE_LOGGING="true"
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}