svelte-vitals 0.35.0 → 0.36.0

package/README.md

@@ -78,12 +78,20 @@ Useful as a CI gate.
 
 ### `svelte-vitals install`
 
-An interactive wizard that wires up the [MCP server](https://www.npmjs.com/package/@svelte-vitals/mcp), the [Vite plugin](https://www.npmjs.com/package/@svelte-vitals/vite)'s live dashboard, Agent Skills (`/svelte-vitals`, `/improve-svelte`) for Claude Code, Cursor, and Codex, and a GitHub Actions CI workflow — grouped by category in the picker so it's clear what each target is for:
+An interactive wizard that wires up the [Vite plugin](https://www.npmjs.com/package/@svelte-vitals/vite)'s live dashboard, Agent Skills (`/svelte-vitals`, `/improve-svelte`) for Claude Code, Codex, and Cursor, a `svelte-vitals.config` file, and a GitHub Actions CI workflow — grouped by category in the picker so it's clear what each target is for:
 
 ```bash
 npx svelte-vitals@latest install
 ```
 
+### `svelte-vitals explain <rule-id>`
+
+Prints one rule's rationale, docs link, fix template, and — for a configurable rule — every option's default, bounds, and how a configured value merges with the built-in default. `--json` emits the same data as an object. This is the per-rule detail an agent needs when it has to decide whether a finding is a defect or a threshold disagreement.
+
+```bash
+npx svelte-vitals@latest explain performance/heavy-import
+```
+
 ### CI integration
 
 `svelte-vitals ci install` scaffolds a GitHub Actions workflow around `@svelte-vitals/action` — inline PR annotations, a job summary, and a sticky PR comment, no YAML to hand-write. The same workflow is also a selectable `ci-workflow` target inside `svelte-vitals install`, so it can be set up in the same pass as everything else. See [CI integration](https://oekazuma.github.io/svelte-vitals/guides/ci/).

package/dist/bin.js

@@ -12,7 +12,7 @@ import {
 } from "./chunk-D6AUX2GC.js";
 
 // src/bin.ts
-import mri3 from "mri";
+import mri4 from "mri";
 import * as p2 from "@clack/prompts";
 
 // src/resolve-args.ts
@@ -179,96 +179,12 @@ function resolveArgs(argv) {
 // src/install/cli.ts
 import { mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname } from "path";
-import { homedir } from "os";
 import { spawnSync } from "child_process";
 import mri from "mri";
 import * as p from "@clack/prompts";
 
 // src/install/index.ts
-import { join as join4 } from "path";
-
-// src/install/clients.ts
-import { join } from "path";
-var MCP_ENTRY = { command: "npx", args: ["-y", "@svelte-vitals/mcp"] };
-var CLIENTS = [
-  {
-    id: "claude-code",
-    label: "Claude Code",
-    scopes: ["project", "global"],
-    format: "json",
-    resolvePath: (scope, cwd, home) => scope === "project" ? join(cwd, ".mcp.json") : join(home, ".claude.json")
-  },
-  {
-    id: "cursor",
-    label: "Cursor",
-    scopes: ["project", "global"],
-    format: "json",
-    resolvePath: (scope, cwd, home) => scope === "project" ? join(cwd, ".cursor", "mcp.json") : join(home, ".cursor", "mcp.json")
-  },
-  {
-    id: "codex",
-    label: "Codex",
-    scopes: ["global"],
-    format: "toml",
-    resolvePath: (_scope, _cwd, home) => join(home, ".codex", "config.toml")
-  }
-];
-function clientById(id) {
-  return CLIENTS.find((c) => c.id === id);
-}
-
-// src/install/merge.ts
-import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-var SERVER_KEY = "svelte-vitals";
-function isPlainObject(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function sameEntry(prior, entry) {
-  if (typeof prior !== "object" || prior === null) return false;
-  const o = prior;
-  return o.command === entry.command && Array.isArray(o.args) && o.args.length === entry.args.length && o.args.every((v, i) => v === entry.args[i]);
-}
-function statusFor(prior, entry, force, created) {
-  if (prior !== void 0) {
-    if (sameEntry(prior, entry)) return "exists";
-    return force ? "updated" : "skip";
-  }
-  return created ? "created" : "added";
-}
-function mergeJson(existing, entry, force) {
-  const created = existing === void 0;
-  const parsed = created ? {} : JSON.parse(existing);
-  if (!isPlainObject(parsed)) {
-    throw new Error("existing config is not a JSON object");
-  }
-  const root = parsed;
-  if (root.mcpServers !== void 0 && !isPlainObject(root.mcpServers)) {
-    throw new Error('existing config has a non-object "mcpServers" table');
-  }
-  const servers = isPlainObject(root.mcpServers) ? root.mcpServers : {};
-  const status = statusFor(servers[SERVER_KEY], entry, force, created);
-  if (status === "exists" || status === "skip") return { content: existing, status: "exists" };
-  servers[SERVER_KEY] = { command: entry.command, args: entry.args };
-  root.mcpServers = servers;
-  return { content: JSON.stringify(root, null, 2) + "\n", status };
-}
-function mergeToml(existing, entry, force) {
-  const created = existing === void 0;
-  const parsed = created ? {} : parseToml(existing);
-  if (!isPlainObject(parsed)) {
-    throw new Error("existing config is not a TOML table");
-  }
-  const root = parsed;
-  if (root.mcp_servers !== void 0 && !isPlainObject(root.mcp_servers)) {
-    throw new Error('existing config has a non-table "mcp_servers" section');
-  }
-  const servers = isPlainObject(root.mcp_servers) ? root.mcp_servers : {};
-  const status = statusFor(servers[SERVER_KEY], entry, force, created);
-  if (status === "exists" || status === "skip") return { content: existing, status: "exists" };
-  servers[SERVER_KEY] = { command: entry.command, args: entry.args };
-  root.mcp_servers = servers;
-  return { content: stringifyToml(root), status };
-}
+import { join as join3 } from "path";
 
 // src/install/vite-targets.ts
 var VITE_TARGETS = [
@@ -444,7 +360,7 @@ Use this whenever you are writing or reviewing SvelteKit route files (\`+page.sv
 
 1. After writing or editing code, run \`npx svelte-vitals . --diff --reporter agent\` and fix any findings it reports.
 2. Before committing, run \`npx svelte-vitals . --staged\` as a pre-commit gate.
-3. For a rule's full rationale and fix examples, use the \`explain_rule\` MCP tool (svelte-vitals MCP server) or open its docs link below.
+3. For a rule's full rationale, configurable options and fix examples, run \`npx svelte-vitals explain <rule-id>\` (add \`--json\` for a structured object) or open its docs link below.
 
 ## Rule digest
 
@@ -535,9 +451,9 @@ Every svelte-vitals rule already carries a reviewer-written fix:
 \`recommendation\` (one line), and where applicable \`fix.description\` +
 \`fix.snippet\` (literal code to drop in). These are embedded verbatim in the
 rule catalog below \u2014 copy them into the plan's Target section, never
-approximate from memory. For the full rationale behind a rule, use the
-\`explain_rule\` MCP tool (if the svelte-vitals MCP server is configured) or
-open its docs link, also in the catalog below.
+approximate from memory. For the full rationale behind a rule, run
+\`npx svelte-vitals explain <rule-id>\` (it also names the rule's configurable
+options) or open its docs link, also in the catalog below.
 
 ## Workflow
 
@@ -559,8 +475,7 @@ Get the machine map before applying judgment:
   findings even appear (see Hard Rule 5).
 - **Stack**: SvelteKit version, static/prerendered vs. SSR vs. adapter-node,
   whether the Vite dev dashboard (\`@svelte-vitals/vite\`, \`ui: true\`) is
-  already wired up, whether an MCP client or the \`svelte-vitals\` skill is
-  already installed.
+  already wired up, whether the \`svelte-vitals\` skill is already installed.
 - **Verification commands**: read \`package.json\`'s \`scripts\` \u2014 do not assume
   a specific package manager; this project's build/typecheck/test/lint
   commands may differ from svelte-vitals' own repo.
@@ -786,7 +701,7 @@ adapted to this file \u2014 never approximated from memory.
 ## Tone
 
 State findings plainly with evidence, and cite the rule id so the reader can
-look it up in the catalog above or via \`explain_rule\`. A short list of
+look it up in the catalog above or via \`svelte-vitals explain\`. A short list of
 high-confidence, high-leverage plans beats a long padded one \u2014 "this route
 is already solid" is a valid audit result. Flag uncertainty honestly: when
 correctness can't be judged from static code alone (a race that depends on
@@ -824,7 +739,7 @@ ${options}
 }
 
 // src/install/config-file-format.ts
-import { join as join2 } from "path";
+import { join } from "path";
 function nodeSupportsNativeTypeScript(version) {
   const match = /^v?(\d+)\.(\d+)/.exec(version);
   if (!match) return false;
@@ -833,10 +748,10 @@ function nodeSupportsNativeTypeScript(version) {
   return major > 23 || major === 23 && minor >= 6 || major === 22 && minor >= 18;
 }
 function findExistingConfigFile(readFile, cwd) {
-  return CONFIG_FILENAMES.find((rel) => readFile(join2(cwd, rel)) !== void 0);
+  return CONFIG_FILENAMES.find((rel) => readFile(join(cwd, rel)) !== void 0);
 }
 function hasSvelteVitalsDependency(readFile, cwd) {
-  const raw = readFile(join2(cwd, "package.json"));
+  const raw = readFile(join(cwd, "package.json"));
   if (raw === void 0) return false;
   try {
     const pkg = JSON.parse(raw);
@@ -846,7 +761,7 @@ function hasSvelteVitalsDependency(readFile, cwd) {
   }
 }
 function isEsmProject(readFile, cwd) {
-  const raw = readFile(join2(cwd, "package.json"));
+  const raw = readFile(join(cwd, "package.json"));
   if (raw === void 0) return false;
   try {
     return JSON.parse(raw).type === "module";
@@ -856,7 +771,7 @@ function isEsmProject(readFile, cwd) {
 }
 function detectBestConfigExtension(opts) {
   if (!nodeSupportsNativeTypeScript(opts.nodeVersion)) return "mjs";
-  const looksTypeScript = opts.readFile(join2(opts.cwd, "tsconfig.json")) !== void 0 || opts.readFile(join2(opts.cwd, "vite.config.ts")) !== void 0;
+  const looksTypeScript = opts.readFile(join(opts.cwd, "tsconfig.json")) !== void 0 || opts.readFile(join(opts.cwd, "vite.config.ts")) !== void 0;
   if (!looksTypeScript) return "mjs";
   return hasSvelteVitalsDependency(opts.readFile, opts.cwd) ? "ts" : "mjs";
 }
@@ -967,7 +882,7 @@ function codemodHooksServer(existing) {
 }
 
 // src/install/package-manager.ts
-import { join as join3 } from "path";
+import { join as join2 } from "path";
 var LOCKFILE_TO_PM = {
   "pnpm-lock.yaml": "pnpm",
   "yarn.lock": "yarn",
@@ -977,7 +892,7 @@ var LOCKFILE_TO_PM = {
 };
 function detectPackageManagerFromLockfile(io) {
   for (const [file, pm] of Object.entries(LOCKFILE_TO_PM)) {
-    if (io.readFile(join3(io.cwd, file)) !== void 0) return pm;
+    if (io.readFile(join2(io.cwd, file)) !== void 0) return pm;
   }
   return void 0;
 }
@@ -985,7 +900,7 @@ function detectPackageManager(io) {
   return detectPackageManagerFromLockfile(io) ?? "npm";
 }
 function hasVitePackage(io) {
-  const raw = io.readFile(join3(io.cwd, "package.json"));
+  const raw = io.readFile(join2(io.cwd, "package.json"));
   if (raw === void 0) return false;
   try {
     const pkg = JSON.parse(raw);
@@ -999,7 +914,7 @@ function installCommand(pm) {
   return { command: pm, args: [action, "-D", "@svelte-vitals/vite"] };
 }
 function readInstalledViteVersion(io) {
-  const raw = io.readFile(join3(io.cwd, "node_modules/@svelte-vitals/vite/package.json"));
+  const raw = io.readFile(join2(io.cwd, "node_modules/@svelte-vitals/vite/package.json"));
   if (raw === void 0) return void 0;
   try {
     return JSON.parse(raw).version;
@@ -1016,19 +931,13 @@ var ACTION_VERSION = "0.4.0";
 function detectPackageManagerNear(io, appDir) {
   return detectPackageManagerFromLockfile({ ...io, cwd: appDir }) ?? detectPackageManager(io);
 }
-function planForClient(client, scope, io, force) {
-  const path = client.resolvePath(scope, io.cwd, io.home);
-  const existing = io.readFile(path);
-  const merged = client.format === "toml" ? mergeToml(existing, MCP_ENTRY, force) : mergeJson(existing, MCP_ENTRY, force);
-  return { id: client.id, label: client.label, scope, path, status: merged.status, content: merged.content };
-}
 function resolveCandidate(io, baseDir, candidates) {
   for (const rel of candidates) {
-    const path = join4(baseDir, rel);
+    const path = join3(baseDir, rel);
     const content = io.readFile(path);
     if (content !== void 0) return { path, content };
   }
-  return { path: join4(baseDir, candidates[0]), content: void 0 };
+  return { path: join3(baseDir, candidates[0]), content: void 0 };
 }
 function planForVitePlugin(io, appDir) {
   const { path, content } = resolveCandidate(io, appDir, ["vite.config.ts", "vite.config.js", "vite.config.mjs"]);
@@ -1057,7 +966,7 @@ function agentTargetContent(id, version) {
 function planForAgentTarget(target, io, force, version) {
   const content = agentTargetContent(target.id, version);
   return target.relPaths.map((relPath) => {
-    const path = join4(io.cwd, relPath);
+    const path = join3(io.cwd, relPath);
     const existing = io.readFile(path);
     const status = existing === void 0 ? "created" : force ? "updated" : "exists";
     return { id: target.id, label: target.label, path, status, content };
@@ -1066,7 +975,7 @@ function planForAgentTarget(target, io, force, version) {
 function planForConfigTarget(target, io, force, appDir) {
   const existingRel = findExistingConfigFile(io.readFile, appDir);
   if (existingRel !== void 0) {
-    const path2 = join4(appDir, existingRel);
+    const path2 = join3(appDir, existingRel);
     const status = force ? "updated" : "exists";
     const content2 = force ? buildConfigFileTemplate({
       useDefineConfig: existingRel.endsWith(".ts") && hasSvelteVitalsDependency(io.readFile, appDir),
@@ -1079,12 +988,12 @@ function planForConfigTarget(target, io, force, appDir) {
     cwd: appDir,
     nodeVersion: io.nodeVersion ?? process.version
   });
-  const path = join4(appDir, `svelte-vitals.config.${ext}`);
+  const path = join3(appDir, `svelte-vitals.config.${ext}`);
   const content = buildConfigFileTemplate({ useDefineConfig: ext === "ts" });
   return { id: target.id, label: target.label, path, status: "created", content };
 }
 function planForCiTarget(target, io, force) {
-  const path = join4(io.cwd, target.relPath);
+  const path = join3(io.cwd, target.relPath);
   const existing = io.readFile(path);
   const plan = planWorkflowWrite(existing, force);
   const content = plan.status === "exists" ? void 0 : buildWorkflowYaml({ actionSha: ACTION_SHA, actionVersion: ACTION_VERSION });
@@ -1094,7 +1003,7 @@ function indent(text) {
   return text.split("\n").map((l) => `      ${l}`).join("\n");
 }
 function rowLine(r) {
-  const head = `  ${r.label}${r.scope ? ` (${r.scope})` : ""} \u2192 ${r.path}  [${r.status}]`;
+  const head = `  ${r.label} \u2192 ${r.path}  [${r.status}]`;
   return r.status === "manual" && r.snippet ? `${head}
 ${indent(r.snippet)}` : head;
 }
@@ -1104,7 +1013,7 @@ async function runRefresh(io, flags, version) {
   for (const target of AGENT_TARGETS) {
     const content = agentTargetContent(target.id, version);
     for (const relPath of target.relPaths) {
-      const path = join4(io.cwd, relPath);
+      const path = join3(io.cwd, relPath);
       try {
         if (io.readFile(path) === void 0) continue;
         rows.push({ id: target.id, label: target.label, path, status: "updated", content });
@@ -1157,29 +1066,30 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
         return false;
       }
     };
-    const detectedClients = CLIENTS.filter(
-      (c) => c.scopes.some((s) => configExists(c.resolvePath(s, io.cwd, io.home)))
-    ).map((c) => c.id);
     const viteConfigExists = ["vite.config.ts", "vite.config.js", "vite.config.mjs"].some(
-      (f) => configExists(join4(io.cwd, f))
+      (f) => configExists(join3(io.cwd, f))
     );
-    const claudeSkillDetected = configExists(join4(io.cwd, ".claude", "settings.json"));
-    const cursorRulesDetected = configExists(join4(io.cwd, ".cursor", "mcp.json"));
+    const claudeSkillDetected = configExists(join3(io.cwd, ".claude", "settings.json"));
+    const cursorRulesDetected = [
+      ".cursor/mcp.json",
+      ".cursor/environment.json",
+      ".cursorrules",
+      ".cursorignore",
+      agentTargetById("cursor-rules").relPaths[0]
+    ].some((rel) => configExists(join3(io.cwd, rel)));
     const detectedAgents = [
       ...claudeSkillDetected ? ["claude-skill"] : [],
       ...cursorRulesDetected ? ["cursor-rules"] : []
     ];
-    const ciWorkflowDetected = configExists(join4(io.cwd, CI_TARGETS[0].relPath));
+    const ciWorkflowDetected = configExists(join3(io.cwd, CI_TARGETS[0].relPath));
     const configFileDetected = findExistingConfigFile((p3) => configExists(p3) ? "" : void 0, io.cwd) !== void 0;
     const detected = [
-      ...detectedClients,
       ...viteConfigExists ? VITE_TARGETS.map((t) => t.id) : [],
       ...detectedAgents,
       ...ciWorkflowDetected ? CI_TARGETS.map((t) => t.id) : [],
       ...configFileDetected ? CONFIG_TARGETS.map((t) => t.id) : []
     ];
     const groups = {
-      "MCP server": CLIENTS.map((c) => ({ id: c.id, label: c.label })),
       "Vite integration": VITE_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
       "Agent Skills & rules": AGENT_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
       "CI (GitHub Actions)": CI_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
@@ -1193,25 +1103,24 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     ids = picked;
   } else {
     io.errorLog(
-      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file,ci-workflow> to install non-interactively."
+      "svelte-vitals: no TTY; pass --client <vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file,ci-workflow> to install non-interactively."
     );
     return 2;
   }
-  const clients = ids.map(clientById).filter((c) => c !== void 0);
   const viteIds = ids.filter(isViteTargetId);
   const agentIds = ids.filter(isAgentTargetId);
   const configIds = ids.filter(isConfigTargetId);
   const ciIds = ids.filter(isCiTargetId);
-  if (clients.length === 0 && viteIds.length === 0 && agentIds.length === 0 && configIds.length === 0 && ciIds.length === 0) {
-    io.errorLog("svelte-vitals: no valid clients or targets selected.");
+  if (viteIds.length === 0 && agentIds.length === 0 && configIds.length === 0 && ciIds.length === 0) {
+    io.errorLog("svelte-vitals: no valid targets selected.");
     return 2;
   }
   const isSvelteKitApp = (dir) => {
     try {
-      if (io.readFile(join4(dir, "svelte.config.js")) !== void 0 || io.readFile(join4(dir, "svelte.config.ts")) !== void 0) {
+      if (io.readFile(join3(dir, "svelte.config.js")) !== void 0 || io.readFile(join3(dir, "svelte.config.ts")) !== void 0) {
         return true;
       }
-      const pkgRaw = io.readFile(join4(dir, "package.json"));
+      const pkgRaw = io.readFile(join3(dir, "package.json"));
       if (pkgRaw === void 0) return false;
       const pkg = JSON.parse(pkgRaw);
       return Boolean(pkg.dependencies?.["@sveltejs/kit"] ?? pkg.devDependencies?.["@sveltejs/kit"]);
@@ -1223,7 +1132,7 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
   let appDir = io.cwd;
   if (needsApp) {
     if (flags.app) {
-      const candidate = join4(io.cwd, flags.app);
+      const candidate = join3(io.cwd, flags.app);
       if (!isSvelteKitApp(candidate)) {
         io.errorLog(
           `svelte-vitals: --app '${flags.app}' is not a SvelteKit app (no svelte.config.{js,ts} or @sveltejs/kit dependency there).`
@@ -1235,7 +1144,7 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
       const apps = await (io.discoverApps ?? discoverApps)(io.cwd);
       if (apps.length === 1) {
         io.errorLog(`svelte-vitals: detected SvelteKit app at ${apps[0]}; targeting it for the Vite/config targets.`);
-        appDir = join4(io.cwd, apps[0]);
+        appDir = join3(io.cwd, apps[0]);
       } else if (apps.length > 1) {
         if (io.isTTY) {
           const picked = await prompts.selectApp(apps);
@@ -1243,7 +1152,7 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
             io.log("Cancelled.");
             return 0;
           }
-          appDir = join4(io.cwd, picked);
+          appDir = join3(io.cwd, picked);
         } else {
           io.errorLog(`svelte-vitals: multiple SvelteKit apps found: ${apps.join(", ")}.`);
           io.errorLog(`svelte-vitals: pass one with --app, e.g. \`svelte-vitals install --app ${apps[0]}\`.`);
@@ -1253,35 +1162,16 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     }
   }
   const rows = [];
-  for (const client of clients) {
-    let scope;
-    if (client.scopes.length === 1) {
-      scope = client.scopes[0];
-    } else if (flags.scope) {
-      scope = flags.scope;
-    } else if (io.isTTY) {
-      const picked = await prompts.selectScope(client);
-      if (picked === null) {
-        io.log("Cancelled.");
-        return 0;
-      }
-      scope = picked;
-    } else {
-      scope = "project";
-    }
+  for (const viteId of viteIds) {
     try {
-      rows.push(planForClient(client, scope, io, flags.force ?? false));
+      rows.push(viteId === "vite-plugin" ? planForVitePlugin(io, appDir) : planForViteHooks(io, appDir));
     } catch (err) {
-      const path = client.resolvePath(scope, io.cwd, io.home);
       io.errorLog(
-        `svelte-vitals: could not parse existing config at ${path}: ${err instanceof Error ? err.message : String(err)}`
+        `svelte-vitals: could not check existing Vite target ${viteId}: ${err instanceof Error ? err.message : String(err)}`
       );
       return 2;
     }
   }
-  for (const viteId of viteIds) {
-    rows.push(viteId === "vite-plugin" ? planForVitePlugin(io, appDir) : planForViteHooks(io, appDir));
-  }
   for (const agentId of agentIds) {
     const target = agentTargetById(agentId);
     try {
@@ -1310,7 +1200,7 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
       rows.push(planForCiTarget(target, io, flags.force ?? false));
     } catch (err) {
       io.errorLog(
-        `svelte-vitals: could not check existing workflow at ${join4(io.cwd, target.relPath)}: ${err instanceof Error ? err.message : String(err)}`
+        `svelte-vitals: could not check existing workflow at ${join3(io.cwd, target.relPath)}: ${err instanceof Error ? err.message : String(err)}`
       );
       return 2;
     }
@@ -1375,7 +1265,7 @@ ${indent(r.snippet ?? "")}`);
   }
   if (hadFailure) return 2;
   io.log("");
-  if (clients.length > 0) io.log("Restart your client to load the svelte-vitals MCP server.");
+  if (agentIds.length > 0) io.log("Restart your agent (or start a new session) to pick up the generated skill.");
   if (viteWasWritten) io.log("Restart `vite dev` (or your build) to pick up the change.");
   io.log("Done.");
   return 0;
@@ -1383,7 +1273,6 @@ ${indent(r.snippet ?? "")}`);
 
 // src/install/args.ts
 var VALID_TARGETS = [
-  ...CLIENTS.map((c) => c.id),
   ...VITE_TARGETS.map((t) => t.id),
   ...AGENT_TARGETS.map((t) => t.id),
   ...CONFIG_TARGETS.map((t) => t.id),
@@ -1405,11 +1294,8 @@ function resolveInstallArgs(argv) {
   if (rawClients.length > 0 && client.length === 0) {
     errors.push(`svelte-vitals: no valid --client values; expected ${EXPECTED_TARGETS}.`);
   }
-  let scope;
-  const rawScope = argv.scope;
-  if (typeof rawScope === "string") {
-    if (rawScope === "project" || rawScope === "global") scope = rawScope;
-    else errors.push(`svelte-vitals: unknown --scope '${rawScope}'; expected project|global.`);
+  if (argv.scope !== void 0) {
+    warnings.push("svelte-vitals: --scope is no longer used (all install targets are project-scoped). Ignoring.");
   }
   const app = typeof argv.app === "string" && argv.app.trim() !== "" ? argv.app.trim() : void 0;
   const refresh = Boolean(argv.refresh);
@@ -1417,13 +1303,12 @@ function resolveInstallArgs(argv) {
     errors.push("svelte-vitals: --refresh regenerates existing files and cannot be combined with --client.");
   }
   if (errors.length > 0) return { flags: null, warnings, errors };
-  if (refresh && (scope !== void 0 || Boolean(argv.yes) || Boolean(argv.force) || app !== void 0)) {
-    warnings.push("svelte-vitals: --scope, --yes, --force, and --app are ignored with --refresh.");
+  if (refresh && (Boolean(argv.yes) || Boolean(argv.force) || app !== void 0)) {
+    warnings.push("svelte-vitals: --yes, --force, and --app are ignored with --refresh.");
   }
   return {
     flags: {
       ...client.length > 0 ? { client } : {},
-      ...scope ? { scope } : {},
       ...app !== void 0 && !refresh ? { app } : {},
       yes: Boolean(argv.yes),
       dryRun: Boolean(argv["dry-run"]),
@@ -1436,15 +1321,15 @@ function resolveInstallArgs(argv) {
 }
 
 // src/install/cli.ts
-var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals MCP server, Vite integration, agent skills/rules, and CI
+var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals Vite integration, agent skills/rules, config file, and CI
 
 Usage:
   svelte-vitals install [options]
 
 Options:
-  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file,ci-workflow
+  --client <ids>    Comma-separated: vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file,ci-workflow
                     (skips the interactive picker; the picker groups these by category \u2014
-                    MCP server, Vite integration, Agent Skills & rules, CI, Config file)
+                    Vite integration, Agent Skills & rules, CI, Config file)
                     vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-hooks
                     wires up the svelteVitalsHandle hook in src/hooks.server.{ts,js}, which improves the
                     live dashboard's per-route accuracy as you browse. --force does not apply
@@ -1467,13 +1352,12 @@ Options:
                     \`svelte-vitals ci install\` writes standalone \u2014 pick it here to set it up in
                     the same pass as everything else; supports --force to regenerate. \`svelte-vitals
                     ci upgrade\` remains the way to bump an existing workflow's pinned action version.
-  --scope <scope>   project | global (applies to all selected clients; codex is always global)
   --app <dir>       Monorepo: the SvelteKit app directory the vite-plugin/vite-hooks/config-file
                     targets write into (e.g. --app apps/web). Without it, when the current
                     directory isn't itself a SvelteKit app, one detected app is used
                     automatically (with a notice), several prompt a picker on a TTY, and
-                    non-interactive runs exit 2 asking for --app. All other targets (MCP
-                    configs, skills, ci-workflow) always write at the current directory \u2014
+                    non-interactive runs exit 2 asking for --app. All other targets
+                    (skills, ci-workflow) always write at the current directory \u2014
                     the repo root is their correct home.
   --yes, -y         Skip the confirmation prompt
   --dry-run         Print the planned changes and exit without writing
@@ -1497,7 +1381,6 @@ function realIO() {
       writeFileSync(path, content);
     },
     cwd: process.cwd(),
-    home: homedir(),
     isTTY: Boolean(process.stdout.isTTY),
     nodeVersion: process.version,
     log: (line) => console.log(line),
@@ -1537,14 +1420,6 @@ function clackPrompts() {
       });
       return p.isCancel(res) ? null : res;
     },
-    selectScope: async (client) => {
-      const res = await p.select({
-        message: `Scope for ${client.label}?`,
-        options: client.scopes.map((s) => ({ value: s, label: s })),
-        initialValue: client.scopes[0]
-      });
-      return p.isCancel(res) ? null : res;
-    },
     selectApp: async (apps) => {
       const res = await p.select({
         message: "Multiple SvelteKit apps found \u2014 which one should the Vite/config targets go into?",
@@ -1563,6 +1438,8 @@ ${planText}` });
 async function runInstallCli(args) {
   const argv = mri(args, {
     boolean: ["yes", "dry-run", "force", "refresh", "help"],
+    // `scope` is still declared although the flag is gone: it keeps `--scope global` from
+    // parsing its value as a positional, so resolveInstallArgs can warn and carry on.
     string: ["client", "scope", "app"],
     alias: { y: "yes", h: "help" }
   });
@@ -1578,7 +1455,7 @@ async function runInstallCli(args) {
 }
 
 // src/ci/cli.ts
-import { join as join5 } from "path";
+import { join as join4 } from "path";
 import mri2 from "mri";
 
 // src/ci/upgrade.ts
@@ -1656,7 +1533,7 @@ async function runCiCli(args, io = realIO()) {
     io.log(CI_HELP);
     return 0;
   }
-  const path = join5(io.cwd, WORKFLOW_PATH);
+  const path = join4(io.cwd, WORKFLOW_PATH);
   const existing = io.readFile(path);
   const plan = planWorkflowWrite(existing, Boolean(argv.force));
   io.log("Plan:");
@@ -1690,7 +1567,7 @@ async function runCiUpgrade(args, io) {
     io.log(CI_HELP);
     return 0;
   }
-  const path = join5(io.cwd, WORKFLOW_PATH);
+  const path = join4(io.cwd, WORKFLOW_PATH);
   const existing = io.readFile(path);
   if (existing === void 0) {
     io.errorLog(`svelte-vitals: no ${WORKFLOW_PATH} found \u2014 run \`svelte-vitals ci install\` first.`);
@@ -1720,12 +1597,76 @@ async function runCiUpgrade(args, io) {
   return 0;
 }
 
+// src/explain.ts
+import mri3 from "mri";
+import { explainRule } from "@svelte-vitals/core";
+var EXPLAIN_HELP = `svelte-vitals explain \u2014 print a rule's rationale, fix, and configurable options
+
+Usage:
+  svelte-vitals explain <rule-id>
+
+Options:
+  --json        Print the rule metadata as JSON instead of text
+  -h, --help    Show this help
+
+Rule ids are category/kebab-case and matched exactly, e.g. \`svelte-vitals explain seo/ssr-disabled\`.`;
+var realIO2 = {
+  log: (line) => console.log(line),
+  errorLog: (line) => console.error(line)
+};
+function describeOptions(id, options) {
+  const MERGE = {
+    integer: "replaces the default",
+    "string-list": "added to the default entries, never replaces them",
+    "string-map": "merged over the default entries \u2014 a new key is added, a built-in key has its value overridden"
+  };
+  const lines = options.map((o) => {
+    const bounds = [o.min !== void 0 ? `>= ${o.min}` : "", o.max !== void 0 ? `<= ${o.max}` : ""].filter(Boolean).join(", ");
+    return `- ${o.name} (${o.kind}, default ${JSON.stringify(o.default)}${bounds ? `, ${bounds}` : ""}) \u2014 ${MERGE[o.kind]}`;
+  });
+  return `set in svelte-vitals.config.* as \`rules: { '${id}': { options: { \u2026 } } }\`, or per path in \`overrides\`:
+${lines.join("\n")}`;
+}
+function formatRuleExplanation(info) {
+  return `${info.id} \u2014 ${info.title} (${info.severity}, ${info.category})
+
+${info.rationale}
+
+Docs: ${info.docsUrl}` + (info.fix ? `
+
+Fix: ${info.fix.description}` : "") + (info.options ? `
+
+Configurable: ${describeOptions(info.id, info.options)}` : "");
+}
+function runExplainCli(args, io = realIO2) {
+  const argv = mri3(args, { boolean: ["json", "help"], alias: { h: "help" } });
+  if (argv.help) {
+    io.log(EXPLAIN_HELP);
+    return 0;
+  }
+  const id = argv._[0];
+  if (id === void 0) {
+    io.errorLog("svelte-vitals: explain needs a rule id, e.g. `svelte-vitals explain seo/ssr-disabled`.");
+    io.errorLog(`svelte-vitals: known rule ids: ${knownRuleIds().join(", ")}.`);
+    return 2;
+  }
+  const info = explainRule(String(id));
+  if (!info) {
+    io.errorLog(`svelte-vitals: unknown rule id '${id}'.`);
+    io.errorLog(`svelte-vitals: known rule ids: ${knownRuleIds().join(", ")}.`);
+    return 2;
+  }
+  io.log(argv.json ? JSON.stringify(info, null, 2) : formatRuleExplanation(info));
+  return 0;
+}
+
 // src/bin.ts
 var HELP = `svelte-vitals \u2014 a deterministic SvelteKit code-health scanner (SEO \xB7 performance \xB7 correctness \xB7 security \xB7 architecture)
 
 Usage:
   svelte-vitals [path] [options]
-  svelte-vitals install          Set up the MCP server, Vite integration, or agent skills/rules
+  svelte-vitals explain <id>     Print a rule's rationale, fix, and configurable options
+  svelte-vitals install          Set up the Vite integration, agent skills/rules, config file, or CI
   svelte-vitals ci install       Add a GitHub Actions PR gate (annotations + summary comment)
   svelte-vitals ci upgrade       Refresh the pinned @svelte-vitals/action in an existing workflow
 
@@ -1771,6 +1712,9 @@ async function selectApp(apps) {
 }
 async function main() {
   const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === "explain") {
+    process.exit(runExplainCli(rawArgs.slice(1)));
+  }
   if (rawArgs[0] === "install") {
     const code2 = await runInstallCli(rawArgs.slice(1));
     process.exit(code2);
@@ -1779,7 +1723,7 @@ async function main() {
     const code2 = await runCiCli(rawArgs.slice(1));
     process.exit(code2);
   }
-  const argv = mri3(process.argv.slice(2), {
+  const argv = mri4(process.argv.slice(2), {
     alias: { h: "help", v: "version" },
     boolean: ["by-route", "staged", "score", "verbose", "update-suppressions"],
     string: [

package/dist/index.d.ts

@@ -190,7 +190,7 @@ interface AnalyzeOptions {
      * the route/layout (head-resolution) parse path via `collectRoutes` —
      * `collectComponentFacts` (Correctness facts) is unaffected and still scans
      * every component on each call. Callers that don't need cross-call reuse
-     * (the CLI's `run()`, MCP, the Action — each analyzes once per process) can
+     * (the CLI's `run()`, the Action — each analyzes once per process) can
      * omit this; a fresh cache is created automatically.
      */
     parseCache?: ParseCache;
@@ -207,7 +207,7 @@ interface AnalyzeResult {
  * Throws ProjectError when `cwd` is not a SvelteKit project. Also throws when a
  * `svelte-vitals.config.{mjs,js,ts}` file in `cwd` fails to load or fails
  * validation (unknown rule ids in `rules`, invalid `weights` entries) — see
- * `loadConfigFile`. Shared by the CLI's run() and by @svelte-vitals/mcp (issue #24).
+ * `loadConfigFile`. Shared by the CLI's run() and by embedding callers (issue #24).
  *
  * Config precedence is per field: an explicit option here wins, otherwise the
  * config file's value is used, otherwise the built-in default (design doc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "A SvelteKit SEO checker — not a runtime Web Vitals reporter. Static analysis of your routes' head metadata.",
   "type": "module",
   "license": "MIT",
@@ -43,10 +43,9 @@
     "log-update": "^8.0.0",
     "magicast": "^0.5.3",
     "mri": "^1.2.0",
-    "smol-toml": "^1.7.1",
     "svelte": "^5.56.8",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.31.0"
+    "@svelte-vitals/core": "0.31.1"
   },
   "devDependencies": {
     "@types/estree": "^1.0.9",