@agent-scope/cli 1.19.0 → 1.20.0

package/dist/cli.js

@@ -3,7 +3,7 @@
 // src/program.ts
 import { readFileSync as readFileSync13 } from "fs";
 import { generateTest, loadTrace } from "@agent-scope/playwright";
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 
 // src/browser.ts
 import { writeFileSync } from "fs";
@@ -214,13 +214,15 @@ function buildTable(headers, rows) {
 }
 function formatListTable(rows) {
   if (rows.length === 0) return "No components found.";
-  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS"];
+  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS", "COLLECTION", "INTERNAL"];
   const tableRows = rows.map((r) => [
     r.name,
     r.file,
     r.complexityClass,
     String(r.hookCount),
-    String(r.contextCount)
+    String(r.contextCount),
+    r.collection ?? "\u2014",
+    r.internal ? "yes" : "no"
   ]);
   return buildTable(headers, tableRows);
 }
@@ -251,6 +253,8 @@ function formatGetTable(name, descriptor) {
     `  Composes:       ${descriptor.composes.join(", ") || "none"}`,
     `  Composed By:    ${descriptor.composedBy.join(", ") || "none"}`,
     `  Side Effects:   ${formatSideEffects(descriptor.sideEffects)}`,
+    `  Collection:     ${descriptor.collection ?? "\u2014"}`,
+    `  Internal:       ${descriptor.internal}`,
     "",
     `  Props (${propNames.length}):`
   ];
@@ -273,8 +277,16 @@ function formatGetJson(name, descriptor) {
 }
 function formatQueryTable(rows, queryDesc) {
   if (rows.length === 0) return `No components match: ${queryDesc}`;
-  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS"];
-  const tableRows = rows.map((r) => [r.name, r.file, r.complexityClass, r.hooks, r.contexts]);
+  const headers = ["NAME", "FILE", "COMPLEXITY", "HOOKS", "CONTEXTS", "COLLECTION", "INTERNAL"];
+  const tableRows = rows.map((r) => [
+    r.name,
+    r.file,
+    r.complexityClass,
+    r.hooks,
+    r.contexts,
+    r.collection ?? "\u2014",
+    r.internal ? "yes" : "no"
+  ]);
   return `Query: ${queryDesc}
 
 ${buildTable(headers, tableRows)}`;
@@ -998,7 +1010,7 @@ function parseChecks(raw) {
 }
 function createCiCommand() {
   return new Command("ci").description(
-    "Run a non-interactive CI pipeline (manifest -> render -> compliance -> regression) with exit codes"
+    "Run the full Scope pipeline non-interactively and exit with a structured code.\n\nPIPELINE STEPS (in order):\n  1. manifest generate    scan source, build .reactscope/manifest.json\n  2. render all           screenshot every component\n  3. tokens compliance    score on-token CSS coverage\n  4. visual regression    pixel diff against --baseline (if provided)\n\nCHECKS (--checks flag, comma-separated):\n  compliance        token coverage below --threshold \u2192 exit 1\n  a11y              accessibility violations \u2192 exit 2\n  console-errors    console.error during render \u2192 exit 3\n  visual-regression pixel diff against baseline \u2192 exit 4\n  (render failures always \u2192 exit 5 regardless of --checks)\n\nEXIT CODES:\n  0   all checks passed\n  1   compliance below threshold\n  2   accessibility violations\n  3   console errors during render\n  4   visual regression detected\n  5   component render failures\n\nExamples:\n  scope ci\n  scope ci --baseline .reactscope/baseline --threshold 0.95\n  scope ci --checks compliance,a11y --json -o ci-result.json\n  scope ci --viewport 1280x720"
   ).option(
     "-b, --baseline <dir>",
     "Baseline directory for visual regression comparison (omit to skip)"
@@ -1160,7 +1172,25 @@ function formatCheck(check) {
   return `  [${ICONS[check.status]}] ${check.name.padEnd(12)} ${check.message}`;
 }
 function createDoctorCommand() {
-  return new Command2("doctor").description("Check the health of your Scope setup (config, tokens, CSS, manifest)").option("--json", "Emit structured JSON output", false).action((opts) => {
+  return new Command2("doctor").description(
+    `Verify your Scope project setup before running other commands.
+
+CHECKS PERFORMED:
+  config      reactscope.config.json exists and is valid JSON
+  tokens      reactscope.tokens.json exists and passes validation
+  css         globalCSS files referenced in config actually exist
+  manifest    .reactscope/manifest.json exists and is not stale
+              (stale = source files modified after last generate)
+
+STATUS LEVELS: ok | warn | error
+
+Run this first whenever renders fail or produce unexpected output.
+
+Examples:
+  scope doctor
+  scope doctor --json
+  scope doctor --json | jq '.checks[] | select(.status == "error")'`
+  ).option("--json", "Emit structured JSON output", false).action((opts) => {
     const cwd = process.cwd();
     const checks = [
       checkConfig(cwd),
@@ -1198,6 +1228,26 @@ function createDoctorCommand() {
   });
 }
 
+// src/get-skill-command.ts
+import { Command as Command3 } from "commander";
+
+// 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';
+
+// src/get-skill-command.ts
+function createGetSkillCommand() {
+  return new Command3("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'
+  ).option("--json", "Wrap output in JSON { skill: string } instead of raw markdown").action((opts) => {
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify({ skill: SKILL_CONTENT }, null, 2)}
+`);
+    } else {
+      process.stdout.write(SKILL_CONTENT);
+    }
+  });
+}
+
 // src/init/index.ts
 import { appendFileSync, existsSync as existsSync5, mkdirSync, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
 import { join as join3 } from "path";
@@ -1382,7 +1432,7 @@ function detectProject(rootDir) {
 
 // src/init/index.ts
 import { generateManifest as generateManifest2 } from "@agent-scope/manifest";
-import { Command as Command3 } from "commander";
+import { Command as Command4 } from "commander";
 function buildDefaultConfig(detected, tokenFile, outputDir) {
   const include = detected.componentPatterns.length > 0 ? detected.componentPatterns : ["src/**/*.tsx"];
   return {
@@ -1683,7 +1733,9 @@ async function runInit(options) {
   };
 }
 function createInitCommand() {
-  return new Command3("init").description("Initialise a Scope project \u2014 scaffold reactscope.config.json and friends").option("-y, --yes", "Accept all detected defaults without prompting", false).option("--force", "Overwrite existing reactscope.config.json if present", false).action(async (opts) => {
+  return new Command4("init").description(
+    "Auto-detect your project layout and scaffold reactscope.config.json.\n\nWHAT IT DOES:\n  - Detects component glob patterns from tsconfig / package.json / directory scan\n  - Detects globalCSS files (Tailwind, PostCSS)\n  - Writes reactscope.config.json with all detected values\n  - Adds .reactscope/ to .gitignore\n  - Creates .reactscope/ output directory\n\nCONFIG FIELDS GENERATED:\n  components.include      glob patterns for component discovery\n  components.wrappers     providers + globalCSS to inject on every render\n  render.viewport         default viewport (1280\xD7800)\n  tokens.file             path to reactscope.tokens.json\n  output.dir              .reactscope/ (all outputs go here)\n  ci.complianceThreshold  0.90 (90% on-token required to pass CI)\n\nSafe to re-run \u2014 will not overwrite existing config unless --force.\n\nExamples:\n  scope init\n  scope init --yes          # accept all detected defaults, no prompts\n  scope init --force        # overwrite existing config"
+  ).option("-y, --yes", "Accept all detected defaults without prompting", false).option("--force", "Overwrite existing reactscope.config.json if present", false).action(async (opts) => {
     try {
       const result = await runInit({ yes: opts.yes, force: opts.force });
       if (!result.success && !result.skipped) {
@@ -1701,13 +1753,13 @@ function createInitCommand() {
 import { resolve as resolve8 } from "path";
 import { getBrowserEntryScript as getBrowserEntryScript5 } from "@agent-scope/playwright";
 import { BrowserPool as BrowserPool2 } from "@agent-scope/render";
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/manifest-commands.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
 import { resolve as resolve4 } from "path";
 import { generateManifest as generateManifest3 } from "@agent-scope/manifest";
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 var MANIFEST_PATH = ".reactscope/manifest.json";
 function loadManifest(manifestPath = MANIFEST_PATH) {
   const absPath = resolve4(process.cwd(), manifestPath);
@@ -1724,34 +1776,56 @@ function resolveFormat(formatFlag) {
   return isTTY() ? "table" : "json";
 }
 function registerList(manifestCmd) {
-  manifestCmd.command("list").description("List all components in the manifest").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--filter <glob>", "Filter components by name glob pattern").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action((opts) => {
-    try {
-      const manifest = loadManifest(opts.manifest);
-      const format = resolveFormat(opts.format);
-      let entries = Object.entries(manifest.components);
-      if (opts.filter !== void 0) {
-        const filterPattern = opts.filter ?? "";
-        entries = entries.filter(([name]) => matchGlob(filterPattern, name));
-      }
-      const rows = entries.map(([name, descriptor]) => ({
-        name,
-        file: descriptor.filePath,
-        complexityClass: descriptor.complexityClass,
-        hookCount: descriptor.detectedHooks.length,
-        contextCount: descriptor.requiredContexts.length
-      }));
-      const output = format === "json" ? formatListJson(rows) : formatListTable(rows);
-      process.stdout.write(`${output}
+  manifestCmd.command("list").description(
+    `List all components in the manifest as a table (TTY) or JSON (piped).
+
+Examples:
+  scope manifest list
+  scope manifest list --format json | jq '.[].name'
+  scope manifest list --filter "Button*"`
+  ).option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--filter <glob>", "Filter components by name glob pattern").option("--collection <name>", "Filter to only components in the named collection").option("--internal", "Show only internal components").option("--no-internal", "Hide internal components from output").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
+    (opts) => {
+      try {
+        const manifest = loadManifest(opts.manifest);
+        const format = resolveFormat(opts.format);
+        let entries = Object.entries(manifest.components);
+        if (opts.filter !== void 0) {
+          const filterPattern = opts.filter ?? "";
+          entries = entries.filter(([name]) => matchGlob(filterPattern, name));
+        }
+        if (opts.collection !== void 0) {
+          const col = opts.collection;
+          entries = entries.filter(([, d]) => d.collection === col);
+        }
+        if (opts.internal === true) {
+          entries = entries.filter(([, d]) => d.internal);
+        } else if (opts.internal === false) {
+          entries = entries.filter(([, d]) => !d.internal);
+        }
+        const rows = entries.map(([name, descriptor]) => ({
+          name,
+          file: descriptor.filePath,
+          complexityClass: descriptor.complexityClass,
+          hookCount: descriptor.detectedHooks.length,
+          contextCount: descriptor.requiredContexts.length,
+          collection: descriptor.collection,
+          internal: descriptor.internal
+        }));
+        const output = format === "json" ? formatListJson(rows) : formatListTable(rows);
+        process.stdout.write(`${output}
 `);
-    } catch (err) {
-      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+      } catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
 `);
-      process.exit(1);
+        process.exit(1);
+      }
     }
-  });
+  );
 }
 function registerGet(manifestCmd) {
-  manifestCmd.command("get <name>").description("Get full details of a single component by name").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action((name, opts) => {
+  manifestCmd.command("get <name>").description(
+    "Get full details of a single component: props, hooks, complexity class, file path.\n\nExamples:\n  scope manifest get Button\n  scope manifest get Button --format json\n  scope manifest get Button --format json | jq '.complexity'"
+  ).option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action((name, opts) => {
     try {
       const manifest = loadManifest(opts.manifest);
       const format = resolveFormat(opts.format);
@@ -1775,10 +1849,12 @@ Available: ${available}${hint}`
   });
 }
 function registerQuery(manifestCmd) {
-  manifestCmd.command("query").description("Query components by attributes").option("--context <name>", "Find components consuming a context").option("--hook <name>", "Find components using a specific hook").option("--complexity <class>", "Filter by complexity class: simple or complex").option("--side-effects", "Find components with any side effects", false).option("--has-fetch", "Find components with fetch calls", false).option(
+  manifestCmd.command("query").description(
+    'Filter components by structural attributes. All flags are AND-combined.\n\nCOMPLEXITY CLASSES:\n  simple   \u2014 pure/presentational, no side effects, Satori-renderable\n  complex  \u2014 uses context/hooks/effects, requires BrowserPool to render\n\nExamples:\n  scope manifest query --complexity simple\n  scope manifest query --has-fetch\n  scope manifest query --hook useContext --side-effects\n  scope manifest query --has-prop "variant:union" --format json\n  scope manifest query --composed-by Layout'
+  ).option("--context <name>", "Find components consuming a context").option("--hook <name>", "Find components using a specific hook").option("--complexity <class>", "Filter by complexity class: simple or complex").option("--side-effects", "Find components with any side effects", false).option("--has-fetch", "Find components with fetch calls", false).option(
     "--has-prop <spec>",
     "Find components with a prop matching name or name:type (e.g. 'loading' or 'variant:union')"
-  ).option("--composed-by <name>", "Find components that compose the named component").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
+  ).option("--composed-by <name>", "Find components that compose the named component").option("--internal", "Find only internal components", false).option("--collection <name>", "Filter to only components in the named collection").option("--format <fmt>", "Output format: json or table (default: auto-detect)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH).action(
     (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -1791,9 +1867,11 @@ function registerQuery(manifestCmd) {
         if (opts.hasFetch) queryParts.push("has-fetch");
         if (opts.hasProp !== void 0) queryParts.push(`has-prop=${opts.hasProp}`);
         if (opts.composedBy !== void 0) queryParts.push(`composed-by=${opts.composedBy}`);
+        if (opts.internal) queryParts.push("internal");
+        if (opts.collection !== void 0) queryParts.push(`collection=${opts.collection}`);
         if (queryParts.length === 0) {
           process.stderr.write(
-            "No query flags specified. Use --context, --hook, --complexity, --side-effects, --has-fetch, --has-prop, or --composed-by.\n"
+            "No query flags specified. Use --context, --hook, --complexity, --side-effects, --has-fetch, --has-prop, --composed-by, --internal, or --collection.\n"
           );
           process.exit(1);
         }
@@ -1838,15 +1916,24 @@ function registerQuery(manifestCmd) {
           const targetName = opts.composedBy;
           entries = entries.filter(([, d]) => {
             const composedBy = d.composedBy;
-            return composedBy !== void 0 && composedBy.includes(targetName);
+            return composedBy?.includes(targetName);
           });
         }
+        if (opts.internal) {
+          entries = entries.filter(([, d]) => d.internal);
+        }
+        if (opts.collection !== void 0) {
+          const col = opts.collection;
+          entries = entries.filter(([, d]) => d.collection === col);
+        }
         const rows = entries.map(([name, d]) => ({
           name,
           file: d.filePath,
           complexityClass: d.complexityClass,
           hooks: d.detectedHooks.join(", ") || "\u2014",
-          contexts: d.requiredContexts.join(", ") || "\u2014"
+          contexts: d.requiredContexts.join(", ") || "\u2014",
+          collection: d.collection,
+          internal: d.internal
         }));
         const output = format === "json" ? formatQueryJson(rows) : formatQueryTable(rows, queryDesc);
         process.stdout.write(`${output}
@@ -1861,7 +1948,7 @@ function registerQuery(manifestCmd) {
 }
 function registerGenerate(manifestCmd) {
   manifestCmd.command("generate").description(
-    "Generate the component manifest from source and write to .reactscope/manifest.json"
+    'Scan source files and generate .reactscope/manifest.json.\n\nUses Babel static analysis \u2014 no runtime or bundler required.\nRe-run whenever components are added, removed, or significantly changed.\n\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 = resolve4(process.cwd(), opts.root ?? ".");
@@ -1895,8 +1982,8 @@ function registerGenerate(manifestCmd) {
   });
 }
 function createManifestCommand() {
-  const manifestCmd = new Command4("manifest").description(
-    "Query and explore the component manifest"
+  const manifestCmd = new Command5("manifest").description(
+    "Query and explore the component manifest (.reactscope/manifest.json).\n\nThe manifest is the source-of-truth registry of every React component\nin your codebase \u2014 generated by static analysis (no runtime needed).\n\nRun `scope manifest generate` first, then use list/get/query to explore.\n\nExamples:\n  scope manifest generate\n  scope manifest list\n  scope manifest get Button\n  scope manifest query --complexity complex --has-fetch"
   );
   registerList(manifestCmd);
   registerGet(manifestCmd);
@@ -2218,7 +2305,19 @@ async function runHooksProfiling(componentName, filePath, props) {
 }
 function createInstrumentHooksCommand() {
   const cmd = new Cmd("hooks").description(
-    "Profile per-hook-instance data for a component: update counts, cache hit rates, effect counts, and more"
+    `Profile per-hook-instance data for a component.
+
+METRICS CAPTURED per hook instance:
+  useState    update count, current value
+  useCallback cache hit rate (stable reference %)
+  useMemo     cache hit rate (recompute %)
+  useEffect   execution count
+  useRef      current value snapshot
+
+Examples:
+  scope instrument hooks SearchInput
+  scope instrument hooks SearchInput --props '{"value":"hello"}' --json
+  scope instrument hooks Dropdown --json | jq '.hooks[] | select(.type == "useMemo")'  `
   ).argument("<component>", "Component name (must exist in the manifest)").option("--props <json>", "Inline props JSON passed to the component", "{}").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH2).option("--format <fmt>", "Output format: json|text (default: auto)", "json").option("--show-flags", "Show heuristic flags only (useful for CI checks)", false).action(
     async (componentName, opts) => {
       try {
@@ -2508,7 +2607,19 @@ async function runInteractionProfile(componentName, filePath, props, interaction
 }
 function createInstrumentProfileCommand() {
   const cmd = new Cmd2("profile").description(
-    "Capture a full interaction-scoped performance profile: renders, timing, layout shifts"
+    `Capture a full performance profile for an interaction sequence.
+
+PROFILE INCLUDES:
+  renders       total re-renders triggered by the interaction
+  timing        interaction start \u2192 paint time (ms)
+  layoutShifts  cumulative layout shift (CLS) score
+  scriptTime    JS execution time (ms)
+  longTasks     count of tasks >50ms
+
+Examples:
+  scope instrument profile Button --interaction '[{"action":"click","target":"button"}]'
+  scope instrument profile Modal --interaction '[{"action":"click","target":".open-btn"}]' --json
+  scope instrument profile Form --json | jq '.summary.renderCount'`
   ).argument("<component>", "Component name (must exist in the manifest)").option(
     "--interaction <json>",
     `Interaction steps JSON, e.g. '[{"action":"click","target":"button.primary"}]'`,
@@ -2571,7 +2682,7 @@ Available: ${available}`
 // src/instrument/tree.ts
 import { resolve as resolve7 } from "path";
 import { getBrowserEntryScript as getBrowserEntryScript4 } from "@agent-scope/playwright";
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 import { chromium as chromium4 } from "playwright";
 var MANIFEST_PATH4 = ".reactscope/manifest.json";
 var DEFAULT_VIEWPORT_WIDTH = 375;
@@ -2852,7 +2963,21 @@ async function runInstrumentTree(options) {
   }
 }
 function createInstrumentTreeCommand() {
-  return new Command5("tree").description("Render a component via BrowserPool and output a structured instrumentation tree").argument("<component>", "Component name to instrument (must exist in the manifest)").option("--sort-by <field>", "Sort nodes by field: renderCount | depth").option("--limit <n>", "Limit output to the first N nodes (depth-first)").option("--uses-context <name>", "Filter to components that use a specific context").option("--provider-depth", "Annotate each node with its context-provider nesting depth", false).option(
+  return new Command6("tree").description(
+    `Render a component and output the full instrumentation tree:
+DOM structure, computed styles per node, a11y roles, and React fibers.
+
+OUTPUT STRUCTURE per node:
+  tag / id / className    DOM identity
+  computedStyles          resolved CSS properties
+  a11y                    role, name, focusable
+  children                nested child nodes
+
+Examples:
+  scope instrument tree Card
+  scope instrument tree Button --props '{"variant":"primary"}' --json
+  scope instrument tree Input --json | jq '.tree.computedStyles'`
+  ).argument("<component>", "Component name to instrument (must exist in the manifest)").option("--sort-by <field>", "Sort nodes by field: renderCount | depth").option("--limit <n>", "Limit output to the first N nodes (depth-first)").option("--uses-context <name>", "Filter to components that use a specific context").option("--provider-depth", "Annotate each node with its context-provider nesting depth", false).option(
     "--wasted-renders",
     "Filter to components with wasted renders (no prop/state/context changes, not memoized)",
     false
@@ -3248,7 +3373,8 @@ Available: ${available}`
   }
   const rootDir = process.cwd();
   const filePath = resolve8(rootDir, descriptor.filePath);
-  const preScript = getBrowserEntryScript5() + "\n" + buildInstrumentationScript();
+  const preScript = `${getBrowserEntryScript5()}
+${buildInstrumentationScript()}`;
   const htmlHarness = await buildComponentHarness(
     filePath,
     options.componentName,
@@ -3337,7 +3463,24 @@ function formatRendersTable(result) {
   return lines.join("\n");
 }
 function createInstrumentRendersCommand() {
-  return new Command6("renders").description("Trace re-render causality chains for a component during an interaction sequence").argument("<component>", "Component name to instrument (must be in manifest)").option(
+  return new Command7("renders").description(
+    `Trace every re-render triggered by an interaction and identify root causes.
+
+OUTPUT INCLUDES per render event:
+  component      which component re-rendered
+  trigger        why it re-rendered: state_change | props_change | context_change |
+                 parent_rerender | force_update | hook_dependency
+  wasted         true if re-rendered with no changed inputs and not memoized
+  chain          full causality chain from root cause to this render
+
+WASTED RENDERS: propsChanged=false AND stateChanged=false AND contextChanged=false
+AND memoized=false \u2014 these are optimisation opportunities.
+
+Examples:
+  scope instrument renders SearchPage --interaction '[{"action":"type","target":"input","text":"hello"}]'
+  scope instrument renders Button --interaction '[{"action":"click","target":"button"}]' --json
+  scope instrument renders Form --json | jq '.events[] | select(.wasted == true)'`
+  ).argument("<component>", "Component name to instrument (must be in manifest)").option(
     "--interaction <json>",
     `Interaction sequence JSON, e.g. '[{"action":"click","target":"button"}]'`,
     "[]"
@@ -3382,8 +3525,29 @@ function createInstrumentRendersCommand() {
   );
 }
 function createInstrumentCommand() {
-  const instrumentCmd = new Command6("instrument").description(
-    "Structured instrumentation commands for React component analysis"
+  const instrumentCmd = new Command7("instrument").description(
+    `Runtime instrumentation for React component behaviour analysis.
+
+All instrument commands:
+  1. Build an esbuild harness for the component
+  2. Load it in a Playwright browser
+  3. Inject instrumentation hooks into React DevTools fiber
+  4. Execute interactions and collect events
+
+PREREQUISITES:
+  scope manifest generate   (component must be in manifest)
+  reactscope.config.json    (for wrappers/globalCSS)
+
+INTERACTION FORMAT:
+  JSON array of step objects: [{action, target, text?}]
+  Actions: click | type | focus | blur | hover | key
+  Target: CSS selector for the element to interact with
+
+Examples:
+  scope instrument renders Button --interaction '[{"action":"click","target":"button"}]'
+  scope instrument hooks SearchInput --props '{"value":"hello"}'
+  scope instrument profile Modal --interaction '[{"action":"click","target":".open-btn"}]'
+  scope instrument tree Card`
   );
   instrumentCmd.addCommand(createInstrumentRendersCommand());
   instrumentCmd.addCommand(createInstrumentHooksCommand());
@@ -3405,7 +3569,7 @@ import {
   safeRender as safeRender2,
   stressAxis
 } from "@agent-scope/render";
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 
 // src/scope-file.ts
 import { existsSync as existsSync7, mkdirSync as mkdirSync3, rmSync } from "fs";
@@ -3795,7 +3959,27 @@ Available: ${available}`
   return { __default__: {} };
 }
 function registerRenderSingle(renderCmd) {
-  renderCmd.command("component <component>", { isDefault: true }).description("Render a single component to PNG or JSON").option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--scenario <name>", "Run a named scenario from the component's .scope file").option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).action(
+  renderCmd.command("component <component>", { isDefault: true }).description(
+    `Render one component to a PNG screenshot or JSON data object.
+
+PROP SOURCES (in priority order):
+  --scenario <name>    named scenario from <ComponentName>.scope file
+  --props <json>       inline props JSON string
+  (no flag)            component rendered with all-default props
+
+FORMAT DETECTION:
+  --format png    always write PNG
+  --format json   always write JSON render data
+  auto (default)  PNG when -o has .png extension or stdout is file;
+                  JSON when stdout is a pipe
+
+Examples:
+  scope render component Button
+  scope render component Button --props '{"variant":"primary","size":"lg"}'
+  scope render component Button --scenario hover-state -o button-hover.png
+  scope render component Card --viewport 375x812 --theme dark
+  scope render component Badge --format json | jq '.a11y'`
+  ).option("--props <json>", `Inline props JSON, e.g. '{"variant":"primary"}'`).option("--scenario <name>", "Run a named scenario from the component's .scope file").option("--viewport <WxH>", "Viewport size e.g. 1280x720", "375x812").option("--theme <name>", "Theme name from the token system").option("-o, --output <path>", "Write PNG to file instead of stdout").option("--format <fmt>", "Output format: png or json (default: auto)").option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).action(
     async (componentName, opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -3920,7 +4104,9 @@ Available: ${available}`
   );
 }
 function registerRenderMatrix(renderCmd) {
-  renderCmd.command("matrix <component>").description("Render a component across a matrix of prop axes").option(
+  renderCmd.command("matrix <component>").description(
+    'Render every combination of values across one or more prop axes.\nProduces a matrix of screenshots \u2014 one cell per combination.\n\nAXES FORMAT (two equivalent forms):\n  Short:  --axes "variant:primary,ghost size:sm,md,lg"\n  JSON:   --axes {"variant":["primary","ghost"],"size":["sm","md","lg"]}\n\nCOMPOSITION CONTEXTS (--contexts):\n  Test component in different layout environments.\n  Available IDs: centered, rtl, sidebar, dark-bg, light-bg\n  (Define custom contexts in reactscope.config.json)\n\nSTRESS PRESETS (--stress):\n  Inject adversarial content to test edge cases.\n  Available IDs: text.long, text.unicode, text.empty\n\nExamples:\n  scope render matrix Button --axes "variant:primary,ghost,destructive"\n  scope render matrix Button --axes "variant:primary,ghost size:sm,lg" --sprite matrix.png\n  scope render matrix Badge --axes "type:info,warn,error" --contexts centered,rtl\n  scope render matrix Input --stress text.long,text.unicode --format json'
+  ).option(
     "--axes <spec>",
     `Axis definitions: key:v1,v2 space-separated OR JSON object e.g. 'variant:primary,ghost size:sm,lg' or '{"variant":["primary","ghost"],"size":["sm","lg"]}'`
   ).option(
@@ -4079,7 +4265,9 @@ Available: ${available}`
   );
 }
 function registerRenderAll(renderCmd) {
-  renderCmd.command("all").description("Render all components from the manifest").option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
+  renderCmd.command("all").description(
+    "Render every component in the manifest and write to .reactscope/renders/.\n\nAlso emits .reactscope/compliance-styles.json (computed CSS class\u2192value map)\nwhich is required by `scope tokens compliance`.\n\nSCENARIO SELECTION:\n  Each component is rendered using its default scenario from its .scope file\n  if one exists, otherwise with all-default props.\n\nMATRIX AUTO-DETECTION:\n  If a component has a .scope file with a matrix block, render all\n  will render the matrix cells in addition to the default screenshot.\n\nExamples:\n  scope render all\n  scope render all --concurrency 8\n  scope render all --format json --output-dir .reactscope/renders\n  scope render all --manifest ./custom/manifest.json"
+  ).option("--concurrency <n>", "Max parallel renders", "4").option("--output-dir <dir>", "Output directory for renders", DEFAULT_OUTPUT_DIR).option("--manifest <path>", "Path to manifest.json", MANIFEST_PATH6).option("--format <fmt>", "Output format: json|png (default: png)", "png").action(
     async (opts) => {
       try {
         const manifest = loadManifest(opts.manifest);
@@ -4300,8 +4488,8 @@ function resolveMatrixFormat(formatFlag, spriteAlreadyWritten) {
   return "json";
 }
 function createRenderCommand() {
-  const renderCmd = new Command7("render").description(
-    "Render components to PNG or JSON via esbuild + BrowserPool"
+  const renderCmd = new Command8("render").description(
+    'Render React components to PNG screenshots or JSON render data.\n\nScope uses two render engines depending on component complexity:\n  Satori     \u2014 fast SVG\u2192PNG renderer for simple/presentational components\n  BrowserPool \u2014 Playwright headless browser for complex components\n               (context providers, hooks, async, global CSS)\n\nPREREQUISITES:\n  1. reactscope.config.json exists  (scope init)\n  2. manifest.json is up to date    (scope manifest generate)\n  3. If using globalCSS: Tailwind/PostCSS is configured in the project\n\nOUTPUTS (written to .reactscope/renders/<ComponentName>/):\n  screenshot.png     retina-quality PNG (2\xD7 physical pixels, displayed at 1\xD7)\n  render.json        props, dimensions, DOM snapshot, a11y, computed styles\n  compliance-styles.json (render all only) \u2014 token matching input\n\nExamples:\n  scope render component Button\n  scope render matrix Button --axes "variant:primary,ghost size:sm,md,lg"\n  scope render all\n  scope render all --format json --output-dir ./out'
   );
   registerRenderSingle(renderCmd);
   registerRenderMatrix(renderCmd);
@@ -5532,7 +5720,7 @@ import { createReadStream, existsSync as existsSync12, statSync as statSync2 } f
 import { createServer } from "http";
 import { extname, join as join5, resolve as resolve14 } from "path";
 import { buildSite } from "@agent-scope/site";
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 var MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".css": "text/css; charset=utf-8",
@@ -5545,7 +5733,9 @@ var MIME_TYPES = {
   ".ico": "image/x-icon"
 };
 function registerBuild(siteCmd) {
-  siteCmd.command("build").description("Build a static HTML gallery from .reactscope/ output").option("-i, --input <path>", "Path to .reactscope input directory", ".reactscope").option("-o, --output <path>", "Output directory for generated site", ".reactscope/site").option("--base-path <path>", "Base URL path prefix for subdirectory deployment", "/").option("--compliance <path>", "Path to compliance batch report JSON").option("--title <text>", "Site title", "Scope \u2014 Component Gallery").action(
+  siteCmd.command("build").description(
+    'Build the static HTML site from manifest + render outputs.\n\nINPUT DIRECTORY (.reactscope/ by default) must contain:\n  manifest.json       component registry\n  renders/            screenshots and render.json files from `scope render all`\n\nOPTIONAL:\n  --compliance <path>   include token compliance scores on detail pages\n  --base-path <path>    set if deploying to a subdirectory (e.g. /ui-docs)\n\nExamples:\n  scope site build\n  scope site build --title "Design System" -o .reactscope/site\n  scope site build --compliance .reactscope/compliance-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 = resolve14(process.cwd(), opts.input);
@@ -5587,7 +5777,9 @@ Run \`scope manifest generate\` first.`
   );
 }
 function registerServe(siteCmd) {
-  siteCmd.command("serve").description("Serve the built static site locally").option("-p, --port <number>", "Port to listen on", "3000").option("-d, --dir <path>", "Directory to serve", ".reactscope/site").action((opts) => {
+  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) => {
     try {
       const port = Number.parseInt(opts.port, 10);
       if (Number.isNaN(port) || port < 1 || port > 65535) {
@@ -5650,8 +5842,8 @@ Run \`scope site build\` first.`
   });
 }
 function createSiteCommand() {
-  const siteCmd = new Command8("site").description(
-    "Build and serve the static component gallery site"
+  const siteCmd = new Command9("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'
   );
   registerBuild(siteCmd);
   registerServe(siteCmd);
@@ -5668,7 +5860,7 @@ import {
   TokenValidationError,
   validateTokenFile
 } from "@agent-scope/tokens";
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/tokens/compliance.ts
 import { existsSync as existsSync13, readFileSync as readFileSync10 } from "fs";
@@ -5809,7 +6001,9 @@ function formatComplianceReport(batch, threshold) {
   return lines.join("\n");
 }
 function registerCompliance(tokensCmd) {
-  tokensCmd.command("compliance").description("Aggregate token compliance report across all components (Token Spec \xA73.3 format)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH})`).option("--threshold <n>", "Exit code 1 if compliance score is below this percentage (0-100)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
+  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 } = loadTokens(tokenFilePath);
@@ -5855,7 +6049,7 @@ import {
   ThemeResolver,
   TokenResolver as TokenResolver5
 } from "@agent-scope/tokens";
-import { Command as Command9 } from "commander";
+import { Command as Command10 } from "commander";
 var DEFAULT_TOKEN_FILE = "reactscope.tokens.json";
 var CONFIG_FILE = "reactscope.config.json";
 var SUPPORTED_FORMATS = ["css", "ts", "scss", "tailwind", "flat-json", "figma"];
@@ -5878,7 +6072,9 @@ function resolveTokenFilePath2(fileFlag) {
   return resolve16(process.cwd(), DEFAULT_TOKEN_FILE);
 }
 function createTokensExportCommand() {
-  return new Command9("export").description("Export design tokens to a downstream format").requiredOption("--format <fmt>", `Output format: ${SUPPORTED_FORMATS.join(", ")}`).option("--file <path>", "Path to token file (overrides config)").option("--out <path>", "Write output to file instead of stdout").option("--prefix <prefix>", "CSS/SCSS: prefix for variable names (e.g. 'scope')").option("--selector <selector>", "CSS: custom root selector (default: ':root')").option(
+  return new Command10("export").description(
+    'Export design tokens to CSS variables, TypeScript, SCSS, Tailwind config, Figma, or flat JSON.\n\nFORMATS:\n  css          CSS custom properties (:root { --color-primary-500: #3b82f6; })\n  scss         SCSS variables ($color-primary-500: #3b82f6;)\n  ts           TypeScript const export (export const tokens = {...})\n  tailwind     Tailwind theme.extend block (paste into tailwind.config.js)\n  flat-json    Flat { path: value } map (useful for tooling integration)\n  figma        Figma Tokens plugin format\n\nExamples:\n  scope tokens export --format css --out src/tokens.css\n  scope tokens export --format css --prefix brand --selector ":root, [data-theme]"\n  scope tokens export --format tailwind --out tailwind-tokens.js\n  scope tokens export --format ts --out src/tokens.ts\n  scope tokens export --format css --theme dark --out dark-tokens.css'
+  ).requiredOption("--format <fmt>", `Output format: ${SUPPORTED_FORMATS.join(", ")}`).option("--file <path>", "Path to token file (overrides config)").option("--out <path>", "Write output to file instead of stdout").option("--prefix <prefix>", "CSS/SCSS: prefix for variable names (e.g. 'scope')").option("--selector <selector>", "CSS: custom root selector (default: ':root')").option(
     "--theme <name>",
     "Include theme overrides for the named theme (applies to css, ts, scss, tailwind, figma)"
   ).action(
@@ -6025,7 +6221,9 @@ function formatImpactSummary(report) {
   return `\u2192 ${parts.join(", ")}`;
 }
 function registerImpact(tokensCmd) {
-  tokensCmd.command("impact <path>").description("List all components and elements that consume a given token (Token Spec \xA74.3)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH2})`).option("--new-value <value>", "Proposed new value \u2014 report visual severity of the change").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action(
+  tokensCmd.command("impact <path>").description(
+    "List every component and CSS element that uses a given token.\nUse this to understand the blast radius before changing a token value.\n\nPREREQUISITE: scope render all (populates compliance-styles.json)\n\nExamples:\n  scope tokens impact color.primary.500\n  scope tokens impact spacing.4 --format json\n  scope tokens impact font.size.base | grep Button"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH2})`).option("--new-value <value>", "Proposed new value \u2014 report visual severity of the change").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action(
     (tokenPath, opts) => {
       try {
         const tokenFilePath = resolveTokenFilePath(opts.file);
@@ -6120,7 +6318,9 @@ async function renderComponentWithCssOverride(filePath, componentName, cssOverri
   }
 }
 function registerPreview(tokensCmd) {
-  tokensCmd.command("preview <path>").description("Render before/after sprite sheet for components affected by a token change").requiredOption("--new-value <value>", "The proposed new resolved value for the token").option("--sprite", "Output a PNG sprite sheet (default when TTY)", false).option("-o, --output <path>", "Output PNG path (default: .reactscope/previews/<token>.png)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH3})`).option("--manifest <path>", "Path to manifest.json", DEFAULT_MANIFEST_PATH).option("--format <fmt>", "Output format: json or text (default: auto-detect)").option("--timeout <ms>", "Browser timeout per render (ms)", "10000").option("--viewport-width <px>", "Viewport width in pixels", "1280").option("--viewport-height <px>", "Viewport height in pixels", "720").action(
+  tokensCmd.command("preview <path>").description(
+    'Render before/after screenshots of all components affected by a token change.\nUseful for visual review before committing a token value update.\n\nPREREQUISITE: scope render all (provides baseline renders)\n\nExamples:\n  scope tokens preview color.primary.500\n  scope tokens preview color.primary.500 --new-value "#2563eb" -o preview.png'
+  ).requiredOption("--new-value <value>", "The proposed new resolved value for the token").option("--sprite", "Output a PNG sprite sheet (default when TTY)", false).option("-o, --output <path>", "Output PNG path (default: .reactscope/previews/<token>.png)").option("--file <path>", "Path to token file (overrides config)").option("--styles <path>", `Path to compliance styles JSON (default: ${DEFAULT_STYLES_PATH3})`).option("--manifest <path>", "Path to manifest.json", DEFAULT_MANIFEST_PATH).option("--format <fmt>", "Output format: json or text (default: auto-detect)").option("--timeout <ms>", "Browser timeout per render (ms)", "10000").option("--viewport-width <px>", "Viewport width in pixels", "1280").option("--viewport-height <px>", "Viewport height in pixels", "720").action(
     async (tokenPath, opts) => {
       try {
         const tokenFilePath = resolveTokenFilePath(opts.file);
@@ -6367,7 +6567,9 @@ function buildResolutionChain(startPath, rawTokens) {
   return chain;
 }
 function registerGet2(tokensCmd) {
-  tokensCmd.command("get <path>").description("Resolve a token path to its computed value").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+  tokensCmd.command("get <path>").description(
+    "Resolve a token path and print its final computed value.\nFollows all {ref} chains to the raw value.\n\nExamples:\n  scope tokens get color.primary.500\n  scope tokens get spacing.4 --format json\n  scope tokens get font.size.base --file ./tokens/brand.json"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
       const { tokens } = loadTokens(filePath);
@@ -6392,7 +6594,18 @@ function registerGet2(tokensCmd) {
   });
 }
 function registerList2(tokensCmd) {
-  tokensCmd.command("list [category]").description("List tokens, optionally filtered by category or type").option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+  tokensCmd.command("list [category]").description(
+    `List all tokens, optionally filtered by category prefix or type.
+
+CATEGORY: top-level token namespace (e.g. "color", "spacing", "typography")
+TYPE: token value type \u2014 color | spacing | typography | shadow | radius | opacity
+
+Examples:
+  scope tokens list
+  scope tokens list color
+  scope tokens list --type spacing
+  scope tokens list color --format json | jq '.[].path'`
+  ).option("--type <type>", "Filter by token type (color, dimension, fontFamily, etc.)").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
     (category, opts) => {
       try {
         const filePath = resolveTokenFilePath(opts.file);
@@ -6422,7 +6635,9 @@ function registerList2(tokensCmd) {
   );
 }
 function registerSearch(tokensCmd) {
-  tokensCmd.command("search <value>").description("Find which token(s) match a computed value (supports fuzzy color matching)").option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
+  tokensCmd.command("search <value>").description(
+    'Find the token(s) whose computed value matches the given raw value.\nSupports fuzzy color matching (hex \u2194 rgb \u2194 hsl equivalence).\n\nExamples:\n  scope tokens search "#3b82f6"\n  scope tokens search "16px"\n  scope tokens search "rgb(59, 130, 246)"   # fuzzy-matches #3b82f6'
+  ).option("--type <type>", "Restrict search to a specific token type").option("--fuzzy", "Return nearest match even if no exact match exists", false).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or table (default: auto-detect)").action(
     (value, opts) => {
       try {
         const filePath = resolveTokenFilePath(opts.file);
@@ -6505,7 +6720,9 @@ Tip: use --fuzzy for nearest-match search.
   );
 }
 function registerResolve(tokensCmd) {
-  tokensCmd.command("resolve <path>").description("Show the full resolution chain for a token").option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
+  tokensCmd.command("resolve <path>").description(
+    "Print the full reference chain from a token path down to its raw value.\nUseful for debugging circular references or understanding token inheritance.\n\nExamples:\n  scope tokens resolve color.primary.500\n  scope tokens resolve button.background --format json"
+  ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((tokenPath, opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
       const absFilePath = filePath;
@@ -6541,7 +6758,19 @@ function registerResolve(tokensCmd) {
 }
 function registerValidate(tokensCmd) {
   tokensCmd.command("validate").description(
-    "Validate the token file for errors (circular refs, missing refs, type mismatches)"
+    `Validate the token file and report errors.
+
+CHECKS:
+  - Circular reference chains (A \u2192 B \u2192 A)
+  - Broken references ({path.that.does.not.exist})
+  - Type mismatches (token declared as "color" but value is a number)
+  - Duplicate paths
+
+Exits 1 if any errors are found (suitable for CI).
+
+Examples:
+  scope tokens validate
+  scope tokens validate --format json | jq '.errors'`
   ).option("--file <path>", "Path to token file (overrides config)").option("--format <fmt>", "Output format: json or text (default: auto-detect)").action((opts) => {
     try {
       const filePath = resolveTokenFilePath(opts.file);
@@ -6619,8 +6848,8 @@ function outputValidationResult(filePath, errors, useJson) {
   }
 }
 function createTokensCommand() {
-  const tokensCmd = new Command10("tokens").description(
-    "Query and validate design tokens from a reactscope.tokens.json file"
+  const tokensCmd = new Command11("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'
   );
   registerGet2(tokensCmd);
   registerList2(tokensCmd);
@@ -6636,8 +6865,12 @@ function createTokensCommand() {
 
 // src/program.ts
 function createProgram(options = {}) {
-  const program2 = new Command11("scope").version(options.version ?? "0.1.0").description("Scope \u2014 React instrumentation toolkit");
-  program2.command("capture <url>").description("Capture a React component tree from a live URL and output as JSON").option("-o, --output <path>", "Write JSON to file instead of stdout").option("--pretty", "Pretty-print JSON output (default: minified)", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
+  const program2 = new Command12("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.'
+  );
+  program2.command("capture <url>").description(
+    "Capture the live React component tree from a running app and emit it as JSON.\nRequires a running dev server at the given URL (e.g. http://localhost:5173).\n\nExamples:\n  scope capture http://localhost:5173\n  scope capture http://localhost:5173 -o report.json --pretty\n  scope capture http://localhost:5173 --timeout 15000 --wait 500"
+  ).option("-o, --output <path>", "Write JSON to file instead of stdout").option("--pretty", "Pretty-print JSON output (default: minified)", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
         const { report } = await browserCapture({
@@ -6661,7 +6894,9 @@ function createProgram(options = {}) {
       }
     }
   );
-  program2.command("tree <url>").description("Display the React component tree from a live URL").option("--depth <n>", "Max depth to display (default: unlimited)").option("--show-props", "Include prop names next to components", false).option("--show-hooks", "Show hook counts per component", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
+  program2.command("tree <url>").description(
+    "Print a formatted React component tree from a running app.\nUseful for quickly understanding component hierarchy without full capture.\n\nExamples:\n  scope tree http://localhost:5173\n  scope tree http://localhost:5173 --show-props --show-hooks\n  scope tree http://localhost:5173 --depth 4"
+  ).option("--depth <n>", "Max depth to display (default: unlimited)").option("--show-props", "Include prop names next to components", false).option("--show-hooks", "Show hook counts per component", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
         const { report } = await browserCapture({
@@ -6684,7 +6919,9 @@ function createProgram(options = {}) {
       }
     }
   );
-  program2.command("report <url>").description("Capture and display a human-readable summary of a React app").option("--json", "Output as structured JSON instead of human-readable text", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
+  program2.command("report <url>").description(
+    "Capture a React app and print a human-readable analysis summary.\nIncludes component count, hook usage, side-effect summary, and more.\n\nExamples:\n  scope report http://localhost:5173\n  scope report http://localhost:5173 --json\n  scope report http://localhost:5173 --json -o report.json"
+  ).option("--json", "Output as structured JSON instead of human-readable text", false).option("--timeout <ms>", "Max wait time for React to mount (ms)", "10000").option("--wait <ms>", "Additional wait after page load before capture (ms)", "0").action(
     async (url, opts) => {
       try {
         const { report } = await browserCapture({
@@ -6708,7 +6945,9 @@ function createProgram(options = {}) {
       }
     }
   );
-  program2.command("generate").description("Generate a Playwright test from a Scope trace file").argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
+  program2.command("generate").description(
+    'Generate a Playwright test file from a Scope trace (.json).\nTraces are produced by scope instrument renders or scope capture.\n\nExamples:\n  scope generate trace.json\n  scope generate trace.json -o tests/scope.spec.ts -d "User login flow"'
+  ).argument("<trace>", "Path to a serialized Scope trace (.json)").option("-o, --output <path>", "Output file path", "scope.spec.ts").option("-d, --description <text>", "Test description").action((tracePath, opts) => {
     const raw = readFileSync13(tracePath, "utf-8");
     const trace = loadTrace(raw);
     const source = generateTest(trace, {
@@ -6725,6 +6964,7 @@ function createProgram(options = {}) {
   program2.addCommand(createInitCommand());
   program2.addCommand(createCiCommand());
   program2.addCommand(createDoctorCommand());
+  program2.addCommand(createGetSkillCommand());
   const existingReportCmd = program2.commands.find((c) => c.name() === "report");
   if (existingReportCmd !== void 0) {
     registerBaselineSubCommand(existingReportCmd);