@cyanheads/mcp-ts-core 0.12.9 → 0.13.1

package/scripts/lint-packaging.ts

@@ -19,13 +19,13 @@
  *   5. Bundle-content guard: known root dev directories must not appear at
  *      bundle root after `.mcpbignore` evaluation (dev dir not excluded).
  *   6. Bundle-content guard: `.mcpbignore` must not use unanchored patterns
- *      for root dev dirs — an unanchored `skills/` also strips
- *      `node_modules/x/skills/` (runtime path bypass, issues #172/#207).
+ *      for root dev dirs — an unanchored `framework-skills/` also strips
+ *      `node_modules/x/framework-skills/` (runtime path bypass, issues #172/#207).
  *   7. Bundle-content guard: `.mcpbignore` patterns must not strip critical
  *      runtime package paths (e.g. `node_modules/@opentelemetry/api/build/src/`).
  *   8. Post-bundle content: a built `.mcpb` under `dist/` must contain zero
- *      `node_modules/**` agent-doc entries (dependency-shipped `skills/`,
- *      `.claude/`, `.agents/`, `SKILL.md`) — unreachable by root-anchored
+ *      `node_modules/**` agent-doc entries (dependency-shipped `framework-skills/`,
+ *      `skills/`, `.claude/`, `.agents/`, `SKILL.md`) — unreachable by root-anchored
  *      `.mcpbignore` patterns; `scripts/clean-mcpb.ts` strips them at bundle
  *      time (issue #230).
  *   9. Identity: `name`/`title` literals in `createApp()` /
@@ -41,9 +41,19 @@
  *      is a guaranteed install 404. Each present plugin manifest's `version`
  *      must equal `package.json`'s, so a release cannot ship stale plugin
  *      metadata (issue #393); `.codex-plugin/mcp.json` is connection config and
- *      carries no version. Gated by `devcheck.config.json`
- *      `packaging.pluginManifests` (default on); each manifest is skipped
- *      cleanly when absent (issue #240).
+ *      carries no version. No server `env` value may be the empty string: the
+ *      client sets it on the child process, so the placeholder replaces a key
+ *      the user exported and the framework then reads it as unset. Claude Code
+ *      takes user values through `userConfig` + `${user_config.<key>}` (every
+ *      reference must be declared); Codex forwards host variables named in
+ *      `env_vars`. Gated by `devcheck.config.json` `packaging.pluginManifests`
+ *      (default on); each manifest is skipped cleanly when absent (issue #240).
+ *  11. MCPB `user_config` wiring: every declared option is referenced from
+ *      `mcp_config` as `${user_config.<key>}`, every reference is declared,
+ *      `mcp_config` carries no other `${…}` placeholder besides the host's
+ *      path variables (the host delivers anything else as the literal string),
+ *      and an optional string option has `"default": ""` so a blank answer
+ *      arrives as empty rather than as the unsubstituted placeholder.
  *
  * 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,
@@ -80,7 +90,7 @@ interface ManifestUserConfigEntry {
 interface Manifest {
   display_name?: unknown;
   name?: string;
-  server?: { mcp_config?: { env?: Record<string, string> } };
+  server?: { mcp_config?: { args?: unknown[]; env?: Record<string, string> } };
   user_config?: Record<string, ManifestUserConfigEntry>;
 }
 
@@ -89,15 +99,15 @@ const USER_CONFIG_REF = /^\$\{user_config\.([\w-]+)\}$/;
 /**
  * Root dev directories the scaffold template excludes from the bundle, and
  * whose `.mcpbignore` patterns must be anchored with `/` to avoid also
- * stripping nested runtime paths like `node_modules/x/skills/`. Keep in step
+ * stripping nested runtime paths like `node_modules/x/framework-skills/`. Keep in step
  * with the directory entries in `templates/_.mcpbignore`.
  */
-export const KNOWN_DEV_DIRS = ['skills/', '.agents/', '.claude/'];
+export const KNOWN_DEV_DIRS = ['framework-skills/', '.agents/', '.claude/'];
 
 /**
  * Critical runtime paths that must NOT be stripped by any `.mcpbignore` pattern.
- * These are sampled representative paths — enough to catch a bare `skills/`
- * pattern accidentally stripping `node_modules/…/skills/`.
+ * These are sampled representative paths — enough to catch a bare `framework-skills/`
+ * pattern accidentally stripping `node_modules/…/framework-skills/`.
  */
 export const CRITICAL_RUNTIME_PATHS = [
   'node_modules/@opentelemetry/api/build/src/',
@@ -108,11 +118,13 @@ export const CRITICAL_RUNTIME_PATHS = [
 
 /**
  * Agent-doc entries under `node_modules/` that must not ship in a bundle.
+ * `framework-skills/` is this framework's tree; `skills/` covers any other
+ * dependency that vendors agent skills.
  * KEEP IN SYNC with `AGENT_DOC_ENTRY` in `scripts/clean-mcpb.ts` (the strip
  * step this check verifies) — a unit test asserts the two are identical.
  */
 export const AGENT_DOC_ENTRY =
-  /^node_modules\/.*(?:\/skills\/|\/\.claude\/|\/\.agents\/|\/SKILL\.md$)/;
+  /^node_modules\/.*(?:\/framework-skills\/|\/skills\/|\/\.claude\/|\/\.agents\/|\/SKILL\.md$)/;
 
 /**
  * Platform-specific native binding packages that must not ship in a bundle.
@@ -251,7 +263,7 @@ export function checkBundleEntries(entries: string[], bundleLabel: string): stri
   if (agentDocs.length > 0) {
     errors.push(
       `${bundleLabel} contains ${agentDocs.length} node_modules agent-doc entries ` +
-        `(dependency-shipped skills/, .claude/, .agents/, SKILL.md) — re-run the \`bundle\` ` +
+        `(dependency-shipped framework-skills/, skills/, .claude/, .agents/, SKILL.md) — re-run the \`bundle\` ` +
         `script (scripts/clean-mcpb.ts strips them):${sampleOf(agentDocs)}`,
     );
   }
@@ -409,6 +421,81 @@ export function checkManifestIdentity(manifest: Manifest, unscopedName: string):
   return [];
 }
 
+/** Placeholders the MCPB host substitutes in `mcp_config` besides `${user_config.<key>}`. */
+const MCPB_HOST_VARS = new Set([
+  '__dirname',
+  'HOME',
+  'DESKTOP',
+  'DOCUMENTS',
+  'DOWNLOADS',
+  'pathSeparator',
+  '/',
+]);
+
+/**
+ * Check 11: MCPB `user_config` wiring. A value the host collects from the
+ * user reaches the server only through a `${user_config.<key>}` reference in
+ * `mcp_config`; the host substitutes nothing else except its own path
+ * placeholders, so `${API_KEY}` is delivered as that literal string. Every
+ * declared option must therefore be referenced, every reference must be
+ * declared, and an optional string option needs `"default": ""` so a blank
+ * answer arrives as empty rather than as the unsubstituted placeholder.
+ */
+export function checkManifestUserConfigWiring(manifest: Manifest): string[] {
+  const errors: string[] = [];
+  const userConfig = manifest.user_config ?? {};
+  const env = manifest.server?.mcp_config?.env ?? {};
+  const args = manifest.server?.mcp_config?.args ?? [];
+  const referenced = new Set<string>();
+
+  const scan = (value: unknown, where: string): void => {
+    if (typeof value !== 'string') return;
+    for (const match of value.matchAll(/\$\{([^}]+)\}/g)) {
+      const token = match[1] ?? '';
+      if (token.startsWith('user_config.')) {
+        const key = token.slice('user_config.'.length);
+        referenced.add(key);
+        if (!(key in userConfig)) {
+          errors.push(
+            `manifest.json ${where} references "\${user_config.${key}}" but user_config["${key}"] is not declared`,
+          );
+        }
+      } else if (!MCPB_HOST_VARS.has(token)) {
+        errors.push(
+          `manifest.json ${where} references "\${${token}}" — MCPB substitutes only \${user_config.<key>} and its ` +
+            `own path placeholders, so the server receives that literal string; declare the option under user_config ` +
+            `and reference "\${user_config.${token}}"`,
+        );
+      }
+    }
+  };
+  for (const [key, value] of Object.entries(env)) scan(value, `mcp_config.env.${key}`);
+  for (const [i, value] of args.entries()) scan(value, `mcp_config.args[${i}]`);
+
+  for (const [key, entry] of Object.entries(userConfig)) {
+    if (!referenced.has(key)) {
+      errors.push(
+        `manifest.json user_config["${key}"] is never referenced from mcp_config — the host collects the value ` +
+          `and then drops it; add "${key}": "\${user_config.${key}}" to mcp_config.env`,
+      );
+    }
+    if (
+      typeof entry === 'object' &&
+      entry !== null &&
+      entry.type === 'string' &&
+      entry.required !== true &&
+      !('default' in entry)
+    ) {
+      errors.push(
+        `manifest.json user_config["${key}"] is an optional string with no "default" — a blank answer reaches ` +
+          `the server as the literal "\${user_config.${key}}"; add "default": ""`,
+      );
+    }
+  }
+
+  return errors;
+}
+
 /** Parsed plugin marketplace manifests; an absent manifest is `undefined`. */
 export interface PluginManifestInputs {
   claudePlugin?: unknown;
@@ -424,6 +511,11 @@ function installArg(entry: Record<string, unknown>): unknown {
   return Array.isArray(entry.args) ? entry.args[1] : undefined;
 }
 
+/** A server entry's `env` object, or an empty one when absent or malformed. */
+function serverEnv(entry: Record<string, unknown>): Record<string, unknown> {
+  return isRecord(entry.env) ? entry.env : {};
+}
+
 /**
  * Check 10: plugin marketplace manifests. Display fields (`name`, server key,
  * `interface.displayName`) must equal the unscoped machine name; the install
@@ -434,6 +526,15 @@ function installArg(entry: Record<string, unknown>): unknown {
  * and non-plugin consumers are unaffected. The caller gates the whole check on
  * `packaging.pluginManifests`.
  *
+ * A server `env` value of `""` is rejected in both connection configs. The
+ * client sets the entry on the child process, so the placeholder replaces a
+ * key the user exported and the framework's empty-string-as-unset parsing then
+ * drops it — the user's real value never reaches the server. Claude Code
+ * collects user values through `userConfig` and substitutes
+ * `${user_config.<key>}` in `env`; every such reference must name a declared
+ * option. Codex launches stdio servers with a whitelisted environment, so a
+ * host variable reaches the server only when `env_vars` names it.
+ *
  * `.codex-plugin/mcp.json` is connection configuration and carries no version.
  */
 export function checkPluginManifests(
@@ -478,11 +579,31 @@ export function checkPluginManifests(
         );
       }
       const entry = servers[unscopedName];
-      if (isRecord(entry) && installArg(entry) !== fullName) {
-        errors.push(
-          `${f} mcpServers["${unscopedName}"] install arg is "${String(installArg(entry))}" — ` +
-            `must be the full package name "${fullName}" (the npx -y target; an unscoped arg for a scoped package 404s)`,
-        );
+      if (isRecord(entry)) {
+        if (installArg(entry) !== fullName) {
+          errors.push(
+            `${f} mcpServers["${unscopedName}"] install arg is "${String(installArg(entry))}" — ` +
+              `must be the full package name "${fullName}" (the npx -y target; an unscoped arg for a scoped package 404s)`,
+          );
+        }
+        const userConfig = isRecord(claude.userConfig) ? claude.userConfig : {};
+        for (const [key, value] of Object.entries(serverEnv(entry))) {
+          if (value === '') {
+            errors.push(
+              `${f} mcpServers["${unscopedName}"].env.${key} is "" — an empty placeholder replaces the ` +
+                `user's exported ${key} and is read as unset; declare the option under "userConfig" ` +
+                `and set the value to "\${user_config.<option>}"`,
+            );
+          } else if (typeof value === 'string') {
+            const ref = USER_CONFIG_REF.exec(value)?.[1];
+            if (ref !== undefined && !isRecord(userConfig[ref])) {
+              errors.push(
+                `${f} mcpServers["${unscopedName}"].env.${key} references "\${user_config.${ref}}" but ` +
+                  `"userConfig.${ref}" is not declared — Claude Code prompts only for declared options`,
+              );
+            }
+          }
+        }
       }
     }
   }
@@ -530,11 +651,22 @@ export function checkPluginManifests(
       );
     }
     const entry = codexMcp[unscopedName];
-    if (isRecord(entry) && installArg(entry) !== fullName) {
-      errors.push(
-        `${f} "${unscopedName}" install arg is "${String(installArg(entry))}" — ` +
-          `must be the full package name "${fullName}" (the npx -y target)`,
-      );
+    if (isRecord(entry)) {
+      if (installArg(entry) !== fullName) {
+        errors.push(
+          `${f} "${unscopedName}" install arg is "${String(installArg(entry))}" — ` +
+            `must be the full package name "${fullName}" (the npx -y target)`,
+        );
+      }
+      for (const [key, value] of Object.entries(serverEnv(entry))) {
+        if (value === '') {
+          errors.push(
+            `${f} "${unscopedName}".env.${key} is "" — Codex starts stdio servers with a whitelisted ` +
+              `environment, so an empty placeholder adds nothing; remove it and list "${key}" in ` +
+              `"env_vars" to forward the user's value`,
+          );
+        }
+      }
     }
   }
 
@@ -586,6 +718,8 @@ async function main(): Promise<void> {
       }
     }
 
+    errors.push(...checkManifestUserConfigWiring(manifest));
+
     const serverJson = tryReadJson<ServerJson>(resolve('server.json'));
     if (serverJson) {
       const manifestEnv = manifest.server?.mcp_config?.env ?? {};

package/scripts/list-skills.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 /**
  * @fileoverview Surfaces the YAML frontmatter of all SKILL.md files in this
- * project's `.claude/skills/` directory (falling back to `skills/`). Mirrors
+ * project's `.claude/skills/` directory (falling back to `framework-skills/`). Mirrors
  * how the Claude Code harness lists available skills, but as plain stdout an
  * agent can read.
  *
@@ -22,7 +22,7 @@ import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 
-const CANDIDATE_DIRS = ['.claude/skills', 'skills'] as const;
+const CANDIDATE_DIRS = ['.claude/skills', 'framework-skills'] as const;
 
 interface SkillEntry {
   description: string;

package/templates/.claude-plugin/plugin.json

@@ -1,13 +1,17 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "{{PACKAGE_NAME}}",
   "version": "0.1.0",
   "description": "",
   "author": {
-    "name": ""
+    "name": "",
+    "email": "",
+    "url": ""
   },
   "homepage": "",
   "repository": "",
   "license": "Apache-2.0",
+  "keywords": ["mcp", "mcp-server", "model-context-protocol"],
   "mcpServers": {
     "{{PACKAGE_NAME}}": {
       "command": "npx",

package/templates/.env.example

@@ -1,7 +1,7 @@
 # ── Transport ──────────────────────────────────────────────────────────
 # MCP_TRANSPORT_TYPE=stdio          # stdio | http (default: stdio)
 # MCP_HTTP_PORT=3010                # HTTP port (default: 3010)
-# MCP_HTTP_HOST=localhost           # HTTP host (default: localhost)
+# MCP_HTTP_HOST=127.0.0.1           # HTTP host (default: 127.0.0.1)
 # MCP_HTTP_ENDPOINT_PATH=/mcp      # HTTP endpoint path (default: /mcp)
 # MCP_HTTP_MAX_BODY_BYTES=1048576  # Max request body bytes; 413 over limit, 0 disables (default: 1048576)
 # MCP_PUBLIC_URL=                  # Public origin behind a TLS-terminating proxy (e.g. https://mcp.example.com)
@@ -14,7 +14,10 @@
 # STORAGE_PROVIDER_TYPE=in-memory   # in-memory | filesystem | supabase | cloudflare-r2 | cloudflare-kv | cloudflare-d1
 
 # ── Session ──────────────────────────────────────────────────────────
-# MCP_SESSION_MODE=stateful         # stateful | stateless (default: stateful)
+MCP_SESSION_MODE=stateless          # stateful | stateless | auto. Set here, not left to the schema default
+                                    # (auto, which resolves to stateful). Stateless fits a data API:
+                                    # no session store, horizontally scalable. Use stateful when a tool
+                                    # asks the caller for input mid-handler (ctx.requestInput).
 # MCP_HTTP_RESUMABILITY=false       # SSE replay on a dropped stateful stream. Default: true.
                                     # Kill switch only — no effect on stateless serving.
 # MCP_HTTP_RESUMABILITY_MAX_EVENTS=512   # Retained per session, oldest evicted first

package/templates/.github/CONTRIBUTING.md

@@ -2,13 +2,12 @@
 
 Thanks for using `{{PACKAGE_NAME}}`. Bugs, feature requests, and documentation gaps all belong in an issue — that's where they get read and picked up.
 
-Open one from the **Issues** tab and pick the **Bug Report** or **Feature Request** form. Both are structured, and filling in the fields is what makes an issue actionable.
+Open one from the **Issues** tab and pick the **Bug Report** or **Feature Request** form. Both are structured, and filling in the fields is what makes an issue actionable. Anything that fits neither can be a plain issue — a half-formed idea in your own words is fine.
 
 <!-- Optional: swap the line above for direct links once you know your repo URL —
      https://github.com/OWNER/REPO/issues/new?template=bug_report.yml -->
 
-<!-- If you accept pull requests, say so here — e.g. "PRs welcome; open an issue
-     first for anything larger than a typo." Silence reads as "issues only". -->
+<!-- This project takes contributions as issues. Do not add a "pull requests are welcome" line. -->
 
 ## Server bug or framework bug?
 
@@ -40,8 +39,8 @@ Do the triage first — an unverified report costs more to read than it saves to
 
 Two workflows ship with this project:
 
-- [`skills/report-issue-local/SKILL.md`](../skills/report-issue-local/SKILL.md) — filing against this repo.
-- [`skills/report-issue-framework/SKILL.md`](../skills/report-issue-framework/SKILL.md) — filing against `mcp-ts-core` when you've isolated the bug to the framework.
+- [`framework-skills/report-issue-local/SKILL.md`](../framework-skills/report-issue-local/SKILL.md) — filing against this repo.
+- [`framework-skills/report-issue-framework/SKILL.md`](../framework-skills/report-issue-framework/SKILL.md) — filing against `mcp-ts-core` when you've isolated the bug to the framework.
 
 Read the relevant one before filing on a user's behalf.
 

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

@@ -2,11 +2,14 @@ name: Bug Report
 description: Report a bug in {{PACKAGE_NAME}}
 labels: ["bug"]
 # assignees: ["your-github-username"]  # uncomment to auto-assign new issues
+# The secondary labels listed below must exist in the repo — create each once: gh label create <name>
 body:
   - type: markdown
     attributes:
       value: |
-        **Do not include secrets, credentials, API keys, or tokens.** Redact sensitive values from env vars, headers, and logs before submitting. GitHub issues are public.
+        **Server bug or framework bug?** File here if a tool returns wrong data, an upstream API call fails, a schema doesn't match reality, or a description misleads the model. If a builder rejects valid input, `createApp()` fails on a valid config, or transport or auth misbehaves regardless of which tool you call, file against [mcp-ts-core](https://github.com/cyanheads/mcp-ts-core/issues) instead. Not sure? File here and it'll get routed.
+
+        **Do not include secrets, credentials, API keys, tokens, PII, or other sensitive data.** Redact env vars, auth headers, user-identifying information, and internal URLs from all code snippets, logs, and stack traces before submitting. GitHub issues are public and permanent.
 
         **Secondary labels.** `bug` is applied automatically — also add one or more of the following in the sidebar if they apply:
         - `regression` — worked before, broken after a change
@@ -15,8 +18,6 @@ body:
         - `breaking-change` — fix will break public API
         - `surplus-token-idea` — worth exploring when token budget allows
 
-        If a label doesn't exist in this repo yet, create it once: `gh label create <name>`.
-
   - type: input
     id: version
     attributes:
@@ -48,7 +49,7 @@ body:
     id: runtime-version
     attributes:
       label: Runtime version
-      placeholder: "Bun 1.2.x / Node 22.x"
+      placeholder: "Bun 1.4.x / Node 24.x"
     validations:
       required: true
 

package/templates/.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,6 @@
-blank_issues_enabled: false
+blank_issues_enabled: true
+# Optional: route security reports to the private advisory form once you know your repo URL —
+# contact_links:
+#   - name: Report a security vulnerability
+#     url: https://github.com/OWNER/REPO/security/advisories/new
+#     about: Private report — please don't file vulnerabilities as public issues

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

@@ -2,6 +2,7 @@ name: Feature Request
 description: Suggest a new feature or improvement for {{PACKAGE_NAME}}
 labels: ["enhancement"]
 # assignees: ["your-github-username"]  # uncomment to auto-assign new issues
+# The secondary labels listed below must exist in the repo — create each once: gh label create <name>
 body:
   - type: markdown
     attributes:
@@ -12,8 +13,6 @@ body:
         - `breaking-change` — will break public API; requires a major bump
         - `surplus-token-idea` — worth exploring when token budget allows
 
-        If a label doesn't exist in this repo yet, create it once: `gh label create <name>`.
-
   - type: textarea
     id: use-case
     attributes:

package/templates/AGENTS.md

@@ -17,10 +17,10 @@ This project was just scaffolded with `bunx @cyanheads/mcp-ts-core init`. You're
 
 > **Remove this section** from CLAUDE.md / AGENTS.md after completing these steps. The skills and conventions below remain — this block is one-time onboarding only.
 
-1. **Get your bearings.** Take stock of the project tree, the skills in `skills/`, and the tools/MCP servers available. Light tool use is fine for context-building — you're mapping the territory, not committing yet.
+1. **Get your bearings.** Take stock of the project tree, the skills in `framework-skills/`, and the tools/MCP servers available. Light tool use is fine for context-building — you're mapping the territory, not committing yet.
 2. **Read the framework docs** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` (builders, Context, errors, exports, conventions)
-3. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
-4. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+3. **Run the `setup` skill** — read `framework-skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
+4. **Design the server** — read `framework-skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
 
 ---
 
@@ -174,6 +174,22 @@ await createApp({
 
 `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
 
+### Session posture and shutdown
+
+Two more `createApp()` options shape how the server runs rather than how it presents itself:
+
+```ts
+await createApp({
+  sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }
+  setup(core) { startMyWatcher(core.config); },
+  async teardown() { await stopMyWatcher(); },
+});
+```
+
+`sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the prompt. Stdio is never refused.
+
+`teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).
+
 ---
 
 ## Context
@@ -231,7 +247,7 @@ throw new Error('Invalid query format');     // → ValidationError
 
 // McpError — when no factory exists for the code
 import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
-throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
+throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });
 ```
 
 See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
@@ -273,9 +289,9 @@ src/
 
 ## Skills
 
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
+**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
 Available skills:
 
@@ -315,7 +331,7 @@ Available skills:
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
 
-**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
+**Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `framework-skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -331,7 +347,8 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run rebuild` | Clean + build |
 | `bun run clean` | Remove build artifacts |
 | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
+| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
+| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
 | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
 | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
 | `bun run list-skills` | Print the skill registry |
@@ -349,11 +366,11 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
-**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
+**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
 
-**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
+**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `framework-skills/polish-docs-meta/references/readme.md`.
 
 ---
 
@@ -410,7 +427,7 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
-- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
-- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
-- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
 - [ ] `npm run devcheck` passes