codexkit 1.0.0

package/.codex/skills/accessibility-audit/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: accessibility-audit
+description: Use when auditing UI components or pages for accessibility compliance, checking WCAG conformance, identifying keyboard navigation issues, color contrast problems, and pre-launch accessibility verification
+version: 1.0.0
+tags: [ui, code-quality]
+dependencies: []
+---
+
+# Accessibility Audit Skill
+
+## When to Use
+
+- Reviewing UI components for accessibility compliance
+- Auditing pages for WCAG conformance
+- Identifying keyboard navigation issues
+- Checking color contrast
+- Pre-launch accessibility verification
+
+## When NOT to Use
+
+- Non-UI work where accessibility isn't applicable.
+
+
+## Core Workflow
+
+### Phase 1: Visual Accessibility Analysis
+
+```
+Perform a comprehensive accessibility audit:
+
+1. COLOR CONTRAST
+   - Check text/background contrast ratios
+   - WCAG AA: 4.5:1 normal text, 3:1 large text
+   - Identify failing elements
+
+2. VISUAL HIERARCHY
+   - Heading structure (logical H1-H6)
+   - Visual grouping of related elements
+   - Touch targets (44x44px minimum)
+
+3. CONTENT ACCESSIBILITY
+   - Images needing alt text
+   - Icons without text labels
+   - Color-only information
+
+4. INTERACTIVE ELEMENTS
+   - Buttons/links with unclear purpose
+   - Form fields without labels
+   - Missing error states
+
+5. MOTION
+   - Auto-playing content
+   - Potential vestibular triggers
+
+Provide WCAG criterion references for each issue.
+```
+
+### Phase 2: Component Checklist
+
+For each interactive component:
+
+```markdown
+## Component: [Name]
+
+### Keyboard Navigation
+
+- [ ] Focusable with Tab
+- [ ] Visible focus indicator
+- [ ] Operable with Enter/Space
+- [ ] Escape closes modals
+- [ ] Arrow keys for menus
+
+### Screen Reader
+
+- [ ] Meaningful accessible name
+- [ ] Role announced correctly
+- [ ] State changes announced
+- [ ] Errors associated with inputs
+
+### Visual
+
+- [ ] 4.5:1 contrast ratio (text)
+- [ ] 3:1 contrast ratio (UI)
+- [ ] 44x44px touch targets
+- [ ] No color-only information
+
+### Motion
+
+- [ ] Respects prefers-reduced-motion
+- [ ] No auto-play >5 seconds
+```
+
+## WCAG Quick Reference
+
+### Level A (Minimum)
+
+| Criterion | Description            | Fix               |
+| --------- | ---------------------- | ----------------- |
+| 1.1.1     | Non-text Content       | Add alt text      |
+| 1.3.1     | Info and Relationships | Use semantic HTML |
+| 2.1.1     | Keyboard               | All via keyboard  |
+| 2.4.1     | Bypass Blocks          | Skip links        |
+| 4.1.2     | Name, Role, Value      | ARIA labels       |
+
+### Level AA (Recommended)
+
+| Criterion | Description   | Fix                    |
+| --------- | ------------- | ---------------------- |
+| 1.4.3     | Contrast      | 4.5:1 text, 3:1 UI     |
+| 1.4.4     | Resize Text   | Support 200% zoom      |
+| 2.4.6     | Headings      | Descriptive headings   |
+| 2.4.7     | Focus Visible | Clear focus indicators |
+
+## Common Fixes
+
+### Accessible Button
+
+```tsx
+// Bad
+<div onClick={handleClick}>Click me</div>
+
+// Good
+<button type="button" onClick={handleClick}>
+  Click me
+</button>
+```
+
+### Accessible Icon Button
+
+```tsx
+// Bad
+<button><Icon /></button>
+
+// Good
+<button aria-label="Close dialog">
+  <Icon aria-hidden="true" />
+</button>
+```
+
+### Form with Error
+
+```tsx
+<label htmlFor="email">Email</label>
+<input
+  id="email"
+  aria-describedby="email-error"
+  aria-invalid={hasError}
+/>
+{hasError && (
+  <span id="email-error" role="alert">
+    Please enter a valid email
+  </span>
+)}
+```
+
+## Report Template
+
+```markdown
+# Accessibility Audit Report
+
+**Date:** [Date]
+**Page:** [Name]
+**WCAG Level:** AA
+
+## Summary
+
+- Critical Issues: X
+- Major Issues: X
+- Minor Issues: X
+
+## Issues
+
+### [Issue Title]
+
+- **Severity:** Critical/Major/Minor
+- **WCAG:** [X.X.X]
+- **Element:** [selector]
+- **Issue:** [Description]
+- **Fix:** [Recommendation]
+```
+
+## Storage
+
+Save audit reports to `.codex/memory/design/accessibility/`
+
+## Related Skills
+
+| Need           | Skill             |
+| -------------- | ----------------- |
+| Design quality | `frontend-design` |
+| UI research    | `ui-ux-research`  |

package/.codex/skills/agent-browser/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: agent-browser
+description: Browser automation CLI for AI agents using Playwright
+version: 1.0.0
+tags: [automation, mcp]
+dependencies: []
+---
+
+# agent-browser
+
+## When to Use
+
+- When you need Playwright-based browser automation via the agent-browser CLI.
+
+## When NOT to Use
+
+- When MCP-based browser control is required instead of a CLI workflow.
+
+
+## Installation
+
+```bash
+npm install -g agent-browser
+agent-browser install  # Download Chromium
+```
+
+Linux: `agent-browser install --with-deps`
+
+## Architecture
+
+- **Rust CLI** (fast native binary) parses commands, communicates with daemon
+- **Node.js daemon** manages Playwright browser instance, persists between commands
+- Daemon auto-starts on first command, stays alive for fast subsequent ops
+- Each session has own daemon process + Unix socket (or TCP on Windows)
+
+## Core Workflow
+
+1. **Open page**: `agent-browser open <url>`
+2. **Get snapshot**: `agent-browser snapshot -i` (interactive elements only)
+3. **Use refs**: `agent-browser click @e2` / `agent-browser fill @e3 "text"`
+4. **Repeat snapshot** after page changes
+
+## Refs (Primary Selection Method)
+
+Snapshot generates ARIA accessibility tree with `[ref=eN]` tags. Refs map to `getByRole()` locators internally.
+
+```bash
+agent-browser snapshot
+# - heading "Example Domain" [ref=e1] [level=1]
+# - button "Submit" [ref=e2]
+# - textbox "Email" [ref=e3]
+# - link "Learn more" [ref=e4]
+
+agent-browser click @e2           # Click button
+agent-browser fill @e3 "test@example.com"
+agent-browser get text @e1        # Get heading text
+```
+
+Ref syntax: `@e1`, `e1`, or `ref=e1` all work.
+
+**Why refs?**
+
+- Deterministic: points to exact element from snapshot
+- Fast: no DOM re-query, uses cached role/name locator
+- AI-friendly: snapshot + ref workflow optimal for LLMs
+
+### Interactive Roles (get refs automatically)
+
+`button`, `link`, `textbox`, `checkbox`, `radio`, `combobox`, `listbox`, `menuitem`, `option`, `searchbox`, `slider`, `spinbutton`, `switch`, `tab`, `treeitem`
+
+### Content Roles (get refs when named)
+
+`heading`, `cell`, `gridcell`, `columnheader`, `rowheader`, `listitem`, `article`, `region`, `main`, `navigation`
+
+## Commands
+
+### Navigation
+
+```bash
+agent-browser open <url>          # Auto-prepends https:// if needed
+agent-browser back
+agent-browser forward
+agent-browser reload
+agent-browser close               # Closes browser + daemon
+```
+
+### Interaction
+
+```bash
+agent-browser click <sel>         # Left click
+agent-browser dblclick <sel>      # Double click
+agent-browser fill <sel> <text>   # Clear field + set value (atomic)
+agent-browser type <sel> <text>   # Type character by character (preserves existing)
+agent-browser press <key>         # Key press: Enter, Tab, Control+a, Shift+Tab
+agent-browser keydown <key>       # Hold key down
+agent-browser keyup <key>         # Release key
+agent-browser hover <sel>
+agent-browser focus <sel>
+agent-browser select <sel> <val>  # Select dropdown option by value
+agent-browser check <sel>         # Check checkbox
+agent-browser uncheck <sel>       # Uncheck checkbox
+agent-browser scroll up|down|left|right [px]  # Default 300px
+agent-browser scrollintoview <sel>
+agent-browser drag <src> <tgt>    # Drag and drop
+agent-browser upload <sel> <file1> [file2...]
+```
+
+### Get Info
+
+```bash
+agent-browser get text <sel>      # textContent
+agent-browser get html <sel>      # innerHTML
+agent-browser get value <sel>     # input value
+agent-browser get attr <sel> <attr>
+agent-browser get title
+agent-browser get url
+agent-browser get count <sel>     # Number of matching elements
+agent-browser get box <sel>       # Bounding box {x,y,width,height}
+```
+
+### Check State
+
+```bash
+agent-browser is visible <sel>
+agent-browser is enabled <sel>
+agent-browser is checked <sel>
+```
+
+### Snapshot Options
+
+```bash
+agent-browser snapshot            # Full accessibility tree
+agent-browser snapshot -i         # Interactive elements only (buttons, inputs, links)
+agent-browser snapshot -c         # Compact (remove empty structural elements)
+agent-browser snapshot -d 3       # Limit depth to 3 levels
+agent-browser snapshot -s "#main" # Scope to CSS selector
+agent-browser snapshot -i -c -d 5 # Combine options
+```
+
+### Screenshots & PDF
+
+```bash
+agent-browser screenshot [path]   # PNG to stdout (base64) or file
+agent-browser screenshot --full   # Full page screenshot
+agent-browser screenshot -f page.png
+agent-browser pdf <path>          # Save as PDF (format: Letter, A4, etc)
+```
+
+### Wait
+
+```bash
+agent-browser wait <selector>     # Wait for element visible
+agent-browser wait <ms>           # Wait for time (numeric = milliseconds)
+agent-browser wait --text "Welcome"
+agent-browser wait --url "**/dashboard"
+agent-browser wait --load networkidle  # load | domcontentloaded | networkidle
+agent-browser wait --fn "window.ready === true"  # Wait for JS condition
+```
+
+### Find (Semantic Locators)
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find placeholder "Search" fill "query"
+agent-browser find alt "Logo" click        # By alt text
+agent-browser find title "Close" click     # By title attribute
+agent-browser find testid "submit-btn" click
+agent-browser find first ".item" click     # First match
+agent-browser find last ".item" click      # Last match
+agent-browser find nth 2 "a" text          # Nth match (0-indexed)
+```
+
+Actions: `click`, `fill`, `check`, `hover`, `text`
+
+### Sessions (Isolated Browser Instances)
+
+```bash
+agent-browser --session agent1 open site-a.com
+agent-browser --session agent2 open site-b.com
+AGENT_BROWSER_SESSION=agent1 agent-browser click @e2
+
+agent-browser session list        # List active sessions
+agent-browser session             # Show current session
+```
+
+Each session has: own browser, cookies/storage, navigation history, auth state.
+
+### Storage & Cookies
+
+```bash
+agent-browser cookies             # Get all cookies
+agent-browser cookies set <name> <val>
+agent-browser cookies clear
+
+agent-browser storage local       # Get all localStorage
+agent-browser storage local <key> # Get specific key
+agent-browser storage local set <k> <v>
+agent-browser storage local clear
+agent-browser storage session     # Same for sessionStorage
+```
+
+### Tabs & Windows
+
+```bash
+agent-browser tab                 # List tabs
+agent-browser tab new [url]       # New tab
+agent-browser tab <n>             # Switch to tab n
+agent-browser tab close [n]       # Close tab
+agent-browser window new          # New window (new context)
+```
+
+### Frames
+
+```bash
+agent-browser frame <sel>         # Switch to iframe by selector
+agent-browser frame main          # Back to main frame
+```
+
+### Dialogs (alert/confirm/prompt)
+
+```bash
+agent-browser dialog accept [text]  # Accept (with optional prompt text)
+agent-browser dialog dismiss        # Dismiss
+```
+
+### Network Interception
+
+```bash
+agent-browser network route <url>              # Intercept requests
+agent-browser network route <url> --abort      # Block requests
+agent-browser network route <url> --body '{"mock":true}'  # Mock response
+agent-browser network unroute [url]            # Remove routes
+agent-browser network requests                 # View tracked requests
+agent-browser network requests --filter api    # Filter by URL pattern
+```
+
+### Browser Settings
+
+```bash
+agent-browser set viewport <w> <h>
+agent-browser set device "iPhone 14"   # Emulate device
+agent-browser set geo <lat> <lng>      # Geolocation
+agent-browser set offline [on|off]     # Toggle offline mode
+agent-browser set media dark|light     # Color scheme
+agent-browser set credentials <u> <p>  # HTTP basic auth
+agent-browser set headers '{"X-Custom":"value"}'
+```
+
+### Debug & Tracing
+
+```bash
+agent-browser --headed open <url>   # Show browser window (not headless)
+agent-browser console               # View console messages
+agent-browser console --clear       # Clear console
+agent-browser errors                # View page errors
+agent-browser errors --clear
+agent-browser highlight <sel>       # Highlight element visually
+agent-browser eval <js>             # Run JavaScript, returns result
+agent-browser trace start [path]    # Start recording trace
+agent-browser trace stop [path]     # Stop and save trace
+```
+
+### Auth State Persistence
+
+```bash
+agent-browser state save auth.json  # Save cookies, localStorage, sessionStorage
+agent-browser state load auth.json  # Load at next launch (must be at browser start)
+```
+
+### Mouse Control
+
+```bash
+agent-browser mouse move <x> <y>    # Move to coordinates
+agent-browser mouse down [button]   # left|right|middle
+agent-browser mouse up [button]
+agent-browser mouse wheel <dy> [dx] # Scroll wheel
+```
+
+## Options
+
+| Option             | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `--session <name>` | Isolated session (or `AGENT_BROWSER_SESSION` env) |
+| `--json`           | JSON output (for parsing)                         |
+| `--full, -f`       | Full page screenshot                              |
+| `--headed`         | Show browser window                               |
+| `--name, -n`       | Locator name filter                               |
+| `--exact`          | Exact text match                                  |
+| `--debug`          | Debug output                                      |
+
+## Selector Types
+
+1. **Refs** (preferred): `@e1`, `@e2` from snapshot
+2. **CSS**: `#id`, `.class`, `div > button`
+3. **Text**: `text=Submit`
+4. **XPath**: `xpath=//button`
+
+## JSON Output Format
+
+```bash
+agent-browser snapshot --json
+# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}
+
+agent-browser get text @e1 --json
+# {"success":true,"data":{"text":"Hello World"}}
+
+agent-browser is visible @e2 --json
+# {"success":true,"data":{"visible":true}}
+```
+
+## Patterns
+
+### Login Flow
+
+```bash
+agent-browser open https://example.com/login
+agent-browser snapshot -i
+# Identify refs for username, password, submit
+agent-browser fill @e2 "username"
+agent-browser fill @e3 "password"
+agent-browser click @e4
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json  # Persist auth for later
+```
+
+### Form Submission
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i --json
+# Parse refs from JSON response
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser select @e3 "option-value"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --text "Success"
+```
+
+### Scraping Data
+
+```bash
+agent-browser open https://example.com/data
+agent-browser snapshot
+agent-browser get text @e1
+agent-browser get attr @e2 "href"
+agent-browser eval "document.querySelectorAll('.item').length"
+agent-browser eval "JSON.stringify([...document.querySelectorAll('.price')].map(e => e.textContent))"
+```
+
+### Multi-page Navigation
+
+```bash
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e3  # Navigate to new page
+agent-browser wait --load networkidle
+agent-browser snapshot -i  # Fresh snapshot for new page
+```
+
+### Parallel Browser Sessions
+
+```bash
+# Terminal 1
+agent-browser --session scraper1 open https://site-a.com
+agent-browser --session scraper1 snapshot -i
+
+# Terminal 2
+agent-browser --session scraper2 open https://site-b.com
+agent-browser --session scraper2 snapshot -i
+```
+
+### Mock API Response
+
+```bash
+agent-browser network route "**/api/users" --body '[{"id":1,"name":"Mock User"}]'
+agent-browser open https://example.com  # App sees mocked data
+agent-browser network unroute "**/api/users"
+```
+
+### Handle File Downloads
+
+```bash
+agent-browser open https://example.com/downloads
+agent-browser snapshot -i
+agent-browser click @e2  # Download button
+# Download handled automatically, saved to suggested filename
+```
+
+## Anti-Patterns
+
+- **Don't use CSS selectors when refs available** - refs from snapshot are deterministic
+- **Don't skip snapshot after page changes** - refs become stale after navigation
+- **Don't use `type` when `fill` works** - `fill` atomically clears + sets, `type` appends
+- **Don't hardcode wait times** - use semantic waits (`--text`, `--url`, `--load`, `--fn`)
+- **Don't use `--headed` in automation** - only for debugging
+- **Don't call `state load` after browser started** - must be at launch time
+
+## Timeouts
+
+Default timeout: 10 seconds (Playwright default is 30s). Commands will fail after timeout if element not found or condition not met.
+
+## Browser Support
+
+| Platform    | Binary      | Fallback |
+| ----------- | ----------- | -------- |
+| macOS ARM64 | Native Rust | Node.js  |
+| macOS x64   | Native Rust | Node.js  |
+| Linux ARM64 | Native Rust | Node.js  |
+| Linux x64   | Native Rust | Node.js  |
+| Windows     | -           | Node.js  |