real-prototypes-skill 0.1.0

package/.claude/skills/real-prototypes-skill/docs/TROUBLESHOOTING.md

@@ -0,0 +1,278 @@
+# Troubleshooting Guide
+
+Common issues and solutions for the real-prototypes-skill capture system.
+
+## Authentication Issues
+
+### "Authentication failed - still on login page"
+
+**Possible causes:**
+1. Incorrect credentials
+2. CAPTCHA or 2FA required
+3. Form selectors not matching
+4. Account locked or needs verification
+
+**Solutions:**
+
+1. **Verify credentials**
+   ```bash
+   # Check environment variables are set
+   echo $PLATFORM_EMAIL
+   echo $PLATFORM_PASSWORD
+   ```
+
+2. **Use explicit CSS selectors** in your config:
+   ```json
+   {
+     "auth": {
+       "credentials": {
+         "emailSelector": "#email",
+         "passwordSelector": "#password",
+         "submitSelector": "button[type='submit']"
+       }
+     }
+   }
+   ```
+
+3. **Run with headed browser** to see what's happening:
+   ```bash
+   agent-browser open https://your-platform.com/login --headed
+   agent-browser snapshot -i
+   ```
+
+4. **Check for CAPTCHA** - If present, you may need to use interactive mode or pre-authenticate manually.
+
+### "Could not find email/username field"
+
+**Cause:** The capture engine couldn't identify the email field in the login form.
+
+**Solutions:**
+
+1. **Inspect the login page** to find correct selectors:
+   ```bash
+   agent-browser open https://your-platform.com/login
+   agent-browser snapshot -i
+   ```
+
+2. **Use explicit selector**:
+   ```json
+   {
+     "auth": {
+       "credentials": {
+         "emailSelector": "input[name='username']"
+       }
+     }
+   }
+   ```
+
+3. **Common selector patterns**:
+   - `#email`, `#username`, `#login-email`
+   - `[name='email']`, `[name='username']`
+   - `[type='email']`
+   - `[placeholder*='email']`
+
+### "strict mode violation: getByText resolved to 2 elements"
+
+**Cause:** Multiple elements have the same text (e.g., "Sign in" appears twice).
+
+**Solution:** Use CSS selector instead of text-based matching:
+```json
+{
+  "auth": {
+    "credentials": {
+      "submitSelector": "form button[type='submit']"
+    }
+  }
+}
+```
+
+## Capture Issues
+
+### "No pages discovered"
+
+**Possible causes:**
+1. Authentication failed silently
+2. Starting page has no links
+3. All links are excluded
+
+**Solutions:**
+
+1. **Check authentication** worked:
+   ```bash
+   agent-browser get url  # Should not be login page
+   ```
+
+2. **Use manual mode** with explicit pages:
+   ```json
+   {
+     "capture": {
+       "mode": "manual",
+       "include": ["/dashboard", "/settings", "/accounts"]
+     }
+   }
+   ```
+
+3. **Verify exclusion patterns** aren't too broad:
+   ```json
+   {
+     "capture": {
+       "exclude": ["/logout"]  // Don't exclude too much
+     }
+   }
+   ```
+
+### "Failed to capture [page]: timeout"
+
+**Cause:** Page took too long to load or element wasn't found.
+
+**Solutions:**
+
+1. **Increase wait times**:
+   ```json
+   {
+     "capture": {
+       "waitAfterLoad": 5000,
+       "waitAfterInteraction": 2000
+     }
+   }
+   ```
+
+2. **Check for slow-loading content** (SPAs, infinite scroll)
+
+3. **Reduce maximum pages** to prevent timeout accumulation
+
+### "Screenshots missing or corrupt"
+
+**Possible causes:**
+1. Disk full
+2. Permission issues
+3. Path too long (Windows)
+
+**Solutions:**
+
+1. Check disk space
+2. Verify output directory is writable:
+   ```bash
+   mkdir -p ./references/screenshots
+   touch ./references/screenshots/test.txt
+   ```
+
+## Validation Failures
+
+### "Page entries missing 'name' field"
+
+**Cause:** The manifest.json has malformed page entries.
+
+**Solution:** Regenerate the manifest by running capture again. Each page needs:
+```json
+{
+  "name": "page-name",
+  "url": "/path",
+  "screenshot": "screenshots/page-name-desktop.png"
+}
+```
+
+### "Minimum pages not met"
+
+**Cause:** Fewer than 5 pages were captured (default minimum).
+
+**Solutions:**
+
+1. **Check authentication** - may have failed silently
+2. **Use hybrid mode** to include specific pages:
+   ```json
+   {
+     "capture": {
+       "mode": "hybrid",
+       "include": ["/dashboard", "/settings", "/profile", "/accounts", "/contacts"]
+     }
+   }
+   ```
+3. **Lower the threshold** (not recommended for production):
+   ```json
+   {
+     "validation": {
+       "minPages": 3
+     }
+   }
+   ```
+
+### "Insufficient colors extracted"
+
+**Cause:** HTML capture didn't find enough color values.
+
+**Solutions:**
+
+1. **Ensure HTML capture is enabled**:
+   ```json
+   {
+     "output": {
+       "html": true
+     }
+   }
+   ```
+
+2. **Check that pages have actual content** (not just loading spinners)
+
+3. **Manually create design-tokens.json** based on the platform's style guide
+
+### "Default Tailwind colors found in prototype"
+
+**Cause:** Generated code uses colors like `bg-blue-500` instead of custom colors.
+
+**Solution:** Update the prototype to use only colors from design-tokens.json:
+```jsx
+// Bad
+<button className="bg-blue-500">
+
+// Good
+<button style={{ backgroundColor: '#1a73e8' }}>
+
+// Or define custom colors in tailwind.config.js
+```
+
+## Browser Issues
+
+### "agent-browser command not found"
+
+**Solution:** Install the agent-browser-skill:
+```bash
+npm install -g agent-browser
+# or
+npx agent-browser open https://example.com
+```
+
+### "Browser window doesn't open"
+
+**Cause:** Running in headless mode by default.
+
+**Solution:** Use `--headed` flag for debugging:
+```bash
+agent-browser open https://example.com --headed
+```
+
+### "Failed to read: Resource temporarily unavailable"
+
+**Cause:** Another process is using the browser or system resources.
+
+**Solutions:**
+1. Close other browser automation processes
+2. Restart and try again
+3. Check system memory usage
+
+## Getting Help
+
+If you're still stuck:
+
+1. **Enable verbose logging** by examining the snapshot:
+   ```bash
+   agent-browser snapshot -i > debug-snapshot.txt
+   ```
+
+2. **Check the agent-browser skill documentation** for command options
+
+3. **File an issue** with:
+   - Config file (redact credentials)
+   - Error message
+   - Platform URL (if public)
+   - Browser snapshot output

package/.claude/skills/real-prototypes-skill/docs/schemas/capture-config.md

@@ -0,0 +1,167 @@
+# Capture Configuration Schema
+
+The capture configuration file defines how the platform capture engine discovers, authenticates, and captures pages from a target platform.
+
+## Complete Example
+
+```json
+{
+  "platform": {
+    "name": "My Platform",
+    "baseUrl": "https://app.example.com"
+  },
+  "auth": {
+    "type": "form",
+    "loginUrl": "/login",
+    "credentials": {
+      "emailField": "Email",
+      "emailSelector": "#email",
+      "passwordField": "Password",
+      "passwordSelector": "#password",
+      "submitButton": "Sign in",
+      "submitSelector": "button[type='submit']"
+    },
+    "successUrl": "/dashboard",
+    "waitAfterLogin": 3000
+  },
+  "capture": {
+    "mode": "auto",
+    "maxPages": 100,
+    "maxDepth": 5,
+    "viewports": [
+      { "name": "desktop", "width": 1920, "height": 1080 },
+      { "name": "tablet", "width": 768, "height": 1024 },
+      { "name": "mobile", "width": 375, "height": 812 }
+    ],
+    "interactions": {
+      "clickButtons": true,
+      "clickDropdowns": true,
+      "clickTabs": true,
+      "clickTableRows": true,
+      "clickModals": true
+    },
+    "include": ["/settings", "/profile"],
+    "exclude": ["/logout", "/signout", "/delete"],
+    "waitAfterLoad": 2000,
+    "waitAfterInteraction": 1000
+  },
+  "output": {
+    "directory": "./references",
+    "screenshots": true,
+    "html": true,
+    "designTokens": true
+  },
+  "validation": {
+    "minPages": 5,
+    "minColors": 10,
+    "requireDetailPages": true,
+    "requireAllTabs": true
+  }
+}
+```
+
+## Schema Reference
+
+### `platform` (required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Human-readable name of the platform |
+| `baseUrl` | string | Yes | Base URL of the platform (e.g., `https://app.example.com`) |
+
+### `auth`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `type` | string | No | `"form"` | Authentication type: `"form"`, `"none"`, or `"oauth"` |
+| `loginUrl` | string | No | `"/login"` | Path to the login page |
+| `credentials` | object | No | - | Login form configuration (see below) |
+| `successUrl` | string | No | - | URL pattern to verify successful login |
+| `waitAfterLogin` | number | No | `3000` | Milliseconds to wait after login attempt |
+
+#### `auth.credentials`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `emailField` | string | Label text for email/username field (e.g., `"Email"`) |
+| `emailSelector` | string | CSS selector for email field (e.g., `"#email"`, `"[name='email']"`) |
+| `passwordField` | string | Label text for password field |
+| `passwordSelector` | string | CSS selector for password field |
+| `submitButton` | string | Text on submit button (e.g., `"Sign in"`) |
+| `submitSelector` | string | CSS selector for submit button |
+
+**Note:** You can use either `*Field` (label-based) or `*Selector` (CSS-based) fields. CSS selectors are more reliable for complex forms.
+
+### `capture`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | string | `"auto"` | `"auto"` (discover all), `"manual"` (only include list), `"hybrid"` (both) |
+| `maxPages` | number | `100` | Maximum pages to capture |
+| `maxDepth` | number | `5` | Maximum link depth to follow |
+| `viewports` | array | Desktop only | List of viewport configurations |
+| `interactions` | object | All true | Which interactive elements to capture |
+| `include` | array | `[]` | URL paths to always include (for manual/hybrid mode) |
+| `exclude` | array | Common logout paths | URL patterns to skip |
+| `waitAfterLoad` | number | `2000` | Ms to wait after page load |
+| `waitAfterInteraction` | number | `1000` | Ms to wait after clicking elements |
+
+**Backwards compatibility:** `manualPages` is accepted as an alias for `include`.
+
+#### `capture.viewports[]`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Viewport name (used in filename) |
+| `width` | number | Yes | Viewport width in pixels |
+| `height` | number | Yes | Viewport height in pixels |
+
+#### `capture.interactions`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `clickButtons` | boolean | `true` | Capture button click states |
+| `clickDropdowns` | boolean | `true` | Open and capture dropdowns |
+| `clickTabs` | boolean | `true` | Click through tab interfaces |
+| `clickTableRows` | boolean | `true` | Click table rows to discover detail pages |
+| `clickModals` | boolean | `true` | Open and capture modals |
+
+### `output`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `directory` | string | `"./references"` | Output directory for captured assets |
+| `screenshots` | boolean | `true` | Capture PNG screenshots |
+| `html` | boolean | `true` | Capture raw HTML |
+| `designTokens` | boolean | `true` | Extract design tokens (colors, fonts) |
+
+### `validation`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `minPages` | number | `5` | Minimum pages required for valid capture |
+| `minColors` | number | `10` | Minimum colors to extract |
+| `requireDetailPages` | boolean | `true` | Require detail pages for list views |
+| `requireAllTabs` | boolean | `true` | Require all tabs to be captured |
+
+## Environment Variables
+
+Credentials can be provided via environment variables instead of config:
+
+```bash
+export PLATFORM_EMAIL=user@example.com
+export PLATFORM_PASSWORD=secretpassword
+```
+
+These override any values in the config file.
+
+## Selector Strategy
+
+The capture engine tries selectors in this order:
+
+1. **Explicit CSS selector** (`emailSelector`, `passwordSelector`, `submitSelector`)
+2. **Snapshot refs** (automatically detected from page structure)
+3. **Label text** (`emailField`, `passwordField`)
+4. **Common patterns** (input types, common IDs)
+
+For best results on complex forms, provide explicit CSS selectors.

package/.claude/skills/real-prototypes-skill/docs/schemas/design-tokens.md

@@ -0,0 +1,183 @@
+# Design Tokens Schema
+
+The `design-tokens.json` file contains colors, fonts, and other design values extracted from captured HTML. This file is essential for generating prototypes that match the original platform's visual design.
+
+## Complete Example
+
+```json
+{
+  "extractedAt": "2024-01-15T10:30:00.000Z",
+  "totalColorsFound": 47,
+  "colors": {
+    "primary": "#1a73e8",
+    "secondary": "#5f6368",
+    "background": {
+      "white": "#ffffff",
+      "light": "#f8f9fa",
+      "dark": "#202124"
+    },
+    "text": {
+      "primary": "#202124",
+      "secondary": "#5f6368",
+      "disabled": "#9aa0a6"
+    },
+    "border": {
+      "default": "#dadce0",
+      "focus": "#1a73e8"
+    },
+    "status": {
+      "success": "#1e8e3e",
+      "warning": "#f9ab00",
+      "error": "#d93025",
+      "info": "#1a73e8"
+    }
+  },
+  "fonts": {
+    "families": [
+      "Google Sans",
+      "Roboto",
+      "Arial",
+      "sans-serif"
+    ],
+    "primary": "Google Sans"
+  },
+  "rawColors": [
+    ["#ffffff", 245],
+    ["#1a73e8", 89],
+    ["#202124", 76],
+    ["#f8f9fa", 54],
+    ["#5f6368", 43],
+    ["#dadce0", 38],
+    ["#1e8e3e", 12],
+    ["#d93025", 8]
+  ]
+}
+```
+
+## Schema Reference
+
+### Root Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `extractedAt` | string | Yes | ISO 8601 timestamp of extraction |
+| `totalColorsFound` | number | **Yes** | Total unique colors found (used for validation) |
+| `colors` | object | Yes | Categorized color palette |
+| `fonts` | object | Yes | Font information |
+| `rawColors` | array | No | All colors sorted by frequency |
+
+### `colors`
+
+Categorized color values. All values are hex color strings (e.g., `"#1a73e8"`).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `primary` | string | Primary brand/accent color |
+| `secondary` | string | Secondary accent color |
+| `background` | object | Background colors |
+| `text` | object | Text colors |
+| `border` | object | Border colors |
+| `status` | object | Status/feedback colors |
+
+#### `colors.background`
+
+| Field | Description |
+|-------|-------------|
+| `white` | Pure white or near-white background |
+| `light` | Light gray background (cards, sections) |
+| `dark` | Dark background (dark mode, headers) |
+
+#### `colors.text`
+
+| Field | Description |
+|-------|-------------|
+| `primary` | Main body text color |
+| `secondary` | Subdued text (captions, labels) |
+| `disabled` | Disabled/placeholder text |
+
+#### `colors.border`
+
+| Field | Description |
+|-------|-------------|
+| `default` | Standard border color |
+| `focus` | Focus state border color |
+
+#### `colors.status`
+
+| Field | Description |
+|-------|-------------|
+| `success` | Success/positive actions (green) |
+| `warning` | Warning states (yellow/orange) |
+| `error` | Error/destructive actions (red) |
+| `info` | Informational messages (blue) |
+
+### `fonts`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `families` | array | List of font families found |
+| `primary` | string | Most commonly used font family |
+
+### `rawColors`
+
+Array of `[color, count]` tuples, sorted by frequency (most common first).
+
+```json
+[
+  ["#ffffff", 245],  // white appeared 245 times
+  ["#1a73e8", 89],   // primary blue appeared 89 times
+  ...
+]
+```
+
+## Validation Requirements
+
+For validation to pass:
+
+1. **`totalColorsFound` must be >= 10** (default minimum)
+2. **`colors.primary` should be identified** (warning if missing)
+3. **File must exist** at `references/design-tokens.json`
+
+## Color Categorization Logic
+
+Colors are automatically categorized based on:
+
+- **Primary**: First blue-dominant color with high frequency
+- **Background**: Colors with luminance > 0.8
+- **Text**: Colors with luminance < 0.5
+- **Status colors**: Based on RGB dominance (red=error, green=success)
+
+## Usage in Prototype Generation
+
+When generating prototypes:
+
+1. **Use ONLY colors from this file** - Never use Tailwind defaults
+2. **Reference by category** - Use `colors.primary`, `colors.text.primary`, etc.
+3. **Inline styles for custom colors** - Tailwind custom colors may not work reliably
+
+Example Tailwind config extension:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#1a73e8',
+        'text-primary': '#202124',
+        'text-secondary': '#5f6368',
+        'bg-light': '#f8f9fa',
+        // ... other colors from design-tokens.json
+      }
+    }
+  }
+}
+```
+
+Or use inline styles:
+
+```jsx
+<button style={{ backgroundColor: '#1a73e8', color: '#ffffff' }}>
+  Submit
+</button>
+```