svelte-vitals 0.35.0 → 0.37.0

package/README.md

@@ -78,12 +78,25 @@ 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 docs` / `svelte-vitals explain`
+
+Both read out of the CLI itself, so the answer always matches the installed version and needs no network — the thing an AI agent otherwise guesses at or fetches from a page describing a different release.
+
+```bash
+npx svelte-vitals@latest docs list             # every bundled topic, with a one-line description
+npx svelte-vitals@latest docs show scoping
+npx svelte-vitals@latest explain --list        # every rule, by category
+npx svelte-vitals@latest explain performance/heavy-import
+```
+
+`explain <rule-id>` prints that 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: the detail needed to decide whether a finding is a defect or a threshold disagreement. `docs list` and both forms of `explain` take `--json`; `docs show` prints the topic as Markdown.
+
 ### 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

@@ -9,10 +9,13 @@ import {
   readCoreVersion,
   readPackageVersion,
   run
-} from "./chunk-D6AUX2GC.js";
+} from "./chunk-I2MKPWWT.js";
+import {
+  consoleIO
+} from "./chunk-SLUMRYUD.js";
 
 // src/bin.ts
-import mri3 from "mri";
+import mri4 from "mri";
 import * as p2 from "@clack/prompts";
 
 // src/resolve-args.ts
@@ -179,96 +182,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 +363,8 @@ 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.
+4. For anything else \u2014 reporters, the config file, scoping to a change, CI, monorepos \u2014 run \`npx svelte-vitals docs list\` and then \`npx svelte-vitals docs show <name>\`. Those guides ship inside the CLI, so they match the version installed here; prefer them over searching the web.
 
 ## Rule digest
 
@@ -535,9 +455,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 +479,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 +705,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 +743,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 +752,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 +765,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 +775,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 +886,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 +896,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 +904,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 +918,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 +935,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 +970,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 +979,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 +992,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 +1007,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 +1017,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 +1070,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 +1107,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 +1136,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 +1148,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 +1156,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 +1166,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 +1204,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 +1269,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 +1277,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 +1298,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 +1307,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 +1325,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 +1356,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 +1385,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 +1424,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 +1442,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 +1459,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 +1537,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 +1571,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 +1601,102 @@ async function runCiUpgrade(args, io) {
   return 0;
 }
 
+// src/explain.ts
+import mri3 from "mri";
+import { allRules as allRules2, CATEGORIES as CATEGORIES2, 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 --list          List every rule id, grouped by category
+  svelte-vitals explain <rule-id>       Explain one rule
+
+Options:
+  --list        List every rule instead of explaining one
+  --json        Machine-readable output (works with --list and with a rule id)
+  -h, --help    Show this help
+
+Rule ids are category/kebab-case and matched exactly, e.g. \`svelte-vitals explain seo/ssr-disabled\`.`;
+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 renderRuleList() {
+  const sections = CATEGORIES2.map((category) => {
+    const rules = allRules2.filter((r) => r.category === category);
+    const width = Math.max(...rules.map((r) => r.id.length));
+    const lines = rules.map((r) => `  ${r.id.padEnd(width)}  ${r.severity.padEnd(8)} ${r.title}`);
+    return [`${category} (${rules.length})`, ...lines].join("\n");
+  });
+  return [...sections, "", `${allRules2.length} rules. Explain one with \`svelte-vitals explain <rule-id>\`.`].join(
+    "\n\n"
+  );
+}
+function runExplainCli(args, io = consoleIO) {
+  const argv = mri3(args, { boolean: ["json", "list", "help"], alias: { h: "help" } });
+  if (argv.help) {
+    io.log(EXPLAIN_HELP);
+    return 0;
+  }
+  if (argv.list) {
+    if (argv._.length > 0) {
+      io.errorLog("svelte-vitals: explain --list takes no rule id; drop --list to explain one.");
+      return 2;
+    }
+    io.log(
+      argv.json ? JSON.stringify(
+        allRules2.map((r) => ({ id: r.id, category: r.category, severity: r.severity, title: r.title })),
+        null,
+        2
+      ) : renderRuleList()
+    );
+    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`; `--list` shows them all."
+    );
+    io.errorLog(`svelte-vitals: known rule ids: ${knownRuleIds().join(", ")}.`);
+    return 2;
+  }
+  const info = explainRule(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 docs list        List the bundled guides (docs show <name> prints one)
+  svelte-vitals explain --list   List every rule (explain <rule-id> explains one)
+  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
 
@@ -1760,7 +1731,24 @@ Config file:
 Exit codes:
   0  no failing findings
   1  critical finding present (or --fail-on threshold reached)
-  2  execution error (not a SvelteKit project / internal error)`;
+  2  execution error (not a SvelteKit project / internal error)
+
+If you are an AI agent:
+  - \`svelte-vitals docs list\` then \`docs show <name>\` \u2014 the guides ship inside this CLI, so
+    they match this exact version and need no network. Read those before searching the web.
+  - \`--reporter agent\` gives every failing finding a location, a concrete fix and an acceptance
+    check; it is auto-selected when an agent environment is detected. \`--reporter json\` is the
+    structured form.
+  - \`--diff\` scopes the report to what you just changed; \`--staged\` is the pre-commit gate.
+  - \`svelte-vitals explain <rule-id>\` says why a rule exists and which options it takes, before
+    you decide to turn it off.
+  - Do NOT reach for \`--update-suppressions\` to make a run pass: it accepts every current
+    finding into a committed file and un-gates CI for all of them. Fix the findings, or scope
+    the run with \`--diff\`. Only a human should decide to accept a backlog.
+  - Exit 2 is never a pass \u2014 it means the analysis did not run. Read stderr.
+  - Analysis never prompts when stdout is not a TTY: where it would have asked, it exits 2
+    naming the flag to pass. \`install\` is the exception \u2014 non-interactively it skips its
+    confirmation and writes, so pass \`--dry-run\` first if you need to see the plan.`;
 var VERSION = readPackageVersion();
 async function selectApp(apps) {
   const res = await p2.select({
@@ -1771,6 +1759,15 @@ async function selectApp(apps) {
 }
 async function main() {
   const rawArgs = process.argv.slice(2);
+  if (rawArgs[0] === "docs") {
+    const { runDocsCli } = await import("./cli-SOIIGBH7.js");
+    process.exitCode = runDocsCli(rawArgs.slice(1));
+    return;
+  }
+  if (rawArgs[0] === "explain") {
+    process.exitCode = runExplainCli(rawArgs.slice(1));
+    return;
+  }
   if (rawArgs[0] === "install") {
     const code2 = await runInstallCli(rawArgs.slice(1));
     process.exit(code2);
@@ -1779,7 +1776,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: [
@@ -1800,11 +1797,12 @@ async function main() {
   });
   if (argv.help) {
     console.log(HELP);
-    process.exit(0);
+    return;
   }
   if (argv.version) {
     console.log(`${VERSION} (core ${readCoreVersion()})`);
-    process.exit(0);
+    console.error("svelte-vitals: run `svelte-vitals docs list` for the bundled guides.");
+    return;
   }
   const { options, warnings, errors } = resolveArgs(argv);
   for (const w of warnings) console.error(w);

package/dist/{chunk-D6AUX2GC.js → chunk-I2MKPWWT.js}

@@ -109,7 +109,7 @@ async function detectProject(rt, cwd) {
   const hasRoutes = await rt.exists(rt.join(cwd, ROUTES_DIR));
   if (hasKitDep || hasConfig && hasRoutes) return;
   throw new ProjectError(
-    "No SvelteKit project found in the current directory. Run this inside a SvelteKit app, or pass a path (e.g. npx svelte-vitals apps/web)."
+    "No SvelteKit project found in the current directory. Run this inside a SvelteKit app, or pass a path (e.g. npx svelte-vitals apps/web). See `svelte-vitals docs show monorepo` for how the app is resolved."
   );
 }
 async function enumerateRoutePages(rt, cwd) {
@@ -1664,7 +1664,7 @@ async function run(opts = {}) {
     } else {
       if (reporter === "agent" && isAutoDetectedAgent(opts.reporter, env)) {
         errorLog(
-          "svelte-vitals: agent reporter auto-selected (AI-agent env detected); override with --reporter console|json."
+          "svelte-vitals: agent reporter auto-selected (AI-agent env detected); override with --reporter console|json. Run `svelte-vitals docs list` for the bundled guides."
         );
       }
       if (reporter === "github" && isAutoDetectedGithub(opts.reporter, env)) {

package/dist/chunk-SLUMRYUD.js

@@ -0,0 +1,9 @@
+// src/cli-io.ts
+var consoleIO = {
+  log: (line) => console.log(line),
+  errorLog: (line) => console.error(line)
+};
+
+export {
+  consoleIO
+};

package/dist/cli-SOIIGBH7.js

@@ -0,0 +1,120 @@
+import {
+  consoleIO
+} from "./chunk-SLUMRYUD.js";
+
+// src/docs/cli.ts
+import mri from "mri";
+
+// src/docs/generated.ts
+var EMBEDDED_DOCS = [
+  {
+    name: "ci",
+    title: "Running in CI",
+    description: "Scaffold a GitHub Actions PR gate with `ci install`, what the generated workflow does, and how to gate a pipeline without the Action.",
+    body: "# Running in CI\n\n## Scaffold the GitHub Actions gate\n\n```bash\nnpx svelte-vitals@latest ci install     # writes .github/workflows/svelte-vitals.yml\nnpx svelte-vitals@latest ci upgrade     # bump only the pinned action ref in an existing file\n```\n\n`ci install` also exists as the `ci-workflow` target inside `svelte-vitals install`, so it can be\nset up in the same pass as everything else. Both support `--dry-run` and `--force`.\n\n## What the generated workflow does\n\nOn every `pull_request` it checks out with `fetch-depth: 0` (so the base ref is resolvable), then\ncalls `@svelte-vitals/action`, which runs the analysis **in-process** \u2014 no `npx`, no separate\nscan per output \u2014 scoped to the PR with `diff: origin/<base>` and `baseline: origin/<base>`. From\nthat one analysis it produces:\n\n- inline annotations on the diff,\n- a job summary,\n- a sticky PR comment (a hidden `<!-- svelte-vitals-report -->` marker updates the same comment\n  instead of piling up new ones).\n\nIt fails the job **after** the summary and comment are written, so a failing run still leaves the\nfeedback behind.\n\nAction inputs: `path` (default `.`), `diff`, `baseline`, `github-token`. There is no `reporter`\ninput \u2014 the fan-out is fixed. The action reads your committed `svelte-vitals.config.*` and\n`svelte-vitals-suppressions.json` like the CLI does, so rule policy stays in those files.\n\nRequired permissions: `contents: read` and `pull-requests: write`. On PRs from forks GitHub\ndowngrades the token regardless, so the action detects that and skips the comment (never failing\nthe job); annotations and the summary still work.\n\n## Without the Action\n\nAny CI can run the CLI directly. On GitHub, `GITHUB_ACTIONS=true` auto-selects the `github`\nreporter, so annotations come for free \u2014 but a detected AI-agent environment outranks it, so a\njob driven by an agent gets `agent` instead. Pass `--reporter github` when you need the\nannotations regardless of who is running the job:\n\n```bash\npnpm build\nnpx svelte-vitals@latest --reporter github --fail-on warning\n```\n\nFor a PR gate that ignores a legacy backlog, pair the two scoping flags:\n\n```bash\nnpx svelte-vitals@latest --diff origin/main --baseline origin/main --fail-on warning\n```\n\nGate on the score instead of, or as well as, individual findings with `--min-health <0-100>`.\n\nExit `1` means findings gated the run; exit `2` means the run did not happen \u2014 fail the job\nloudly on `2` rather than treating it as a pass.\n\n## Related\n\n- `svelte-vitals docs show scoping` \u2014 what `--diff` / `--baseline` / suppressions each do\n- `svelte-vitals docs show output` \u2014 reporters and exit codes"
+  },
+  {
+    name: "config",
+    title: "The config file",
+    description: "Where svelte-vitals.config lives, every top-level option, how to disable or re-grade a rule, and how to scope rules to routes or files.",
+    body: "# The config file\n\n## Where it lives\n\nIn the **analyzed directory only** \u2014 no upward search. First match wins:\n\n1. `svelte-vitals.config.mjs`\n2. `svelte-vitals.config.js`\n3. `svelte-vitals.config.ts`\n\nNo file means built-in defaults. `svelte-vitals install --client config-file` scaffolds one with\nevery option commented out.\n\n```js\n// svelte-vitals.config.mjs\nexport default {\n  treatDynamicAs: 'warn',\n  metaComponents: ['Seo'],\n  rules: { 'seo/json-ld': 'off' },\n  failOn: 'warning',\n  weights: { seo: 2 }\n};\n```\n\nA `.ts` config can `import { defineConfig } from 'svelte-vitals'` for type-checking, but that is\na **runtime** import \u2014 it requires svelte-vitals to be a declared dependency, and Node 22.18+\n(or 23.6+) to load `.ts` at all. A plain `export default {}` in `.mjs` behaves identically and\nalways works.\n\n## Options\n\n| Option           | Type                                                           | Default            |\n| ---------------- | -------------------------------------------------------------- | ------------------ |\n| `treatDynamicAs` | `'pass' \\| 'warn' \\| 'fail'`                                   | `'pass'`           |\n| `metaComponents` | `string[]`                                                     | `[]`               |\n| `rules`          | `Record<ruleId, 'off' \\| Severity \\| { severity?, options? }>` | `{}`               |\n| `failOn`         | `'critical' \\| 'warning' \\| 'info'`                            | `'critical'`       |\n| `weights`        | `Partial<Record<Category, number>>`                            | every category `1` |\n| `overrides`      | `RuleOverride[]`                                               | (none)             |\n\n`Severity` is `'critical' | 'warning' | 'info'`. `Category` is `'seo' | 'performance' |\n'correctness' | 'security' | 'architecture'`. A weight of `0` drops a category from the Health\naverage; setting every category to `0` is an error (exit `2`).\n\n## Turning a rule off or down\n\n```js\nexport default {\n  rules: {\n    'seo/json-ld': 'off', // remove its findings entirely\n    'architecture/prop-count': 'info' // keep it, stop it failing the build\n  }\n};\n```\n\nBefore disabling a rule, check whether it is really a **threshold disagreement** rather than a\ndefect \u2014 many rules take options. `svelte-vitals explain <rule-id>` prints each option's name,\ndefault, bounds, and how a configured value merges with the built-in default (`integer`\nreplaces it, `string-list` appends to it, `string-map` is spread over it).\n\n```js\nexport default {\n  rules: {\n    'architecture/prop-count': { options: { max: 12 } }\n  }\n};\n```\n\n## Scoping to routes or files (`overrides`)\n\n`rules` applies everywhere; `overrides` applies only where it matches \u2014 typically routes that\nare deliberately not public.\n\n```js\nexport default {\n  overrides: [\n    { files: 'src/routes/(app)/**', rules: { seo: 'off' } },\n    { route: '/admin/**', rules: { 'seo/title-presence': 'info' } }\n  ]\n};\n```\n\nEach entry needs `rules` (keys are rule ids **or** category names) plus at least one of:\n\n- **`route`** \u2014 glob(s) against the route id as reported (`/blog/[slug]`). SvelteKit `(group)`\n  segments are **not** in the route id, so use `files` to target a group.\n- **`files`** \u2014 glob(s) against the source path.\n\nGlobs are deliberately small: `*` within a segment, `**` across segments, a trailing `/**` also\nmatches the bare prefix. Everything else \u2014 including `(`, `)`, `[`, `]` \u2014 is literal. Later\nentries win.\n\n## Precedence\n\nPer field: **CLI flag > config file > built-in default**. One exception \u2014 `--rules`/`--ignore`\nreplace the config file's `rules` wholesale for that run rather than merging.\n\n`overrides` has no CLI flag; route policy belongs in a committed file.\n\n## Validation\n\nAn unknown rule id, an unknown category or negative weight, a malformed `overrides` entry, or an\ninvalid rule setting is a **hard error (exit `2`)** \u2014 a typo must not silently un-gate CI. An\nunrecognized `treatDynamicAs`/`failOn` value or an unknown top-level key only warns.\n\n## Related\n\n- `svelte-vitals explain --list` \u2014 every rule id\n- `svelte-vitals docs show scoping` \u2014 accepting an existing backlog instead of disabling rules"
+  },
+  {
+    name: "monorepo",
+    title: "Monorepos",
+    description: "How svelte-vitals picks which SvelteKit app to analyze, why it exits 2 instead of prompting in a non-interactive shell, and how to name the app explicitly.",
+    body: '# Monorepos\n\n## Naming the app is always safest\n\n```bash\nnpx svelte-vitals@latest apps/web\n```\n\nAn explicit `path` \u2014 or running from inside the app directory \u2014 takes priority and skips\ndetection entirely. In a script, a hook, or an agent\'s shell, prefer this over relying on\ndetection.\n\n## What happens without a path\n\nWhen no `path` is given and the current directory is not itself a SvelteKit app, svelte-vitals\nlooks for nearby apps \u2014 a directory with `src/routes` **and** either a\n`svelte.config.{js,ts}` or a `package.json` declaring `@sveltejs/kit` (current `sv create`\noutput folds the SvelteKit config into `vite.config.ts` and emits no `svelte.config` file):\n\n| Found       | Interactive terminal                | Non-interactive (CI, agents, piped output)                 |\n| ----------- | ----------------------------------- | ---------------------------------------------------------- |\n| exactly one | analyzed, notice on stderr          | same \u2014 analyzed, notice on stderr                          |\n| several     | single-select prompt                | **exit `2`** listing the apps, asking for an explicit path |\n| none        | exit `2`, "not a SvelteKit project" | same                                                       |\n\n**svelte-vitals never prompts when stdout is not a TTY.** A non-interactive run with several apps\nfails fast with the list rather than hanging or guessing \u2014 if you hit exit `2` here, re-run with\nthe path it printed.\n\nCancelling the interactive prompt exits `0` without analyzing anything.\n\n## `install` in a monorepo\n\n`svelte-vitals install` splits its targets by where they belong:\n\n- `vite-plugin`, `vite-hooks`, `config-file` write into the **app** directory \u2014 they resolve it\n  the same way the analyzer does, and `--app <dir>` names it explicitly.\n- the agent skills and `ci-workflow` always write at the **current** directory, because the repo\n  root is their correct home.\n\n```bash\nnpx svelte-vitals@latest install --client vite-plugin,config-file --app apps/web --yes\n```\n\n`--app` pointing at a directory that is not a SvelteKit app is an error (exit `2`).\n\n## Related\n\n- `svelte-vitals docs show output` \u2014 what exit `2` means versus exit `1`'
+  },
+  {
+    name: "output",
+    title: "Reading the output",
+    description: "Which reporter to use, how one is auto-selected, what goes to stdout vs stderr, and what each exit code means.",
+    body: '# Reading the output\n\n## Pick a reporter\n\n`--reporter <fmt>`: `console` (default) \xB7 `json` \xB7 `agent` \xB7 `sarif` \xB7 `github` \xB7 `html` \xB7 `md`.\n\n- **`agent`** \u2014 a Markdown remediation document: every failing finding with its location, a\n  concrete fix (with a code snippet), and an acceptance check. This is the one to use when\n  something will act on the findings rather than read them.\n- **`json`** \u2014 the full structured report (per-route and site-wide scores, every finding with\n  `fix`, `recommendation` and `docsUrl`). Use it when you need to filter or count.\n- **`console`** \u2014 for a human at a terminal. Grouped and capped; add `--verbose` for everything.\n- **`md`** \u2014 a compact summary table for a PR comment or job summary (capped at 50 rows).\n- **`sarif`** \u2014 SARIF v2.1, for GitHub Code Scanning and other SAST tooling.\n- **`github`** \u2014 `::error` / `::warning` workflow annotations.\n- **`html`** \u2014 a self-contained report file; `--out-file <path>`, or `--out-file -` for stdout.\n\n## Auto-selection\n\nFirst match wins:\n\n1. an explicit `--reporter <fmt>`\n2. `SVELTE_VITALS_REPORTER=<fmt>`\n3. a known AI-agent environment (e.g. `CLAUDECODE` is set) \u2192 `agent`\n4. `GITHUB_ACTIONS=true` \u2192 `github`\n5. otherwise \u2192 `console`\n\nSo inside an agent harness you usually get `agent` without asking. When it is auto-selected\nrather than requested, a one-line hint goes to stderr explaining how to override.\n\n## stdout vs stderr\n\nThe report goes to **stdout**. Diagnostics \u2014 auto-selection hints, suppression counts,\napp-detection notices, warnings, errors \u2014 go to **stderr**. Piping stdout is safe; you will not\nget diagnostics mixed into the report.\n\n`--reporter html` is the exception: it writes a file and prints the path to stderr, unless you\npass `--out-file -`.\n\n## Exit codes\n\n| Code | Meaning                                                                    |\n| ---- | -------------------------------------------------------------------------- |\n| `0`  | no failing findings                                                        |\n| `1`  | a critical finding is present, or `--fail-on` / `--min-health` was reached |\n| `2`  | execution error \u2014 not a SvelteKit project, bad flag, unreadable config     |\n\n`1` means "the code has problems". `2` means "the run did not happen" \u2014 never treat `2` as a\nclean result. `--fail-on <critical|warning|info>` lowers the bar for `1`; `--min-health <0-100>`\nadds a score gate.\n\n## Related\n\n- `svelte-vitals docs show scoping` \u2014 report only what a change introduced\n- `svelte-vitals explain <rule-id>` \u2014 one rule\'s rationale, fix and options'
+  },
+  {
+    name: "scoping",
+    title: "Scoping findings to a change",
+    description: "Use --diff, --staged, --baseline and the suppressions file so only what a change introduced is reported, instead of a legacy backlog.",
+    body: "# Scoping findings to a change\n\nRunning svelte-vitals on an existing project usually surfaces a backlog nobody is about to fix.\nDo not disable rules to get a green run \u2014 scope the report instead.\n\n## Scope by file\n\n- **`--diff [ref]`** \u2014 only findings in files changed versus `ref` (default `HEAD`).\n- **`--staged`** \u2014 only findings in staged files. The pre-commit gate.\n\n```bash\nsvelte-vitals . --diff --reporter agent   # after editing: what did I just break?\nsvelte-vitals . --staged                  # before committing\n```\n\nBoth work when the project is not at the git repo root.\n\n## Scope by finding (`--baseline <ref>`)\n\n`--baseline` reports only findings **not already present** at `ref`. It scopes by finding\nidentity rather than by file, so a pre-existing problem in a file you touched does not fail the\ngate \u2014 only what your change actually introduced does. There is no default ref.\n\n```bash\nsvelte-vitals --diff origin/main --baseline origin/main --fail-on warning   # PR gate\n```\n\nInternally it checks `ref` out into a temporary git worktree and subtracts those findings. If\nthat fails (no git, bad ref), it warns and reports everything rather than failing the run.\n\n## Accept a backlog once (`svelte-vitals-suppressions.json`)\n\n`--baseline` handles the transient case. For a persistent ramp, record today's findings once:\n\n```bash\nsvelte-vitals --update-suppressions\ngit add svelte-vitals-suppressions.json\n```\n\n`--update-suppressions` analyzes the whole project (any `--diff`/`--staged`/`--baseline` scoping\nis ignored), writes every currently-penalized finding, prints a summary to stderr, and exits `0`\nwithout printing a report.\n\nOnce the file exists it applies automatically on every run, after `--diff`/`--staged` and\n`--baseline`, and reports how many findings it removed. Fixing an accepted finding leaves a\n**stale** entry \u2014 that is reported on stderr as a reminder to re-run `--update-suppressions`,\nbut never fails the run. `--no-suppressions` ignores the file for one run.\n\nA malformed suppressions file is a hard error (exit `2`), not a silent skip.\n\n## Which one\n\n| Situation                              | Use                                      |\n| -------------------------------------- | ---------------------------------------- |\n| Checking an edit you just made         | `--diff`                                 |\n| Pre-commit hook                        | `--staged`                               |\n| PR gate against a base branch          | `--diff <base> --baseline <base>`        |\n| Adopting on a legacy project, for good | `--update-suppressions`, commit the file |\n\nMatching ignores line numbers in both `--baseline` and the suppressions file, so a second\nviolation of the same rule lower in the same file does not surface as new.\n\n## Related\n\n- `svelte-vitals docs show ci` \u2014 the generated PR gate already does the `--diff`/`--baseline` pairing\n- `svelte-vitals docs show config` \u2014 turning a rule off for good, when that is genuinely right"
+  }
+];
+
+// src/docs/cli.ts
+var DOCS_HELP = `svelte-vitals docs \u2014 read the bundled guides without leaving the terminal
+
+Usage:
+  svelte-vitals docs list [--json]     List every topic with a one-line description
+  svelte-vitals docs show <name>       Print a topic
+
+Options:
+  --json        Machine-readable output (list only)
+  -h, --help    Show this help
+
+The topics ship inside the CLI, so they always match the version you are running and need no
+network. The full docs site is at https://oekazuma.github.io/svelte-vitals.
+
+\`docs\` is a subcommand, so it wins over a directory of the same name: to analyze a directory
+called \`docs\`, write \`svelte-vitals ./docs\`.`;
+function knownTopicNames() {
+  return EMBEDDED_DOCS.map((d) => d.name).join(", ");
+}
+function renderList() {
+  const width = Math.max(...EMBEDDED_DOCS.map((d) => d.name.length));
+  const lines = EMBEDDED_DOCS.map((d) => `  ${d.name.padEnd(width)}  ${d.description}`);
+  return [
+    "Topics (read one with `svelte-vitals docs show <name>`):",
+    "",
+    ...lines,
+    "",
+    "Rule-level detail is a separate command: `svelte-vitals explain --list`."
+  ].join("\n");
+}
+function runDocsCli(args, io = consoleIO) {
+  const argv = mri(args, { boolean: ["json", "help"], alias: { h: "help" } });
+  const [sub, ...rest] = argv._;
+  if (argv.help) {
+    io.log(DOCS_HELP);
+    return 0;
+  }
+  if (sub === void 0) {
+    io.errorLog(DOCS_HELP);
+    return 2;
+  }
+  if (sub === "list") {
+    if (rest.length > 0) {
+      io.errorLog("svelte-vitals: docs list takes no arguments; use `docs show <name>` to read one.");
+      return 2;
+    }
+    io.log(
+      argv.json ? JSON.stringify(
+        EMBEDDED_DOCS.map((d) => ({ name: d.name, title: d.title, description: d.description })),
+        null,
+        2
+      ) : renderList()
+    );
+    return 0;
+  }
+  if (sub === "show") {
+    if (rest.length !== 1) {
+      io.errorLog(
+        rest.length === 0 ? "svelte-vitals: docs show needs a topic name, e.g. `svelte-vitals docs show config`." : "svelte-vitals: docs show takes one topic at a time."
+      );
+      io.errorLog(`svelte-vitals: known topics: ${knownTopicNames()}.`);
+      return 2;
+    }
+    const doc = EMBEDDED_DOCS.find((d) => d.name === rest[0]);
+    if (!doc) {
+      io.errorLog(`svelte-vitals: unknown docs topic '${rest[0]}'.`);
+      io.errorLog(`svelte-vitals: known topics: ${knownTopicNames()}.`);
+      return 2;
+    }
+    io.log(doc.body);
+    return 0;
+  }
+  io.errorLog(`svelte-vitals: unknown docs subcommand '${sub}'; expected list|show.`);
+  io.errorLog(DOCS_HELP);
+  return 2;
+}
+export {
+  runDocsCli
+};

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/dist/index.js

@@ -11,7 +11,7 @@ import {
   ruleOptionsSpec,
   run,
   spinnerEnabled
-} from "./chunk-D6AUX2GC.js";
+} from "./chunk-I2MKPWWT.js";
 export {
   ProjectError,
   analyzeProject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.35.0",
+  "version": "0.37.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",
@@ -57,6 +56,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "gen:rules-index": "pnpm --filter @svelte-vitals/core build && node scripts/gen-rules-index.mjs",
-    "update-action-pin": "node scripts/gen-action-pin.mjs"
+    "update-action-pin": "node scripts/gen-action-pin.mjs",
+    "gen:docs": "node scripts/gen-docs.mjs"
   }
 }