@cyanheads/mcp-ts-core 0.12.9 → 0.13.0

package/{skills → framework-skills}/setup/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Post-init orientation for an MCP server built on @cyanheads/mcp-ts-core. Use after running `@cyanheads/mcp-ts-core init` to understand the project structure, conventions, and skill sync model. Also use when onboarding to an existing project for the first time.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: workflow
 ---
 
 ## Context
 
-This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
+This skill assumes `bunx @cyanheads/mcp-ts-core init [name]` has already run. The CLI created the project's `CLAUDE.md` and `AGENTS.md` for different agents, copied external skills to `framework-skills/`, and scaffolded the directory structure with echo definitions as starting points. This skill covers what was created and what to do next.
 
 ## Agent Protocol File
 
@@ -41,7 +41,7 @@ Dockerfile                                      # Starter multi-stage image
 server.json                                     # MCP Registry publishing metadata
 changelog/template.md                           # Format reference for per-version changelog files
 scripts/                                        # build, clean, devcheck, lint-mcp, list-skills, build-changelog, tree, check-docs-sync
-skills/                                         # External skills copied from the package (source of truth)
+framework-skills/                               # External skills copied from the package (source of truth)
 src/
   index.ts                                      # createApp() entry point
   mcp-server/
@@ -108,14 +108,14 @@ See the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt`, `add-service`,
 
 ## Skill Sync
 
-Copy all project skills into your agent's skill directory so they're available as context. `skills/` is the source of truth.
+Copy all project skills into your agent's skill directory so they're available as context. `framework-skills/` is the source of truth. It is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, and these are development skills, not skills for the agents that install the server — leave `skills/` for those.
 
-**Don't edit `skills/*/SKILL.md` or `skills/*/references/*`.** These are external skill files synced from `@cyanheads/mcp-ts-core` — the `maintenance` skill overwrites them on package updates, so local edits get lost. Project-specific agent context belongs in `CLAUDE.md` / `AGENTS.md`.
+**Don't edit `framework-skills/*/SKILL.md` or `framework-skills/*/references/*`.** These are external skill files synced from `@cyanheads/mcp-ts-core` — the `maintenance` skill overwrites them on package updates, so local edits get lost. Project-specific agent context belongs in `CLAUDE.md` / `AGENTS.md`.
 
 **For Claude Code:**
 
 ```bash
-mkdir -p .claude/skills && cp -R skills/* .claude/skills/
+mkdir -p .claude/skills && cp -R framework-skills/* .claude/skills/
 ```
 
 **For other agents** (Codex, Cursor, Windsurf, etc.) — copy to the equivalent directory (e.g., `.codex/skills/`, `.cursor/skills/`).
@@ -138,7 +138,9 @@ Complete these one-time setup tasks:
    | `.claude-plugin/plugin.json` | `description` | `lint:packaging` |
    | `.codex-plugin/plugin.json` | `description`, `interface.shortDescription`, `interface.longDescription` | `lint:packaging` |
 
-   Fill the rest of the same blocks while you are in them — `package.json` `description` and `repository.url`, both plugin manifests' `author` / `homepage` / `repository`, the Codex manifest's `interface.developerName` / `category` / `websiteURL`, and `manifest.json` `description` / `author.name`. Nothing gates them, and every install surface reads them.
+   Fill the rest of the same blocks while you are in them — `package.json` `description` and `repository.url`, both plugin manifests' `author` / `homepage` / `repository` / `keywords`, the Codex manifest's `interface.developerName` / `category` / `websiteURL`, and `manifest.json` `description` / `author.name`. Nothing gates them, and every install surface reads them.
+
+   When the server takes a user-supplied value (an API key, a contact email, an instance URL), wire it into the plugin manifests the way each client delivers it — never as `"KEY": ""` in `env`, which `lint:packaging` rejects because the empty value replaces the user's exported key and is read as unset. In `.claude-plugin/plugin.json`, declare the option under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and set `"KEY": "${user_config.<option>}"` in `env`. In `.codex-plugin/mcp.json`, list the variable name in `env_vars`. Mirror the `user_config` block you write in `manifest.json`.
 
    A server that will never be published or installed as a plugin can drop the plugin-manifest gate instead — set `"packaging": { "pluginManifests": false }` in `devcheck.config.json`.
 6. **Verify the scaffold builds clean** — `bun run devcheck`. Fix any issues before starting real work.
@@ -172,7 +174,7 @@ Skip or reorder as the project calls for it. The agent protocol's "What's Next?"
 - [ ] Publishing identity populated (`server.json`, `package.json`, plugin manifests, `manifest.json`) — or the plugin-manifest gate opted out
 - [ ] Framework docs read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` or `AGENTS.md`)
 - [ ] Unused echo definitions cleaned up (and unregistered from `src/index.ts`)
-- [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
+- [ ] Skills copied to agent directory (`cp -R framework-skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)
 - [ ] `bun run devcheck` passes
 - [ ] Next: if new server, move on to `design-mcp-server` to plan the tool surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.12.9",
+  "version": "0.13.0",
   "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": [
@@ -21,7 +21,7 @@
     "scripts/list-skills.ts",
     "scripts/release-github.ts",
     "scripts/tree.ts",
-    "skills/",
+    "framework-skills/",
     "templates/",
     "AGENTS.md",
     "CLAUDE.md",
@@ -189,7 +189,7 @@
     "test:ui": "bunx vitest --ui",
     "test:coverage": "bunx vitest run --coverage",
     "audit": "bun audit",
-    "audit:fix": "bun audit --fix",
+    "audit:fix": "bun audit fix",
     "audit:refresh": "rm -f bun.lock && bun install && bun audit",
     "changelog:build": "bun run scripts/build-changelog.ts",
     "changelog:check": "bun run scripts/build-changelog.ts --check",
@@ -197,9 +197,9 @@
     "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.12",
+    "@biomejs/biome": "2.5.13",
     "@cloudflare/vitest-pool-workers": "^0.22.0",
-    "@cloudflare/workers-types": "5.20260905.1",
+    "@cloudflare/workers-types": "5.20260910.1",
     "@duckdb/node-api": "^1.5.5-r.4",
     "@hono/otel": "^1.1.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
@@ -214,7 +214,7 @@
     "@socketsecurity/bun-security-scanner": "^1.1.2",
     "@supabase/supabase-js": "^2.116.0",
     "@types/bun": "^1.4.2",
-    "@types/node": "26.4.0",
+    "@types/node": "26.5.1",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
     "@types/validator": "^13.15.10",
@@ -247,7 +247,7 @@
     "typescript-v6": "npm:typescript@^6.0.3",
     "unpdf": "^1.8.1",
     "validator": "^13.15.35",
-    "vite": "8.2.2",
+    "vite": "8.3.0",
     "vitest": "^4.1.11"
   },
   "keywords": [
@@ -309,7 +309,7 @@
     "hono": "^4.13.7",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
-    "zod": "^4.6.0"
+    "zod": "^4.6.1"
   },
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",

package/scripts/check-framework-antipatterns.ts

@@ -152,6 +152,6 @@ for (const f of findings) {
   console.error('');
 }
 console.error(
-  'See skills/api-linter/SKILL.md or scripts/check-framework-antipatterns.ts for rule rationale.',
+  'See framework-skills/api-linter/SKILL.md or scripts/check-framework-antipatterns.ts for rule rationale.',
 );
 process.exit(1);

package/scripts/check-skill-versions.ts

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 /**
  * @fileoverview Enforces the skill-versioning policy (#98 → #99): a change to a
- * `skills/<name>/SKILL.md` body must bump `metadata.version` in the same edit.
+ * `framework-skills/<name>/SKILL.md` body must bump `metadata.version` in the same edit.
  * Documenting the policy made the expectation visible; this check makes it stick.
  * The triggering incident was 7 missed bumps across 2 consecutive releases — the
  * kind of low-salience checklist item that needs tooling, not vigilance.
  *
- * For each `skills/<name>/SKILL.md` that differs from `HEAD` (working tree, staged
+ * For each `framework-skills/<name>/SKILL.md` that differs from `HEAD` (working tree, staged
  * or not), it compares the frontmatter `metadata.version` and the body across
  * `HEAD` → working tree. A changed body with an unchanged version is a violation.
  * Whitespace-only body edits never trigger it (the policy's typo/whitespace
@@ -35,7 +35,7 @@ import { resolve } from 'node:path';
 import process from 'node:process';
 
 const ROOT = resolve('.');
-const SKILL_MD_RE = /^skills\/[^/]+\/SKILL\.md$/;
+const SKILL_MD_RE = /^framework-skills\/[^/]+\/SKILL\.md$/;
 
 interface DevcheckConfig {
   skillVersions?: { ignore?: string[] };
@@ -54,7 +54,7 @@ function loadIgnorePatterns(): string[] {
 
 /** Match check-skills-sync semantics: full `<name>/SKILL.md` path or the bare `<name>`. */
 function isIgnored(relPath: string, patterns: string[]): boolean {
-  const name = relPath.split('/')[1]; // skills/<name>/SKILL.md → <name>
+  const name = relPath.split('/')[1]; // framework-skills/<name>/SKILL.md → <name>
   return patterns.some(
     (p) => p === relPath || p === name || (name !== undefined && p === `${name}/SKILL.md`),
   );
@@ -70,10 +70,17 @@ function changedSkillFiles(): string[] {
     .filter((p) => SKILL_MD_RE.test(p));
 }
 
-/** Content of a path at `HEAD`, or null when it didn't exist there (new file). */
+/**
+ * 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
+ * path, so the release that carries the rename still checks every body edit.
+ */
 function headContent(relPath: string): string | null {
-  const result = spawnSync('git', ['show', `HEAD:${relPath}`], { encoding: 'utf-8' });
-  return result.status === 0 ? result.stdout : null;
+  const show = (p: string) => spawnSync('git', ['show', `HEAD:${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;
 }
 
 /** `metadata.version` from skill frontmatter, or null when absent/unparseable. */
@@ -95,8 +102,8 @@ function bodiesDiffer(a: string, b: string): boolean {
   return a.replace(/\s+/g, '') !== b.replace(/\s+/g, '');
 }
 
-if (!existsSync(resolve(ROOT, 'skills'))) {
-  console.log('Skipped: no skills/ directory.');
+if (!existsSync(resolve(ROOT, 'framework-skills'))) {
+  console.log('Skipped: no framework-skills/ directory.');
   process.exit(0);
 }
 

package/scripts/check-skills-sync.ts

@@ -1,21 +1,23 @@
 #!/usr/bin/env node
 /**
- * @fileoverview Verifies that `skills/` (canonical) has been propagated to the
+ * @fileoverview Verifies that `framework-skills/` (canonical) has been propagated to the
  * local mirrors `.agents/skills/` and `.claude/skills/`. The maintenance skill
- * updates `skills/` for downstream servers; the mirrors are what local agent
+ * updates `framework-skills/` for downstream servers; the mirrors are what local agent
  * toolchains actually read, and silent drift means agents run on stale guidance.
  *
- * Propagation is one-way (`skills/` → mirrors), so missing or content-drifted
+ * Propagation is one-way (`framework-skills/` → mirrors), so missing or content-drifted
  * files are reported. A skill that exists *only* in a mirror is left alone when
  * it's externally sourced (globally installed, other tools), but flagged as
  * stale when its `SKILL.md` carries `metadata.audience: external` — a framework
- * skill removed from `skills/` upstream that the mirror never had pruned.
+ * skill removed from `framework-skills/` upstream that the mirror never had pruned.
  *
  * Behavior:
  *   • In sync                          → pass
  *   • Mirrors missing entirely         → skip (no mirrors to sync)
  *   • Drift (missing or changed files) → exit 1 with details (devcheck demotes to warning)
  *   • Stale framework skill in mirror  → exit 1 (mirror-only dir with audience: external)
+ *   • Unmigrated pre-0.13 `skills/`    → exit 1 with the `git mv` step
+ *   • Leftover pre-0.13 `skills/`      → exit 1 with the removal step (both trees present)
  *
  * Ignore specific skills or files via `devcheck.config.json`:
  *
@@ -25,7 +27,7 @@
  *     }
  *   }
  *
- * Patterns match relative paths under `skills/`. A bare name like `add-tool`
+ * Patterns match relative paths under `framework-skills/`. A bare name like `add-tool`
  * ignores the whole directory; `add-tool/SKILL.md` ignores a single file.
  * `.DS_Store` and other OS cruft are ignored by default.
  *
@@ -39,7 +41,13 @@ import { relative, resolve, sep } from 'node:path';
 import process from 'node:process';
 
 const ROOT = resolve('.');
-const SKILLS_DIR = resolve(ROOT, 'skills');
+const SKILLS_DIR = resolve(ROOT, 'framework-skills');
+/**
+ * Where the tree lived before 0.13. Claude Code and Codex auto-load a plugin's
+ * root `skills/`, so a server shipping a plugin manifest handed its development
+ * skills to every installing agent — hence the move.
+ */
+const LEGACY_SKILLS_DIR = resolve(ROOT, 'skills');
 const MIRRORS: { label: string; path: string }[] = [
   { label: '.agents/skills', path: resolve(ROOT, '.agents/skills') },
   { label: '.claude/skills', path: resolve(ROOT, '.claude/skills') },
@@ -95,11 +103,51 @@ function isFrameworkManaged(skillMdPath: string): boolean {
   return /^\s*audience:\s*external\s*$/m.test(readFileSync(skillMdPath, 'utf-8'));
 }
 
+/** Skill directories under `root` whose `SKILL.md` carries `audience: external`. */
+function frameworkManagedDirs(root: string): string[] {
+  return skillDirNames(root).filter((name) => isFrameworkManaged(resolve(root, name, 'SKILL.md')));
+}
+
 if (!existsSync(SKILLS_DIR)) {
-  console.log('Skipped: no skills/ directory.');
+  const unmigrated = frameworkManagedDirs(LEGACY_SKILLS_DIR).length > 0;
+  if (unmigrated) {
+    console.log(
+      [
+        'skills/ still holds framework-managed skills and framework-skills/ is absent.',
+        'The framework moved its skill tree in 0.13.0: plugin hosts auto-load a root skills/,',
+        'which surfaced these development skills to every agent that installed the server.',
+        '',
+        'Fix: git mv skills framework-skills',
+        '     then update the path in CLAUDE.md/AGENTS.md, .mcpbignore (/framework-skills/),',
+        '     and .github/CONTRIBUTING.md, and regenerate docs/tree.md.',
+      ].join('\n'),
+    );
+    process.exit(1);
+  }
+  console.log('Skipped: no framework-skills/ directory.');
   process.exit(0);
 }
 
+// Both trees present. `init` run in place never overwrites an existing file, so an
+// upgrade creates `framework-skills/` and leaves the old copies where a plugin host
+// still auto-loads them. Only a name carried by both trees is a leftover — a `skills/`
+// name of its own is the reserved server-published kind.
+const canonicalDirs = new Set(skillDirNames(SKILLS_DIR));
+const leftover = frameworkManagedDirs(LEGACY_SKILLS_DIR).filter((name) => canonicalDirs.has(name));
+if (leftover.length > 0) {
+  console.log(
+    [
+      `skills/ still holds ${leftover.length} framework skill(s) that framework-skills/ also carries.`,
+      'Plugin hosts auto-load a root skills/, so those development skills still reach every',
+      'agent that installs the server.',
+      '',
+      `Fix: rm -rf ${leftover.map((name) => `skills/${name}`).join(' ')}`,
+      '     Keep skills/ for skills the server publishes to the agents that use it.',
+    ].join('\n'),
+  );
+  process.exit(1);
+}
+
 const presentMirrors = MIRRORS.filter((m) => existsSync(m.path));
 if (presentMirrors.length === 0) {
   console.log('Skipped: no skill mirrors (.agents/skills, .claude/skills) present.');
@@ -131,10 +179,9 @@ for (const mirror of presentMirrors) {
 }
 
 // Stale framework skills: a skill dir present only in a mirror (absent from
-// canonical skills/) is fine when externally sourced, but stale when it carries
-// `audience: external` — a framework skill removed from skills/ that was never
+// canonical framework-skills/) is fine when externally sourced, but stale when it carries
+// `audience: external` — a framework skill removed from framework-skills/ that was never
 // pruned from the mirror. User/external skills (no marker) are left alone.
-const canonicalDirs = new Set(skillDirNames(SKILLS_DIR));
 const stale: Record<string, string[]> = {};
 for (const mirror of presentMirrors) {
   const staleHere = skillDirNames(mirror.path)
@@ -152,13 +199,15 @@ const totals = {
 const driftCount = totals.missing + totals.drifted + totals.stale;
 
 if (driftCount === 0) {
-  console.log(`skills/ is in sync with ${presentMirrors.map((m) => m.label).join(' and ')}.`);
+  console.log(
+    `framework-skills/ is in sync with ${presentMirrors.map((m) => m.label).join(' and ')}.`,
+  );
   process.exit(0);
 }
 
 const lines: string[] = [];
 lines.push(
-  `skills/ has drifted from ${presentMirrors.length > 1 ? 'mirrors' : 'its mirror'} ` +
+  `framework-skills/ has drifted from ${presentMirrors.length > 1 ? 'mirrors' : 'its mirror'} ` +
     `(${totals.missing} missing, ${totals.drifted} changed, ${totals.stale} stale).`,
 );
 
@@ -175,7 +224,9 @@ renderSection('Content differs in', drifted);
 renderSection('Stale framework skill (deleted upstream) in', stale);
 
 lines.push('');
-lines.push('Fix: propagate skills/ to the mirror(s) and delete stale framework skills from them,');
+lines.push(
+  'Fix: propagate framework-skills/ to the mirror(s) and delete stale framework skills from them,',
+);
 lines.push(
   '     or add entries to devcheck.config.json `skillsSync.ignore` to silence specific paths.',
 );

package/scripts/clean-mcpb.ts

@@ -9,8 +9,8 @@
  *   2. Exact-name strip of two entry classes nested under `node_modules/`,
  *      which root-anchored `.mcpbignore` patterns cannot reach by design
  *      (issues #146/#207):
- *        a. Dependency-shipped agent docs — `skills/`, `.claude/`, `.agents/`
- *           trees and stray `SKILL.md` files (issue #230).
+ *        a. Dependency-shipped agent docs — `framework-skills/`, `skills/`,
+ *           `.claude/`, `.agents/` trees and stray `SKILL.md` files (issue #230).
  *        b. Platform-specific native bindings, which would otherwise lock the
  *           bundle to the build host's platform and push it past the 25 MB cap
  *           registries enforce (issue #274).
@@ -36,7 +36,7 @@ import { fileURLToPath } from 'node:url';
  * (post-bundle content check) — 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, which must not ship in a bundle.

package/scripts/devcheck.ts

@@ -696,7 +696,7 @@ const ALL_CHECKS: Check[] = [
     canFix: false,
     getCommand: () => ['bun', 'run', 'scripts/lint-mcp.ts'],
     tip: (c) =>
-      `Fix definition errors above — each diagnostic links to its rule in ${c.bold('skills/api-linter/SKILL.md')}.`,
+      `Fix definition errors above — each diagnostic links to its rule in ${c.bold('framework-skills/api-linter/SKILL.md')}.`,
   },
   {
     name: 'Packaging',
@@ -771,16 +771,19 @@ const ALL_CHECKS: Check[] = [
     name: 'Skills Sync',
     flag: '--no-skills-sync',
     canFix: false,
-    // Compares canonical skills/ against local mirrors (.agents/skills, .claude/skills).
-    // Skipped when skills/ or both mirrors are absent (non-mirrored projects).
-    // Drift is demoted to a warning via isSuccess — intentional ignores live in
-    // devcheck.config.json `skillsSync.ignore`.
+    // Compares canonical framework-skills/ against local mirrors (.agents/skills, .claude/skills).
+    // Skipped when framework-skills/ or both mirrors are absent (non-mirrored projects),
+    // except that a pre-0.13 `skills/` tree always runs — absent or alongside
+    // `framework-skills/` — so the script's migration message surfaces. Drift is demoted to
+    // a warning via isSuccess — intentional ignores live in devcheck.config.json
+    // `skillsSync.ignore`.
     getCommand: () => {
-      const hasSkills = existsSync(path.join(ROOT_DIR, 'skills'));
+      const hasSkills = existsSync(path.join(ROOT_DIR, 'framework-skills'));
+      const hasLegacySkills = existsSync(path.join(ROOT_DIR, 'skills'));
       const hasMirrors =
         existsSync(path.join(ROOT_DIR, '.agents/skills')) ||
         existsSync(path.join(ROOT_DIR, '.claude/skills'));
-      if (!hasSkills || !hasMirrors) return null;
+      if (!hasLegacySkills && (!hasSkills || !hasMirrors)) return null;
       return ['bun', 'run', 'scripts/check-skills-sync.ts'];
     },
     isSuccess: (result) => {
@@ -789,18 +792,18 @@ const ALL_CHECKS: Check[] = [
       return { success: true, warning: firstLine };
     },
     tip: (c) =>
-      `Propagate ${c.bold('skills/')} to ${c.bold('.agents/skills/')} and ${c.bold('.claude/skills/')}, or add entries to ${c.bold('devcheck.config.json')} ${c.bold('skillsSync.ignore')}.`,
+      `Propagate ${c.bold('framework-skills/')} to ${c.bold('.agents/skills/')} and ${c.bold('.claude/skills/')}, or add entries to ${c.bold('devcheck.config.json')} ${c.bold('skillsSync.ignore')}.`,
   },
   {
     name: 'Skill Versions',
     flag: '--no-skill-versions',
     canFix: false,
-    // Flags skills/<name>/SKILL.md body changes (vs HEAD) that lack a metadata.version
-    // bump (#99). Skipped when skills/ is absent. Drift is demoted to a warning via
+    // 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
     // isSuccess — the typo/whitespace carve-out lives in devcheck.config.json
     // `skillVersions.ignore`.
     getCommand: () => {
-      if (!existsSync(path.join(ROOT_DIR, 'skills'))) return null;
+      if (!existsSync(path.join(ROOT_DIR, 'framework-skills'))) return null;
       return ['bun', 'run', 'scripts/check-skill-versions.ts'];
     },
     isSuccess: (result) => {
@@ -903,7 +906,7 @@ const ALL_CHECKS: Check[] = [
   {
     name: 'Security Audit',
     flag: '--no-audit',
-    canFix: false, // audit --fix exists but often requires manual review.
+    canFix: false, // `audit fix` exists but often requires manual review.
     slowCheck: true,
     getCommand: () => [PM_CMD, 'audit'],
     isSuccess: (result, _mode) => {
@@ -951,7 +954,7 @@ const ALL_CHECKS: Check[] = [
       return true;
     },
     tip: (c) =>
-      `Direct dependency vulnerabilities found. Run ${c.bold(`${PM_CMD} update`)} or ${c.bold(`${PM_CMD} audit --fix`)} to resolve.`,
+      `Direct dependency vulnerabilities found. Run ${c.bold(`${PM_CMD} audit fix`)} or ${c.bold(`${PM_CMD} update <pkg>`)} to resolve.`,
   },
   {
     name: 'Dependencies (Outdated)',