@agent-scope/cli 1.20.0 → 1.20.1

package/README.md

@@ -8,6 +8,7 @@ CLI for Scope — capture, replay, and analyze React components from the command
 - [Quick Start](#quick-start)
 - [Commands Reference](#commands-reference)
   - [scope init](#scope-init)
+  - [scope doctor](#scope-doctor)
   - [scope capture](#scope-capture)
   - [scope tree](#scope-tree)
   - [scope report](#scope-report)
@@ -40,10 +41,12 @@ npx scope --help
 
 ```bash
 # 1. Scaffold configuration in your React project
+# Auto-detects Tailwind tokens + CSS entry file, then generates the manifest automatically
 scope init
 
-# 2. Scan your components and build the manifest
-scope manifest generate
+# 2. Validate your setup (recommended before first render)
+scope doctor --json
+scope doctor --print-fix-commands
 
 # 3. Render all components to screenshots
 scope render all
@@ -68,7 +71,9 @@ Scaffold a Scope project — creates `reactscope.config.json`, an empty `reactsc
 | `-y, --yes` | boolean | `false` | Accept all detected defaults without prompting |
 | `--force` | boolean | `false` | Overwrite existing `reactscope.config.json` |
 
-**Auto-detection:** Scope detects your framework (Next.js, Vite, Create React App, etc.), TypeScript support, and likely component file patterns before prompting.
+**Auto-detection:** Scope detects your framework (Next.js, Vite, Create React App, etc.), TypeScript support, likely component file patterns, Tailwind design tokens, and your CSS entry file (`src/index.css`, `src/styles.css`, etc.) before prompting.
+
+After scaffolding, `scope init` automatically runs `scope manifest generate` so you can start rendering immediately.
 
 **Example:**
 
@@ -98,7 +103,10 @@ scope init --force        # overwrite existing config
      /home/user/project/reactscope.tokens.json
      /home/user/project/.reactscope/
 
-   Next steps: run `scope manifest` to scan your components.
+   Scanning components...
+   Found 12 component(s) — manifest written to .reactscope/manifest.json
+
+   Next steps: run `scope render all` to generate screenshots.
 ```
 
 **Files written:**
@@ -112,6 +120,45 @@ scope init --force        # overwrite existing config
 
 ---
 
+### `scope doctor`
+
+Validate your Scope project configuration. Checks config validity, token file, globalCSS paths, manifest freshness, target-project dependencies, and Playwright Chromium availability.
+
+```bash
+scope doctor --json
+scope doctor --print-fix-commands
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--json` | boolean | `false` | Emit structured JSON (for CI integration) |
+| `--print-fix-commands` | boolean | `false` | Print deduplicated remediation commands for failing checks |
+
+**Example output:**
+
+```
+Scope Doctor
+────────────────────────────────────────
+[✓] config   reactscope.config.json valid
+[✓] tokens   Token file valid
+[!] globalCSS  No globalCSS configured — Tailwind styles won't apply to renders
+[✓] manifest Manifest present and up to date
+[✓] dependencies node_modules present
+[✓] playwright Playwright package available
+────────────────────────────────────────
+1 warning(s) — everything works but could be better
+```
+
+Exits `0` when clean (warnings are non-fatal), `1` on any error.
+
+If `dependencies` fails, run your package manager install command in the target project root (for Bun projects: `bun install`), then rerun `scope doctor --json`.
+
+If `playwright` fails, run `PLAYWRIGHT_BROWSERS_PATH=/home/user/.cache/ms-playwright bunx playwright install chromium`, then rerun `scope doctor --json` before retrying `scope render component`, `scope render all`, `scope site build`, or `scope instrument ...`.
+
+Use `scope doctor --print-fix-commands` to emit copy/paste-ready remediation commands for the current project.
+
+---
+
 ### `scope capture`
 
 Capture a React component tree from a live URL and output raw JSON.
@@ -351,10 +398,10 @@ Render a single component.
 | `--manifest <path>` | string | `.reactscope/manifest.json` | Path to manifest |
 
 ```bash
-scope render Button
-scope render Button --props '{"variant":"primary","size":"lg"}'
-scope render Button --viewport 1280x800 --format json
-scope render Button -o screenshots/button.png
+scope render component Button
+scope render component Button --props '{"variant":"primary","size":"lg"}'
+scope render component Button --viewport 1280x800 --format json
+scope render component Button -o screenshots/button.png
 ```
 
 **JSON output:**
@@ -420,6 +467,10 @@ scope render all
 scope render all --concurrency 8 --output-dir ./screenshots
 ```
 
+If a component's `.scope.tsx` file defines 2 or more scenarios, `render all` automatically runs a matrix render and merges the cells into the component's JSON output. No separate `scope render matrix` step needed.
+
+After all renders complete, `.reactscope/compliance-styles.json` is written with aggregated computed styles across every component.
+
 **Progress output (stderr):**
 
 ```