npm - @agent-scope/cli - Versions diffs - 1.19.0 → 1.20.1 - Mend

@agent-scope/cli 1.19.0 → 1.20.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/index.js CHANGED Viewed

@@ -1,11 +1,12 @@
-import { existsSync, writeFileSync, mkdirSync, readFileSync, statSync, appendFileSync, readdirSync, rmSync, createReadStream } from 'fs';
-import { resolve, join, extname, dirname } from 'path';
+import { existsSync, writeFileSync, mkdirSync, readFileSync, statSync, appendFileSync, readdirSync, rmSync, createReadStream, constants, watch } from 'fs';
+import { resolve, join, dirname, extname } from 'path';
 import { generateManifest } from '@agent-scope/manifest';
 import { SpriteSheetGenerator, safeRender, BrowserPool, ALL_CONTEXT_IDS, contextAxis, stressAxis, ALL_STRESS_IDS, RenderMatrix, SatoriRenderer } from '@agent-scope/render';
 import { TokenResolver, ComplianceEngine, parseTokenFileSync, ThemeResolver, exportTokens, validateTokenFile, TokenValidationError, TokenParseError, ImpactAnalyzer } from '@agent-scope/tokens';
 import { Command } from 'commander';
 import * as esbuild2 from 'esbuild';
 import { createRequire } from 'module';
+import { mkdir, access, writeFile } from 'fs/promises';
 import * as readline from 'readline';
 import { loadTrace, generateTest, getBrowserEntryScript } from '@agent-scope/playwright';
 import { chromium } from 'playwright';
@@ -13,10 +14,15 @@ import { tmpdir } from 'os';
 import { createServer } from 'http';
 import { buildSite } from '@agent-scope/site';
-// src/ci/commands.ts
-async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss, wrapperScript) {
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+async function buildComponentHarness(filePath, componentName, props, viewportWidth, projectCss, wrapperScript, screenshotPadding = 0) {
   const bundledScript = await bundleComponentToIIFE(filePath, componentName, props);
-  return wrapInHtml(bundledScript, viewportWidth, projectCss, wrapperScript);
+  return wrapInHtml(bundledScript, viewportWidth, projectCss, wrapperScript, screenshotPadding);
 }
 async function bundleComponentToIIFE(filePath, componentName, props) {
   const propsJson = JSON.stringify(props).replace(/<\/script>/gi, "<\\/script>");
@@ -122,7 +128,7 @@ ${msg}`);
   }
   return outputFile.text;
 }
-function wrapInHtml(bundledScript, viewportWidth, projectCss, wrapperScript) {
+function wrapInHtml(bundledScript, viewportWidth, projectCss, wrapperScript, screenshotPadding = 0) {
   const projectStyleBlock = projectCss != null && projectCss.length > 0 ? `<style id="scope-project-css">
 ${projectCss.replace(/<\/style>/gi, "<\\/style>")}
 </style>` : "";
@@ -132,10 +138,17 @@ ${projectCss.replace(/<\/style>/gi, "<\\/style>")}
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=${viewportWidth}, initial-scale=1.0" />
+  <script>
+    // Reset globals that persist on window across page.setContent() calls
+    // (document.open/write/close clears the DOM but NOT the JS global scope)
+    window.__SCOPE_WRAPPER__ = null;
+    window.__SCOPE_RENDER_COMPLETE__ = false;
+    window.__SCOPE_RENDER_ERROR__ = null;
+  </script>
   <style>
     *, *::before, *::after { box-sizing: border-box; }
     html, body { margin: 0; padding: 0; background: #fff; font-family: system-ui, sans-serif; }
-    #scope-root { display: inline-block; min-width: 1px; min-height: 1px; }
+    #scope-root { display: inline-block; min-width: 1px; min-height: 1px; margin: ${screenshotPadding}px; }
   </style>
   ${projectStyleBlock}
 </head>
@@ -167,13 +180,15 @@ function buildTable(headers, rows) {
 }
 function formatListTable(rows) {
   if (rows.length === 0) return "No components found.";
-  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS"];
+  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS", "COLLECTION", "INTERNAL"];
   const tableRows = rows.map((r) => [
     r.name,
     r.file,
     r.complexityClass,
     String(r.hookCount),
-    String(r.contextCount)
+    String(r.contextCount),
+    r.collection ?? "\u2014",
+    r.internal ? "yes" : "no"
   ]);
   return buildTable(headers, tableRows);
 }
@@ -204,6 +219,8 @@ function formatGetTable(name, descriptor) {
     `  Composes:       ${descriptor.composes.join(", ") || "none"}`,
     `  Composed By:    ${descriptor.composedBy.join(", ") || "none"}`,
     `  Side Effects:   ${formatSideEffects(descriptor.sideEffects)}`,
+    `  Collection:     ${descriptor.collection ?? "\u2014"}`,
+    `  Internal:       ${descriptor.internal}`,
     "",
     `  Props (${propNames.length}):`
   ];
@@ -226,8 +243,16 @@ function formatGetJson(name, descriptor) {
 }
 function formatQueryTable(rows, queryDesc) {
   if (rows.length === 0) return `No components match: ${queryDesc}`;
-  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS"];
-  const tableRows = rows.map((r) => [r.name, r.file, r.complexityClass, r.hooks, r.contexts]);
+  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS", "COLLECTION", "INTERNAL"];
+  const tableRows = rows.map((r) => [
+    r.name,
+    r.file,
+    r.complexityClass,
+    r.hooks,
+    r.contexts,
+    r.collection ?? "\u2014",
+    r.internal ? "yes" : "no"
+  ]);
   return `Query: ${queryDesc}
 ${buildTable(headers, tableRows)}`;
@@ -505,22 +530,22 @@ async function getTailwindCompiler(cwd) {
     from: entryPath,
     loadStylesheet
   });
-  const build3 = result.build.bind(result);
-  compilerCache = { cwd, build: build3 };
-  return build3;
+  const build4 = result.build.bind(result);
+  compilerCache = { cwd, build: build4 };
+  return build4;
 }
 async function getCompiledCssForClasses(cwd, classes) {
-  const build3 = await getTailwindCompiler(cwd);
-  if (build3 === null) return null;
+  const build4 = await getTailwindCompiler(cwd);
+  if (build4 === null) return null;
   const deduped = [...new Set(classes)].filter(Boolean);
   if (deduped.length === 0) return null;
-  return build3(deduped);
+  return build4(deduped);
 }
 async function compileGlobalCssFile(cssFilePath, cwd) {
-  const { existsSync: existsSync16, readFileSync: readFileSync14 } = await import('fs');
+  const { existsSync: existsSync18, readFileSync: readFileSync18 } = await import('fs');
   const { createRequire: createRequire3 } = await import('module');
-  if (!existsSync16(cssFilePath)) return null;
-  const raw = readFileSync14(cssFilePath, "utf-8");
+  if (!existsSync18(cssFilePath)) return null;
+  const raw = readFileSync18(cssFilePath, "utf-8");
   const needsCompile = /@tailwind|@import\s+['"]tailwindcss/.test(raw);
   if (!needsCompile) {
     return raw;
@@ -603,8 +628,17 @@ async function shutdownPool() {
   }
 }
 async function renderComponent(filePath, componentName, props, viewportWidth, viewportHeight) {
+  const PAD = 24;
   const pool = await getPool(viewportWidth, viewportHeight);
-  const htmlHarness = await buildComponentHarness(filePath, componentName, props, viewportWidth);
+  const htmlHarness = await buildComponentHarness(
+    filePath,
+    componentName,
+    props,
+    viewportWidth,
+    void 0,
+    void 0,
+    PAD
+  );
   const slot = await pool.acquire();
   const { page } = slot;
   try {
@@ -644,7 +678,6 @@ async function renderComponent(filePath, componentName, props, viewportWidth, vi
         `Component "${componentName}" rendered with zero bounding box \u2014 it may be invisible or not mounted`
       );
     }
-    const PAD = 24;
     const MIN_W = 320;
     const MIN_H = 200;
     const clipX = Math.max(0, boundingBox.x - PAD);
@@ -946,7 +979,7 @@ function parseChecks(raw) {
 }
 function createCiCommand() {
   return new Command("ci").description(
-    "Run a non-interactive CI pipeline (manifest -> render -> compliance -> regression) with exit codes"
+    "Run the full Scope pipeline non-interactively and exit with a structured code.\n\nPIPELINE STEPS (in order):\n  1. manifest generate    scan source, build .reactscope/manifest.json\n  2. render all           screenshot every component\n  3. tokens compliance    score on-token CSS coverage\n  4. visual regression    pixel diff against --baseline (if provided)\n\nCHECKS (--checks flag, comma-separated):\n  compliance        token coverage below --threshold \u2192 exit 1\n  a11y              accessibility violations \u2192 exit 2\n  console-errors    console.error during render \u2192 exit 3\n  visual-regression pixel diff against baseline \u2192 exit 4\n  (render failures always \u2192 exit 5 regardless of --checks)\n\nEXIT CODES:\n  0   all checks passed\n  1   compliance below threshold\n  2   accessibility violations\n  3   console errors during render\n  4   visual regression detected\n  5   component render failures\n\nExamples:\n  scope ci\n  scope ci --baseline .reactscope/baseline --threshold 0.95\n  scope ci --checks compliance,a11y --json -o ci-result.json\n  scope ci --viewport 1280x720"
   ).option(
     "-b, --baseline <dir>",
     "Baseline directory for visual regression comparison (omit to skip)"
@@ -989,6 +1022,124 @@ function createCiCommand() {
     }
   );
 }
+var PLAYWRIGHT_BROWSER_HINTS = [
+  "executable doesn't exist",
+  "browserType.launch",
+  "looks like playwright was just installed or updated",
+  "please run the following command to download new browsers",
+  "could not find chromium"
+];
+var MISSING_DEPENDENCY_HINTS = ["could not resolve", "cannot find module", "module not found"];
+var REQUIRED_HARNESS_DEPENDENCIES = ["react", "react-dom", "react/jsx-runtime"];
+function getEffectivePlaywrightBrowsersPath() {
+  const value = process.env.PLAYWRIGHT_BROWSERS_PATH;
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function getPlaywrightBrowserRemediation(status) {
+  const effectivePath = status?.effectiveBrowserPath ?? getEffectivePlaywrightBrowsersPath();
+  if (effectivePath !== null) {
+    const pathProblem = status?.browserPathExists === false ? "missing" : status?.browserPathWritable === false ? "unwritable" : "unavailable";
+    return `PLAYWRIGHT_BROWSERS_PATH is set to ${effectivePath}, but that browser cache is ${pathProblem}. Unset PLAYWRIGHT_BROWSERS_PATH and run \`bunx playwright install chromium\`, or install and run with the same writable path: \`PLAYWRIGHT_BROWSERS_PATH=${effectivePath} bunx playwright install chromium\`.`;
+  }
+  return "Run `bunx playwright install chromium` in this sandbox, then retry the Scope command.";
+}
+function diagnoseScopeError(error, cwd = process.cwd()) {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  if (PLAYWRIGHT_BROWSER_HINTS.some((hint) => normalized.includes(hint))) {
+    const browserPath = extractPlaywrightBrowserPath(message);
+    const browserPathHint = browserPath === null ? "" : ` Scope tried to launch Chromium from ${browserPath}.`;
+    return {
+      code: "PLAYWRIGHT_BROWSERS_MISSING",
+      message: "Playwright Chromium is unavailable for Scope browser rendering.",
+      recovery: getPlaywrightBrowserRemediation() + browserPathHint + " Use `scope doctor --json` to verify the browser check passes before rerunning render/site/instrument."
+    };
+  }
+  if (MISSING_DEPENDENCY_HINTS.some((hint) => normalized.includes(hint))) {
+    const packageManager = detectPackageManager(cwd);
+    return {
+      code: "TARGET_PROJECT_DEPENDENCIES_MISSING",
+      message: "The target project's dependencies appear to be missing or incomplete.",
+      recovery: `Run \`${packageManager} install\` in ${cwd}, then rerun \`scope doctor\` and retry the Scope command.`
+    };
+  }
+  return null;
+}
+function formatScopeDiagnostic(error, cwd = process.cwd()) {
+  const message = error instanceof Error ? error.message : String(error);
+  const diagnostic = diagnoseScopeError(error, cwd);
+  if (diagnostic === null) return `Error: ${message}`;
+  return `Error [${diagnostic.code}]: ${diagnostic.message}
+Recovery: ${diagnostic.recovery}
+Cause: ${message}`;
+}
+async function getPlaywrightBrowserStatus(cwd = process.cwd()) {
+  const effectiveBrowserPath = getEffectivePlaywrightBrowsersPath();
+  const executablePath = getPlaywrightChromiumExecutablePath(cwd);
+  const available = executablePath !== null && existsSync(executablePath);
+  const browserPathExists = effectiveBrowserPath === null ? null : existsSync(effectiveBrowserPath);
+  const browserPathWritable = effectiveBrowserPath === null ? null : await isWritableBrowserPath(effectiveBrowserPath);
+  return {
+    effectiveBrowserPath,
+    executablePath,
+    available,
+    browserPathExists,
+    browserPathWritable,
+    remediation: getPlaywrightBrowserRemediation({
+      effectiveBrowserPath,
+      browserPathExists,
+      browserPathWritable
+    })
+  };
+}
+function getPlaywrightChromiumExecutablePath(cwd = process.cwd()) {
+  try {
+    const packageJsonPath = __require.resolve("playwright/package.json", { paths: [cwd] });
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    if (!packageJson.version) return null;
+    const playwrightPath = __require.resolve("playwright", { paths: [cwd] });
+    const { chromium: chromium5 } = __require(playwrightPath);
+    const executablePath = chromium5?.executablePath?.();
+    if (typeof executablePath !== "string" || executablePath.length === 0) return null;
+    return executablePath;
+  } catch {
+    return null;
+  }
+}
+async function isWritableBrowserPath(browserPath) {
+  const candidate = existsSync(browserPath) ? browserPath : dirname(browserPath);
+  try {
+    await access(candidate, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function detectPackageManager(cwd = process.cwd()) {
+  if (existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb"))) return "bun";
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function hasLikelyInstalledDependencies(cwd = process.cwd()) {
+  return existsSync(join(cwd, "node_modules"));
+}
+function getMissingHarnessDependencies(cwd = process.cwd()) {
+  return REQUIRED_HARNESS_DEPENDENCIES.filter((dependencyName) => {
+    try {
+      __require.resolve(dependencyName, { paths: [cwd] });
+      return false;
+    } catch {
+      return true;
+    }
+  });
+}
+function extractPlaywrightBrowserPath(message) {
+  const match = message.match(/Executable doesn't exist at\s+([^\n]+)/i);
+  return match?.[1]?.trim() ?? null;
+}
+// src/doctor-commands.ts
 function collectSourceFiles(dir) {
   if (!existsSync(dir)) return [];
   const results = [];
@@ -1002,13 +1153,43 @@ function collectSourceFiles(dir) {
   }
   return results;
 }
+var TAILWIND_CONFIG_FILES = [
+  "tailwind.config.js",
+  "tailwind.config.cjs",
+  "tailwind.config.mjs",
+  "tailwind.config.ts",
+  "postcss.config.js",
+  "postcss.config.cjs",
+  "postcss.config.mjs",
+  "postcss.config.ts"
+];
+function hasTailwindSetup(cwd) {
+  if (TAILWIND_CONFIG_FILES.some((file) => existsSync(resolve(cwd, file)))) {
+    return true;
+  }
+  const packageJsonPath = resolve(cwd, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return [pkg.dependencies, pkg.devDependencies].some(
+      (deps) => deps && Object.keys(deps).some(
+        (name) => name === "tailwindcss" || name.startsWith("@tailwindcss/")
+      )
+    );
+  } catch {
+    return false;
+  }
+}
+function getPlaywrightInstallCommand(effectiveBrowserPath) {
+  return effectiveBrowserPath === null ? "bunx playwright install chromium" : `PLAYWRIGHT_BROWSERS_PATH=${effectiveBrowserPath} bunx playwright install chromium`;
+}
 function checkConfig(cwd) {
   const configPath = resolve(cwd, "reactscope.config.json");
   if (!existsSync(configPath)) {
     return {
       name: "config",
       status: "error",
-      message: "reactscope.config.json not found \u2014 run `scope init`"
+      message: "reactscope.config.json not found \u2014 run `scope init` in the target project root"
     };
   }
   try {
@@ -1056,6 +1237,13 @@ function checkGlobalCss(cwd) {
     }
   }
   if (globalCss.length === 0) {
+    if (!hasTailwindSetup(cwd)) {
+      return {
+        name: "globalCSS",
+        status: "ok",
+        message: "No globalCSS configured \u2014 skipping CSS injection for this non-Tailwind project"
+      };
+    }
     return {
       name: "globalCSS",
       status: "warn",
@@ -1082,7 +1270,7 @@ function checkManifest(cwd) {
     return {
       name: "manifest",
       status: "warn",
-      message: "Manifest not found \u2014 run `scope manifest generate`"
+      message: "Manifest not found \u2014 run `scope manifest generate` in the target project root"
     };
   }
   const manifestMtime = statSync(manifestPath).mtimeMs;
@@ -1099,23 +1287,105 @@ function checkManifest(cwd) {
   return { name: "manifest", status: "ok", message: "Manifest present and up to date" };
 }
 var ICONS = { ok: "\u2713", warn: "!", error: "\u2717" };
+function checkDependencies(cwd) {
+  const packageManager = detectPackageManager(cwd);
+  if (!hasLikelyInstalledDependencies(cwd)) {
+    return {
+      name: "dependencies",
+      status: "error",
+      remediationCode: "TARGET_PROJECT_DEPENDENCIES_MISSING",
+      fixCommand: `${packageManager} install`,
+      message: `node_modules not found \u2014 run \`${packageManager} install\` in ${cwd} before render/site/instrument`
+    };
+  }
+  const missingHarnessDependencies = getMissingHarnessDependencies(cwd);
+  if (missingHarnessDependencies.length > 0) {
+    return {
+      name: "dependencies",
+      status: "error",
+      remediationCode: "TARGET_PROJECT_HARNESS_DEPENDENCIES_MISSING",
+      fixCommand: `${packageManager} install`,
+      message: `Missing React harness dependencies: ${missingHarnessDependencies.join(", ")}. Run \`${packageManager} install\` in ${cwd}, then retry render/site/instrument.`
+    };
+  }
+  return {
+    name: "dependencies",
+    status: "ok",
+    message: "node_modules and React harness dependencies present"
+  };
+}
+async function checkPlaywright(cwd) {
+  const status = await getPlaywrightBrowserStatus(cwd);
+  const pathDetails = status.effectiveBrowserPath === null ? "PLAYWRIGHT_BROWSERS_PATH is unset" : `PLAYWRIGHT_BROWSERS_PATH=${status.effectiveBrowserPath}; exists=${status.browserPathExists}; writable=${status.browserPathWritable}`;
+  if (status.available) {
+    return {
+      name: "playwright",
+      status: "ok",
+      message: `Playwright package available (${pathDetails})`
+    };
+  }
+  return {
+    name: "playwright",
+    status: "error",
+    remediationCode: "PLAYWRIGHT_BROWSERS_MISSING",
+    fixCommand: getPlaywrightInstallCommand(status.effectiveBrowserPath),
+    message: `Playwright Chromium unavailable (${pathDetails}) \u2014 ${status.remediation}`
+  };
+}
+function collectFixCommands(checks) {
+  return checks.filter((check) => check.status === "error" && check.fixCommand !== void 0).map((check) => check.fixCommand).filter((command, index, commands) => commands.indexOf(command) === index);
+}
 function formatCheck(check) {
   return `  [${ICONS[check.status]}] ${check.name.padEnd(12)} ${check.message}`;
 }
 function createDoctorCommand() {
-  return new Command("doctor").description("Check the health of your Scope setup (config, tokens, CSS, manifest)").option("--json", "Emit structured JSON output", false).action((opts) => {
+  return new Command("doctor").description(
+    `Verify your Scope project setup before running other commands.
+CHECKS PERFORMED:
+  config      reactscope.config.json exists and is valid JSON
+  tokens      reactscope.tokens.json exists and passes validation
+  css         globalCSS files referenced in config actually exist
+  manifest    .reactscope/manifest.json exists and is not stale
+  dependencies node_modules exists in the target project root
+  playwright  Playwright browser runtime is available
+              (stale = source files modified after last generate)
+STATUS LEVELS: ok | warn | error
+Run this first whenever renders fail or produce unexpected output.
+Examples:
+  scope doctor
+  scope doctor --json
+  scope doctor --print-fix-commands
+  scope doctor --json | jq '.checks[] | select(.status == "error")'`
+  ).option("--json", "Emit structured JSON output", false).option(
+    "--print-fix-commands",
+    "Print deduplicated shell remediation commands for failing checks",
+    false
+  ).action(async (opts) => {
     const cwd = process.cwd();
     const checks = [
       checkConfig(cwd),
       checkTokens(cwd),
       checkGlobalCss(cwd),
-      checkManifest(cwd)
+      checkManifest(cwd),
+      checkDependencies(cwd),
+      await checkPlaywright(cwd)
     ];
     const errors = checks.filter((c) => c.status === "error").length;
     const warnings = checks.filter((c) => c.status === "warn").length;
+    const fixCommands = collectFixCommands(checks);
+    if (opts.printFixCommands) {
+      process.stdout.write(`${JSON.stringify({ cwd, fixCommands }, null, 2)}
+`);
+      if (errors > 0) process.exit(1);
+      return;
+    }
     if (opts.json) {
       process.stdout.write(
-        `${JSON.stringify({ passed: checks.length - errors - warnings, warnings, errors, checks }, null, 2)}
+        `${JSON.stringify({ passed: checks.length - errors - warnings, warnings, errors, fixCommands, checks }, null, 2)}
 `
       );
       if (errors > 0) process.exit(1);
@@ -1140,6 +1410,23 @@ function createDoctorCommand() {
     }
   });
 }
+// src/skill-content.ts
+var SKILL_CONTENT = '# Scope \u2014 Agent Skill\n\n## TLDR\nScope is a React codebase introspection toolkit. Use it to answer questions about component structure, props, context dependencies, side effects, and visual output \u2014 without running the app.\n\n**When to reach for it:** Any task requiring "which components use X", "what props does Y accept", "render Z for visual verification", "does this component depend on a provider", or "what design tokens are in use".\n\n**Canonical agent workflow:**\n```\nscope get-skill > /tmp/scope-skill.md    # bootstrap command semantics into agent context\nscope init --yes                         # scaffold config + auto-generate manifest\nscope doctor --json                      # validate config, tokens, globalCSS, manifest freshness, deps, Playwright\nscope manifest query --context ThemeContext --format json\nscope render all --format json --output-dir .reactscope/renders\nscope site build --output .reactscope/site\n```\n\n---\n\n---\n\n## Mental Model\n\nUnderstanding how Scope\'s data flows is the key to using it effectively as an agent.\n\n```\nSource TypeScript files\n       \u2193  (ts-morph AST parse)\n  manifest.json              \u2190 structural facts: props, hooks, contexts, complexity\n       \u2193  (esbuild + Playwright)\n  renders/*.json             \u2190 visual facts: screenshot, computedStyles, dom, a11y\n       \u2193  (token engine)\n  compliance-styles.json     \u2190 audit facts: which CSS values match tokens, which don\'t\n       \u2193  (site generator)\n  site/                      \u2190 human-readable docs combining all of the above\n```\n\nEach layer depends on the previous. If you\'re getting unexpected results, check whether the earlier layers are stale (run `scope doctor` to diagnose).\n\n---\n\n## The Four Subsystems\n\n### 1. Manifest (`scope manifest *`)\nThe manifest is a static analysis snapshot of your TypeScript source. It tells you:\n- What components exist, where they live, and how they\'re exported\n- What props each component accepts (types, defaults, required/optional)\n- What React hooks they call (`detectedHooks`)\n- What contexts they consume (`requiredContexts`) \u2014 must be provided for a render to succeed\n- Whether they compose other components (`composes` / `composedBy`)\n- Their **complexity class** \u2014 `"simple"` or `"complex"` \u2014 which determines the render engine\n\nThe manifest never runs your code. It only reads TypeScript. This means it\'s fast and safe, but it can\'t know about runtime values.\n\n### 2. Render Engine (`scope render *`)\nThe render engine compiles components with esbuild and renders them in Chromium (Playwright). Two paths exist:\n\n| Path | When | Speed | Capability |\n|------|------|-------|------------|\n| **Satori** | `complexityClass: "simple"` | ~8ms | Flexbox only, no JS, no CSS-in-JS |\n| **BrowserPool** | `complexityClass: "complex"` | ~200\u2013800ms | Full DOM, CSS, Tailwind, animations |\n\nMost real-world components route through BrowserPool. Scope defaults to `"complex"` when uncertain (safe fallback).\n\nEach render produces:\n- `screenshot` \u2014 retina-quality PNG (2\xD7 `deviceScaleFactor`; display at CSS px dimensions)\n- `width` / `height` \u2014 CSS pixel dimensions of the component root\n- `computedStyles` \u2014 per-node computed CSS keyed by `#node-0`, `#node-1`, etc.\n- `dom` \u2014 full DOM tree with bounding boxes (BrowserPool only)\n- `accessibility` \u2014 role, aria-name, violation list (BrowserPool only)\n- `renderTimeMs` \u2014 wall-clock render duration\n\n### 3. Scope Files (`.scope.tsx` / `.scope.ts`)\nScope files define **named rendering scenarios** and optional provider wrappers next to a component. They are the primary way to ensure `render all` produces meaningful screenshots.\n\nDiscovery is deterministic: for `Button.tsx`, Scope checks `Button.scope.tsx`, then `.scope.ts`, `.scope.jsx`, `.scope.js` in the same directory and uses the first file that exists.\n\n```tsx\n// Button.scope.tsx\nexport const scenarios = {\n  default: { variant: \'primary\', children: \'Click me\' },\n  ghost: { variant: \'ghost\', children: \'Cancel\' },\n  danger: { variant: \'danger\', children: \'Delete\' },\n  disabled: { variant: \'primary\', children: \'Disabled\', disabled: true },\n} satisfies Record<string, Record<string, unknown>>;\n```\n\nOptional wrapper:\n\n```tsx\nimport type { ReactNode } from \'react\';\nimport { ThemeProvider } from \'../providers/ThemeProvider\';\n\nexport function wrapper({ children }: { children: ReactNode }) {\n  return <ThemeProvider theme="dark">{children}</ThemeProvider>;\n}\n```\n\nContract:\n- Export `scenarios` as a plain object of scenario-name \u2192 props-object, either as a named export or under `default.scenarios`\n- Export `wrapper` as a function, either as a named export or under `default.wrapper`\n- Non-object scenario values are skipped with a warning\n- If no scope file or no valid scenarios exist, Scope falls back to one bare render and inferred required-prop defaults\n- If 2+ scenarios exist, `render all` automatically runs a matrix and merges cells into each component JSON\n\nWhen a component renders blank with `{}` props, **the fix is usually to create a `.scope.tsx` file** with real props.\n\n### 4. Token Compliance\nThe compliance pipeline:\n1. `scope render all` captures `computedStyles` for every element in every component\n2. These are written to `.reactscope/compliance-styles.json`\n3. The token engine compares each computed CSS value against your `reactscope.tokens.json`\n4. `scope tokens compliance` reports the aggregate on-system percentage\n5. `scope ci` fails if the percentage is below `complianceThreshold` (default 90%)\n\n**On-system** means the value exactly matches a resolved token value. Off-system means it\'s a hardcoded value with no token backing it.\n\n---\n\n## Complexity Classes \u2014 Practical Guide\n\nThe `complexityClass` field determines which render engine runs. Scope auto-detects it, but agents should understand it:\n\n**`"simple"` components:**\n- Pure presentational, flexbox layout only\n- No CSS grid, no absolute/fixed/sticky positioning\n- No CSS animations, transitions, or transforms\n- No `className` values Scope can\'t statically trace (e.g. dynamic Tailwind classes)\n- Renders in ~8ms via Satori (SVG-based, no browser needed)\n\n**`"complex"` components:**\n- Anything using Tailwind (CSS injection required)\n- CSS grid, positioned elements, overflow, z-index\n- Components that read from context at render time\n- Any component Scope isn\'t sure about (conservative default)\n- Renders in ~200\u2013800ms via Playwright BrowserPool\n\nWhen in doubt: complex is always safe. Simple is an optimization.\n\n---\n\n## Required Contexts \u2014 Why Renders Fail\n\nIf `requiredContexts` is non-empty, the component calls `useContext` on one or more contexts. Without a provider, it will either render broken or throw entirely.\n\nTwo ways to fix:\n1. **Provider presets in config** (recommended): add provider names to `reactscope.config.json \u2192 components.wrappers.providers`\n2. **Scope file with wrapper**: wrap the component in a provider in the scenario itself\n\nBuilt-in mocks (always provided): `ThemeContext \u2192 { theme: \'light\' }`, `LocaleContext \u2192 { locale: \'en-US\' }`.\n\n---\n\n## `scope doctor` \u2014 Always Run This First\n\nBefore debugging any render issue, run:\n```bash\nscope doctor --json\n```\n\nIt checks:\n- `reactscope.config.json` is valid JSON\n- Token file exists and has a `version` field\n- Every path in `globalCSS` resolves on disk\n- Manifest is present and up to date (not stale relative to source)\n- Target-project dependencies are installed (`node_modules` exists)\n- Playwright Chromium is available for render/site/instrument commands\n\n**If `globalCSS` is empty or missing**: Tailwind styles won\'t apply to renders. Every component will look unstyled. This is the most common footgun. Fix: add your CSS entry file (the one with `@tailwind base; @tailwind components; @tailwind utilities;`) to `globalCSS` in config.\n\n---\n\n## Agent Decision Tree\n\n**"I want to know what props Component X accepts"**\n\u2192 `scope manifest get X --format json | jq \'.props\'`\n\n**"I want to know which components will break if I change a context"**\n\u2192 `scope manifest query --context MyContext --format json`\n\n**"I want to render a component to verify visual output"**\n\u2192 Create a `.scope.tsx` file with real props first, then `scope render component X --format json`\n\n**"I want to render all variants of a component"**\n\u2192 Define all variants in `.scope.tsx`, then `scope render all --format json --output-dir .reactscope/renders` (auto-matrix)\n\u2192 Or: `scope render matrix X --axes \'variant:primary,secondary,danger\' --format json`\n\n**"I want to audit token compliance"**\n\u2192 `scope render all` first (populates computedStyles), then `scope tokens compliance`\n\n**"Renders look unstyled / blank"**\n\u2192 Run `scope doctor` \u2014 likely missing `globalCSS`\n\u2192 If props are the issue: create/update the `.scope.tsx` file\n\n**"I want to understand blast radius of a token change"**\n\u2192 `scope tokens impact color.primary.500 --new-value \'#0077dd\'`\n\u2192 `scope tokens preview color.primary.500 --new-value \'#0077dd\'` for visual diff\n\n**"I need to set up Scope in a new project"**\n\u2192 `scope init --yes` (auto-detects Tailwind + CSS, generates manifest automatically)\n\u2192 `scope doctor` to validate\n\u2192 Create `.scope.tsx` files for key components\n\u2192 `scope render all`\n\n**"I want to profile a live SPA"**\n\u2192 Generate a manifest, then `scope instrument profile SearchPage --interaction \'[{"action":"click","target":"button"}]\'`\n\u2192 For auth/timing-heavy apps, follow `docs/profiling-production-spas.md`\n\n**"I want to run Scope in CI"**\n\u2192 `scope ci --json --output ci-result.json`\n\u2192 Exit code 0 = pass, non-zero = specific failure type\n\n---\n\n\n## Installation\n\nPublished package:\n\n```bash\nnpm install -g @agent-scope/cli          # global\nnpm install --save-dev @agent-scope/cli  # per-project\n```\n\nLocal-from-source quickstart for this repo:\n\n```bash\nbun install\nbun run build\nbunx playwright install chromium\ncd fixtures/tailwind-showcase\nbun install\n../../packages/cli/dist/cli.js init --yes\n../../packages/cli/dist/cli.js doctor --json\n../../packages/cli/dist/cli.js render all --format json --output-dir .reactscope/renders\n../../packages/cli/dist/cli.js site build --output .reactscope/site\n```\n\nBinary: `scope` (published install) or `packages/cli/dist/cli.js` (local build)\n\n---\n\n## Core Workflow\n\n```\nget-skill \u2192 init --yes \u2192 doctor --json \u2192 manifest query/get/list --format json \u2192 render all --format json \u2192 site build \u2192 instrument profile \u2192 ci\n```\n\n- **init**: Scaffold `reactscope.config.json` + token stub, auto-detect framework/globalCSS, **immediately runs `manifest generate`** so you see results right away.\n- **doctor**: Health-check command \u2014 validates config, token file, globalCSS presence, manifest staleness, target-project dependencies, and Playwright Chromium availability.\n- **generate**: Parse TypeScript AST and emit `.reactscope/manifest.json`. Run once per codebase change (or automatically via `scope init`).\n- **query / get / list**: Ask structural questions. No network required. Works from manifest alone. Supports filtering by `--collection` and `--internal`.\n- **render**: Produce PNGs of components via esbuild + Playwright (BrowserPool). Requires manifest for file paths. Auto-injects required prop defaults and globalCSS.\n- **token audit**: Validate design tokens via `@scope/tokens` CLI commands (`tokens list`, `tokens compliance`, `tokens impact`, `tokens preview`, `tokens export`).\n- **ci**: Run compliance checks and exit with code 0/1 for CI pipelines. `report pr-comment` posts results to GitHub PRs.\n\n---\n\n## Full CLI Reference\n\n### `scope init`\nScaffold config, detect framework, extract Tailwind tokens, detect globalCSS files, and **automatically run `scope manifest generate`**.\n\n```bash\nscope init\nscope init --force    # overwrite existing config\n```\n\nAfter init completes, the manifest is already written \u2014 no manual `scope manifest generate` step needed.\n\n**Tailwind token extraction**: reads `tailwind.config.js`, extracts colors (with nested scale support), spacing, fontFamily, borderRadius. Stored in `reactscope.tokens.json`.\n\n**globalCSS detection**: checks 9 common patterns (`src/styles.css`, `src/index.css`, `app/globals.css`, etc.). Stored in `components.wrappers.globalCSS` in config.\n\n---\n\n### `scope doctor`\nValidate the Scope setup. Exits non-zero on errors, zero on warnings-only.\n\n```bash\nscope doctor --json\nscope doctor --json\n```\n\nChecks:\n- `config` \u2014 `reactscope.config.json` is valid JSON with required fields\n- `tokens` \u2014 token file is present and has a valid `version` field\n- `globalCSS` \u2014 globalCSS files listed in config exist on disk\n- `manifest` \u2014 manifest exists and is not stale (compares source file mtimes)\n- `dependencies` \u2014 `node_modules` exists in the target project root\n- `playwright` \u2014 Playwright Chromium is available before render/site/instrument\n\nIf `dependencies` fails, run `bun install` (or the package manager detected by your lockfile) in the target project root, then rerun `scope doctor --json`.\n\nIf `playwright` fails, run `bunx playwright install chromium`, then rerun `scope doctor --json` before retrying `scope render component`, `scope render all`, `scope site build`, or `scope instrument ...`.\n\n```\n$ scope doctor --json\nScope Doctor\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  [\u2713] config       reactscope.config.json valid\n  [\u2713] tokens       Token file valid\n  [\u2713] globalCSS    1 globalCSS file(s) present\n  [!] manifest     Manifest may be stale \u2014 5 source file(s) modified since last generate\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  1 warning(s) \u2014 everything works but could be better\n```\n\n---\n\n### `scope capture <url>`\nCapture a live React component tree from a running app URL.\n\n```bash\nscope capture http://localhost:3000\nscope capture http://localhost:3000 --output report.json --pretty\nscope capture http://localhost:3000 --timeout 15000 --wait 2000\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `-o, --output <path>` | string | stdout | Write JSON to file |\n| `--pretty` | bool | false | Pretty-print JSON |\n| `--timeout <ms>` | number | 10000 | Max wait for React to mount |\n| `--wait <ms>` | number | 0 | Additional wait after page load |\n\nOutput (stdout): serialized PageReport JSON (or path when `--output` is set)\n\n---\n\n### `scope tree <url>`\nPrint the React component tree from a live URL.\n\n```bash\nscope tree http://localhost:3000\nscope tree http://localhost:3000 --depth 3 --show-props --show-hooks\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--depth <n>` | number | unlimited | Max depth to display |\n| `--show-props` | bool | false | Include prop names next to components |\n| `--show-hooks` | bool | false | Show hook counts per component |\n| `--timeout <ms>` | number | 10000 | Max wait for React to mount |\n| `--wait <ms>` | number | 0 | Additional wait after page load |\n\n---\n\n### `scope report <url>`\nCapture and print a human-readable summary of a React app.\n\n```bash\nscope report http://localhost:3000\nscope report http://localhost:3000 --json\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--json` | bool | false | Emit structured JSON instead of text |\n| `--timeout <ms>` | number | 10000 | Max wait for React to mount |\n| `--wait <ms>` | number | 0 | Additional wait after page load |\n\n---\n\n### `scope report baseline`\nSave a baseline snapshot for future diff comparisons.\n\n```bash\nscope report baseline\nscope report baseline --output baselines/my-baseline.json\n```\n\n---\n\n### `scope report diff`\nDiff the current app state against a saved baseline.\n\n```bash\nscope report diff\nscope report diff --baseline baselines/my-baseline.json\nscope report diff --json\n```\n\n---\n\n### `scope report pr-comment`\nPost a Scope CI report as a GitHub PR comment. Used in CI pipelines via the reusable `scope-ci` workflow.\n\n```bash\nscope report pr-comment --report-path scope-ci-report.json\n```\n\nRequires `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, and `GITHUB_PR_NUMBER` in environment.\n\n---\n\n### `scope manifest generate`\nScan source files and write `.reactscope/manifest.json`.\n\n```bash\nscope manifest generate\nscope manifest generate --root ./packages/ui\nscope manifest generate --include "src/**/*.tsx" --exclude "**/*.test.tsx"\nscope manifest generate --output custom/manifest.json\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--root <path>` | string | cwd | Project root directory |\n| `--output <path>` | string | `.reactscope/manifest.json` | Output path |\n| `--include <globs>` | string | `src/**/*.tsx,src/**/*.ts` | Comma-separated include globs |\n| `--exclude <globs>` | string | `**/node_modules/**,...` | Comma-separated exclude globs |\n\n---\n\n### `scope manifest list`\nList all components in the manifest.\n\n```bash\nscope manifest list\nscope manifest list --filter "Button*"\nscope manifest list --format json\nscope manifest list --collection Forms          # filter to named collection\nscope manifest list --internal                  # only internal components\nscope manifest list --no-internal               # hide internal components\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--format <fmt>` | `json\\|table` | auto (TTY\u2192table, pipe\u2192json) | Output format |\n| `--filter <glob>` | string | \u2014 | Filter component names by glob |\n| `--collection <name>` | string | \u2014 | Filter to named collection |\n| `--internal` | bool | false | Show only internal components |\n| `--no-internal` | bool | false | Hide internal components |\n| `--manifest <path>` | string | `.reactscope/manifest.json` | Manifest path |\n\nTTY table output (includes COLLECTION and INTERNAL columns):\n```\nNAME          FILE                         COMPLEXITY  HOOKS  CONTEXTS  COLLECTION  INTERNAL\n------------  ---------------------------  ----------  -----  --------  ----------  --------\nButton        src/components/Button.tsx    simple      1      0         \u2014           no\nThemeToggle   src/components/Toggle.tsx    complex     3      1         Forms        no\n```\n\n---\n\n### `scope manifest get <name>`\nGet full details of a single component.\n\n```bash\nscope manifest get Button\nscope manifest get Button --format json\n```\n\nJSON output includes `collection` and `internal` fields:\n```json\n{\n  "name": "Button",\n  "filePath": "src/components/Button.tsx",\n  "collection": "Primitives",\n  "internal": false,\n  ...\n}\n```\n\n---\n\n### `scope manifest query`\nQuery components by attributes.\n\n```bash\nscope manifest query --context ThemeContext\nscope manifest query --hook useEffect\nscope manifest query --complexity complex\nscope manifest query --side-effects\nscope manifest query --has-fetch\nscope manifest query --has-prop <propName>\nscope manifest query --composed-by <ComponentName>\nscope manifest query --internal\nscope manifest query --collection Forms\nscope manifest query --context ThemeContext --format json\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--context <name>` | string | \u2014 | Find components consuming a context by name |\n| `--hook <name>` | string | \u2014 | Find components using a specific hook |\n| `--complexity <class>` | `simple\\|complex` | \u2014 | Filter by complexity class |\n| `--side-effects` | bool | false | Any side effects detected |\n| `--has-fetch` | bool | false | Components with fetch calls specifically |\n| `--has-prop <name>` | string | \u2014 | Components that accept a specific prop |\n| `--composed-by <name>` | string | \u2014 | Components rendered inside a specific parent |\n| `--internal` | bool | false | Only internal components |\n| `--collection <name>` | string | \u2014 | Filter to named collection |\n| `--format <fmt>` | `json\\|table` | auto | Output format |\n| `--manifest <path>` | string | `.reactscope/manifest.json` | Manifest path |\n\n---\n\n### `scope render <component>`\nRender a single component to PNG (TTY) or JSON (pipe).\n\n**Auto prop defaults**: if `--props` is omitted, Scope injects sensible defaults so required props don\'t produce blank renders: strings/nodes \u2192 component name, unions \u2192 first value, booleans \u2192 `false`, numbers \u2192 `0`.\n\n**globalCSS auto-injection**: reads `components.wrappers.globalCSS` from config and compiles/injects CSS (supports Tailwind v3 via PostCSS) into the render harness. A warning is printed to stderr if no globalCSS is configured (common cause of unstyled renders).\n\n```bash\nscope render component Button\nscope render component Button --props \'{"variant":"primary","children":"Click me"}\'\nscope render component Button --viewport 375x812\nscope render component Button --output button.png\nscope render component Button --format json\n```\n\nFlags:\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n| `--props <json>` | string | `{}` | Inline props as JSON string |\n| `--viewport <WxH>` | string | `375x812` | Viewport size |\n| `--theme <name>` | string | \u2014 | Theme name from token system |\n| `-o, --output <path>` | string | \u2014 | Write PNG to specific path |\n| `--format <fmt>` | `png\\|json` | auto (TTY\u2192file, pipe\u2192json) | Output format |\n| `--manifest <path>` | string | `.reactscope/manifest.json` | Manifest path |\n\n---\n\n### `scope render matrix <component>`\nRender across a Cartesian product of prop axes. Accepts both `key:v1,v2` and `{"key":["v1","v2"]}` JSON format for `--axes`.\n\n```bash\nscope render matrix Button --axes \'variant:primary,secondary,danger\'\nscope render matrix Button --axes \'{"variant":["primary","secondary"]}\'\nscope render matrix Button --axes \'variant:primary,secondary size:sm,md,lg\'\nscope render matrix Button --sprite button-matrix.png --format json\n```\n\n---\n\n### `scope render all`\nRender every component in the manifest.\n\n```bash\nscope render all\nscope render all --concurrency 4 --output-dir renders/\n```\n\nHandles imports of CSS files in components (maps to empty loader so styles are injected at page level). SVG and font imports are handled via dataurl loaders.\n\n---\n\n### `scope instrument tree`\nCapture the live React component tree with instrumentation metadata.\n\n```bash\nscope instrument tree http://localhost:3000\nscope instrument tree http://localhost:3000 --depth 5 --show-props\n```\n\n**Implementation note**: uses a fresh `chromium.launch()` + `newContext()` + `newPage()` per call (not BrowserPool), with `addInitScript` called before `setContent` to ensure the Scope runtime is injected at document-start before React loads.\n\n---\n\n### `scope instrument hooks`\nProfile hook execution in live components.\n\n```bash\nscope instrument hooks http://localhost:3000\nscope instrument hooks http://localhost:3000 --component Button\n```\n\n**Implementation note**: requires `addInitScript({ content: getBrowserEntryScript() })` before `setContent` so `__REACT_DEVTOOLS_GLOBAL_HOOK__` is present when React loads its renderer.\n\n---\n\n### `scope instrument profile`\nProfile render performance of live components.\n\n```bash\nscope instrument profile SearchPage --interaction \'[{"action":"click","target":"button"}]\'\n```\n\n---\n\n### `scope instrument renders`\nRe-render causality analysis \u2014 what triggered each render.\n\n```bash\nscope instrument renders http://localhost:3000\n```\n\n---\n\n### `scope tokens get <name>`\nGet details of a single design token.\n\n### `scope tokens list`\nList all tokens. Token file must have a `version` field (written by `scope init`).\n\n```bash\nscope tokens list\nscope tokens list --type color\nscope tokens list --format json\n```\n\n### `scope tokens search <query>`\nFull-text search across token names/values.\n\n### `scope tokens resolve <value>`\nResolve a CSS value or alias back to its token name.\n\n### `scope tokens validate`\nValidate token file schema.\n\n### `scope tokens compliance`\nCheck rendered components for design token compliance.\n\n```bash\nscope tokens compliance\nscope tokens compliance --threshold 95\n```\n\n### `scope tokens impact <token>`\nAnalyze impact of changing a token \u2014 which components use it.\n\n```bash\nscope tokens impact --token color.primary.500\n```\n\n### `scope tokens preview <token>`\nPreview a token value change visually before committing.\n\n### `scope tokens export`\nExport tokens in multiple formats.\n\n```bash\nscope tokens export --format flat-json\nscope tokens export --format css\nscope tokens export --format scss\nscope tokens export --format ts\nscope tokens export --format tailwind\nscope tokens export --format style-dictionary\n```\n\n**Format aliases** (auto-corrected with "Did you mean?" hint):\n- `json` \u2192 `flat-json`\n- `js` \u2192 `ts`\n- `sass` \u2192 `scss`\n- `tw` \u2192 `tailwind`\n\n---\n\n### `scope ci`\nRun all CI checks (compliance, accessibility, console errors) and exit 0/1.\n\n```bash\nscope ci\nscope ci --json\nscope ci --threshold 90    # compliance threshold (default: 90)\n```\n\n```\n$ scope ci --json\n\u2192 CI passed in 3.2s\n\u2192 Compliance 100.0% >= threshold 90.0% \u2705\n\u2192 Accessibility audit not yet implemented \u2014 skipped \u2705\n\u2192 No console errors detected \u2705\n\u2192 Exit code 0\n```\n\nThe `scope-ci` **reusable GitHub Actions workflow** is available at `.github/workflows/scope-ci.yml` and can be included in any repo\'s CI to run `scope ci` and post results as a PR comment via `scope report pr-comment`.\n\n---\n\n### `scope site build`\nGenerate a static HTML component gallery site from the manifest.\n\n```bash\nscope site build\nscope site build --output ./dist/site\n```\n\n**Collections support**: components are grouped under named collection sections in the sidebar and index grid. Internal components are hidden from the sidebar and card grid but appear in composition detail sections with an `internal` badge.\n\n**Collection display rules**:\n- Sidebar: one section divider per collection + an "Ungrouped" section; internal components excluded\n- Index page: named sections with heading + optional description; internal components excluded\n- Component detail page: Composes/Composed By lists ALL components including internal ones (with subtle badge)\n- Falls back to flat list when no collections configured (backwards-compatible)\n\n### `scope site serve`\nServe the generated site locally.\n\n```bash\nscope site serve\nscope site serve --port 4000\n```\n\n---\n\n## Collections & Internal Components\n\nComponents can be organized into named **collections** and flagged as **internal** (library implementation details not shown in the public gallery).\n\n### Defining collections\n\n**1. TSDoc tag** (highest precedence):\n```tsx\n/**\n * @collection Forms\n */\nexport function Input() { ... }\n```\n\n**2. `.scope.ts` co-located file**:\n```ts\n// Input.scope.ts\nexport const collection = "Forms"\n```\n\n**3. Config-level glob patterns**:\n```json\n// reactscope.config.json\n{\n  "collections": [\n    { "name": "Forms", "description": "Form inputs and controls", "patterns": ["src/forms/**"] },\n    { "name": "Primitives", "patterns": ["src/primitives/**"] }\n  ]\n}\n```\n\nResolution precedence: TSDoc `@collection` > `.scope.ts` export > config pattern.\n\n### Flagging internal components\n\n**TSDoc tag**:\n```tsx\n/**\n * @internal\n */\nexport function InternalHelperButton() { ... }\n```\n\n**Config glob patterns**:\n```json\n{\n  "internalPatterns": ["src/internal/**", "src/**/*Internal*"]\n}\n```\n\n---\n\n## Manifest Output Schema\n\nFile: `.reactscope/manifest.json`\n\n```typescript\n{\n  version: "0.1",\n  generatedAt: string,          // ISO 8601\n  collections: CollectionConfig[],  // echoes config.collections, [] when not set\n  components: Record<string, ComponentDescriptor>,\n  tree: Record<string, { children: string[], parents: string[] }>\n}\n```\n\n### `ComponentDescriptor` fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `filePath` | `string` | Relative path from project root to source file |\n| `exportType` | `"named" \\| "default" \\| "none"` | How the component is exported |\n| `displayName` | `string` | `displayName` if set, else function/class name |\n| `collection` | `string?` | Resolved collection name (`undefined` = ungrouped) |\n| `internal` | `boolean` | `true` if flagged as internal (default: `false`) |\n| `props` | `Record<string, PropDescriptor>` | Extracted prop types keyed by prop name |\n| `composes` | `string[]` | Components this one renders in its JSX |\n| `composedBy` | `string[]` | Components that render this one in their JSX |\n| `complexityClass` | `"simple" \\| "complex"` | Render path: simple = Satori-safe, complex = requires BrowserPool |\n| `requiredContexts` | `string[]` | React context names consumed |\n| `detectedHooks` | `string[]` | All hooks called, sorted alphabetically |\n| `sideEffects` | `SideEffects` | Side effect categories detected |\n| `memoized` | `boolean` | Wrapped with `React.memo` |\n| `forwardedRef` | `boolean` | Wrapped with `React.forwardRef` |\n| `hocWrappers` | `string[]` | HOC wrapper names (excluding memo/forwardRef) |\n| `loc` | `{ start: number, end: number }` | Line numbers in source file |\n\n---\n\n## Common Agent Workflows\n\n### Structural queries\n\n```bash\n# Which components use ThemeContext?\nscope manifest query --context ThemeContext\n\n# What props does Button accept?\nscope manifest get Button --format json | jq \'.props\'\n\n# Which components are safe to render without a provider?\nscope manifest query --complexity simple  # + check requiredContexts === []\n\n# Show all components with side effects\nscope manifest query --side-effects\n\n# Which components make fetch calls?\nscope manifest query --has-fetch\n\n# Which components use useEffect?\nscope manifest query --hook useEffect\n\n# Which components accept a disabled prop?\nscope manifest query --has-prop disabled\n\n# Which components are composed inside Modal?\nscope manifest query --composed-by Modal\n\n# All components in the Forms collection\nscope manifest list --collection Forms\n\n# All internal components (library implementation details)\nscope manifest list --internal\n\n# Public components only (hide internals)\nscope manifest list --no-internal\n```\n\n### Render workflows\n\n```bash\n# Render Button in all variants (auto-defaults props if not provided)\nscope render matrix Button --axes \'variant:primary,secondary,danger\'\n\n# Render with JSON axes format\nscope render matrix Button --axes \'{"variant":["primary","secondary"]}\'\n\n# Render with explicit props\nscope render component Button --props \'{"variant":"primary","disabled":true}\'\n\n# Render all components (handles CSS/SVG/font imports automatically)\nscope render all --concurrency 8\n\n# Get render as JSON\nscope render component Button --format json | jq \'.screenshot\' | base64 -d > button.png\n```\n\n### Token workflows\n\n```bash\n# List all tokens\nscope tokens list\n\n# Check compliance\nscope tokens compliance --threshold 95\n\n# See what a token change impacts\nscope tokens impact --token color.primary.500\n\n# Export for Tailwind\nscope tokens export --format tailwind\n```\n\n### CI workflow\n\n```bash\n# Full compliance check\nscope ci --json\n\n# In GitHub Actions \u2014 use the reusable workflow\n# .github/workflows/ci.yml:\n# uses: FlatFilers/Scope/.github/workflows/scope-ci.yml@main\n```\n\n---\n\n## Error Patterns\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| `"React root not found"` | App not running, wrong URL, or Vite HMR interfering | Use `scope capture --wait 2000` |\n| `"Component not in manifest"` | Manifest is stale | Run `scope manifest generate` first |\n| `"Manifest not found"` | Missing manifest | Run `scope init` or `scope manifest generate` |\n| `"requiredContexts missing"` | Component needs a provider | Add provider presets to `reactscope.config.json` |\n| Blank PNG / 16\xD76px renders | No globalCSS injected (common with Tailwind) | Set `components.wrappers.globalCSS` in config; run `scope doctor` to verify |\n| `PLAYWRIGHT_BROWSERS_MISSING` / `browserType.launch: Executable doesn\'t exist` | Playwright Chromium is not installed in this sandbox | Run `bunx playwright install chromium`, then `scope doctor --json`, then retry render/site/instrument |\n| `TARGET_PROJECT_DEPENDENCIES_MISSING` / `Could not resolve "react"` | Target project dependencies are missing | Run `bun install` (or the detected package manager) in the target project root, then `scope doctor --json` |\n| `"Invalid props JSON"` | Malformed JSON in `--props` | Use single outer quotes: `--props \'{"key":"val"}\'` |\n| `"SCOPE_CAPTURE_JSON not available"` | Scope runtime not injected before React loaded | Fixed in PR #83 \u2014 update CLI |\n| `"No React DevTools hook found"` | Hook instrumentation init order bug | Fixed in PR #83 \u2014 update CLI |\n| `"ERR_MODULE_NOT_FOUND"` after tokens commands | Old Node shebang in CLI binary | Fixed in PR #90 \u2014 CLI now uses `#!/usr/bin/env bun` |\n| `"version" field missing in tokens` | Token stub written by old `scope init` | Re-run `scope init --force` or add `"version": "1"` to token file |\n| `"unknown option --has-prop"` | Old CLI version | Fixed in PR #90 \u2014 update CLI |\n| Format alias error (`json`, `js`, `sass`, `tw`) | Wrong format name for `tokens export` | Use `flat-json`, `ts`, `scss`, `tailwind`; CLI shows "Did you mean?" hint |\n\n---\n\n## `reactscope.config.json`\n\n```json\n{\n  "components": {\n    "wrappers": {\n      "globalCSS": ["src/styles.css"]\n    }\n  },\n  "tokens": {\n    "file": "reactscope.tokens.json"\n  },\n  "collections": [\n    { "name": "Forms", "description": "Form inputs and controls", "patterns": ["src/forms/**"] },\n    { "name": "Primitives", "patterns": ["src/primitives/**"] }\n  ],\n  "internalPatterns": ["src/internal/**"],\n  "providers": {\n    "theme": { "component": "ThemeProvider", "props": { "theme": "light" } },\n    "router": { "component": "MemoryRouter", "props": { "initialEntries": ["/"] } }\n  }\n}\n```\n\n**Built-in mock providers** (always available, no config needed):\n- `ThemeContext` \u2192 `{ theme: \'light\' }` (or `--theme <name>`)\n- `LocaleContext` \u2192 `{ locale: \'en-US\' }`\n\n---\n\n## What Scope Cannot Do\n\n- **Runtime state**: `useState` values after user interaction\n- **Network requests**: `fetch`, `XHR`, `WebSocket`\n- **User interactions**: click, type, hover, drag\n- **Auth/session-gated components**: components that redirect or throw without a session\n- **Server components (RSC)**: React Server Components\n- **Dynamic CSS**: CSS-in-JS styles computed at runtime from props Scope can\'t infer\n\n---\n\n## Version History\n\n| Version | Date | Summary |\n|---------|------|---------|\n| v1.0 | 2026-03-11 | Initial SKILL.md (PR #36) \u2014 manifest, render, capture, tree, report, tokens, ci commands |\n| v1.1 | 2026-03-11 | Updated through PR #82 \u2014 Phase 2 CLI commands complete |\n| v1.2 | 2026-03-13 | PRs #83\u2013#95: runtime injection fix, dogfooding fixes (12 bugs), `scope doctor`, `scope init` auto-manifest, globalCSS render warning, collections & internal components feature |\n';
+// src/get-skill-command.ts
+function createGetSkillCommand() {
+  return new Command("get-skill").description(
+    'Print the embedded Scope SKILL.md to stdout.\n\nAgents: load this first, then follow the canonical workflow in the skill:\n  init --yes \u2192 doctor --json \u2192 manifest --format json \u2192 render all --format json \u2192 site build\nThe skill documents .scope.tsx discovery/exports, config paths, profiler usage,\nand failure recovery.\n\nEMBEDDED AT BUILD TIME \u2014 works in any install context (global npm, npx, local).\n\nExamples:\n  scope get-skill                     # raw markdown to stdout\n  scope get-skill --json              # { "skill": "..." } for structured ingestion\n  scope get-skill | head -50          # preview the skill\n  scope get-skill > /tmp/SKILL.md     # save locally'
+  ).option("--json", "Wrap output in JSON { skill: string } instead of raw markdown").action((opts) => {
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify({ skill: SKILL_CONTENT }, null, 2)}
+`);
+    } else {
+      process.stdout.write(SKILL_CONTENT);
+    }
+  });
+}
 function hasConfigFile(dir, stem) {
   if (!existsSync(dir)) return false;
   try {
@@ -1163,7 +1450,7 @@ function detectFramework(rootDir, packageDeps) {
   if ("react-scripts" in packageDeps) return "cra";
   return "unknown";
 }
-function detectPackageManager(rootDir) {
+function detectPackageManager2(rootDir) {
   if (existsSync(join(rootDir, "bun.lock"))) return "bun";
   if (existsSync(join(rootDir, "yarn.lock"))) return "yarn";
   if (existsSync(join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
@@ -1239,6 +1526,31 @@ var TAILWIND_STEMS = ["tailwind.config"];
 var CSS_EXTS = [".css", ".scss", ".sass", ".less"];
 var THEME_SUFFIXES = [".theme.ts", ".theme.js", ".theme.tsx"];
 var CSS_CUSTOM_PROPS_RE = /:root\s*\{[^}]*--[a-zA-Z]/;
+var TAILWIND_V4_THEME_RE = /@theme\s*(?:inline\s*)?\{[^}]*--[a-zA-Z]/;
+var MAX_SCAN_DEPTH = 4;
+var SKIP_CSS_NAMES = ["compiled", ".min."];
+function collectCSSFiles(dir, depth) {
+  if (depth > MAX_SCAN_DEPTH) return [];
+  const results = [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".next") {
+        continue;
+      }
+      const full = join(dir, entry.name);
+      if (entry.isFile() && CSS_EXTS.some((x) => entry.name.endsWith(x))) {
+        if (!SKIP_CSS_NAMES.some((skip) => entry.name.includes(skip))) {
+          results.push(full);
+        }
+      } else if (entry.isDirectory()) {
+        results.push(...collectCSSFiles(full, depth + 1));
+      }
+    }
+  } catch {
+  }
+  return results;
+}
 function detectTokenSources(rootDir) {
   const sources = [];
   for (const stem of TAILWIND_STEMS) {
@@ -1254,32 +1566,53 @@ function detectTokenSources(rootDir) {
     }
   }
   const srcDir = join(rootDir, "src");
-  const dirsToScan = existsSync(srcDir) ? [srcDir] : [];
-  for (const scanDir of dirsToScan) {
-    try {
-      const entries = readdirSync(scanDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isFile() && CSS_EXTS.some((x) => entry.name.endsWith(x))) {
-          const filePath = join(scanDir, entry.name);
-          const content = readSafe(filePath);
-          if (content !== null && CSS_CUSTOM_PROPS_RE.test(content)) {
-            sources.push({ kind: "css-custom-properties", path: filePath });
-          }
-        }
+  if (existsSync(srcDir)) {
+    const cssFiles = collectCSSFiles(srcDir, 0);
+    const seen = /* @__PURE__ */ new Set();
+    for (const filePath of cssFiles) {
+      const content = readSafe(filePath);
+      if (content === null) continue;
+      if (TAILWIND_V4_THEME_RE.test(content) && !seen.has(filePath)) {
+        sources.push({ kind: "tailwind-v4-theme", path: filePath });
+        seen.add(filePath);
+      }
+      if (CSS_CUSTOM_PROPS_RE.test(content) && !seen.has(filePath)) {
+        sources.push({ kind: "css-custom-properties", path: filePath });
+        seen.add(filePath);
+      }
+    }
+  }
+  for (const tokenDir of ["tokens", "styles", "theme"]) {
+    const dir = join(rootDir, tokenDir);
+    if (!existsSync(dir)) continue;
+    const cssFiles = collectCSSFiles(dir, 0);
+    for (const filePath of cssFiles) {
+      const content = readSafe(filePath);
+      if (content === null) continue;
+      if (TAILWIND_V4_THEME_RE.test(content)) {
+        sources.push({ kind: "tailwind-v4-theme", path: filePath });
+      } else if (CSS_CUSTOM_PROPS_RE.test(content)) {
+        sources.push({ kind: "css-custom-properties", path: filePath });
       }
-    } catch {
     }
   }
   if (existsSync(srcDir)) {
-    try {
-      const entries = readdirSync(srcDir);
-      for (const entry of entries) {
-        if (THEME_SUFFIXES.some((s) => entry.endsWith(s))) {
-          sources.push({ kind: "theme-file", path: join(srcDir, entry) });
+    const scanThemeFiles = (dir, depth) => {
+      if (depth > MAX_SCAN_DEPTH) return;
+      try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name === "node_modules" || entry.name === "dist") continue;
+          if (entry.isFile() && THEME_SUFFIXES.some((s) => entry.name.endsWith(s))) {
+            sources.push({ kind: "theme-file", path: join(dir, entry.name) });
+          } else if (entry.isDirectory()) {
+            scanThemeFiles(join(dir, entry.name), depth + 1);
+          }
         }
+      } catch {
       }
-    } catch {
-    }
+    };
+    scanThemeFiles(srcDir, 0);
   }
   return sources;
 }
@@ -1299,7 +1632,7 @@ function detectProject(rootDir) {
   }
   const framework = detectFramework(rootDir, packageDeps);
   const { typescript, tsconfigPath } = detectTypeScript(rootDir);
-  const packageManager = detectPackageManager(rootDir);
+  const packageManager = detectPackageManager2(rootDir);
   const componentPatterns = detectComponentPatterns(rootDir, typescript);
   const tokenSources = detectTokenSources(rootDir);
   const globalCSSFiles = detectGlobalCSSFiles(rootDir);
@@ -1350,9 +1683,9 @@ function createRL() {
   });
 }
 async function ask(rl, question) {
-  return new Promise((resolve19) => {
+  return new Promise((resolve21) => {
     rl.question(question, (answer) => {
-      resolve19(answer.trim());
+      resolve21(answer.trim());
     });
   });
 }
@@ -1613,7 +1946,9 @@ async function runInit(options) {
   };
 }
 function createInitCommand() {
-  return new Command("init").description("Initialise a Scope project \u2014 scaffold reactscope.config.json and friends").option("-y, --yes", "Accept all detected defaults without prompting", false).option("--force", "Overwrite existing reactscope.config.json if present", false).action(async (opts) => {
+  return new Command("init").description(
+    "Auto-detect your project layout and scaffold reactscope.config.json.\n\nWHAT IT DOES:\n  - Detects component glob patterns from tsconfig / package.json / directory scan\n  - Detects globalCSS files (Tailwind, PostCSS)\n  - Writes reactscope.config.json with all detected values\n  - Adds .reactscope/ to .gitignore\n  - Creates .reactscope/ output directory\n\nCONFIG FIELDS GENERATED:\n  components.include      glob patterns for component discovery\n  components.wrappers     providers + globalCSS to inject on every render\n  render.viewport         default viewport (1280\xD7800)\n  tokens.file             path to reactscope.tokens.json\n  output.dir              .reactscope/ (all outputs go here)\n  ci.complianceThreshold  0.90 (90% on-token required to pass CI)\n\nSafe to re-run \u2014 will not overwrite existing config unless --force.\n\nExamples:\n  scope init\n  scope init --yes          # accept all detected defaults, no prompts\n  scope init --force        # overwrite existing config"
+  ).option("-y, --yes", "Accept all detected defaults without prompting", false).option("--force", "Overwrite existing reactscope.config.json if present", false).action(async (opts) => {
     try {
       const result = await runInit({ yes: opts.yes, force: opts.force });
       if (!result.success && !result.skipped) {
@@ -1642,34 +1977,56 @@ function resolveFormat(formatFlag) {
   return isTTY() ? "table" : "json";
 }
 function registerList(manifestCmd) {
-  manifestCmd.command("list").description("List all components in the manifest").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--filter <glob>", "Filter components by name glob pattern").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action((opts) => {
-    try {
-      const manifest = loadManifest(opts.manifest);
-      const format = resolveFormat(opts.format);
-      let entries = Object.entries(manifest.components);
-      if (opts.filter !== void 0) {
-        const filterPattern = opts.filter ?? "";
-        entries = entries.filter(([name]) => matchGlob(filterPattern, name));
-      }
-      const rows = entries.map(([name, descriptor]) => ({
-        name,
-        file: descriptor.filePath,
-        complexityClass: descriptor.complexityClass,
-        hookCount: descriptor.detectedHooks.length,
-        contextCount: descriptor.requiredContexts.length
-      }));
-      const output = format === "json" ? formatListJson(rows) : formatListTable(rows);
-      process.stdout.write(`${output}
+  manifestCmd.command("list").description(
+    `List all components in the manifest as a table (TTY) or JSON (piped).
+Examples:
+  scope manifest list
+  scope manifest list --format json | jq '.[].name'
+  scope manifest list --filter "Button*"`
+  ).option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--filter <glob>", "Filter components by name glob pattern").option("--collection <name>", "Filter to only components in the named collection").option("--internal", "Show only internal components").option("--no-internal", "Hide internal components from output").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
+    (opts) => {
+      try {
+        const manifest = loadManifest(opts.manifest);
+        const format = resolveFormat(opts.format);
+        let entries = Object.entries(manifest.components);
+        if (opts.filter !== void 0) {
+          const filterPattern = opts.filter ?? "";
+          entries = entries.filter(([name]) => matchGlob(filterPattern, name));
+        }
+        if (opts.collection !== void 0) {
+          const col = opts.collection;
+          entries = entries.filter(([, d]) => d.collection === col);
+        }
+        if (opts.internal === true) {
+          entries = entries.filter(([, d]) => d.internal);
+        } else if (opts.internal === false) {
+          entries = entries.filter(([, d]) => !d.internal);
+        }
+        const rows = entries.map(([name, descriptor]) => ({
+          name,
+          file: descriptor.filePath,
+          complexityClass: descriptor.complexityClass,
+          hookCount: descriptor.detectedHooks.length,
+          contextCount: descriptor.requiredContexts.length,
+          collection: descriptor.collection,
+          internal: descriptor.internal
+        }));
+        const output = format === "json" ? formatListJson(rows) : formatListTable(rows);
+        process.stdout.write(`${output}
 `);
-    } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
-      process.exit(1);
+        process.exit(1);
+      }
     }
-  });
+  );
 }
 function registerGet(manifestCmd) {
-  manifestCmd.command("get <name>").description("Get full details of a single component by name").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action((name, opts) => {
+  manifestCmd.command("get <name>").description(
+    "Get full details of a single component: props, hooks, complexity class, file path.\n\nExamples:\n  scope manifest get Button\n  scope manifest get Button --format json\n  scope manifest get Button --format json | jq '.complexity'"
+  ).option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action((name, opts) => {
     try {
       const manifest = loadManifest(opts.manifest);
       const format = resolveFormat(opts.format);
@@ -1693,10 +2050,12 @@ Available: ${available}${hint}`
   });
 }
 function registerQuery(manifestCmd) {
-  manifestCmd.command("query").description("Query components by attributes").option("--context <name>", "Find components consuming a context").option("--hook <name>", "Find components using a specific hook").option("--complexity <class>", "Filter by complexity class: simple or complex").option("--side-effects", "Find components with any side effects", false).option("--has-fetch", "Find components with fetch calls", false).option(
+  manifestCmd.command("query").description(
+    'Filter components by structural attributes. All flags are AND-combined.\n\nCOMPLEXITY CLASSES:\n  simple   \u2014 pure/presentational, no side effects, Satori-renderable\n  complex  \u2014 uses context/hooks/effects, requires BrowserPool to render\n\nExamples:\n  scope manifest query --complexity simple\n  scope manifest query --has-fetch\n  scope manifest query --hook useContext --side-effects\n  scope manifest query --has-prop "variant:union" --format json\n  scope manifest query --composed-by Layout'
+  ).option("--context <name>", "Find components consuming a context").option("--hook <name>", "Find components using a specific hook").option("--complexity <class>", "Filter by complexity class: simple or complex").option("--side-effects", "Find components with any side effects", false).option("--has-fetch", "Find components with fetch calls", false).option(
     "--has-prop <spec>",
     "Find components with a prop matching name or name:type (e.g. 'loading' or 'variant:union')"
-  ).option("--composed-by <name>", "Find components that compose the named component").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
+  ).option("--composed-by <name>", "Find components that compose the named component").option("--internal", "Find only internal components", false).option("--collection <name>", "Filter to only components in the named collection").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
     (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1709,9 +2068,11 @@ function registerQuery(manifestCmd) {
         if (opts.hasFetch) queryParts.push("has-fetch");
         if (opts.hasProp !== void 0) queryParts.push(`has-prop=${opts.hasProp}`);
         if (opts.composedBy !== void 0) queryParts.push(`composed-by=${opts.composedBy}`);
+        if (opts.internal) queryParts.push("internal");
+        if (opts.collection !== void 0) queryParts.push(`collection=${opts.collection}`);
         if (queryParts.length === 0) {
           process.stderr.write(
-            "No query flags specified. Use --context, --hook, --complexity, --side-effects, --has-fetch, --has-prop, or --composed-by.\n"
+            "No query flags specified. Use --context, --hook, --complexity, --side-effects, --has-fetch, --has-prop, --composed-by, --internal, or --collection.\n"
           );
           process.exit(1);
         }
@@ -1756,15 +2117,24 @@ function registerQuery(manifestCmd) {
           const targetName = opts.composedBy;
           entries = entries.filter(([, d]) => {
             const composedBy = d.composedBy;
-            return composedBy !== void 0 && composedBy.includes(targetName);
+            return composedBy?.includes(targetName);
           });
         }
+        if (opts.internal) {
+          entries = entries.filter(([, d]) => d.internal);
+        }
+        if (opts.collection !== void 0) {
+          const col = opts.collection;
+          entries = entries.filter(([, d]) => d.collection === col);
+        }
         const rows = entries.map(([name, d]) => ({
           name,
           file: d.filePath,
           complexityClass: d.complexityClass,
           hooks: d.detectedHooks.join(", ") || "\u2014",
-          contexts: d.requiredContexts.join(", ") || "\u2014"
+          contexts: d.requiredContexts.join(", ") || "\u2014",
+          collection: d.collection,
+          internal: d.internal
         }));
         const output = format === "json" ? formatQueryJson(rows) : formatQueryTable(rows, queryDesc);
         process.stdout.write(`${output}
@@ -1777,21 +2147,64 @@ function registerQuery(manifestCmd) {
     }
   );
 }
+function loadReactScopeConfig(rootDir) {
+  const configPath = resolve(rootDir, "reactscope.config.json");
+  if (!existsSync(configPath)) return null;
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    const result = {};
+    const components = cfg.components;
+    if (components !== void 0 && typeof components === "object" && components !== null) {
+      if (Array.isArray(components.include)) {
+        result.include = components.include;
+      }
+      if (Array.isArray(components.exclude)) {
+        result.exclude = components.exclude;
+      }
+    }
+    if (Array.isArray(cfg.internalPatterns)) {
+      result.internalPatterns = cfg.internalPatterns;
+    }
+    if (Array.isArray(cfg.collections)) {
+      result.collections = cfg.collections;
+    }
+    const icons = cfg.icons;
+    if (icons !== void 0 && typeof icons === "object" && icons !== null) {
+      if (Array.isArray(icons.patterns)) {
+        result.iconPatterns = icons.patterns;
+      }
+    }
+    return result;
+  } catch {
+    return null;
+  }
+}
 function registerGenerate(manifestCmd) {
   manifestCmd.command("generate").description(
-    "Generate the component manifest from source and write to .reactscope/manifest.json"
+    'Scan source files and generate .reactscope/manifest.json.\n\nUses Babel static analysis \u2014 no runtime or bundler required.\nRe-run whenever components are added, removed, or significantly changed.\n\nReads reactscope.config.json for:\n  components.include      glob patterns for source files\n  components.exclude      glob patterns to skip\n  internalPatterns         globs to flag components as internal\n  collections             named groups of components\n\nCLI flags (--include, --exclude) override config-file values.\n\nWHAT IT CAPTURES per component:\n  - File path and export name\n  - All props with types and default values\n  - Hook usage (useState, useEffect, useContext, custom hooks)\n  - Side effects (fetch, timers, subscriptions)\n  - Complexity class: simple | complex\n  - Context dependencies and composed child components\n\nExamples:\n  scope manifest generate\n  scope manifest generate --root ./packages/ui\n  scope manifest generate --include "src/components/**/*.tsx" --exclude "**/*.stories.tsx"\n  scope manifest generate --output ./custom-manifest.json'
   ).option("--root <path>", "Project root directory (default: cwd)").option("--output <path>", "Output path for manifest.json", MANIFEST_PATH).option("--include <globs>", "Comma-separated glob patterns to include").option("--exclude <globs>", "Comma-separated glob patterns to exclude").action(async (opts) => {
     try {
       const rootDir = resolve(process.cwd(), opts.root ?? ".");
       const outputPath = resolve(process.cwd(), opts.output);
-      const include = opts.include?.split(",").map((s) => s.trim());
-      const exclude = opts.exclude?.split(",").map((s) => s.trim());
+      const configValues = loadReactScopeConfig(rootDir);
+      const include = opts.include?.split(",").map((s) => s.trim()) ?? configValues?.include;
+      const exclude = opts.exclude?.split(",").map((s) => s.trim()) ?? configValues?.exclude;
       process.stderr.write(`Scanning ${rootDir} for React components...
 `);
       const manifest = await generateManifest({
         rootDir,
         ...include !== void 0 && { include },
-        ...exclude !== void 0 && { exclude }
+        ...exclude !== void 0 && { exclude },
+        ...configValues?.internalPatterns !== void 0 && {
+          internalPatterns: configValues.internalPatterns
+        },
+        ...configValues?.collections !== void 0 && {
+          collections: configValues.collections
+        },
+        ...configValues?.iconPatterns !== void 0 && {
+          iconPatterns: configValues.iconPatterns
+        }
       });
       const componentCount = Object.keys(manifest.components).length;
       process.stderr.write(`Found ${componentCount} components.
@@ -1814,7 +2227,7 @@ function registerGenerate(manifestCmd) {
 }
 function createManifestCommand() {
   const manifestCmd = new Command("manifest").description(
-    "Query and explore the component manifest"
+    "Query and explore the component manifest (.reactscope/manifest.json).\n\nThe manifest is the source-of-truth registry of every React component\nin your codebase \u2014 generated by static analysis (no runtime needed).\n\nRun `scope manifest generate` first, then use list/get/query to explore.\n\nExamples:\n  scope manifest generate\n  scope manifest list\n  scope manifest get Button\n  scope manifest query --complexity complex --has-fetch"
   );
   registerList(manifestCmd);
   registerGet(manifestCmd);
@@ -2130,7 +2543,19 @@ async function runHooksProfiling(componentName, filePath, props) {
 }
 function createInstrumentHooksCommand() {
   const cmd = new Command("hooks").description(
-    "Profile per-hook-instance data for a component: update counts, cache hit rates, effect counts, and more"
+    `Profile per-hook-instance data for a component.
+METRICS CAPTURED per hook instance:
+  useState    update count, current value
+  useCallback cache hit rate (stable reference %)
+  useMemo     cache hit rate (recompute %)
+  useEffect   execution count
+  useRef      current value snapshot
+Examples:
+  scope instrument hooks SearchInput
+  scope instrument hooks SearchInput --props '{"value":"hello"}' --json
+  scope instrument hooks Dropdown --json | jq '.hooks[] | select(.type == "useMemo")'  `
   ).argument("<component>", "Component name (must exist in the manifest)").option("--props <json>", "Inline props JSON passed to the component", "{}").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).option("--format <fmt>", "Output format: json|text (default: auto)", "json").option("--show-flags", "Show heuristic flags only (useful for CI checks)", false).action(
     async (componentName, opts) => {
       try {
@@ -2168,7 +2593,7 @@ Available: ${available}`
         process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
       } catch (err) {
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -2271,13 +2696,11 @@ function buildProfilingCollectScript() {
   // mount commit), it *may* have been wasted if it didn't actually need to re-render.
   // For the initial snapshot we approximate: wastedRenders = max(0, totalCommits - 1) * 0.3
   // This is a heuristic \u2014 real wasted render detection needs shouldComponentUpdate/React.memo tracing.
-  var wastedRenders = Math.max(0, Math.round((totalCommits - 1) * uniqueNames.length * 0.3));
   return {
     commitCount: totalCommits,
     uniqueComponents: uniqueNames.length,
     componentNames: uniqueNames,
-    wastedRenders: wastedRenders,
+    wastedRenders: null,
     layoutTime: window.__scopeLayoutTime || 0,
     paintTime: window.__scopePaintTime || 0,
     layoutShifts: window.__scopeLayoutShifts || { count: 0, score: 0 }
@@ -2325,7 +2748,7 @@ async function replayInteraction(page, steps) {
 }
 function analyzeProfileFlags(totalRenders, wastedRenders, timing, layoutShifts) {
   const flags = /* @__PURE__ */ new Set();
-  if (wastedRenders > 0 && wastedRenders / Math.max(1, totalRenders) > 0.3) {
+  if (wastedRenders !== null && wastedRenders > 0 && wastedRenders / Math.max(1, totalRenders) > 0.3) {
     flags.add("WASTED_RENDER");
   }
   if (totalRenders > 10) {
@@ -2396,13 +2819,18 @@ async function runInteractionProfile(componentName, filePath, props, interaction
     };
     const totalRenders = profileData.commitCount ?? 0;
     const uniqueComponents = profileData.uniqueComponents ?? 0;
-    const wastedRenders = profileData.wastedRenders ?? 0;
+    const wastedRenders = profileData.wastedRenders ?? null;
     const flags = analyzeProfileFlags(totalRenders, wastedRenders, timing, layoutShifts);
     return {
       component: componentName,
       totalRenders,
       uniqueComponents,
       wastedRenders,
+      wastedRendersHeuristic: {
+        measured: false,
+        value: null,
+        note: "profile.wastedRenders is retained for compatibility but set to null because Scope does not directly measure wasted renders yet."
+      },
       timing,
       layoutShifts,
       flags,
@@ -2414,7 +2842,19 @@ async function runInteractionProfile(componentName, filePath, props, interaction
 }
 function createInstrumentProfileCommand() {
   const cmd = new Command("profile").description(
-    "Capture a full interaction-scoped performance profile: renders, timing, layout shifts"
+    `Capture a full performance profile for an interaction sequence.
+PROFILE INCLUDES:
+  renders       total re-renders triggered by the interaction
+  timing        interaction start \u2192 paint time (ms)
+  layoutShifts  cumulative layout shift (CLS) score
+  scriptTime    JS execution time (ms)
+  longTasks     count of tasks >50ms
+Examples:
+  scope instrument profile Button --interaction '[{"action":"click","target":"button"}]'
+  scope instrument profile Modal --interaction '[{"action":"click","target":".open-btn"}]' --json
+  scope instrument profile Form --json | jq '.summary.renderCount'`
   ).argument("<component>", "Component name (must exist in the manifest)").option(
     "--interaction <json>",
     `Interaction steps JSON, e.g. '[{"action":"click","target":"button.primary"}]'`,
@@ -2465,7 +2905,7 @@ Available: ${available}`
         process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
       } catch (err) {
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -2750,7 +3190,21 @@ async function runInstrumentTree(options) {
   }
 }
 function createInstrumentTreeCommand() {
-  return new Command("tree").description("Render a component via BrowserPool and output a structured instrumentation tree").argument("<component>", "Component name to instrument (must exist in the manifest)").option("--sort-by <field>", "Sort nodes by field: renderCount | depth").option("--limit <n>", "Limit output to the first N nodes (depth-first)").option("--uses-context <name>", "Filter to components that use a specific context").option("--provider-depth", "Annotate each node with its context-provider nesting depth", false).option(
+  return new Command("tree").description(
+    `Render a component and output the full instrumentation tree:
+DOM structure, computed styles per node, a11y roles, and React fibers.
+OUTPUT STRUCTURE per node:
+  tag / id / className    DOM identity
+  computedStyles          resolved CSS properties
+  a11y                    role, name, focusable
+  children                nested child nodes
+Examples:
+  scope instrument tree Card
+  scope instrument tree Button --props '{"variant":"primary"}' --json
+  scope instrument tree Input --json | jq '.tree.computedStyles'`
+  ).argument("<component>", "Component name to instrument (must exist in the manifest)").option("--sort-by <field>", "Sort nodes by field: renderCount | depth").option("--limit <n>", "Limit output to the first N nodes (depth-first)").option("--uses-context <name>", "Filter to components that use a specific context").option("--provider-depth", "Annotate each node with its context-provider nesting depth", false).option(
     "--wasted-renders",
     "Filter to components with wasted renders (no prop/state/context changes, not memoized)",
     false
@@ -2796,7 +3250,7 @@ Available: ${available}`
 `);
       }
     } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+      process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
       process.exit(1);
     }
@@ -3144,7 +3598,8 @@ Available: ${available}`
   }
   const rootDir = process.cwd();
   const filePath = resolve(rootDir, descriptor.filePath);
-  const preScript = getBrowserEntryScript() + "\n" + buildInstrumentationScript();
+  const preScript = `${getBrowserEntryScript()}
+${buildInstrumentationScript()}`;
   const htmlHarness = await buildComponentHarness(
     filePath,
     options.componentName,
@@ -3233,7 +3688,24 @@ function formatRendersTable(result) {
   return lines.join("\n");
 }
 function createInstrumentRendersCommand() {
-  return new Command("renders").description("Trace re-render causality chains for a component during an interaction sequence").argument("<component>", "Component name to instrument (must be in manifest)").option(
+  return new Command("renders").description(
+    `Trace every re-render triggered by an interaction and identify root causes.
+OUTPUT INCLUDES per render event:
+  component      which component re-rendered
+  trigger        why it re-rendered: state_change | props_change | context_change |
+                 parent_rerender | force_update | hook_dependency
+  wasted         true if re-rendered with no changed inputs and not memoized
+  chain          full causality chain from root cause to this render
+WASTED RENDERS: propsChanged=false AND stateChanged=false AND contextChanged=false
+AND memoized=false \u2014 these are optimisation opportunities.
+Examples:
+  scope instrument renders SearchPage --interaction '[{"action":"type","target":"input","text":"hello"}]'
+  scope instrument renders Button --interaction '[{"action":"click","target":"button"}]' --json
+  scope instrument renders Form --json | jq '.events[] | select(.wasted == true)'`
+  ).argument("<component>", "Component name to instrument (must be in manifest)").option(
     "--interaction <json>",
     `Interaction sequence JSON, e.g. '[{"action":"click","target":"button"}]'`,
     "[]"
@@ -3270,7 +3742,7 @@ function createInstrumentRendersCommand() {
         }
       } catch (err) {
         await shutdownPool2();
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -3279,7 +3751,28 @@ function createInstrumentRendersCommand() {
 }
 function createInstrumentCommand() {
   const instrumentCmd = new Command("instrument").description(
-    "Structured instrumentation commands for React component analysis"
+    `Runtime instrumentation for React component behaviour analysis.
+All instrument commands:
+  1. Build an esbuild harness for the component
+  2. Load it in a Playwright browser
+  3. Inject instrumentation hooks into React DevTools fiber
+  4. Execute interactions and collect events
+PREREQUISITES:
+  scope manifest generate   (component must be in manifest)
+  reactscope.config.json    (for wrappers/globalCSS)
+INTERACTION FORMAT:
+  JSON array of step objects: [{action, target, text?}]
+  Actions: click | type | focus | blur | hover | key
+  Target: CSS selector for the element to interact with
+Examples:
+  scope instrument renders Button --interaction '[{"action":"click","target":"button"}]'
+  scope instrument hooks SearchInput --props '{"value":"hello"}'
+  scope instrument profile Modal --interaction '[{"action":"click","target":".open-btn"}]'
+  scope instrument tree Card`
   );
   instrumentCmd.addCommand(createInstrumentRendersCommand());
   instrumentCmd.addCommand(createInstrumentHooksCommand());
@@ -3327,6 +3820,54 @@ function writeReportToFile(report, outputPath, pretty) {
   const json = pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
   writeFileSync(outputPath, json, "utf-8");
 }
+var RUN_SUMMARY_PATH = ".reactscope/run-summary.json";
+function buildNextActions(summary) {
+  const actions = /* @__PURE__ */ new Set();
+  for (const failure of summary.failures) {
+    if (failure.stage === "render" || failure.stage === "matrix") {
+      actions.add(
+        `Inspect ${failure.outputPath ?? ".reactscope/renders"} and add/fix ${failure.component}.scope.tsx scenarios or wrappers.`
+      );
+    } else if (failure.stage === "playground") {
+      actions.add(
+        `Open the generated component page and inspect the playground bundling error for ${failure.component}.`
+      );
+    } else if (failure.stage === "compliance") {
+      actions.add(
+        "Run `scope render all` first, then inspect .reactscope/compliance-styles.json and reactscope.tokens.json."
+      );
+    } else if (failure.stage === "site") {
+      actions.add(
+        "Inspect .reactscope/site output and rerun `scope site build` after fixing render/playground failures."
+      );
+    }
+  }
+  if (summary.compliance && summary.compliance.auditedProperties === 0) {
+    actions.add(
+      "No CSS properties were audited. Verify renders produced computed styles and your token file contains matching token categories."
+    );
+  } else if (summary.compliance && summary.compliance.threshold !== void 0 && summary.compliance.score < summary.compliance.threshold) {
+    actions.add(
+      "Inspect .reactscope/compliance-report.json for off-system values and update tokens or component styles."
+    );
+  }
+  if (actions.size === 0) {
+    actions.add("No follow-up needed. Outputs are ready for inspection.");
+  }
+  return [...actions];
+}
+function writeRunSummary(summary, summaryPath = RUN_SUMMARY_PATH) {
+  const outputPath = resolve(process.cwd(), summaryPath);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  const payload = {
+    ...summary,
+    generatedAt: summary.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    nextActions: summary.nextActions ?? buildNextActions(summary)
+  };
+  writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}
+`, "utf-8");
+  return outputPath;
+}
 var SCOPE_EXTENSIONS = [".scope.tsx", ".scope.ts", ".scope.jsx", ".scope.js"];
 function findScopeFile(componentFilePath) {
   const dir = dirname(componentFilePath);
@@ -3454,6 +3995,63 @@ function loadGlobalCssFilesFromConfig(cwd) {
     return [];
   }
 }
+var TAILWIND_CONFIG_FILES2 = [
+  "tailwind.config.js",
+  "tailwind.config.cjs",
+  "tailwind.config.mjs",
+  "tailwind.config.ts",
+  "postcss.config.js",
+  "postcss.config.cjs",
+  "postcss.config.mjs",
+  "postcss.config.ts"
+];
+function shouldWarnForMissingGlobalCss(cwd) {
+  if (TAILWIND_CONFIG_FILES2.some((file) => existsSync(resolve(cwd, file)))) {
+    return true;
+  }
+  const packageJsonPath = resolve(cwd, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return [pkg.dependencies, pkg.devDependencies].some(
+      (deps) => deps && Object.keys(deps).some(
+        (name) => name === "tailwindcss" || name.startsWith("@tailwindcss/")
+      )
+    );
+  } catch {
+    return false;
+  }
+}
+function loadIconPatternsFromConfig(cwd) {
+  const configPath = resolve(cwd, "reactscope.config.json");
+  if (!existsSync(configPath)) return [];
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return cfg.icons?.patterns ?? [];
+  } catch {
+    return [];
+  }
+}
+function matchGlob2(pattern, value) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const regexStr = escaped.replace(/\*\*/g, "\xA7GLOBSTAR\xA7").replace(/\*/g, "[^/]*").replace(/§GLOBSTAR§/g, ".*");
+  return new RegExp(`^${regexStr}$`, "i").test(value);
+}
+function isIconComponent(filePath, displayName, patterns) {
+  return patterns.length > 0 && patterns.some((p) => matchGlob2(p, filePath) || matchGlob2(p, displayName));
+}
+function formatAggregateRenderFailureJson(componentName, failures, scenarioCount, runSummaryPath) {
+  return {
+    command: `scope render component ${componentName}`,
+    status: "failed",
+    component: componentName,
+    scenarioCount,
+    failureCount: failures.length,
+    failures,
+    runSummaryPath
+  };
+}
 var MANIFEST_PATH6 = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR = ".reactscope/renders";
 var _pool3 = null;
@@ -3474,7 +4072,7 @@ async function shutdownPool3() {
     _pool3 = null;
   }
 }
-function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, globalCssFiles = [], projectCwd = process.cwd(), wrapperScript) {
+function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, globalCssFiles = [], projectCwd = process.cwd(), wrapperScript, iconMode = false) {
   const satori = new SatoriRenderer({
     defaultViewport: { width: viewportWidth, height: viewportHeight }
   });
@@ -3484,13 +4082,15 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, g
       const startMs = performance.now();
       const pool = await getPool3(viewportWidth, viewportHeight);
       const projectCss = await loadGlobalCss(globalCssFiles, projectCwd);
+      const PAD = 8;
       const htmlHarness = await buildComponentHarness(
         filePath,
         componentName,
         props,
         viewportWidth,
         projectCss ?? void 0,
-        wrapperScript
+        wrapperScript,
+        PAD
       );
       const slot = await pool.acquire();
       const { page } = slot;
@@ -3531,17 +4131,28 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, g
             `Component "${componentName}" rendered with zero bounding box \u2014 it may be invisible or not mounted`
           );
         }
-        const PAD = 8;
         const clipX = Math.max(0, boundingBox.x - PAD);
         const clipY = Math.max(0, boundingBox.y - PAD);
         const rawW = boundingBox.width + PAD * 2;
         const rawH = boundingBox.height + PAD * 2;
         const safeW = Math.min(rawW, viewportWidth - clipX);
         const safeH = Math.min(rawH, viewportHeight - clipY);
-        const screenshot = await page.screenshot({
-          clip: { x: clipX, y: clipY, width: safeW, height: safeH },
-          type: "png"
-        });
+        let svgContent;
+        let screenshot;
+        if (iconMode) {
+          svgContent = await page.evaluate((sel) => {
+            const root = document.querySelector(sel);
+            const el = root?.firstElementChild;
+            if (!el) return void 0;
+            return el.outerHTML;
+          }, "[data-reactscope-root]") ?? void 0;
+          screenshot = Buffer.alloc(0);
+        } else {
+          screenshot = await page.screenshot({
+            clip: { x: clipX, y: clipY, width: safeW, height: safeH },
+            type: "png"
+          });
+        }
         const STYLE_PROPS = [
           "display",
           "width",
@@ -3664,7 +4275,7 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, g
           name: a11yInfo.name,
           violations: imgViolations
         };
-        return {
+        const renderResult = {
           screenshot,
           width: Math.round(safeW),
           height: Math.round(safeH),
@@ -3673,6 +4284,10 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, g
           dom,
           accessibility
         };
+        if (iconMode && svgContent) {
+          renderResult.svgContent = svgContent;
+        }
+        return renderResult;
       } finally {
         pool.release(slot);
       }
@@ -3709,7 +4324,27 @@ Available: ${available}`
   return { __default__: {} };
 }
 function registerRenderSingle(renderCmd) {
-  renderCmd.command("component <component>", { isDefault: true }).description("Render a single component to PNG or JSON").option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--scenario <name>", "Run a named scenario from the component's .scope file").option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).action(
+  renderCmd.command("component <component>", { isDefault: true }).description(
+    `Render one component to a PNG screenshot or JSON data object.
+PROP SOURCES (in priority order):
+  --scenario <name>    named scenario from <ComponentName>.scope file
+  --props <json>       inline props JSON string
+  (no flag)            component rendered with all-default props
+FORMAT DETECTION:
+  --format png    always write PNG
+  --format json   always write JSON render data
+  auto (default)  PNG when -o has .png extension or stdout is file;
+                  JSON when stdout is a pipe
+Examples:
+  scope render component Button
+  scope render component Button --props '{"variant":"primary","size":"lg"}'
+  scope render component Button --scenario hover-state -o button-hover.png
+  scope render component Card --viewport 375x812 --theme dark
+  scope render component Badge --format json | jq '.a11y'`
+  ).option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--scenario <name>", "Run a named scenario from the component's .scope file").option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -3752,7 +4387,7 @@ Available: ${available}`
         const wrapperScript = scopeData?.hasWrapper === true ? await buildWrapperScript(scopeData.filePath) : void 0;
         const scenarios = buildScenarioMap(opts, scopeData);
         const globalCssFiles = loadGlobalCssFilesFromConfig(rootDir);
-        if (globalCssFiles.length === 0) {
+        if (globalCssFiles.length === 0 && shouldWarnForMissingGlobalCss(rootDir)) {
           process.stderr.write(
             "warning: No globalCSS files configured. Tailwind/CSS styles will not be applied to renders.\n  Add `components.wrappers.globalCSS` to reactscope.config.json\n"
           );
@@ -3771,7 +4406,8 @@ Available: ${available}`
 `
         );
         const fmt2 = resolveSingleFormat(opts.format);
-        let anyFailed = false;
+        const failures = [];
+        const outputPaths = [];
         for (const [scenarioName, props2] of Object.entries(scenarios)) {
           const isNamed = scenarioName !== "__default__";
           const label = isNamed ? `${componentName}:${scenarioName}` : componentName;
@@ -3794,7 +4430,14 @@ Available: ${available}`
               process.stderr.write(`  Hints: ${hintList}
 `);
             }
-            anyFailed = true;
+            failures.push({
+              component: componentName,
+              scenario: isNamed ? scenarioName : void 0,
+              stage: "render",
+              message: outcome.error.message,
+              outputPath: `${DEFAULT_OUTPUT_DIR}/${isNamed ? `${componentName}-${scenarioName}.error.json` : `${componentName}.error.json`}`,
+              hints: outcome.error.heuristicFlags
+            });
             continue;
           }
           const result = outcome.result;
@@ -3802,6 +4445,7 @@ Available: ${available}`
           if (opts.output !== void 0 && !isNamed) {
             const outPath = resolve(process.cwd(), opts.output);
             writeFileSync(outPath, result.screenshot);
+            outputPaths.push(outPath);
             process.stdout.write(
               `\u2713 ${label} \u2192 ${opts.output} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
 `
@@ -3816,17 +4460,36 @@ Available: ${available}`
             const outPath = resolve(dir, outFileName);
             writeFileSync(outPath, result.screenshot);
             const relPath = `${DEFAULT_OUTPUT_DIR}/${outFileName}`;
+            outputPaths.push(relPath);
             process.stdout.write(
               `\u2713 ${label} \u2192 ${relPath} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
 `
             );
           }
         }
+        const summaryPath = writeRunSummary({
+          command: `scope render ${componentName}`,
+          status: failures.length > 0 ? "failed" : "success",
+          outputPaths,
+          failures
+        });
+        process.stderr.write(`[scope/render] Run summary written to ${summaryPath}
+`);
+        if (fmt2 === "json" && failures.length > 0) {
+          const aggregateFailure = formatAggregateRenderFailureJson(
+            componentName,
+            failures,
+            Object.keys(scenarios).length,
+            summaryPath
+          );
+          process.stderr.write(`${JSON.stringify(aggregateFailure, null, 2)}
+`);
+        }
         await shutdownPool3();
-        if (anyFailed) process.exit(1);
+        if (failures.length > 0) process.exit(1);
       } catch (err) {
         await shutdownPool3();
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -3834,7 +4497,9 @@ Available: ${available}`
   );
 }
 function registerRenderMatrix(renderCmd) {
-  renderCmd.command("matrix <component>").description("Render a component across a matrix of prop axes").option(
+  renderCmd.command("matrix <component>").description(
+    'Render every combination of values across one or more prop axes.\nProduces a matrix of screenshots \u2014 one cell per combination.\n\nAXES FORMAT (two equivalent forms):\n  Short:  --axes "variant:primary,ghost size:sm,md,lg"\n  JSON:   --axes {"variant":["primary","ghost"],"size":["sm","md","lg"]}\n\nCOMPOSITION CONTEXTS (--contexts):\n  Test component in different layout environments.\n  Available IDs: centered, rtl, sidebar, dark-bg, light-bg\n  (Define custom contexts in reactscope.config.json)\n\nSTRESS PRESETS (--stress):\n  Inject adversarial content to test edge cases.\n  Available IDs: text.long, text.unicode, text.empty\n\nExamples:\n  scope render matrix Button --axes "variant:primary,ghost,destructive"\n  scope render matrix Button --axes "variant:primary,ghost size:sm,lg" --sprite matrix.png\n  scope render matrix Badge --axes "type:info,warn,error" --contexts centered,rtl\n  scope render matrix Input --stress text.long,text.unicode --format json'
+  ).option(
     "--axes <spec>",
     `Axis definitions: key:v1,v2 space-separated OR JSON object e.g. 'variant:primary,ghost size:sm,lg' or '{"variant":["primary","ghost"],"size":["sm","lg"]}'`
   ).option(
@@ -3985,7 +4650,7 @@ Available: ${available}`
         }
       } catch (err) {
         await shutdownPool3();
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -3993,7 +4658,9 @@ Available: ${available}`
   );
 }
 function registerRenderAll(renderCmd) {
-  renderCmd.command("all").description("Render all components from the manifest").option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
+  renderCmd.command("all").description(
+    "Render every component in the manifest and write to .reactscope/renders/.\n\nAlso emits .reactscope/compliance-styles.json (computed CSS class\u2192value map)\nwhich is required by `scope tokens compliance`.\n\nSCENARIO SELECTION:\n  Each component is rendered using its default scenario from its .scope file\n  if one exists, otherwise with all-default props.\n\nMATRIX AUTO-DETECTION:\n  If a component has a .scope file with a matrix block, render all\n  will render the matrix cells in addition to the default screenshot.\n\nExamples:\n  scope render all\n  scope render all --concurrency 8\n  scope render all --format json --output-dir .reactscope/renders\n  scope render all --manifest ./custom/manifest.json"
+  ).option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
     async (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -4001,7 +4668,21 @@ function registerRenderAll(renderCmd) {
         const total = componentNames.length;
         if (total === 0) {
           process.stderr.write("No components found in manifest.\n");
-          return;
+          const summaryPath2 = writeRunSummary({
+            command: "scope render all",
+            status: "failed",
+            outputPaths: [],
+            failures: [
+              {
+                component: "*",
+                stage: "render",
+                message: "No components found in manifest; refusing to report a false-green batch render."
+              }
+            ]
+          });
+          process.stderr.write(`[scope/render] Run summary written to ${summaryPath2}
+`);
+          process.exit(1);
         }
         const concurrency = Math.max(1, parseInt(opts.concurrency, 10) || 4);
         const outputDir = resolve(process.cwd(), opts.outputDir);
@@ -4010,13 +4691,17 @@ function registerRenderAll(renderCmd) {
         process.stderr.write(`Rendering ${total} components (concurrency: ${concurrency})\u2026
 `);
         const results = [];
+        const failures = [];
+        const outputPaths = [];
         const complianceStylesMap = {};
         let completed = 0;
+        const iconPatterns = loadIconPatternsFromConfig(process.cwd());
         const renderOne = async (name) => {
           const descriptor = manifest.components[name];
           if (descriptor === void 0) return;
           const filePath = resolve(rootDir, descriptor.filePath);
           const allCssFiles = loadGlobalCssFilesFromConfig(process.cwd());
+          const isIcon = isIconComponent(descriptor.filePath, name, iconPatterns);
           const scopeData = await loadScopeFileForComponent(filePath);
           const scenarioEntries = scopeData !== null ? Object.entries(scopeData.scenarios) : [];
           const defaultEntry = scenarioEntries.find(([k]) => k === "default") ?? scenarioEntries[0];
@@ -4029,7 +4714,8 @@ function registerRenderAll(renderCmd) {
             812,
             allCssFiles,
             process.cwd(),
-            wrapperScript
+            wrapperScript,
+            isIcon
           );
           const outcome = await safeRender(
             () => renderer.renderCell(renderProps, descriptor.complexityClass),
@@ -4066,14 +4752,32 @@ function registerRenderAll(renderCmd) {
                 2
               )
             );
+            failures.push({
+              component: name,
+              stage: "render",
+              message: outcome.error.message,
+              outputPath: errPath,
+              hints: outcome.error.heuristicFlags
+            });
+            outputPaths.push(errPath);
             return;
           }
           const result = outcome.result;
           results.push({ name, renderTimeMs: result.renderTimeMs, success: true });
-          const pngPath = resolve(outputDir, `${name}.png`);
-          writeFileSync(pngPath, result.screenshot);
+          if (!isIcon) {
+            const pngPath = resolve(outputDir, `${name}.png`);
+            writeFileSync(pngPath, result.screenshot);
+            outputPaths.push(pngPath);
+          }
           const jsonPath = resolve(outputDir, `${name}.json`);
-          writeFileSync(jsonPath, JSON.stringify(formatRenderJson(name, {}, result), null, 2));
+          const renderJson = formatRenderJson(name, {}, result);
+          const extResult = result;
+          if (isIcon && extResult.svgContent) {
+            renderJson.svgContent = extResult.svgContent;
+            delete renderJson.screenshot;
+          }
+          writeFileSync(jsonPath, JSON.stringify(renderJson, null, 2));
+          outputPaths.push(jsonPath);
           const rawStyles = result.computedStyles["[data-reactscope-root] > *"] ?? {};
           const compStyles = {
             colors: {},
@@ -4139,15 +4843,21 @@ function registerRenderAll(renderCmd) {
               existingJson.axisLabels = [scenarioAxis.values];
               writeFileSync(jsonPath, JSON.stringify(existingJson, null, 2));
             } catch (matrixErr) {
-              process.stderr.write(
-                `  [warn] Matrix render for ${name} failed: ${matrixErr instanceof Error ? matrixErr.message : String(matrixErr)}
-`
-              );
+              const message = matrixErr instanceof Error ? matrixErr.message : String(matrixErr);
+              process.stderr.write(`  [warn] Matrix render for ${name} failed: ${message}
+`);
+              failures.push({
+                component: name,
+                stage: "matrix",
+                message,
+                outputPath: jsonPath
+              });
             }
           }
           if (isTTY()) {
+            const suffix = isIcon ? " [icon/svg]" : "";
             process.stdout.write(
-              `\u2713 ${name} \u2192 ${opts.outputDir}/${name}.png (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)
+              `\u2713 ${name} \u2192 ${opts.outputDir}/${name}${isIcon ? ".json" : ".png"} (${result.width}\xD7${result.height}, ${result.renderTimeMs.toFixed(0)}ms)${suffix}
 `
             );
           }
@@ -4174,15 +4884,25 @@ function registerRenderAll(renderCmd) {
           "compliance-styles.json"
         );
         writeFileSync(compStylesPath, JSON.stringify(complianceStylesMap, null, 2));
+        outputPaths.push(compStylesPath);
         process.stderr.write(`[scope/render] \u2713 Wrote compliance-styles.json
 `);
         process.stderr.write("\n");
         const summary = formatSummaryText(results, outputDir);
         process.stderr.write(`${summary}
 `);
+        const summaryPath = writeRunSummary({
+          command: "scope render all",
+          status: failures.length > 0 ? "failed" : "success",
+          outputPaths,
+          failures
+        });
+        process.stderr.write(`[scope/render] Run summary written to ${summaryPath}
+`);
+        if (failures.length > 0) process.exit(1);
       } catch (err) {
         await shutdownPool3();
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -4215,7 +4935,7 @@ function resolveMatrixFormat(formatFlag, spriteAlreadyWritten) {
 }
 function createRenderCommand() {
   const renderCmd = new Command("render").description(
-    "Render components to PNG or JSON via esbuild + BrowserPool"
+    'Render React components to PNG screenshots or JSON render data.\n\nScope uses two render engines depending on component complexity:\n  Satori     \u2014 fast SVG\u2192PNG renderer for simple/presentational components\n  BrowserPool \u2014 Playwright headless browser for complex components\n               (context providers, hooks, async, global CSS)\n\nPREREQUISITES:\n  1. reactscope.config.json exists  (scope init)\n  2. manifest.json is up to date    (scope manifest generate)\n  3. If using globalCSS: Tailwind/PostCSS is configured in the project\n\nOUTPUTS (written to .reactscope/renders/<ComponentName>/):\n  screenshot.png     retina-quality PNG (2\xD7 physical pixels, displayed at 1\xD7)\n  render.json        props, dimensions, DOM snapshot, a11y, computed styles\n  compliance-styles.json (render all only) \u2014 token matching input\n\nExamples:\n  scope render component Button\n  scope render matrix Button --axes "variant:primary,ghost size:sm,md,lg"\n  scope render all\n  scope render all --format json --output-dir ./out'
   );
   registerRenderSingle(renderCmd);
   registerRenderMatrix(renderCmd);
@@ -4242,8 +4962,17 @@ async function shutdownPool4() {
   }
 }
 async function renderComponent2(filePath, componentName, props, viewportWidth, viewportHeight) {
+  const PAD = 24;
   const pool = await getPool4(viewportWidth, viewportHeight);
-  const htmlHarness = await buildComponentHarness(filePath, componentName, props, viewportWidth);
+  const htmlHarness = await buildComponentHarness(
+    filePath,
+    componentName,
+    props,
+    viewportWidth,
+    void 0,
+    void 0,
+    PAD
+  );
   const slot = await pool.acquire();
   const { page } = slot;
   try {
@@ -4283,7 +5012,6 @@ async function renderComponent2(filePath, componentName, props, viewportWidth, v
         `Component "${componentName}" rendered with zero bounding box \u2014 it may be invisible or not mounted`
       );
     }
-    const PAD = 24;
     const MIN_W = 320;
     const MIN_H = 200;
     const clipX = Math.max(0, boundingBox.x - PAD);
@@ -4375,12 +5103,12 @@ async function runBaseline(options = {}) {
   mkdirSync(rendersDir, { recursive: true });
   let manifest;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync14 } = await import('fs');
+    const { readFileSync: readFileSync18 } = await import('fs');
     const absPath = resolve(rootDir, manifestPath);
     if (!existsSync(absPath)) {
       throw new Error(`Manifest not found at ${absPath}.`);
     }
-    manifest = JSON.parse(readFileSync14(absPath, "utf-8"));
+    manifest = JSON.parse(readFileSync18(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -4572,8 +5300,17 @@ async function shutdownPool5() {
   }
 }
 async function renderComponent3(filePath, componentName, props, viewportWidth, viewportHeight) {
+  const PAD = 24;
   const pool = await getPool5(viewportWidth, viewportHeight);
-  const htmlHarness = await buildComponentHarness(filePath, componentName, props, viewportWidth);
+  const htmlHarness = await buildComponentHarness(
+    filePath,
+    componentName,
+    props,
+    viewportWidth,
+    void 0,
+    void 0,
+    PAD
+  );
   const slot = await pool.acquire();
   const { page } = slot;
   try {
@@ -4613,7 +5350,6 @@ async function renderComponent3(filePath, componentName, props, viewportWidth, v
         `Component "${componentName}" rendered with zero bounding box \u2014 it may be invisible or not mounted`
       );
     }
-    const PAD = 24;
     const MIN_W = 320;
     const MIN_H = 200;
     const clipX = Math.max(0, boundingBox.x - PAD);
@@ -4710,6 +5446,7 @@ function classifyComponent(entry, regressionThreshold) {
 async function runDiff(options = {}) {
   const {
     baselineDir: baselineDirRaw = DEFAULT_BASELINE_DIR2,
+    complianceTokens = [],
     componentsGlob,
     manifestPath,
     viewportWidth = 375,
@@ -4825,7 +5562,7 @@ async function runDiff(options = {}) {
   if (isTTY() && total > 0) {
     process.stderr.write("\n");
   }
-  const resolver = new TokenResolver([]);
+  const resolver = new TokenResolver(complianceTokens);
   const engine = new ComplianceEngine(resolver);
   const currentBatchReport = engine.auditBatch(computedStylesMap);
   const entries = [];
@@ -5421,6 +6158,161 @@ function buildStructuredReport(report) {
     route: report.route?.pattern ?? null
   };
 }
+async function buildPlaygroundHarness(filePath, componentName, projectCss, wrapperScript) {
+  const bundledScript = await bundlePlaygroundIIFE(filePath, componentName);
+  return wrapPlaygroundHtml(bundledScript, projectCss);
+}
+async function bundlePlaygroundIIFE(filePath, componentName) {
+  const wrapperCode = (
+    /* ts */
+    `
+import * as __scopeMod from ${JSON.stringify(filePath)};
+import { createRoot } from "react-dom/client";
+import { createElement, Component as ReactComponent } from "react";
+(function scopePlaygroundHarness() {
+  var Target =
+    __scopeMod["default"] ||
+    __scopeMod[${JSON.stringify(componentName)}] ||
+    (Object.values(__scopeMod).find(
+      function(v) { return typeof v === "function" && /^[A-Z]/.test(v.name || ""); }
+    ));
+  if (!Target) {
+    document.getElementById("scope-root").innerHTML =
+      '<p style="color:#dc2626;font-family:system-ui;font-size:13px">No renderable component found.</p>';
+    return;
+  }
+  // Error boundary to catch async render errors (React unmounts the whole
+  // root when an error is uncaught \u2014 this keeps the error visible instead).
+  var errorStyle = "color:#dc2626;font-family:system-ui;font-size:13px;padding:12px";
+  class ScopeBoundary extends ReactComponent {
+    constructor(p) { super(p); this.state = { error: null }; }
+    static getDerivedStateFromError(err) { return { error: err }; }
+    render() {
+      if (this.state.error) {
+        return createElement("pre", { style: errorStyle },
+          "Render error: " + (this.state.error.message || String(this.state.error)));
+      }
+      return this.props.children;
+    }
+  }
+  var rootEl = document.getElementById("scope-root");
+  var root = createRoot(rootEl);
+  var Wrapper = window.__SCOPE_WRAPPER__;
+  function render(props) {
+    var inner = createElement(Target, props);
+    if (Wrapper) inner = createElement(Wrapper, null, inner);
+    root.render(createElement(ScopeBoundary, null, inner));
+  }
+  // Render immediately with empty props
+  render({});
+  // Listen for messages from the parent frame
+  window.addEventListener("message", function(e) {
+    if (!e.data) return;
+    if (e.data.type === "scope-playground-props") {
+      render(e.data.props || {});
+    } else if (e.data.type === "scope-playground-theme") {
+      document.documentElement.classList.toggle("dark", e.data.theme === "dark");
+    }
+  });
+  // Report content height changes to the parent frame
+  var ro = new ResizeObserver(function() {
+    var h = rootEl.scrollHeight;
+    if (parent !== window) {
+      parent.postMessage({ type: "scope-playground-height", height: h }, "*");
+    }
+  });
+  ro.observe(rootEl);
+})();
+`
+  );
+  const result = await esbuild2.build({
+    stdin: {
+      contents: wrapperCode,
+      resolveDir: dirname(filePath),
+      loader: "tsx",
+      sourcefile: "__scope_playground__.tsx"
+    },
+    bundle: true,
+    format: "iife",
+    write: false,
+    platform: "browser",
+    jsx: "automatic",
+    jsxImportSource: "react",
+    target: "es2020",
+    external: [],
+    define: {
+      "process.env.NODE_ENV": '"production"',
+      global: "globalThis"
+    },
+    logLevel: "silent",
+    banner: {
+      js: "/* @agent-scope/cli playground harness */"
+    },
+    loader: {
+      ".css": "empty",
+      ".svg": "dataurl",
+      ".png": "dataurl",
+      ".jpg": "dataurl",
+      ".jpeg": "dataurl",
+      ".gif": "dataurl",
+      ".webp": "dataurl",
+      ".ttf": "dataurl",
+      ".woff": "dataurl",
+      ".woff2": "dataurl"
+    }
+  });
+  if (result.errors.length > 0) {
+    const msg = result.errors.map((e) => `${e.text}${e.location ? ` (${e.location.file}:${e.location.line})` : ""}`).join("\n");
+    throw new Error(`esbuild failed to bundle playground component:
+${msg}`);
+  }
+  const outputFile = result.outputFiles?.[0];
+  if (outputFile === void 0 || outputFile.text.length === 0) {
+    throw new Error("esbuild produced no playground output");
+  }
+  return outputFile.text;
+}
+function wrapPlaygroundHtml(bundledScript, projectCss, wrapperScript) {
+  const projectStyleBlock = projectCss != null && projectCss.length > 0 ? `<style id="scope-project-css">
+${projectCss.replace(/<\/style>/gi, "<\\/style>")}
+</style>` : "";
+  const wrapperScriptBlock = "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <script>
+    window.__SCOPE_WRAPPER__ = null;
+    // Prevent React DevTools from interfering with the embedded playground.
+    // The hook causes render instability in same-origin iframes.
+    delete window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+  </script>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    html, body { margin: 0; padding: 0; font-family: system-ui, sans-serif; }
+    #scope-root { padding: 16px; min-width: 1px; min-height: 1px; }
+  </style>
+  ${projectStyleBlock}
+  <style>html, body { background: transparent !important; }</style>
+</head>
+<body>
+  <div id="scope-root" data-reactscope-root></div>
+  ${wrapperScriptBlock}
+  <script>${bundledScript}</script>
+</body>
+</html>`;
+}
+// src/site-commands.ts
 var MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".css": "text/css; charset=utf-8",
@@ -5432,8 +6324,419 @@ var MIME_TYPES = {
   ".svg": "image/svg+xml",
   ".ico": "image/x-icon"
 };
+function slugify(name) {
+  return name.replace(/([A-Z])/g, (m) => `-${m.toLowerCase()}`).replace(/^-/, "").replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function loadGlobalCssFilesFromConfig2(cwd) {
+  const configPath = resolve(cwd, "reactscope.config.json");
+  if (!existsSync(configPath)) return [];
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return cfg.components?.wrappers?.globalCSS ?? [];
+  } catch {
+    return [];
+  }
+}
+function loadIconPatternsFromConfig2(cwd) {
+  const configPath = resolve(cwd, "reactscope.config.json");
+  if (!existsSync(configPath)) return [];
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return cfg.icons?.patterns ?? [];
+  } catch {
+    return [];
+  }
+}
+var LIVERELOAD_SCRIPT = `<script>(function(){var s=new EventSource("/__livereload");s.onmessage=function(e){if(e.data==="reload")location.reload()};s.onerror=function(){setTimeout(function(){location.reload()},2000)}})()</script>`;
+function injectLiveReloadScript(html) {
+  const idx = html.lastIndexOf("</body>");
+  if (idx >= 0) return html.slice(0, idx) + LIVERELOAD_SCRIPT + html.slice(idx);
+  return html + LIVERELOAD_SCRIPT;
+}
+function loadWatchConfig(rootDir) {
+  const configPath = resolve(rootDir, "reactscope.config.json");
+  if (!existsSync(configPath)) return null;
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    const result = {};
+    const components = cfg.components;
+    if (components && typeof components === "object") {
+      if (Array.isArray(components.include)) result.include = components.include;
+      if (Array.isArray(components.exclude)) result.exclude = components.exclude;
+    }
+    if (Array.isArray(cfg.internalPatterns))
+      result.internalPatterns = cfg.internalPatterns;
+    if (Array.isArray(cfg.collections)) result.collections = cfg.collections;
+    const icons = cfg.icons;
+    if (icons && typeof icons === "object" && Array.isArray(icons.patterns)) {
+      result.iconPatterns = icons.patterns;
+    }
+    return result;
+  } catch {
+    return null;
+  }
+}
+function watchGlob(pattern, filePath) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const regexStr = escaped.replace(/\*\*/g, "\xA7GLOBSTAR\xA7").replace(/\*/g, "[^/]*").replace(/\u00a7GLOBSTAR\u00a7/g, ".*");
+  return new RegExp(`^${regexStr}$`, "i").test(filePath);
+}
+function matchesWatchPatterns(filePath, include, exclude) {
+  for (const pattern of exclude) {
+    if (watchGlob(pattern, filePath)) return false;
+  }
+  for (const pattern of include) {
+    if (watchGlob(pattern, filePath)) return true;
+  }
+  return false;
+}
+function findAffectedComponents(manifest, changedFiles, previousManifest) {
+  const affected = /* @__PURE__ */ new Set();
+  const normalised = changedFiles.map((f) => f.replace(/\\/g, "/"));
+  for (const [name, descriptor] of Object.entries(manifest.components)) {
+    const componentFile = descriptor.filePath.replace(/\\/g, "/");
+    for (const changed of normalised) {
+      if (componentFile === changed) {
+        affected.add(name);
+        break;
+      }
+      const scopeBase = changed.replace(/\.scope\.(ts|tsx|js|jsx)$/, "");
+      const compBase = componentFile.replace(/\.(tsx|ts|jsx|js)$/, "");
+      if (scopeBase !== changed && compBase === scopeBase) {
+        affected.add(name);
+        break;
+      }
+    }
+  }
+  if (previousManifest) {
+    const oldNames = new Set(Object.keys(previousManifest.components));
+    for (const name of Object.keys(manifest.components)) {
+      if (!oldNames.has(name)) affected.add(name);
+    }
+  }
+  return [...affected];
+}
+async function renderComponentsForWatch(manifest, componentNames, rootDir, inputDir) {
+  if (componentNames.length === 0) return;
+  const rendersDir = join(inputDir, "renders");
+  await mkdir(rendersDir, { recursive: true });
+  const cssFiles = loadGlobalCssFilesFromConfig2(rootDir);
+  const iconPatterns = loadIconPatternsFromConfig2(rootDir);
+  const complianceStylesPath = join(inputDir, "compliance-styles.json");
+  let complianceStyles = {};
+  if (existsSync(complianceStylesPath)) {
+    try {
+      complianceStyles = JSON.parse(readFileSync(complianceStylesPath, "utf-8"));
+    } catch {
+    }
+  }
+  for (const name of componentNames) {
+    const descriptor = manifest.components[name];
+    if (!descriptor) continue;
+    const filePath = resolve(rootDir, descriptor.filePath);
+    const isIcon = isIconComponent(descriptor.filePath, name, iconPatterns);
+    let scopeData = null;
+    try {
+      scopeData = await loadScopeFileForComponent(filePath);
+    } catch {
+    }
+    const scenarioEntries = scopeData ? Object.entries(scopeData.scenarios) : [];
+    const defaultEntry = scenarioEntries.find(([k]) => k === "default") ?? scenarioEntries[0];
+    const renderProps = defaultEntry?.[1] ?? {};
+    let wrapperScript;
+    try {
+      wrapperScript = scopeData?.hasWrapper ? await buildWrapperScript(scopeData.filePath) : void 0;
+    } catch {
+    }
+    const renderer = buildRenderer(
+      filePath,
+      name,
+      375,
+      812,
+      cssFiles,
+      rootDir,
+      wrapperScript,
+      isIcon
+    );
+    const outcome = await safeRender(
+      () => renderer.renderCell(renderProps, descriptor.complexityClass),
+      {
+        props: renderProps,
+        sourceLocation: { file: descriptor.filePath, line: descriptor.loc.start, column: 0 }
+      }
+    );
+    if (outcome.crashed) {
+      process.stderr.write(`  \u2717 ${name}: ${outcome.error.message}
+`);
+      continue;
+    }
+    const result = outcome.result;
+    if (!isIcon) {
+      writeFileSync(join(rendersDir, `${name}.png`), result.screenshot);
+    }
+    const renderJson = formatRenderJson(name, renderProps, result);
+    const extResult = result;
+    if (isIcon && extResult.svgContent) {
+      renderJson.svgContent = extResult.svgContent;
+      delete renderJson.screenshot;
+    }
+    writeFileSync(join(rendersDir, `${name}.json`), JSON.stringify(renderJson, null, 2));
+    const rawStyles = result.computedStyles["[data-reactscope-root] > *"] ?? {};
+    const compStyles = {
+      colors: {},
+      spacing: {},
+      typography: {},
+      borders: {},
+      shadows: {}
+    };
+    for (const [prop, val] of Object.entries(rawStyles)) {
+      if (!val || val === "none" || val === "") continue;
+      const lower = prop.toLowerCase();
+      if (lower.includes("color") || lower.includes("background")) {
+        compStyles.colors[prop] = val;
+      } else if (lower.includes("padding") || lower.includes("margin") || lower.includes("gap") || lower.includes("width") || lower.includes("height")) {
+        compStyles.spacing[prop] = val;
+      } else if (lower.includes("font") || lower.includes("lineheight") || lower.includes("letterspacing") || lower.includes("texttransform")) {
+        compStyles.typography[prop] = val;
+      } else if (lower.includes("border") || lower.includes("radius") || lower.includes("outline")) {
+        compStyles.borders[prop] = val;
+      } else if (lower.includes("shadow")) {
+        compStyles.shadows[prop] = val;
+      }
+    }
+    complianceStyles[name] = compStyles;
+    process.stderr.write(`  \u2713 ${name} (${result.renderTimeMs.toFixed(0)}ms)
+`);
+  }
+  await shutdownPool3();
+  writeFileSync(complianceStylesPath, JSON.stringify(complianceStyles, null, 2), "utf-8");
+}
+async function watchRebuildSite(inputDir, outputDir, title, basePath) {
+  const rootDir = process.cwd();
+  await generatePlaygrounds(inputDir, outputDir);
+  const iconPatterns = loadIconPatternsFromConfig2(rootDir);
+  let tokenFilePath;
+  const autoPath = resolve(rootDir, "reactscope.tokens.json");
+  if (existsSync(autoPath)) tokenFilePath = autoPath;
+  let compliancePath;
+  const crPath = join(inputDir, "compliance-report.json");
+  if (existsSync(crPath)) compliancePath = crPath;
+  await buildSite({
+    inputDir,
+    outputDir,
+    basePath,
+    ...compliancePath && { compliancePath },
+    ...tokenFilePath && { tokenFilePath },
+    title,
+    iconPatterns
+  });
+}
+function findStaleComponents(manifest, previousManifest, rendersDir) {
+  const stale = [];
+  for (const [name, descriptor] of Object.entries(manifest.components)) {
+    const jsonPath = join(rendersDir, `${name}.json`);
+    if (!existsSync(jsonPath)) {
+      stale.push(name);
+      continue;
+    }
+    if (!previousManifest) continue;
+    const prev = previousManifest.components[name];
+    if (!prev) {
+      stale.push(name);
+      continue;
+    }
+    if (JSON.stringify(prev) !== JSON.stringify(descriptor)) {
+      stale.push(name);
+    }
+  }
+  return stale;
+}
+async function runFullBuild(rootDir, inputDir, outputDir, title, basePath) {
+  process.stderr.write("[watch] Starting\u2026\n");
+  const config = loadWatchConfig(rootDir);
+  const manifestPath = join(inputDir, "manifest.json");
+  let previousManifest = null;
+  if (existsSync(manifestPath)) {
+    try {
+      previousManifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    } catch {
+    }
+  }
+  process.stderr.write("[watch] Generating manifest\u2026\n");
+  const manifest = await generateManifest({
+    rootDir,
+    ...config?.include && { include: config.include },
+    ...config?.exclude && { exclude: config.exclude },
+    ...config?.internalPatterns && { internalPatterns: config.internalPatterns },
+    ...config?.collections && { collections: config.collections },
+    ...config?.iconPatterns && { iconPatterns: config.iconPatterns }
+  });
+  await mkdir(inputDir, { recursive: true });
+  writeFileSync(join(inputDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf-8");
+  const count = Object.keys(manifest.components).length;
+  process.stderr.write(`[watch] Found ${count} components
+`);
+  const rendersDir = join(inputDir, "renders");
+  const stale = findStaleComponents(manifest, previousManifest, rendersDir);
+  if (stale.length > 0) {
+    process.stderr.write(
+      `[watch] Rendering ${stale.length} component(s) (${count - stale.length} already up-to-date)
+`
+    );
+    await renderComponentsForWatch(manifest, stale, rootDir, inputDir);
+  } else {
+    process.stderr.write("[watch] All renders up-to-date, skipping render step\n");
+  }
+  process.stderr.write("[watch] Building site\u2026\n");
+  await watchRebuildSite(inputDir, outputDir, title, basePath);
+  process.stderr.write("[watch] Ready\n");
+  return manifest;
+}
+function startFileWatcher(opts) {
+  const { rootDir, inputDir, outputDir, title, basePath, notifyReload } = opts;
+  let previousManifest = opts.previousManifest;
+  const config = loadWatchConfig(rootDir);
+  const includePatterns = config?.include ?? ["src/**/*.tsx", "src/**/*.ts"];
+  const excludePatterns = config?.exclude ?? [
+    "**/node_modules/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/dist/**",
+    "**/*.d.ts"
+  ];
+  let debounceTimer = null;
+  const pendingFiles = /* @__PURE__ */ new Set();
+  let isRunning = false;
+  const IGNORE_PREFIXES = ["node_modules/", ".reactscope/", "dist/", ".git/", ".next/", ".turbo/"];
+  const handleChange = async () => {
+    if (isRunning) return;
+    isRunning = true;
+    const changedFiles = [...pendingFiles];
+    pendingFiles.clear();
+    try {
+      process.stderr.write(`
+[watch] ${changedFiles.length} file(s) changed
+`);
+      process.stderr.write("[watch] Regenerating manifest\u2026\n");
+      const newManifest = await generateManifest({
+        rootDir,
+        ...config?.include && { include: config.include },
+        ...config?.exclude && { exclude: config.exclude },
+        ...config?.internalPatterns && { internalPatterns: config.internalPatterns },
+        ...config?.collections && { collections: config.collections },
+        ...config?.iconPatterns && { iconPatterns: config.iconPatterns }
+      });
+      writeFileSync(join(inputDir, "manifest.json"), JSON.stringify(newManifest, null, 2), "utf-8");
+      const affected = findAffectedComponents(newManifest, changedFiles, previousManifest);
+      if (affected.length > 0) {
+        process.stderr.write(`[watch] Re-rendering: ${affected.join(", ")}
+`);
+        await renderComponentsForWatch(newManifest, affected, rootDir, inputDir);
+      } else {
+        process.stderr.write("[watch] No components directly affected\n");
+      }
+      process.stderr.write("[watch] Rebuilding site\u2026\n");
+      await watchRebuildSite(inputDir, outputDir, title, basePath);
+      previousManifest = newManifest;
+      process.stderr.write("[watch] Done\n");
+      notifyReload();
+    } catch (err) {
+      process.stderr.write(`[watch] Error: ${err instanceof Error ? err.message : String(err)}
+`);
+    } finally {
+      isRunning = false;
+      if (pendingFiles.size > 0) {
+        handleChange();
+      }
+    }
+  };
+  const onFileChange = (_eventType, filename) => {
+    if (!filename) return;
+    const normalised = filename.replace(/\\/g, "/");
+    for (const prefix of IGNORE_PREFIXES) {
+      if (normalised.startsWith(prefix)) return;
+    }
+    if (!matchesWatchPatterns(normalised, includePatterns, excludePatterns)) return;
+    pendingFiles.add(normalised);
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      handleChange();
+    }, 500);
+  };
+  try {
+    watch(rootDir, { recursive: true }, onFileChange);
+    process.stderr.write(`[watch] Watching for changes (${includePatterns.join(", ")})
+`);
+  } catch (err) {
+    process.stderr.write(
+      `[watch] Warning: Could not start watcher: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+}
+async function generatePlaygrounds(inputDir, outputDir) {
+  const manifestPath = join(inputDir, "manifest.json");
+  const raw = readFileSync(manifestPath, "utf-8");
+  const manifest = JSON.parse(raw);
+  const rootDir = process.cwd();
+  const componentNames = Object.keys(manifest.components);
+  if (componentNames.length === 0) return [];
+  const playgroundDir = join(outputDir, "playground");
+  await mkdir(playgroundDir, { recursive: true });
+  const cssFiles = loadGlobalCssFilesFromConfig2(rootDir);
+  const projectCss = await loadGlobalCss(cssFiles, rootDir) ?? void 0;
+  let succeeded = 0;
+  const failures = [];
+  const allDefaults = {};
+  for (const name of componentNames) {
+    const descriptor = manifest.components[name];
+    if (!descriptor) continue;
+    const filePath = resolve(rootDir, descriptor.filePath);
+    const slug = slugify(name);
+    try {
+      const scopeData = await loadScopeFileForComponent(filePath);
+      if (scopeData) {
+        const defaultScenario = scopeData.scenarios.default ?? Object.values(scopeData.scenarios)[0];
+        if (defaultScenario) allDefaults[name] = defaultScenario;
+      }
+    } catch {
+    }
+    try {
+      const html = await buildPlaygroundHarness(filePath, name, projectCss);
+      await writeFile(join(playgroundDir, `${slug}.html`), html, "utf-8");
+      succeeded++;
+    } catch (err) {
+      process.stderr.write(
+        `[scope/site]   \u26A0 playground skip: ${name} \u2014 ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      failures.push({
+        component: name,
+        stage: "playground",
+        message: err instanceof Error ? err.message : String(err),
+        outputPath: join(playgroundDir, `${slug}.html`)
+      });
+    }
+  }
+  await writeFile(
+    join(inputDir, "playground-defaults.json"),
+    JSON.stringify(allDefaults, null, 2),
+    "utf-8"
+  );
+  process.stderr.write(
+    `[scope/site] Playgrounds: ${succeeded} built${failures.length > 0 ? `, ${failures.length} failed` : ""}
+`
+  );
+  return failures;
+}
 function registerBuild(siteCmd) {
-  siteCmd.command("build").description("Build a static HTML gallery from .reactscope/ output").option("-i, --input <path>", "Path to .reactscope input directory", ".reactscope").option("-o, --output <path>", "Output directory for generated site", ".reactscope/site").option("--base-path <path>", "Base URL path prefix for subdirectory deployment", "/").option("--compliance <path>", "Path to compliance batch report JSON").option("--title <text>", "Site title", "Scope \u2014 Component Gallery").action(
+  siteCmd.command("build").description(
+    'Build the static HTML site from manifest + render outputs.\n\nINPUT DIRECTORY (.reactscope/ by default) must contain:\n  manifest.json       component registry\n  renders/            screenshots and render.json files from `scope render all`\n\nOPTIONAL:\n  --compliance <path>   include token compliance scores on detail pages\n  --base-path <path>    set if deploying to a subdirectory (e.g. /ui-docs)\n\nExamples:\n  scope site build\n  scope site build --title "Design System" -o .reactscope/site\n  scope site build --compliance .reactscope/compliance-report.json\n  scope site build --tokens reactscope.tokens.json\n  scope site build --base-path /ui'
+  ).option("-i, --input <path>", "Path to .reactscope input directory", ".reactscope").option("-o, --output <path>", "Output directory for generated site", ".reactscope/site").option("--base-path <path>", "Base URL path prefix for subdirectory deployment", "/").option("--compliance <path>", "Path to compliance batch report JSON").option("--tokens <path>", "Path to reactscope.tokens.json (enables token browser page)").option("--title <text>", "Site title", "Scope \u2014 Component Gallery").action(
     async (opts) => {
       try {
         const inputDir = resolve(process.cwd(), opts.input);
@@ -5453,6 +6756,16 @@ Run \`scope manifest generate\` first.`
         }
         process.stderr.write(`Building site from ${inputDir}\u2026
 `);
+        process.stderr.write("Bundling playgrounds\u2026\n");
+        const failures = await generatePlaygrounds(inputDir, outputDir);
+        const iconPatterns = loadIconPatternsFromConfig2(process.cwd());
+        let tokenFilePath = opts.tokens ? resolve(process.cwd(), opts.tokens) : void 0;
+        if (tokenFilePath === void 0) {
+          const autoPath = resolve(process.cwd(), "reactscope.tokens.json");
+          if (existsSync(autoPath)) {
+            tokenFilePath = autoPath;
+          }
+        }
         await buildSite({
           inputDir,
           outputDir,
@@ -5460,14 +6773,44 @@ Run \`scope manifest generate\` first.`
           ...opts.compliance !== void 0 && {
             compliancePath: resolve(process.cwd(), opts.compliance)
           },
-          title: opts.title
+          ...tokenFilePath !== void 0 && { tokenFilePath },
+          title: opts.title,
+          iconPatterns
+        });
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        const componentCount = Object.keys(manifest.components).length;
+        const generatedPlaygroundCount = componentCount === 0 ? 0 : statSync(join(outputDir, "playground")).isDirectory() ? componentCount - failures.length : 0;
+        const siteFailures = [...failures];
+        if (componentCount === 0) {
+          siteFailures.push({
+            component: "*",
+            stage: "site",
+            message: "Manifest contains zero components; generated site is structurally degraded.",
+            outputPath: manifestPath
+          });
+        } else if (generatedPlaygroundCount === 0) {
+          siteFailures.push({
+            component: "*",
+            stage: "site",
+            message: "No playground pages were generated successfully; site build is degraded and should not be treated as green.",
+            outputPath: join(outputDir, "playground")
+          });
+        }
+        const summaryPath = writeRunSummary({
+          command: "scope site build",
+          status: siteFailures.length > 0 ? "failed" : "success",
+          outputPaths: [outputDir, join(outputDir, "index.html")],
+          failures: siteFailures
         });
         process.stderr.write(`Site written to ${outputDir}
+`);
+        process.stderr.write(`[scope/site] Run summary written to ${summaryPath}
 `);
         process.stdout.write(`${outputDir}
 `);
+        if (siteFailures.length > 0) process.exit(1);
       } catch (err) {
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -5475,71 +6818,143 @@ Run \`scope manifest generate\` first.`
   );
 }
 function registerServe(siteCmd) {
-  siteCmd.command("serve").description("Serve the built static site locally").option("-p, --port <number>", "Port to listen on", "3000").option("-d, --dir <path>", "Directory to serve", ".reactscope/site").action((opts) => {
-    try {
-      const port = Number.parseInt(opts.port, 10);
-      if (Number.isNaN(port) || port < 1 || port > 65535) {
-        throw new Error(`Invalid port: ${opts.port}`);
-      }
-      const serveDir = resolve(process.cwd(), opts.dir);
-      if (!existsSync(serveDir)) {
-        throw new Error(
-          `Serve directory not found: ${serveDir}
-Run \`scope site build\` first.`
-        );
-      }
-      const server = createServer((req, res) => {
-        const rawUrl = req.url ?? "/";
-        const urlPath = decodeURIComponent(rawUrl.split("?")[0] ?? "/");
-        const filePath = join(serveDir, urlPath.endsWith("/") ? `${urlPath}index.html` : urlPath);
-        if (!filePath.startsWith(serveDir)) {
-          res.writeHead(403, { "Content-Type": "text/plain" });
-          res.end("Forbidden");
-          return;
+  siteCmd.command("serve").description(
+    "Start a local HTTP server for the built site directory.\n\nRun `scope site build` first, or use --watch to auto-rebuild on changes.\nCtrl+C to stop.\n\nExamples:\n  scope site serve\n  scope site serve --port 8080\n  scope site serve --dir ./my-site-output\n  scope site serve --watch"
+  ).option("-p, --port <number>", "Port to listen on", "3000").option("-d, --dir <path>", "Directory to serve", ".reactscope/site").option("-w, --watch", "Watch source files and rebuild on changes").option(
+    "-i, --input <path>",
+    "Input directory for .reactscope data (watch mode)",
+    ".reactscope"
+  ).option("--title <text>", "Site title (watch mode)", "Scope \u2014 Component Gallery").option("--base-path <path>", "Base URL path prefix (watch mode)", "/").action(
+    async (opts) => {
+      try {
+        let notifyReload2 = function() {
+          for (const client of sseClients) {
+            client.write("data: reload\n\n");
+          }
+        };
+        var notifyReload = notifyReload2;
+        const port = Number.parseInt(opts.port, 10);
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+          throw new Error(`Invalid port: ${opts.port}`);
         }
-        if (existsSync(filePath) && statSync(filePath).isFile()) {
-          const ext = extname(filePath).toLowerCase();
-          const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-          res.writeHead(200, { "Content-Type": contentType });
-          createReadStream(filePath).pipe(res);
-          return;
+        const serveDir = resolve(process.cwd(), opts.dir);
+        const watchMode = opts.watch === true;
+        const sseClients = /* @__PURE__ */ new Set();
+        if (watchMode) {
+          await mkdir(serveDir, { recursive: true });
         }
-        const htmlPath = `${filePath}.html`;
-        if (existsSync(htmlPath) && statSync(htmlPath).isFile()) {
-          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-          createReadStream(htmlPath).pipe(res);
-          return;
+        if (!watchMode && !existsSync(serveDir)) {
+          throw new Error(
+            `Serve directory not found: ${serveDir}
+Run \`scope site build\` first.`
+          );
         }
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end(`Not found: ${urlPath}`);
-      });
-      server.listen(port, () => {
-        process.stderr.write(`Scope site running at http://localhost:${port}
+        const server = createServer((req, res) => {
+          const rawUrl = req.url ?? "/";
+          const urlPath = decodeURIComponent(rawUrl.split("?")[0] ?? "/");
+          if (watchMode && urlPath === "/__livereload") {
+            res.writeHead(200, {
+              "Content-Type": "text/event-stream",
+              "Cache-Control": "no-cache",
+              Connection: "keep-alive",
+              "Access-Control-Allow-Origin": "*"
+            });
+            res.write("data: connected\n\n");
+            sseClients.add(res);
+            req.on("close", () => sseClients.delete(res));
+            return;
+          }
+          const filePath = join(
+            serveDir,
+            urlPath.endsWith("/") ? `${urlPath}index.html` : urlPath
+          );
+          if (!filePath.startsWith(serveDir)) {
+            res.writeHead(403, { "Content-Type": "text/plain" });
+            res.end("Forbidden");
+            return;
+          }
+          if (existsSync(filePath) && statSync(filePath).isFile()) {
+            const ext = extname(filePath).toLowerCase();
+            const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+            if (watchMode && ext === ".html") {
+              const html = injectLiveReloadScript(readFileSync(filePath, "utf-8"));
+              res.writeHead(200, { "Content-Type": contentType });
+              res.end(html);
+              return;
+            }
+            res.writeHead(200, { "Content-Type": contentType });
+            createReadStream(filePath).pipe(res);
+            return;
+          }
+          const htmlPath = `${filePath}.html`;
+          if (existsSync(htmlPath) && statSync(htmlPath).isFile()) {
+            if (watchMode) {
+              const html = injectLiveReloadScript(readFileSync(htmlPath, "utf-8"));
+              res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+              res.end(html);
+              return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            createReadStream(htmlPath).pipe(res);
+            return;
+          }
+          res.writeHead(404, { "Content-Type": "text/plain" });
+          res.end(`Not found: ${urlPath}`);
+        });
+        server.listen(port, () => {
+          process.stderr.write(`Scope site running at http://localhost:${port}
 `);
-        process.stderr.write(`Serving ${serveDir}
+          process.stderr.write(`Serving ${serveDir}
 `);
-        process.stderr.write("Press Ctrl+C to stop.\n");
-      });
-      server.on("error", (err) => {
-        if (err.code === "EADDRINUSE") {
-          process.stderr.write(`Error: Port ${port} is already in use.
+          if (watchMode) {
+            process.stderr.write(
+              "Watch mode enabled \u2014 source changes trigger rebuild + browser reload\n"
+            );
+          }
+          process.stderr.write("Press Ctrl+C to stop.\n");
+        });
+        server.on("error", (err) => {
+          if (err.code === "EADDRINUSE") {
+            process.stderr.write(`Error: Port ${port} is already in use.
 `);
-        } else {
-          process.stderr.write(`Server error: ${err.message}
+          } else {
+            process.stderr.write(`Server error: ${err.message}
 `);
+          }
+          process.exit(1);
+        });
+        if (watchMode) {
+          const rootDir = process.cwd();
+          const inputDir = resolve(rootDir, opts.input);
+          const initialManifest = await runFullBuild(
+            rootDir,
+            inputDir,
+            serveDir,
+            opts.title,
+            opts.basePath
+          );
+          notifyReload2();
+          startFileWatcher({
+            rootDir,
+            inputDir,
+            outputDir: serveDir,
+            title: opts.title,
+            basePath: opts.basePath,
+            previousManifest: initialManifest,
+            notifyReload: notifyReload2
+          });
         }
-        process.exit(1);
-      });
-    } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+      } catch (err) {
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
-      process.exit(1);
+        process.exit(1);
+      }
     }
-  });
+  );
 }
 function createSiteCommand() {
   const siteCmd = new Command("site").description(
-    "Build and serve the static component gallery site"
+    'Build and serve the static HTML component gallery site.\n\nPREREQUISITES:\n  scope manifest generate   (manifest.json)\n  scope render all          (renders/ + compliance-styles.json)\n\nSITE CONTENTS:\n  /index.html               component gallery with screenshots + metadata\n  /<component>/index.html   detail page: props, renders, matrix, X-Ray, compliance\n\nExamples:\n  scope site build && scope site serve\n  scope site build --title "Acme UI" --compliance .reactscope/compliance-report.json\n  scope site serve --port 8080'
   );
   registerBuild(siteCmd);
   registerServe(siteCmd);
@@ -5583,11 +6998,11 @@ function categoryForProperty(property) {
 }
 function buildCategorySummary(batch) {
   const cats = {
-    color: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
-    spacing: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
-    typography: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
-    border: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 },
-    shadow: { total: 0, onSystem: 0, offSystem: 0, compliance: 1 }
+    color: { total: 0, onSystem: 0, offSystem: 0, compliance: 0 },
+    spacing: { total: 0, onSystem: 0, offSystem: 0, compliance: 0 },
+    typography: { total: 0, onSystem: 0, offSystem: 0, compliance: 0 },
+    border: { total: 0, onSystem: 0, offSystem: 0, compliance: 0 },
+    shadow: { total: 0, onSystem: 0, offSystem: 0, compliance: 0 }
   };
   for (const report of Object.values(batch.components)) {
     for (const [property, result] of Object.entries(report.properties)) {
@@ -5603,7 +7018,7 @@ function buildCategorySummary(batch) {
     }
   }
   for (const summary of Object.values(cats)) {
-    summary.compliance = summary.total === 0 ? 1 : summary.onSystem / summary.total;
+    summary.compliance = summary.total === 0 ? 0 : summary.onSystem / summary.total;
   }
   return cats;
 }
@@ -5644,6 +7059,11 @@ function formatComplianceReport(batch, threshold) {
   const lines = [];
   const thresholdLabel = threshold !== void 0 ? pct >= threshold ? " \u2713 (pass)" : ` \u2717 (below threshold ${threshold}%)` : "";
   lines.push(`Overall compliance score: ${pct}%${thresholdLabel}`);
+  if (batch.totalProperties === 0) {
+    lines.push(
+      "No CSS properties were audited; run `scope render all` and inspect .reactscope/compliance-styles.json before treating compliance as green."
+    );
+  }
   lines.push("");
   const cats = buildCategorySummary(batch);
   const catEntries = Object.entries(cats).filter(([, s]) => s.total > 0);
@@ -5677,41 +7097,85 @@ function formatComplianceReport(batch, threshold) {
   return lines.join("\n");
 }
 function registerCompliance(tokensCmd) {
-  tokensCmd.command("compliance").description("Aggregate token compliance report across all components (Token Spec \xA73.3 format)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH})`).option("--threshold <n>", "Exit code 1 if compliance score is below this percentage (0-100)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
-    try {
-      const tokenFilePath = resolveTokenFilePath(opts.file);
-      const { tokens } = loadTokens(tokenFilePath);
-      const resolver = new TokenResolver(tokens);
-      const engine = new ComplianceEngine(resolver);
-      const stylesPath = opts.styles ?? DEFAULT_STYLES_PATH;
-      const stylesFile = loadStylesFile(stylesPath);
-      const componentMap = /* @__PURE__ */ new Map();
-      for (const [name, styles] of Object.entries(stylesFile)) {
-        componentMap.set(name, styles);
-      }
-      if (componentMap.size === 0) {
-        process.stderr.write(`Warning: No components found in styles file at ${stylesPath}
+  tokensCmd.command("compliance").description(
+    "Compute a token compliance score across all rendered components.\n\nCompares computed CSS values from .reactscope/compliance-styles.json\nagainst the token file \u2014 reports what % of style values are on-token.\n\nPREREQUISITES:\n  scope render all must have run first (produces compliance-styles.json)\n\nSCORING:\n  compliant     value exactly matches a token\n  near-match    value is within tolerance of a token (e.g. close color)\n  off-token     value not found in token file\n\nEXIT CODES:\n  0   compliance >= threshold (or no --threshold set)\n  1   compliance < threshold\n\nExamples:\n  scope tokens compliance\n  scope tokens compliance --threshold 90\n  scope tokens compliance --format json | jq '.summary'\n  scope tokens compliance --out .reactscope/compliance-report.json\n  scope tokens compliance --styles ./custom/compliance-styles.json"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH})`).option(
+    "--out <path>",
+    "Write JSON report to file (for use with scope site build --compliance)"
+  ).option("--threshold <n>", "Exit code 1 if compliance score is below this percentage (0-100)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action(
+    (opts) => {
+      try {
+        const tokenFilePath = resolveTokenFilePath(opts.file);
+        const { tokens } = loadTokens(tokenFilePath);
+        const resolver = new TokenResolver(tokens);
+        const engine = new ComplianceEngine(resolver);
+        const stylesPath = opts.styles ?? DEFAULT_STYLES_PATH;
+        const stylesFile = loadStylesFile(stylesPath);
+        const componentMap = /* @__PURE__ */ new Map();
+        for (const [name, styles] of Object.entries(stylesFile)) {
+          componentMap.set(name, styles);
+        }
+        if (componentMap.size === 0) {
+          process.stderr.write(`Warning: No components found in styles file at ${stylesPath}
 `);
-      }
-      const batch = engine.auditBatch(componentMap);
-      const useJson = opts.format === "json" || opts.format !== "text" && !isTTY();
-      const threshold = opts.threshold !== void 0 ? Number.parseInt(opts.threshold, 10) : void 0;
-      if (useJson) {
-        process.stdout.write(`${JSON.stringify(batch, null, 2)}
+        }
+        const batch = engine.auditBatch(componentMap);
+        const threshold = opts.threshold !== void 0 ? Number.parseInt(opts.threshold, 10) : void 0;
+        const failures = [];
+        if (batch.totalProperties === 0) {
+          failures.push({
+            component: "*",
+            stage: "compliance",
+            message: `No CSS properties were audited from ${stylesPath}; refusing to report silent success.`,
+            outputPath: stylesPath
+          });
+        } else if (threshold !== void 0 && Math.round(batch.aggregateCompliance * 100) < threshold) {
+          failures.push({
+            component: "*",
+            stage: "compliance",
+            message: `Compliance ${Math.round(batch.aggregateCompliance * 100)}% is below threshold ${threshold}%.`,
+            outputPath: opts.out ?? ".reactscope/compliance-report.json"
+          });
+        }
+        if (opts.out !== void 0) {
+          const outPath = resolve(process.cwd(), opts.out);
+          writeFileSync(outPath, JSON.stringify(batch, null, 2), "utf-8");
+          process.stderr.write(`Compliance report written to ${outPath}
 `);
-      } else {
-        process.stdout.write(`${formatComplianceReport(batch, threshold)}
+        }
+        const useJson = opts.format === "json" || opts.format !== "text" && !isTTY();
+        if (useJson) {
+          process.stdout.write(`${JSON.stringify(batch, null, 2)}
+`);
+        } else {
+          process.stdout.write(`${formatComplianceReport(batch, threshold)}
+`);
+        }
+        const summaryPath = writeRunSummary({
+          command: "scope tokens compliance",
+          status: failures.length > 0 ? "failed" : "success",
+          outputPaths: [opts.out ?? ".reactscope/compliance-report.json", stylesPath],
+          compliance: {
+            auditedProperties: batch.totalProperties,
+            onSystemProperties: batch.totalOnSystem,
+            offSystemProperties: batch.totalOffSystem,
+            score: Math.round(batch.aggregateCompliance * 100),
+            threshold
+          },
+          failures
+        });
+        process.stderr.write(`[scope/tokens] Run summary written to ${summaryPath}
+`);
+        if (failures.length > 0) {
+          process.exit(1);
+        }
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
-      }
-      if (threshold !== void 0 && Math.round(batch.aggregateCompliance * 100) < threshold) {
         process.exit(1);
       }
-    } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
-`);
-      process.exit(1);
     }
-  });
+  );
 }
 var DEFAULT_TOKEN_FILE = "reactscope.tokens.json";
 var CONFIG_FILE = "reactscope.config.json";
@@ -5735,7 +7199,9 @@ function resolveTokenFilePath2(fileFlag) {
   return resolve(process.cwd(), DEFAULT_TOKEN_FILE);
 }
 function createTokensExportCommand() {
-  return new Command("export").description("Export design tokens to a downstream format").requiredOption("--format <fmt>", `Output format: ${SUPPORTED_FORMATS.join(", ")}`).option("--file <path>", "Path to token file (overrides config)").option("--out <path>", "Write output to file instead of stdout").option("--prefix <prefix>", "CSS/SCSS: prefix for variable names (e.g. 'scope')").option("--selector <selector>", "CSS: custom root selector (default: ':root')").option(
+  return new Command("export").description(
+    'Export design tokens to CSS variables, TypeScript, SCSS, Tailwind config, Figma, or flat JSON.\n\nFORMATS:\n  css          CSS custom properties (:root { --color-primary-500: #3b82f6; })\n  scss         SCSS variables ($color-primary-500: #3b82f6;)\n  ts           TypeScript const export (export const tokens = {...})\n  tailwind     Tailwind theme.extend block (paste into tailwind.config.js)\n  flat-json    Flat { path: value } map (useful for tooling integration)\n  figma        Figma Tokens plugin format\n\nExamples:\n  scope tokens export --format css --out src/tokens.css\n  scope tokens export --format css --prefix brand --selector ":root, [data-theme]"\n  scope tokens export --format tailwind --out tailwind-tokens.js\n  scope tokens export --format ts --out src/tokens.ts\n  scope tokens export --format css --theme dark --out dark-tokens.css'
+  ).requiredOption("--format <fmt>", `Output format: ${SUPPORTED_FORMATS.join(", ")}`).option("--file <path>", "Path to token file (overrides config)").option("--out <path>", "Write output to file instead of stdout").option("--prefix <prefix>", "CSS/SCSS: prefix for variable names (e.g. 'scope')").option("--selector <selector>", "CSS: custom root selector (default: ':root')").option(
     "--theme <name>",
     "Include theme overrides for the named theme (applies to css, ts, scss, tailwind, figma)"
   ).action(
@@ -5875,7 +7341,9 @@ function formatImpactSummary(report) {
   return `\u2192 ${parts.join(", ")}`;
 }
 function registerImpact(tokensCmd) {
-  tokensCmd.command("impact <path>").description("List all components and elements that consume a given token (Token Spec \xA74.3)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH2})`).option("--new-value <value>", "Proposed new value \u2014 report visual severity of the change").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action(
+  tokensCmd.command("impact <path>").description(
+    "List every component and CSS element that uses a given token.\nUse this to understand the blast radius before changing a token value.\n\nPREREQUISITE: scope render all (populates compliance-styles.json)\n\nExamples:\n  scope tokens impact color.primary.500\n  scope tokens impact spacing.4 --format json\n  scope tokens impact font.size.base | grep Button"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH2})`).option("--new-value <value>", "Proposed new value \u2014 report visual severity of the change").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action(
     (tokenPath, opts) => {
       try {
         const tokenFilePath = resolveTokenFilePath(opts.file);
@@ -5912,18 +7380,242 @@ ${formatImpactSummary(report)}
     }
   );
 }
+var DEFAULT_TOKEN_FILE2 = "reactscope.tokens.json";
+var CONFIG_FILE2 = "reactscope.config.json";
+function resolveOutputPath(fileFlag) {
+  if (fileFlag !== void 0) {
+    return resolve(process.cwd(), fileFlag);
+  }
+  const configPath = resolve(process.cwd(), CONFIG_FILE2);
+  if (existsSync(configPath)) {
+    try {
+      const raw = readFileSync(configPath, "utf-8");
+      const config = JSON.parse(raw);
+      if (typeof config === "object" && config !== null && "tokens" in config && typeof config.tokens === "object" && config.tokens !== null && typeof config.tokens?.file === "string") {
+        const file = config.tokens.file;
+        return resolve(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return resolve(process.cwd(), DEFAULT_TOKEN_FILE2);
+}
+var CSS_VAR_RE = /--([\w-]+)\s*:\s*([^;]+)/g;
+var HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+var COLOR_FN_RE = /^(?:rgba?|hsla?|oklch|oklab|lch|lab|color|hwb)\(/;
+var DIMENSION_RE = /^-?\d+(?:\.\d+)?(?:px|rem|em|%|vw|vh|ch|ex|cap|lh|dvh|svh|lvh)$/;
+var DURATION_RE = /^-?\d+(?:\.\d+)?(?:ms|s)$/;
+var FONT_FAMILY_RE = /^["']|,\s*(?:sans-serif|serif|monospace|cursive|fantasy|system-ui)/;
+var NUMBER_RE = /^-?\d+(?:\.\d+)?$/;
+var CUBIC_BEZIER_RE = /^cubic-bezier\(/;
+var SHADOW_RE = /^\d.*(?:px|rem|em)\s+(?:#|rgba?|hsla?|oklch|oklab)/i;
+function inferTokenType(value) {
+  const v = value.trim();
+  if (HEX_COLOR_RE.test(v) || COLOR_FN_RE.test(v)) return "color";
+  if (DURATION_RE.test(v)) return "duration";
+  if (DIMENSION_RE.test(v)) return "dimension";
+  if (FONT_FAMILY_RE.test(v)) return "fontFamily";
+  if (CUBIC_BEZIER_RE.test(v)) return "cubicBezier";
+  if (SHADOW_RE.test(v)) return "shadow";
+  if (NUMBER_RE.test(v)) return "number";
+  return "color";
+}
+function setNestedToken(root, segments, value, type) {
+  let node = root;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i];
+    if (seg === void 0) continue;
+    if (!(seg in node) || typeof node[seg] !== "object" || node[seg] === null) {
+      node[seg] = {};
+    }
+    node = node[seg];
+  }
+  const leaf = segments[segments.length - 1];
+  if (leaf === void 0) return;
+  node[leaf] = { value, type };
+}
+function extractBlockBody(css, openBrace) {
+  let depth = 0;
+  let end = -1;
+  for (let i = openBrace; i < css.length; i++) {
+    if (css[i] === "{") depth++;
+    else if (css[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end === -1) return "";
+  return css.slice(openBrace + 1, end);
+}
+function parseScopedBlocks(css) {
+  const blocks = [];
+  const blockRe = /(?::root|@theme(?:\s+inline)?|\.dark\.high-contrast|\.dark)\s*\{/g;
+  let match = blockRe.exec(css);
+  while (match !== null) {
+    const selector = match[0];
+    const braceIdx = css.indexOf("{", match.index);
+    if (braceIdx === -1) {
+      match = blockRe.exec(css);
+      continue;
+    }
+    const body = extractBlockBody(css, braceIdx);
+    let scope;
+    if (selector.includes(".dark.high-contrast")) scope = "dark-high-contrast";
+    else if (selector.includes(".dark")) scope = "dark";
+    else if (selector.includes("@theme")) scope = "theme";
+    else scope = "root";
+    blocks.push({ scope, body });
+    match = blockRe.exec(css);
+  }
+  return blocks;
+}
+function extractVarsFromBody(body) {
+  const results = [];
+  for (const m of body.matchAll(CSS_VAR_RE)) {
+    const name = m[1];
+    const value = m[2]?.trim();
+    if (name === void 0 || value === void 0 || value.length === 0) continue;
+    if (value.startsWith("var(") || value.startsWith("calc(")) continue;
+    results.push({ name, value });
+  }
+  return results;
+}
+function extractCSSCustomProperties(tokenSources) {
+  const cssSources = tokenSources.filter(
+    (s) => s.kind === "css-custom-properties" || s.kind === "tailwind-v4-theme"
+  );
+  if (cssSources.length === 0) return null;
+  const tokens = {};
+  const themes = {};
+  let found = false;
+  for (const source of cssSources) {
+    try {
+      if (source.path.includes("compiled") || source.path.includes(".min.")) continue;
+      const raw = readFileSync(source.path, "utf-8");
+      const blocks = parseScopedBlocks(raw);
+      for (const block of blocks) {
+        const vars = extractVarsFromBody(block.body);
+        for (const { name, value } of vars) {
+          const segments = name.split("-").filter(Boolean);
+          if (segments.length === 0) continue;
+          if (block.scope === "root" || block.scope === "theme") {
+            const type = inferTokenType(value);
+            setNestedToken(tokens, segments, value, type);
+            found = true;
+          } else {
+            const themeName = block.scope;
+            if (!themes[themeName]) themes[themeName] = {};
+            const path = segments.join(".");
+            themes[themeName][path] = value;
+            found = true;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return found ? { tokens, themes } : null;
+}
+function registerTokensInit(tokensCmd) {
+  tokensCmd.command("init").description(
+    "Detect design-token sources in the project and generate a token file.\n\nDETECTED SOURCES:\n  - Tailwind config (colors, spacing, fontFamily, borderRadius)\n  - CSS custom properties (:root { --color-primary: #0070f3; })\n\nWill not overwrite an existing token file unless --force is passed.\n\nOUTPUT PATH RESOLUTION (in priority order):\n  1. --file <path>                  explicit override\n  2. tokens.file in reactscope.config.json\n  3. reactscope.tokens.json         default (project root)\n\nExamples:\n  scope tokens init\n  scope tokens init --force\n  scope tokens init --file tokens/brand.json\n  scope tokens init --force --file custom-tokens.json"
+  ).option("--file <path>", "Output path for the token file (overrides config)").option("--force", "Overwrite existing token file", false).action((opts) => {
+    try {
+      const outPath = resolveOutputPath(opts.file);
+      if (existsSync(outPath) && !opts.force) {
+        process.stderr.write(
+          `Token file already exists at ${outPath}.
+Run with --force to overwrite.
+`
+        );
+        process.exit(1);
+      }
+      const rootDir = process.cwd();
+      const detected = detectProject(rootDir);
+      const tailwindTokens = extractTailwindTokens(detected.tokenSources);
+      const cssResult = extractCSSCustomProperties(detected.tokenSources);
+      const mergedTokens = {};
+      const mergedThemes = {};
+      if (tailwindTokens !== null) {
+        Object.assign(mergedTokens, tailwindTokens);
+      }
+      if (cssResult !== null) {
+        for (const [key, value] of Object.entries(cssResult.tokens)) {
+          if (!(key in mergedTokens)) {
+            mergedTokens[key] = value;
+          }
+        }
+        for (const [themeName, overrides] of Object.entries(cssResult.themes)) {
+          if (!mergedThemes[themeName]) mergedThemes[themeName] = {};
+          Object.assign(mergedThemes[themeName], overrides);
+        }
+      }
+      const tokenFile = {
+        $schema: "https://raw.githubusercontent.com/FlatFilers/Scope/main/packages/tokens/schema.json",
+        version: "1.0.0",
+        meta: {
+          name: "Design Tokens",
+          lastUpdated: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+        },
+        tokens: mergedTokens
+      };
+      if (Object.keys(mergedThemes).length > 0) {
+        tokenFile.themes = mergedThemes;
+      }
+      writeFileSync(outPath, `${JSON.stringify(tokenFile, null, 2)}
+`);
+      const tokenGroupCount = Object.keys(mergedTokens).length;
+      const themeNames = Object.keys(mergedThemes);
+      if (detected.tokenSources.length > 0) {
+        process.stdout.write("Detected token sources:\n");
+        for (const source of detected.tokenSources) {
+          process.stdout.write(`  ${source.kind}: ${source.path}
+`);
+        }
+        process.stdout.write("\n");
+      }
+      if (tokenGroupCount > 0) {
+        process.stdout.write(`Extracted ${tokenGroupCount} token group(s) \u2192 ${outPath}
+`);
+        if (themeNames.length > 0) {
+          for (const name of themeNames) {
+            const count = Object.keys(mergedThemes[name] ?? {}).length;
+            process.stdout.write(`  theme "${name}": ${count} override(s)
+`);
+          }
+        }
+      } else {
+        process.stdout.write(
+          `No token sources detected. Created empty token file \u2192 ${outPath}
+Add tokens manually or re-run after configuring a design system.
+`
+        );
+      }
+    } catch (err) {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
 var DEFAULT_STYLES_PATH3 = ".reactscope/compliance-styles.json";
 var DEFAULT_MANIFEST_PATH = ".reactscope/manifest.json";
 var DEFAULT_OUTPUT_DIR2 = ".reactscope/previews";
 async function renderComponentWithCssOverride(filePath, componentName, cssOverride, vpWidth, vpHeight, timeoutMs) {
+  const PAD = 16;
   const htmlHarness = await buildComponentHarness(
     filePath,
     componentName,
     {},
     // no props
     vpWidth,
-    cssOverride
+    cssOverride,
     // injected as <style>
+    void 0,
+    PAD
   );
   const pool = new BrowserPool({
     size: { browsers: 1, pagesPerBrowser: 1 },
@@ -5944,7 +7636,6 @@ async function renderComponentWithCssOverride(filePath, componentName, cssOverri
     );
     const rootLocator = page.locator("[data-reactscope-root]");
     const bb = await rootLocator.boundingBox();
-    const PAD = 16;
     const MIN_W = 320;
     const MIN_H = 120;
     const clipX = Math.max(0, (bb?.x ?? 0) - PAD);
@@ -5964,7 +7655,9 @@ async function renderComponentWithCssOverride(filePath, componentName, cssOverri
   }
 }
 function registerPreview(tokensCmd) {
-  tokensCmd.command("preview <path>").description("Render before/after sprite sheet for components affected by a token change").requiredOption("--new-value <value>", "The proposed new resolved value for the token").option("--sprite", "Output a PNG sprite sheet (default when TTY)", false).option("-o, --output <path>", "Output PNG path (default: .reactscope/previews/<token>.png)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH3})`).option("--manifest <path>", "Path to manifest.json", DEFAULT_MANIFEST_PATH).option("--format <fmt>", "Output format: json or text (default: auto-detect)").option("--timeout <ms>", "Browser timeout per render (ms)", "10000").option("--viewport-width <px>", "Viewport width in pixels", "1280").option("--viewport-height <px>", "Viewport height in pixels", "720").action(
+  tokensCmd.command("preview <path>").description(
+    'Render before/after screenshots of all components affected by a token change.\nUseful for visual review before committing a token value update.\n\nPREREQUISITE: scope render all (provides baseline renders)\n\nExamples:\n  scope tokens preview color.primary.500\n  scope tokens preview color.primary.500 --new-value "#2563eb" -o preview.png'
+  ).requiredOption("--new-value <value>", "The proposed new resolved value for the token").option("--sprite", "Output a PNG sprite sheet (default when TTY)", false).option("-o, --output <path>", "Output PNG path (default: .reactscope/previews/<token>.png)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH3})`).option("--manifest <path>", "Path to manifest.json", DEFAULT_MANIFEST_PATH).option("--format <fmt>", "Output format: json or text (default: auto-detect)").option("--timeout <ms>", "Browser timeout per render (ms)", "10000").option("--viewport-width <px>", "Viewport width in pixels", "1280").option("--viewport-height <px>", "Viewport height in pixels", "720").action(
     async (tokenPath, opts) => {
       try {
         const tokenFilePath = resolveTokenFilePath(opts.file);
@@ -6131,8 +7824,8 @@ function registerPreview(tokensCmd) {
 }
 // src/tokens/commands.ts
-var DEFAULT_TOKEN_FILE2 = "reactscope.tokens.json";
-var CONFIG_FILE2 = "reactscope.config.json";
+var DEFAULT_TOKEN_FILE3 = "reactscope.tokens.json";
+var CONFIG_FILE3 = "reactscope.config.json";
 function isTTY2() {
   return process.stdout.isTTY === true;
 }
@@ -6154,7 +7847,7 @@ function resolveTokenFilePath(fileFlag) {
   if (fileFlag !== void 0) {
     return resolve(process.cwd(), fileFlag);
   }
-  const configPath = resolve(process.cwd(), CONFIG_FILE2);
+  const configPath = resolve(process.cwd(), CONFIG_FILE3);
   if (existsSync(configPath)) {
     try {
       const raw = readFileSync(configPath, "utf-8");
@@ -6166,7 +7859,7 @@ function resolveTokenFilePath(fileFlag) {
     } catch {
     }
   }
-  return resolve(process.cwd(), DEFAULT_TOKEN_FILE2);
+  return resolve(process.cwd(), DEFAULT_TOKEN_FILE3);
 }
 function loadTokens(absPath) {
   if (!existsSync(absPath)) {
@@ -6211,7 +7904,9 @@ function buildResolutionChain(startPath, rawTokens) {
   return chain;
 }
 function registerGet2(tokensCmd) {
-  tokensCmd.command("get <path>").description("Resolve a token path to its computed value").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+  tokensCmd.command("get <path>").description(
+    "Resolve a token path and print its final computed value.\nFollows all {ref} chains to the raw value.\n\nExamples:\n  scope tokens get color.primary.500\n  scope tokens get spacing.4 --format json\n  scope tokens get font.size.base --file ./tokens/brand.json"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
       const { tokens } = loadTokens(filePath);
@@ -6236,7 +7931,18 @@ function registerGet2(tokensCmd) {
   });
 }
 function registerList2(tokensCmd) {
-  tokensCmd.command("list [category]").description("List tokens, optionally filtered by category or type").option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+  tokensCmd.command("list [category]").description(
+    `List all tokens, optionally filtered by category prefix or type.
+CATEGORY: top-level token namespace (e.g. "color", "spacing", "typography")
+TYPE: token value type \u2014 color | spacing | typography | shadow | radius | opacity
+Examples:
+  scope tokens list
+  scope tokens list color
+  scope tokens list --type spacing
+  scope tokens list color --format json | jq '.[].path'`
+  ).option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
     (category, opts) => {
       try {
         const filePath = resolveTokenFilePath(opts.file);
@@ -6266,7 +7972,9 @@ function registerList2(tokensCmd) {
   );
 }
 function registerSearch(tokensCmd) {
-  tokensCmd.command("search <value>").description("Find which token(s) match a computed value (supports fuzzy color matching)").option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+  tokensCmd.command("search <value>").description(
+    'Find the token(s) whose computed value matches the given raw value.\nSupports fuzzy color matching (hex \u2194 rgb \u2194 hsl equivalence).\n\nExamples:\n  scope tokens search "#3b82f6"\n  scope tokens search "16px"\n  scope tokens search "rgb(59, 130, 246)"   # fuzzy-matches #3b82f6'
+  ).option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
     (value, opts) => {
       try {
         const filePath = resolveTokenFilePath(opts.file);
@@ -6349,7 +8057,9 @@ Tip: use --fuzzy for nearest-match search.
   );
 }
 function registerResolve(tokensCmd) {
-  tokensCmd.command("resolve <path>").description("Show the full resolution chain for a token").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+  tokensCmd.command("resolve <path>").description(
+    "Print the full reference chain from a token path down to its raw value.\nUseful for debugging circular references or understanding token inheritance.\n\nExamples:\n  scope tokens resolve color.primary.500\n  scope tokens resolve button.background --format json"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
       const absFilePath = filePath;
@@ -6385,7 +8095,19 @@ function registerResolve(tokensCmd) {
 }
 function registerValidate(tokensCmd) {
   tokensCmd.command("validate").description(
-    "Validate the token file for errors (circular refs, missing refs, type mismatches)"
+    `Validate the token file and report errors.
+CHECKS:
+  - Circular reference chains (A \u2192 B \u2192 A)
+  - Broken references ({path.that.does.not.exist})
+  - Type mismatches (token declared as "color" but value is a number)
+  - Duplicate paths
+Exits 1 if any errors are found (suitable for CI).
+Examples:
+  scope tokens validate
+  scope tokens validate --format json | jq '.errors'`
   ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
@@ -6464,8 +8186,9 @@ function outputValidationResult(filePath, errors, useJson) {
 }
 function createTokensCommand() {
   const tokensCmd = new Command("tokens").description(
-    "Query and validate design tokens from a reactscope.tokens.json file"
+    'Query, validate, and export design tokens from reactscope.tokens.json.\n\nTOKEN FILE RESOLUTION (in priority order):\n  1. --file <path>                  explicit override\n  2. tokens.file in reactscope.config.json\n  3. reactscope.tokens.json         default (project root)\n\nTOKEN FILE FORMAT (reactscope.tokens.json):\n  Nested JSON. Each leaf is a token with { value, type } or just a raw value.\n  Paths use dot notation: color.primary.500, spacing.4, font.size.base\n  References use {path.to.other.token} syntax.\n  Themes: top-level "themes" key with named override maps.\n\nTOKEN TYPES: color | spacing | typography | shadow | radius | opacity | other\n\nExamples:\n  scope tokens validate\n  scope tokens list color\n  scope tokens get color.primary.500\n  scope tokens compliance\n  scope tokens export --format css --out tokens.css'
   );
+  registerTokensInit(tokensCmd);
   registerGet2(tokensCmd);
   registerList2(tokensCmd);
   registerSearch(tokensCmd);
@@ -6480,8 +8203,12 @@ function createTokensCommand() {
 // src/program.ts
 function createProgram(options = {}) {
-  const program = new Command("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
-  program.command("capture <url>").description("Capture a React component tree from a live URL and output as JSON").option("-o, --output <path>", "Write JSON to file instead of stdout").option("--pretty", "Pretty-print JSON output (default: minified)", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
+  const program = new Command("scope").version(options.version ?? "0.1.0").description(
+    'Scope \u2014 static analysis + visual rendering toolkit for React component libraries.\n\nScope answers questions about React codebases \u2014 structure, props, visual output,\ndesign token compliance \u2014 without running the full application.\n\nAGENT QUICKSTART:\n  scope get-skill > /tmp/scope-skill.md\n  scope init --yes\n  scope doctor --json\n  scope manifest list --format json\n  scope render all --format json --output-dir .reactscope/renders\n  scope site build --output .reactscope/site\n  scope instrument profile http://localhost:5173\n\nCI QUICKSTART:\n  scope ci --json --output .reactscope/ci-result.json\n\nCONFIG FILE: reactscope.config.json (created by `scope init`)\n  components.include      glob patterns for component files (e.g. "src/**/*.tsx")\n  components.wrappers     providers and globalCSS to wrap every render\n  render.viewport         default viewport width\xD7height in px\n  tokens.file             path to reactscope.tokens.json (default)\n  output.dir              output root (default: .reactscope/)\n  ci.complianceThreshold  fail threshold for `scope ci` (default: 0.90)\n\nOUTPUT DIRECTORY: .reactscope/\n  manifest.json           component registry \u2014 updated by `scope manifest generate`\n  renders/<Name>/         PNGs + render.json per component\n  compliance-styles.json  computed-style map for token matching\n  site/                   static HTML gallery (built by `scope site build`)\n\nRun `scope <command> --help` for detailed flags and examples.'
+  );
+  program.command("capture <url>").description(
+    "Capture the live React component tree from a running app and emit it as JSON.\nRequires a running dev server at the given URL (e.g. http://localhost:5173).\n\nExamples:\n  scope capture http://localhost:5173\n  scope capture http://localhost:5173 -o report.json --pretty\n  scope capture http://localhost:5173 --timeout 15000 --wait 500"
+  ).option("-o, --output <path>", "Write JSON to file instead of stdout").option("--pretty", "Pretty-print JSON output (default: minified)", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
         const { report } = await browserCapture({
@@ -6505,7 +8232,9 @@ function createProgram(options = {}) {
       }
     }
   );
-  program.command("tree <url>").description("Display the React component tree from a live URL").option("--depth <n>", "Max depth to display (default: unlimited)").option("--show-props", "Include prop names next to components", false).option("--show-hooks", "Show hook counts per component", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
+  program.command("tree <url>").description(
+    "Print a formatted React component tree from a running app.\nUseful for quickly understanding component hierarchy without full capture.\n\nExamples:\n  scope tree http://localhost:5173\n  scope tree http://localhost:5173 --show-props --show-hooks\n  scope tree http://localhost:5173 --depth 4"
+  ).option("--depth <n>", "Max depth to display (default: unlimited)").option("--show-props", "Include prop names next to components", false).option("--show-hooks", "Show hook counts per component", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
         const { report } = await browserCapture({
@@ -6528,7 +8257,9 @@ function createProgram(options = {}) {
       }
     }
   );
-  program.command("report <url>").description("Capture and display a human-readable summary of a React app").option("--json", "Output as structured JSON instead of human-readable text", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
+  program.command("report <url>").description(
+    "Capture a React app and print a human-readable analysis summary.\nIncludes component count, hook usage, side-effect summary, and more.\n\nExamples:\n  scope report http://localhost:5173\n  scope report http://localhost:5173 --json\n  scope report http://localhost:5173 --json -o report.json"
+  ).option("--json", "Output as structured JSON instead of human-readable text", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
         const { report } = await browserCapture({
@@ -6552,7 +8283,9 @@ function createProgram(options = {}) {
       }
     }
   );
-  program.command("generate").description("Generate a Playwright test from a Scope trace file").argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
+  program.command("generate").description(
+    'Generate a Playwright test file from a Scope trace (.json).\nTraces are produced by scope instrument renders or scope capture.\n\nExamples:\n  scope generate trace.json\n  scope generate trace.json -o tests/scope.spec.ts -d "User login flow"'
+  ).argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
     const raw = readFileSync(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
@@ -6569,6 +8302,7 @@ function createProgram(options = {}) {
   program.addCommand(createInitCommand());
   program.addCommand(createCiCommand());
   program.addCommand(createDoctorCommand());
+  program.addCommand(createGetSkillCommand());
   const existingReportCmd = program.commands.find((c) => c.name() === "report");
   if (existingReportCmd !== void 0) {
     registerBaselineSubCommand(existingReportCmd);
@@ -6579,6 +8313,6 @@ function createProgram(options = {}) {
   return program;
 }
-export { CI_EXIT, createCiCommand, createDoctorCommand, createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, formatCiReport, isTTY, matchGlob, resolveTokenFilePath2 as resolveTokenFilePath, runCi, runInit };
+export { CI_EXIT, createCiCommand, createDoctorCommand, createGetSkillCommand, createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, formatCiReport, isTTY, matchGlob, resolveTokenFilePath2 as resolveTokenFilePath, runCi, runInit };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map