@cyanheads/mcp-ts-core 0.12.8 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.12.8",
+  "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",
@@ -212,9 +212,9 @@
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
     "@socketsecurity/bun-security-scanner": "^1.1.2",
-    "@supabase/supabase-js": "^2.115.0",
-    "@types/bun": "^1.4.1",
-    "@types/node": "26.4.0",
+    "@supabase/supabase-js": "^2.116.0",
+    "@types/bun": "^1.4.2",
+    "@types/node": "26.5.1",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
     "@types/validator": "^13.15.10",
@@ -230,7 +230,7 @@
     "execa": "^10.0.1",
     "fast-check": "^4.9.0",
     "fast-xml-parser": "^5.11.1",
-    "ignore": "^7.0.8",
+    "ignore": "^7.0.9",
     "js-yaml": "^5.4.1",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
@@ -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": [
@@ -282,7 +282,7 @@
   ],
   "packageManager": "bun@1.4.0",
   "engines": {
-    "bun": ">=1.3.0",
+    "bun": ">=1.4.0",
     "node": ">=24.0.0"
   },
   "depcheck": {
@@ -302,14 +302,14 @@
   "dependencies": {
     "@hono/node-server": "^2.1.1",
     "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/ext-apps": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.1",
     "dotenv": "^17.4.2",
     "hono": "^4.13.7",
     "jose": "^6.2.12",
     "pino": "^10.3.1",
-    "zod": "^4.5.4"
+    "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

@@ -437,7 +437,8 @@ interface OutdatedRow {
   current: string;
   /** The declared key when attribution is unambiguous, else null. */
   declaredKey: string | null;
-  group: DependencyGroup | null;
+  /** The block the row belongs to; `bun outdated` leaves `prod` rows unmarked. */
+  group: DependencyGroup;
   /** The row verbatim, used to key the rendered rewrite back to its line. */
   line: string;
   /** First cell as printed, marker included. */
@@ -457,11 +458,11 @@ interface OutdatedRow {
  */
 function attributeOutdatedRow(
   target: string,
-  group: DependencyGroup | null,
+  group: DependencyGroup,
   current: string,
 ): Pick<OutdatedRow, 'candidates' | 'declaredKey'> {
   const matches = DECLARED_DEPENDENCIES.filter(
-    (declared) => declared.target === target && (group === null || declared.group === group),
+    (declared) => declared.target === target && declared.group === group,
   );
   const candidates = matches.map((declared) => declared.key);
   if (candidates.length <= 1) return { candidates, declaredKey: candidates[0] ?? null };
@@ -481,7 +482,7 @@ function parseOutdatedRows(output: string): OutdatedRow[] {
     const rawName = cells[1] ?? '';
     // Skip table chrome: header row and separator (e.g., "---")
     if (!rawName || rawName === 'Package' || /^-+$/.test(rawName)) continue;
-    const group = (OUTDATED_GROUP_MARKER.exec(rawName)?.[1] ?? null) as DependencyGroup | null;
+    const group = (OUTDATED_GROUP_MARKER.exec(rawName)?.[1] ?? 'prod') as DependencyGroup;
     const target = rawName.replace(OUTDATED_GROUP_MARKER, '');
     const current = cells[2] ?? '';
     const update = (cells[3] ?? '').replace(/\*/g, '').trim();
@@ -514,7 +515,7 @@ function renderOutdatedTable(output: string): string {
     const row = attributed.get(line);
     let display = cell.trim();
     if (row?.declaredKey && row.declaredKey !== row.target) {
-      display = row.group ? `${row.declaredKey} (${row.group})` : row.declaredKey;
+      display = row.group === 'prod' ? row.declaredKey : `${row.declaredKey} (${row.group})`;
     }
     return { line, display };
   });
@@ -552,9 +553,12 @@ function renderOutdatedTable(output: string): string {
  * Parses `bun audit` output and classifies high/critical vulnerabilities as
  * direct (in our package.json) or upstream (transitive dependency we can't fix).
  *
- * Bun audit format per vulnerability block:
- *   <package>  <version-range>        ← header (no indent, 2+ spaces before range)
- *     <parent> › <child> [› ...]      ← dependency path (indented, › = transitive)
+ * Bun audit format per vulnerability block — Bun 1.4 changed the header token
+ * and the path separator, so both shapes are accepted:
+ *   <package>  <version-range>        ← header, Bun <1.4 (no indent, 2+ spaces before range)
+ *   <package>@<version>               ← header, Bun ≥1.4
+ *     <parent> › <child> [› ...]      ← dependency path (indented; › or, Bun ≥1.4, > = transitive)
+ *     (direct dependency)             ← dependency path of a direct dependency, Bun ≥1.4
  *     <severity>: <description>       ← advisory (indented)
  *
  * Returns null if parsing yields no results (caller should fall back to default behavior).
@@ -567,8 +571,10 @@ function classifyAuditVulns(output: string): { direct: string[]; upstream: strin
     let i = 0;
 
     while (i < lines.length) {
-      // Package header: non-indented, name followed by 2+ spaces then version constraint
-      const pkgMatch = lines[i]?.match(/^([@\w][\w./-]*)\s{2,}(.+)$/);
+      // Package header: non-indented `name  range` (2+ spaces, Bun <1.4) or
+      // `name@version` (Bun ≥1.4). A scoped name leads with `@`, so only a
+      // later `@` splits the Bun 1.4 form.
+      const pkgMatch = lines[i]?.match(/^(@?\w[\w./-]*)(?:\s{2,}|@)(\S.*)$/);
       if (!pkgMatch) {
         i++;
         continue;
@@ -593,14 +599,15 @@ function classifyAuditVulns(output: string): { direct: string[]; upstream: strin
 
       if (!hasHighCritical) continue;
 
-      // Direct if: the vulnerable package is in our package.json,
-      // or any dependency path lacks › (meaning it's not pulled in transitively)
+      // Direct if: the vulnerable package is in our package.json, or any
+      // dependency path lacks a transitive separator — U+203A `›` (Bun <1.4)
+      // or `>` (Bun ≥1.4). Bun 1.4's literal `(direct dependency)` path has neither.
       const pkgName = pkg ?? '';
-      const isDirect = DIRECT_DEPS.has(pkgName) || paths.some((p) => !p.includes('\u203a'));
+      const isDirect = DIRECT_DEPS.has(pkgName) || paths.some((p) => !/[\u203a>]/.test(p));
       if (isDirect) {
         direct.push(`${pkgName} ${versionRange}`);
       } else {
-        const via = paths[0]?.split(/\s*\u203a\s*/)[0] ?? 'unknown';
+        const via = paths[0]?.split(/\s*[\u203a>]\s*/)[0] ?? 'unknown';
         upstream.push(`${pkgName} ${versionRange} (via ${via})`);
       }
     }
@@ -689,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',
@@ -764,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) => {
@@ -782,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) => {
@@ -896,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) => {
@@ -944,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)',