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

@agent-scope/cli 1.20.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.cjs CHANGED Viewed

@@ -8,6 +8,7 @@ var tokens = require('@agent-scope/tokens');
 var commander = require('commander');
 var esbuild2 = require('esbuild');
 var module$1 = require('module');
+var promises = require('fs/promises');
 var readline = require('readline');
 var playwright = require('@agent-scope/playwright');
 var playwright$1 = require('playwright');
@@ -37,10 +38,15 @@ function _interopNamespace(e) {
 var esbuild2__namespace = /*#__PURE__*/_interopNamespace(esbuild2);
 var readline__namespace = /*#__PURE__*/_interopNamespace(readline);
-// 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>");
@@ -146,7 +152,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>` : "";
@@ -156,10 +162,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>
@@ -541,22 +554,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;
@@ -639,8 +652,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 {
@@ -680,7 +702,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);
@@ -1025,6 +1046,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 && fs.existsSync(executablePath);
+  const browserPathExists = effectiveBrowserPath === null ? null : fs.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(fs.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 = fs.existsSync(browserPath) ? browserPath : path.dirname(browserPath);
+  try {
+    await promises.access(candidate, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function detectPackageManager(cwd = process.cwd()) {
+  if (fs.existsSync(path.join(cwd, "bun.lock")) || fs.existsSync(path.join(cwd, "bun.lockb"))) return "bun";
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function hasLikelyInstalledDependencies(cwd = process.cwd()) {
+  return fs.existsSync(path.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 (!fs.existsSync(dir)) return [];
   const results = [];
@@ -1038,13 +1177,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) => fs.existsSync(path.resolve(cwd, file)))) {
+    return true;
+  }
+  const packageJsonPath = path.resolve(cwd, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.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 = path.resolve(cwd, "reactscope.config.json");
   if (!fs.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 {
@@ -1092,6 +1261,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",
@@ -1118,7 +1294,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 = fs.statSync(manifestPath).mtimeMs;
@@ -1135,6 +1311,54 @@ 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}`;
 }
@@ -1147,6 +1371,8 @@ CHECKS PERFORMED:
   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
@@ -1156,20 +1382,34 @@ 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).action((opts) => {
+  ).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);
@@ -1196,12 +1436,12 @@ Examples:
 }
 // 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**3-command workflow:**\n```\nscope init                               # scaffold config + auto-generate manifest\nscope manifest query --context ThemeContext  # ask questions about the codebase\nscope render Button                      # produce a PNG of a component\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`)\nScope files let you define **named rendering scenarios** for a component alongside it in the source tree. They are the primary way to ensure `render all` produces meaningful screenshots.\n\n```tsx\n// Button.scope.tsx\nimport type { ScopeFile } from \'@agent-scope/cli\';\nimport { Button } from \'./Button\';\n\nexport default {\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 ScopeFile<typeof Button>;\n```\n\nKey rules:\n- The file must be named `<ComponentName>.scope.tsx` in the same directory\n- Export a default object where keys are scenario names and values are props\n- `render all` uses the `default` scenario (or first defined) as the primary screenshot\n- If 2+ scenarios exist, `render all` automatically runs a matrix and merges cells into the component JSON\n- Scenarios also feed the interactive Playground in the docs site\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\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\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 X`\n\n**"I want to render all variants of a component"**\n\u2192 Define all variants in `.scope.tsx`, then `scope render all` (auto-matrix)\n\u2192 Or: `scope render matrix X --axes \'variant:primary,secondary,danger\'`\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 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\n```bash\nnpm install -g @agent-scope/cli          # global\nnpm install --save-dev @agent-scope/cli  # per-project\n```\n\nBinary: `scope`\n\n---\n\n## Core Workflow\n\n```\ninit \u2192 manifest generate \u2192 manifest query/get/list \u2192 render \u2192 (token audit) \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, and manifest staleness.\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\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\n```\n$ scope doctor\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 Button\nscope render Button --props \'{"variant":"primary","children":"Click me"}\'\nscope render Button --viewport 375x812\nscope render Button --output button.png\nscope render 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 http://localhost:3000\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 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 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| `"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';
+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 commander.Command("get-skill").description(
-    'Print the embedded Scope SKILL.md to stdout.\n\nAgents: pipe this command into your context loader to bootstrap Scope knowledge.\nThe skill covers: when to use each command, config requirements, output format,\nrender engine selection, and common failure modes.\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'
+    '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)}
@@ -1234,7 +1474,7 @@ function detectFramework(rootDir, packageDeps) {
   if ("react-scripts" in packageDeps) return "cra";
   return "unknown";
 }
-function detectPackageManager(rootDir) {
+function detectPackageManager2(rootDir) {
   if (fs.existsSync(path.join(rootDir, "bun.lock"))) return "bun";
   if (fs.existsSync(path.join(rootDir, "yarn.lock"))) return "yarn";
   if (fs.existsSync(path.join(rootDir, "pnpm-lock.yaml"))) return "pnpm";
@@ -1310,6 +1550,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 = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".next") {
+        continue;
+      }
+      const full = path.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) {
@@ -1325,32 +1590,53 @@ function detectTokenSources(rootDir) {
     }
   }
   const srcDir = path.join(rootDir, "src");
-  const dirsToScan = fs.existsSync(srcDir) ? [srcDir] : [];
-  for (const scanDir of dirsToScan) {
-    try {
-      const entries = fs.readdirSync(scanDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isFile() && CSS_EXTS.some((x) => entry.name.endsWith(x))) {
-          const filePath = path.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 (fs.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 = path.join(rootDir, tokenDir);
+    if (!fs.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 (fs.existsSync(srcDir)) {
-    try {
-      const entries = fs.readdirSync(srcDir);
-      for (const entry of entries) {
-        if (THEME_SUFFIXES.some((s) => entry.endsWith(s))) {
-          sources.push({ kind: "theme-file", path: path.join(srcDir, entry) });
+    const scanThemeFiles = (dir, depth) => {
+      if (depth > MAX_SCAN_DEPTH) return;
+      try {
+        const entries = fs.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: path.join(dir, entry.name) });
+          } else if (entry.isDirectory()) {
+            scanThemeFiles(path.join(dir, entry.name), depth + 1);
+          }
         }
+      } catch {
       }
-    } catch {
-    }
+    };
+    scanThemeFiles(srcDir, 0);
   }
   return sources;
 }
@@ -1370,7 +1656,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);
@@ -1421,9 +1707,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());
     });
   });
 }
@@ -1885,21 +2171,64 @@ function registerQuery(manifestCmd) {
     }
   );
 }
+function loadReactScopeConfig(rootDir) {
+  const configPath = path.resolve(rootDir, "reactscope.config.json");
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const raw = fs.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(
-    '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\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'
+    '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 = path.resolve(process.cwd(), opts.root ?? ".");
       const outputPath = path.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$1 = await manifest.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$1.components).length;
       process.stderr.write(`Found ${componentCount} components.
@@ -2288,7 +2617,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);
       }
@@ -2391,13 +2720,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 }
@@ -2445,7 +2772,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) {
@@ -2516,13 +2843,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,
@@ -2597,7 +2929,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);
       }
@@ -2942,7 +3274,7 @@ Available: ${available}`
 `);
       }
     } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+      process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
       process.exit(1);
     }
@@ -3434,7 +3766,7 @@ Examples:
         }
       } catch (err) {
         await shutdownPool2();
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
         process.exit(1);
       }
@@ -3512,6 +3844,54 @@ function writeReportToFile(report, outputPath, pretty) {
   const json = pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
   fs.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 = path.resolve(process.cwd(), summaryPath);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const payload = {
+    ...summary,
+    generatedAt: summary.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    nextActions: summary.nextActions ?? buildNextActions(summary)
+  };
+  fs.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 = path.dirname(componentFilePath);
@@ -3639,6 +4019,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) => fs.existsSync(path.resolve(cwd, file)))) {
+    return true;
+  }
+  const packageJsonPath = path.resolve(cwd, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.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 = path.resolve(cwd, "reactscope.config.json");
+  if (!fs.existsSync(configPath)) return [];
+  try {
+    const raw = fs.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;
@@ -3659,7 +4096,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 render.SatoriRenderer({
     defaultViewport: { width: viewportWidth, height: viewportHeight }
   });
@@ -3669,13 +4106,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;
@@ -3716,17 +4155,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",
@@ -3849,7 +4299,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),
@@ -3858,6 +4308,10 @@ function buildRenderer(filePath, componentName, viewportWidth, viewportHeight, g
           dom,
           accessibility
         };
+        if (iconMode && svgContent) {
+          renderResult.svgContent = svgContent;
+        }
+        return renderResult;
       } finally {
         pool.release(slot);
       }
@@ -3957,7 +4411,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"
           );
@@ -3976,7 +4430,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;
@@ -3999,7 +4454,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;
@@ -4007,6 +4469,7 @@ Available: ${available}`
           if (opts.output !== void 0 && !isNamed) {
             const outPath = path.resolve(process.cwd(), opts.output);
             fs.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)
 `
@@ -4021,17 +4484,36 @@ Available: ${available}`
             const outPath = path.resolve(dir, outFileName);
             fs.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);
       }
@@ -4192,7 +4674,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);
       }
@@ -4210,7 +4692,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 = path.resolve(process.cwd(), opts.outputDir);
@@ -4219,13 +4715,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 = path.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];
@@ -4238,7 +4738,8 @@ function registerRenderAll(renderCmd) {
             812,
             allCssFiles,
             process.cwd(),
-            wrapperScript
+            wrapperScript,
+            isIcon
           );
           const outcome = await render.safeRender(
             () => renderer.renderCell(renderProps, descriptor.complexityClass),
@@ -4275,14 +4776,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 = path.resolve(outputDir, `${name}.png`);
-          fs.writeFileSync(pngPath, result.screenshot);
+          if (!isIcon) {
+            const pngPath = path.resolve(outputDir, `${name}.png`);
+            fs.writeFileSync(pngPath, result.screenshot);
+            outputPaths.push(pngPath);
+          }
           const jsonPath = path.resolve(outputDir, `${name}.json`);
-          fs.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;
+          }
+          fs.writeFileSync(jsonPath, JSON.stringify(renderJson, null, 2));
+          outputPaths.push(jsonPath);
           const rawStyles = result.computedStyles["[data-reactscope-root] > *"] ?? {};
           const compStyles = {
             colors: {},
@@ -4348,15 +4867,21 @@ function registerRenderAll(renderCmd) {
               existingJson.axisLabels = [scenarioAxis.values];
               fs.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}
 `
             );
           }
@@ -4383,15 +4908,25 @@ function registerRenderAll(renderCmd) {
           "compliance-styles.json"
         );
         fs.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);
       }
@@ -4451,8 +4986,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 {
@@ -4492,7 +5036,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);
@@ -4584,12 +5127,12 @@ async function runBaseline(options = {}) {
   fs.mkdirSync(rendersDir, { recursive: true });
   let manifest$1;
   if (manifestPath !== void 0) {
-    const { readFileSync: readFileSync14 } = await import('fs');
+    const { readFileSync: readFileSync18 } = await import('fs');
     const absPath = path.resolve(rootDir, manifestPath);
     if (!fs.existsSync(absPath)) {
       throw new Error(`Manifest not found at ${absPath}.`);
     }
-    manifest$1 = JSON.parse(readFileSync14(absPath, "utf-8"));
+    manifest$1 = JSON.parse(readFileSync18(absPath, "utf-8"));
     process.stderr.write(`Loaded manifest from ${manifestPath}
 `);
   } else {
@@ -4781,8 +5324,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 {
@@ -4822,7 +5374,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);
@@ -4919,6 +5470,7 @@ function classifyComponent(entry, regressionThreshold) {
 async function runDiff(options = {}) {
   const {
     baselineDir: baselineDirRaw = DEFAULT_BASELINE_DIR2,
+    complianceTokens = [],
     componentsGlob,
     manifestPath,
     viewportWidth = 375,
@@ -5034,7 +5586,7 @@ async function runDiff(options = {}) {
   if (isTTY() && total > 0) {
     process.stderr.write("\n");
   }
-  const resolver = new tokens.TokenResolver([]);
+  const resolver = new tokens.TokenResolver(complianceTokens);
   const engine = new tokens.ComplianceEngine(resolver);
   const currentBatchReport = engine.auditBatch(computedStylesMap);
   const entries = [];
@@ -5630,129 +6182,803 @@ function buildStructuredReport(report) {
     route: report.route?.pattern ?? null
   };
 }
-var MIME_TYPES = {
-  ".html": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "application/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".svg": "image/svg+xml",
-  ".ico": "image/x-icon"
-};
-function registerBuild(siteCmd) {
-  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-styles.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("--title <text>", "Site title", "Scope \u2014 Component Gallery").action(
-    async (opts) => {
-      try {
-        const inputDir = path.resolve(process.cwd(), opts.input);
-        const outputDir = path.resolve(process.cwd(), opts.output);
-        if (!fs.existsSync(inputDir)) {
-          throw new Error(
-            `Input directory not found: ${inputDir}
-Run \`scope manifest generate\` and \`scope render\` first.`
-          );
-        }
-        const manifestPath = path.join(inputDir, "manifest.json");
-        if (!fs.existsSync(manifestPath)) {
-          throw new Error(
-            `Manifest not found at ${manifestPath}
-Run \`scope manifest generate\` first.`
-          );
-        }
-        process.stderr.write(`Building site from ${inputDir}\u2026
-`);
-        await site.buildSite({
-          inputDir,
-          outputDir,
-          basePath: opts.basePath,
-          ...opts.compliance !== void 0 && {
-            compliancePath: path.resolve(process.cwd(), opts.compliance)
-          },
-          title: opts.title
-        });
-        process.stderr.write(`Site written to ${outputDir}
-`);
-        process.stdout.write(`${outputDir}
-`);
-      } catch (err) {
-        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
-`);
-        process.exit(1);
-      }
+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__namespace.build({
+    stdin: {
+      contents: wrapperCode,
+      resolveDir: path.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 registerServe(siteCmd) {
-  siteCmd.command("serve").description(
-    "Start a local HTTP server for the built site directory.\n\nRun `scope site build` first.\nCtrl+C to stop.\n\nExamples:\n  scope site serve\n  scope site serve --port 8080\n  scope site serve --dir ./my-site-output"
-  ).option("-p, --port <number>", "Port to listen on", "3000").option("-d, --dir <path>", "Directory to serve", ".reactscope/site").action((opts) => {
+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",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".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 = path.resolve(cwd, "reactscope.config.json");
+  if (!fs.existsSync(configPath)) return [];
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const cfg = JSON.parse(raw);
+    return cfg.components?.wrappers?.globalCSS ?? [];
+  } catch {
+    return [];
+  }
+}
+function loadIconPatternsFromConfig2(cwd) {
+  const configPath = path.resolve(cwd, "reactscope.config.json");
+  if (!fs.existsSync(configPath)) return [];
+  try {
+    const raw = fs.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 = path.resolve(rootDir, "reactscope.config.json");
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const raw = fs.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 = path.join(inputDir, "renders");
+  await promises.mkdir(rendersDir, { recursive: true });
+  const cssFiles = loadGlobalCssFilesFromConfig2(rootDir);
+  const iconPatterns = loadIconPatternsFromConfig2(rootDir);
+  const complianceStylesPath = path.join(inputDir, "compliance-styles.json");
+  let complianceStyles = {};
+  if (fs.existsSync(complianceStylesPath)) {
+    try {
+      complianceStyles = JSON.parse(fs.readFileSync(complianceStylesPath, "utf-8"));
+    } catch {
+    }
+  }
+  for (const name of componentNames) {
+    const descriptor = manifest.components[name];
+    if (!descriptor) continue;
+    const filePath = path.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 {
-      const port = Number.parseInt(opts.port, 10);
-      if (Number.isNaN(port) || port < 1 || port > 65535) {
-        throw new Error(`Invalid port: ${opts.port}`);
+      wrapperScript = scopeData?.hasWrapper ? await buildWrapperScript(scopeData.filePath) : void 0;
+    } catch {
+    }
+    const renderer = buildRenderer(
+      filePath,
+      name,
+      375,
+      812,
+      cssFiles,
+      rootDir,
+      wrapperScript,
+      isIcon
+    );
+    const outcome = await render.safeRender(
+      () => renderer.renderCell(renderProps, descriptor.complexityClass),
+      {
+        props: renderProps,
+        sourceLocation: { file: descriptor.filePath, line: descriptor.loc.start, column: 0 }
       }
-      const serveDir = path.resolve(process.cwd(), opts.dir);
-      if (!fs.existsSync(serveDir)) {
-        throw new Error(
-          `Serve directory not found: ${serveDir}
-Run \`scope site build\` first.`
-        );
+    );
+    if (outcome.crashed) {
+      process.stderr.write(`  \u2717 ${name}: ${outcome.error.message}
+`);
+      continue;
+    }
+    const result = outcome.result;
+    if (!isIcon) {
+      fs.writeFileSync(path.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;
+    }
+    fs.writeFileSync(path.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;
       }
-      const server = http.createServer((req, res) => {
-        const rawUrl = req.url ?? "/";
-        const urlPath = decodeURIComponent(rawUrl.split("?")[0] ?? "/");
-        const filePath = path.join(serveDir, urlPath.endsWith("/") ? `${urlPath}index.html` : urlPath);
-        if (!filePath.startsWith(serveDir)) {
-          res.writeHead(403, { "Content-Type": "text/plain" });
-          res.end("Forbidden");
-          return;
+    }
+    complianceStyles[name] = compStyles;
+    process.stderr.write(`  \u2713 ${name} (${result.renderTimeMs.toFixed(0)}ms)
+`);
+  }
+  await shutdownPool3();
+  fs.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 = path.resolve(rootDir, "reactscope.tokens.json");
+  if (fs.existsSync(autoPath)) tokenFilePath = autoPath;
+  let compliancePath;
+  const crPath = path.join(inputDir, "compliance-report.json");
+  if (fs.existsSync(crPath)) compliancePath = crPath;
+  await site.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 = path.join(rendersDir, `${name}.json`);
+    if (!fs.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 = path.join(inputDir, "manifest.json");
+  let previousManifest = null;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      previousManifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    } catch {
+    }
+  }
+  process.stderr.write("[watch] Generating manifest\u2026\n");
+  const manifest$1 = await manifest.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 promises.mkdir(inputDir, { recursive: true });
+  fs.writeFileSync(path.join(inputDir, "manifest.json"), JSON.stringify(manifest$1, null, 2), "utf-8");
+  const count = Object.keys(manifest$1.components).length;
+  process.stderr.write(`[watch] Found ${count} components
+`);
+  const rendersDir = path.join(inputDir, "renders");
+  const stale = findStaleComponents(manifest$1, 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$1, 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$1;
+}
+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 manifest.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 }
+      });
+      fs.writeFileSync(path.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 {
+    fs.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 = path.join(inputDir, "manifest.json");
+  const raw = fs.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 = path.join(outputDir, "playground");
+  await promises.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 = path.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 promises.writeFile(path.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: path.join(playgroundDir, `${slug}.html`)
+      });
+    }
+  }
+  await promises.writeFile(
+    path.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 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 = path.resolve(process.cwd(), opts.input);
+        const outputDir = path.resolve(process.cwd(), opts.output);
+        if (!fs.existsSync(inputDir)) {
+          throw new Error(
+            `Input directory not found: ${inputDir}
+Run \`scope manifest generate\` and \`scope render\` first.`
+          );
         }
-        if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
-          const ext = path.extname(filePath).toLowerCase();
-          const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
-          res.writeHead(200, { "Content-Type": contentType });
-          fs.createReadStream(filePath).pipe(res);
-          return;
+        const manifestPath = path.join(inputDir, "manifest.json");
+        if (!fs.existsSync(manifestPath)) {
+          throw new Error(
+            `Manifest not found at ${manifestPath}
+Run \`scope manifest generate\` first.`
+          );
         }
-        const htmlPath = `${filePath}.html`;
-        if (fs.existsSync(htmlPath) && fs.statSync(htmlPath).isFile()) {
-          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-          fs.createReadStream(htmlPath).pipe(res);
-          return;
+        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 ? path.resolve(process.cwd(), opts.tokens) : void 0;
+        if (tokenFilePath === void 0) {
+          const autoPath = path.resolve(process.cwd(), "reactscope.tokens.json");
+          if (fs.existsSync(autoPath)) {
+            tokenFilePath = autoPath;
+          }
         }
-        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}
+        await site.buildSite({
+          inputDir,
+          outputDir,
+          basePath: opts.basePath,
+          ...opts.compliance !== void 0 && {
+            compliancePath: path.resolve(process.cwd(), opts.compliance)
+          },
+          ...tokenFilePath !== void 0 && { tokenFilePath },
+          title: opts.title,
+          iconPatterns
+        });
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        const componentCount = Object.keys(manifest.components).length;
+        const generatedPlaygroundCount = componentCount === 0 ? 0 : fs.statSync(path.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: path.join(outputDir, "playground")
+          });
+        }
+        const summaryPath = writeRunSummary({
+          command: "scope site build",
+          status: siteFailures.length > 0 ? "failed" : "success",
+          outputPaths: [outputDir, path.join(outputDir, "index.html")],
+          failures: siteFailures
+        });
+        process.stderr.write(`Site written to ${outputDir}
 `);
-        process.stderr.write(`Serving ${serveDir}
+        process.stderr.write(`[scope/site] Run summary written to ${summaryPath}
 `);
-        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.
+        process.stdout.write(`${outputDir}
 `);
-        } else {
-          process.stderr.write(`Server error: ${err.message}
+        if (siteFailures.length > 0) process.exit(1);
+      } catch (err) {
+        process.stderr.write(`${formatScopeDiagnostic(err)}
 `);
-        }
         process.exit(1);
-      });
-    } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+      }
+    }
+  );
+}
+function registerServe(siteCmd) {
+  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}`);
+        }
+        const serveDir = path.resolve(process.cwd(), opts.dir);
+        const watchMode = opts.watch === true;
+        const sseClients = /* @__PURE__ */ new Set();
+        if (watchMode) {
+          await promises.mkdir(serveDir, { recursive: true });
+        }
+        if (!watchMode && !fs.existsSync(serveDir)) {
+          throw new Error(
+            `Serve directory not found: ${serveDir}
+Run \`scope site build\` first.`
+          );
+        }
+        const server = http.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 = path.join(
+            serveDir,
+            urlPath.endsWith("/") ? `${urlPath}index.html` : urlPath
+          );
+          if (!filePath.startsWith(serveDir)) {
+            res.writeHead(403, { "Content-Type": "text/plain" });
+            res.end("Forbidden");
+            return;
+          }
+          if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+            const ext = path.extname(filePath).toLowerCase();
+            const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+            if (watchMode && ext === ".html") {
+              const html = injectLiveReloadScript(fs.readFileSync(filePath, "utf-8"));
+              res.writeHead(200, { "Content-Type": contentType });
+              res.end(html);
+              return;
+            }
+            res.writeHead(200, { "Content-Type": contentType });
+            fs.createReadStream(filePath).pipe(res);
+            return;
+          }
+          const htmlPath = `${filePath}.html`;
+          if (fs.existsSync(htmlPath) && fs.statSync(htmlPath).isFile()) {
+            if (watchMode) {
+              const html = injectLiveReloadScript(fs.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" });
+            fs.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.exit(1);
+          process.stderr.write(`Serving ${serveDir}
+`);
+          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}
+`);
+          }
+          process.exit(1);
+        });
+        if (watchMode) {
+          const rootDir = process.cwd();
+          const inputDir = path.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
+          });
+        }
+      } catch (err) {
+        process.stderr.write(`${formatScopeDiagnostic(err)}
+`);
+        process.exit(1);
+      }
     }
-  });
+  );
 }
 function createSiteCommand() {
   const siteCmd = new commander.Command("site").description(
-    '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-styles.json\n  scope site serve --port 8080'
+    '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);
@@ -5796,11 +7022,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)) {
@@ -5816,7 +7042,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;
 }
@@ -5857,6 +7083,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);
@@ -5891,42 +7122,84 @@ function formatComplianceReport(batch, threshold) {
 }
 function registerCompliance(tokensCmd) {
   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 --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("--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: tokens$1 } = loadTokens(tokenFilePath);
-      const resolver = new tokens.TokenResolver(tokens$1);
-      const engine = new tokens.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}
+    "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: tokens$1 } = loadTokens(tokenFilePath);
+        const resolver = new tokens.TokenResolver(tokens$1);
+        const engine = new tokens.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 = path.resolve(process.cwd(), opts.out);
+          fs.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";
@@ -6131,18 +7404,242 @@ ${formatImpactSummary(report)}
     }
   );
 }
+var DEFAULT_TOKEN_FILE2 = "reactscope.tokens.json";
+var CONFIG_FILE2 = "reactscope.config.json";
+function resolveOutputPath(fileFlag) {
+  if (fileFlag !== void 0) {
+    return path.resolve(process.cwd(), fileFlag);
+  }
+  const configPath = path.resolve(process.cwd(), CONFIG_FILE2);
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.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 path.resolve(process.cwd(), file);
+      }
+    } catch {
+    }
+  }
+  return path.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 = fs.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 (fs.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;
+      }
+      fs.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 render.BrowserPool({
     size: { browsers: 1, pagesPerBrowser: 1 },
@@ -6163,7 +7660,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);
@@ -6352,8 +7848,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;
 }
@@ -6375,7 +7871,7 @@ function resolveTokenFilePath(fileFlag) {
   if (fileFlag !== void 0) {
     return path.resolve(process.cwd(), fileFlag);
   }
-  const configPath = path.resolve(process.cwd(), CONFIG_FILE2);
+  const configPath = path.resolve(process.cwd(), CONFIG_FILE3);
   if (fs.existsSync(configPath)) {
     try {
       const raw = fs.readFileSync(configPath, "utf-8");
@@ -6387,7 +7883,7 @@ function resolveTokenFilePath(fileFlag) {
     } catch {
     }
   }
-  return path.resolve(process.cwd(), DEFAULT_TOKEN_FILE2);
+  return path.resolve(process.cwd(), DEFAULT_TOKEN_FILE3);
 }
 function loadTokens(absPath) {
   if (!fs.existsSync(absPath)) {
@@ -6716,6 +8212,7 @@ function createTokensCommand() {
   const tokensCmd = new commander.Command("tokens").description(
     '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);
@@ -6731,7 +8228,7 @@ function createTokensCommand() {
 // src/program.ts
 function createProgram(options = {}) {
   const program = new commander.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\nQUICKSTART (new project):\n  scope init              # detect config, scaffold reactscope.config.json\n  scope doctor            # verify setup before doing anything else\n  scope manifest generate # scan source and build component manifest\n  scope render all        # screenshot every component\n  scope site build        # build HTML gallery\n  scope site serve        # open at http://localhost:3000\n\nQUICKSTART (existing project / CI):\n  scope ci                # manifest \u2192 render \u2192 compliance \u2192 regression in one step\n\nAGENT BOOTSTRAP:\n  scope get-skill         # print SKILL.md to stdout \u2014 pipe into agent context\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.'
+    '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"