cokit-cli 1.3.0 → 1.4.0

package/docs/cokit-sync-and-maintenance-guide.md

@@ -78,7 +78,7 @@ mappings:
   ck-brainstorm:
     origin: upstream
     original: brainstorm
-    upstream_file: skills/brainstorm/SKILL.md
+    upstream_file: skills/ck-brainstorm/SKILL.md
     description: Explore solutions with trade-off analysis
 
   ck-plan:

package/docs/copilot-processing-flow.md

@@ -82,18 +82,18 @@ You are a research-first planner...
 ```
 
 **CoKit Agents (12 total):**
-- `planner` - Creates implementation plans
-- `code-reviewer` - Provides comprehensive code review
-- `debugger` - Investigates and diagnoses issues
-- `tester` - Writes and validates tests
-- `researcher` - Finds and synthesizes documentation
-- `scout` - Locates files in codebase
-- `git-manager` - Handles commits and workflows
-- `brainstormer` - Ideates solutions
-- `docs-manager` - Creates and updates documentation
-- `code-simplifier` - Refactors and simplifies code
-- `fullstack-developer` - Full-stack implementation
-- `ui-ux-designer` - UI/UX design and implementation
+- `ck-planner` - Creates implementation plans
+- `ck-code-reviewer` - Provides comprehensive code review
+- `ck-debugger` - Investigates and diagnoses issues
+- `ck-tester` - Writes and validates tests
+- `ck-researcher` - Finds and synthesizes documentation
+- `ck-scout` - Locates files in codebase
+- `ck-git-manager` - Handles commits and workflows
+- `ck-brainstormer` - Ideates solutions
+- `ck-docs-manager` - Creates and updates documentation
+- `ck-code-simplifier` - Refactors and simplifies code
+- `ck-fullstack-developer` - Full-stack implementation
+- `ck-ui-ux-designer` - UI/UX design and implementation
 
 **When to use:** Referenced by prompts to specialize execution
 
@@ -164,8 +164,8 @@ id: ck-core
 name: CoKit Core Workflows
 description: Essential agents, prompts, and skills
 items:
-  - path: agents/planner.agent.md
-  - path: agents/code-reviewer.agent.md
+  - path: agents/ck-planner.agent.md
+  - path: agents/ck-code-reviewer.agent.md
   - path: prompts/ck-plan.prompt.md
   - path: prompts/ck-code.prompt.md
   - path: skills/ck-planning/
@@ -212,4 +212,4 @@ Output: Systematic debugging solution
 
 ## One-liner
 
-> User calls **Prompt** (e.g., `/ck-fix`) → Prompt references **Agent** (e.g., `debugger`) → Agent auto-receives **Instructions** by file pattern → Agent activates **Skills** when needed → All can be bundled in **Collection** (e.g., `ck-core`).
+> User calls **Prompt** (e.g., `/ck-fix`) → Prompt references **Agent** (e.g., `ck-debugger`) → Agent auto-receives **Instructions** by file pattern → Agent activates **Skills** when needed → All can be bundled in **Collection** (e.g., `ck-core`).

package/docs/project-overview-pdr.md

@@ -11,7 +11,7 @@ Make GitHub Copilot smarter in 30 seconds via curated prompts, agents, and workf
 CoKit CLI installs pre-built resources to `~/.copilot/`:
 - **31 prompts**: CoKit (ck-*)
 - **13 agents**: brainstormer, planner, tester, code-simplifier, fullstack-developer, ui-ux-designer, project-manager, etc.
-- **30 skills**: debugging, planning, code-review, frontend-design, databases, devops, deploy, ship, security, etc.
+- **31 skills**: debugging, planning, code-review, frontend-design, databases, devops, deploy, ship, security, etc.
 - **5 collections**: bundled workflows
 
 ## Key Features

package/docs/upstream-porting-rules.md

@@ -47,6 +47,7 @@ Key things to re-check periodically:
 | `.claude/` paths | `$HOME/.copilot/` | Global config directory |
 | `~/.claude/` | `$HOME/.copilot/` | Same as above |
 | `subagent` | `agent` | Copilot terminology |
+| Unprefixed skill/agent name | `ck-` prefixed | Namespace consistency |
 
 ## 2. Command References
 
@@ -94,12 +95,12 @@ Key things to re-check periodically:
 ## 5. Agent-Specific Rules
 
 ### CoKit agents (12)
-`brainstormer`, `code-reviewer`, `code-simplifier`, `debugger`, `docs-manager`, `fullstack-developer`, `git-manager`, `planner`, `researcher`, `scout`, `tester`, `ui-ux-designer`
+`ck-brainstormer`, `ck-code-reviewer`, `ck-code-simplifier`, `ck-debugger`, `ck-docs-manager`, `ck-fullstack-developer`, `ck-git-manager`, `ck-planner`, `ck-researcher`, `ck-scout`, `ck-tester`, `ck-ui-ux-designer`
 
 ### Upstream agents that DON'T exist in CoKit
 | Upstream Agent | CoKit Replacement |
 |-----------------|-------------------|
-| `project-manager` | Direct action (describe what to do) |
+| `ck-project-manager` | Direct action (describe what to do) |
 | `journal-writer` | Remove or convert to manual journaling |
 | `mcp-manager` | Remove or use `mcp-management` skill |
 
@@ -172,7 +173,7 @@ grep -r "^name:\|^model:\|^memory:" agents/ prompts/  # Invalid frontmatter
 ## 10. Common Mistakes
 
 1. **`@agent-name`** → Use `` `agent-name` agent `` (no `@` prefix)
-2. **`project-manager` agent** → Doesn't exist, replace with direct instructions
+2. **`ck-project-manager` agent** → Doesn't exist, replace with direct instructions
 3. **Team Mode sections** → Don't port, Copilot subagents are isolated
 4. **Missing "(if available)"** → External tools need `(if available)` qualifier. Use this single flag only — never "(if installed)"
 5. **Counting variants as prompts** → Variants don't bump prompt count

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cokit-cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Make GitHub Copilot smarter in 30 seconds",
   "main": "src/index.js",
   "bin": {

package/prompts/ck-bootstrap.prompt.md

@@ -40,7 +40,7 @@ argument-hint: 'Describe your project requirements'
 
 Follow strictly these following steps:
 
-**First thing first:** check if Git has been initialized, if not, ask the user if they want to initialize it, if yes, use `git-manager` agent to initialize it.
+**First thing first:** check if Git has been initialized, if not, ask the user if they want to initialize it, if yes, use `ck-git-manager` agent to initialize it.
 
 ### Fullfill the request
 
@@ -50,19 +50,19 @@ Follow strictly these following steps:
 
 ### Research
 
-* Use multiple `researcher` agents in parallel to explore the user's request, idea validation, challenges, and find the best possible solutions.
+* Use multiple `ck-researcher` agents in parallel to explore the user's request, idea validation, challenges, and find the best possible solutions.
 * Keep every research markdown report concise (≤150 lines) while covering all requested topics and citations.
 
 ### Tech Stack
 
 1. Ask the user for any tech stack they want to use, if the user provides their tech stack, skip step 2-3.
-2. Use `planner` agent and multiple `researcher` agents in parallel to find a best fit tech stack for this project, keeping research reports within the ≤150 lines limit.
+2. Use `ck-planner` agent and multiple `ck-researcher` agents in parallel to find a best fit tech stack for this project, keeping research reports within the ≤150 lines limit.
 3. Ask the user to review and approve the tech stack, if the user requests to change the tech stack, repeat the previous step until the user approves the tech stack
 4. Write the tech stack down in `./docs` directory
 
 ### Planning
 
-* Use `planner` agent to create a detailed implementation plan following the progressive disclosure structure:
+* Use `ck-planner` agent to create a detailed implementation plan following the progressive disclosure structure:
   - Create a directory using naming pattern from `## Naming` section.
   - Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
   - For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
@@ -74,11 +74,11 @@ Follow strictly these following steps:
 ### Wireframe & Design
 
 * Ask the user if they want to create wireframes and design guidelines, if yes, continue to the next step, if no, skip to **"Implementation"** phase.
-* Use `ui-ux-designer` agent and multiple `researcher` agents in parallel to create a design plan that follows the same directory/phase structure described above, keeping related research reports within the ≤150 lines limit.
+* Use `ck-ui-ux-designer` agent and multiple `ck-researcher` agents in parallel to create a design plan that follows the same directory/phase structure described above, keeping related research reports within the ≤150 lines limit.
    - **Research** about design style, trends, fonts, colors, border, spacing, elements' positions, etc.
    - Describe details of the assets in the design so they can be generated later on.
    - **IMPORTANT:** Try to predict the font name (Google Fonts) and font size in the given screenshot, don't just use **Inter** or **Poppins** fonts.
-* Then use `ui-ux-designer` agent to create the design guidelines at `./docs/design-guidelines.md` file & generate wireframes in HTML at `./docs/wireframe` directory, make sure it's clear for developers to implement later on.
+* Then use `ck-ui-ux-designer` agent to create the design guidelines at `./docs/design-guidelines.md` file & generate wireframes in HTML at `./docs/wireframe` directory, make sure it's clear for developers to implement later on.
 * Use `agent-browser` skill to take a screenshot of the wireframes and save it at `./docs/wireframes/` directory.
 * Ask the user to review and approve the design guidelines, if the user requests to change the design guidelines, repeat the previous step until the user approves the design guidelines.
 
@@ -88,26 +88,26 @@ Follow strictly these following steps:
 ### Implementation
 
 * Use `general agent (main agent)` to implement the plan step by step, follow the implementation plan in `./plans` directory.
-* Use `ui-ux-designer` agent to implement the frontend part follow the design guidelines at `./docs/design-guidelines.md` file.
+* Use `ck-ui-ux-designer` agent to implement the frontend part follow the design guidelines at `./docs/design-guidelines.md` file.
   * Generate and verify visual assets as needed.
 * Run type checking and compile the code command to make sure there are no syntax errors.
 
 ### Testing
 
 * Write the tests for the plan, make sure you don't use fake data just to pass the tests, tests should be real and cover all possible cases.
-* Use `tester` agent to run the tests, make sure it works, then report back to main agent.
-* If there are issues or failed tests, use `debugger` agent to find the root cause of the issues, then ask main agent to fix all of them and 
+* Use `ck-tester` agent to run the tests, make sure it works, then report back to main agent.
+* If there are issues or failed tests, use `ck-debugger` agent to find the root cause of the issues, then ask main agent to fix all of them and 
 * Repeat the process until all tests pass or no more issues are reported. Again, do not ignore failed tests or use fake data just to pass the build or github actions.
 
 ### Code Review
 
-* After finishing, delegate to `code-reviewer` agent to review code. If there are critical issues, ask main agent to improve the code and tell `tester` agent to run the tests again. Repeat the process until all tests pass.
+* After finishing, delegate to `ck-code-reviewer` agent to review code. If there are critical issues, ask main agent to improve the code and tell `ck-tester` agent to run the tests again. Repeat the process until all tests pass.
 * When all tests pass, code is reviewed, the tasks are completed, report back to user with a summary of the changes and explain everything briefly, ask user to review the changes and approve them.
 * **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
 
 ### Documentation
 
-* If user approves the changes, use `docs-manager` agent to update the docs if needed.
+* If user approves the changes, use `ck-docs-manager` agent to update the docs if needed.
   * Create/update `./docs/README.md` file (keep it concise, under 300 lines).
   * Create/update `./docs/codebase-summary.md` file.
   * Create/update `./docs/project-overview.-pdr.md` (Product Development Requirements) file.
@@ -124,7 +124,7 @@ Follow strictly these following steps:
 
 ### Final Report
 * Report back to user with a summary of the changes and explain everything briefly, guide user to get started and suggest the next steps.
-* Ask the user if they want to commit and push to git repository, if yes, use `git-manager` agent to commit and push to git repository.
+* Ask the user if they want to commit and push to git repository, if yes, use `ck-git-manager` agent to commit and push to git repository.
 - **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
 - **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
 

package/prompts/ck-cook.prompt.md

@@ -62,15 +62,15 @@ Human review required at these checkpoints (skipped with `--auto`):
 
 | Phase | Agent |
 |-------|-------|
-| Research | `researcher` agent (parallel, optional in fast) |
-| Scout | `scout` agent |
-| Plan | `planner` agent |
-| UI Work | `ui-ux-designer` agent |
-| Implement | `fullstack-developer` agent (parallel mode) |
-| Simplify | `code-simplifier` agent (post-implement) |
-| Testing | `tester`, `debugger` agents |
-| Review | `code-reviewer` agent |
-| Finalize | `docs-manager`, `git-manager` agents |
+| Research | `ck-researcher` agent (parallel, optional in fast) |
+| Scout | `ck-scout` agent |
+| Plan | `ck-planner` agent |
+| UI Work | `ck-ui-ux-designer` agent |
+| Implement | `ck-fullstack-developer` agent (parallel mode) |
+| Simplify | `ck-code-simplifier` agent (post-implement) |
+| Testing | `ck-tester`, `ck-debugger` agents |
+| Review | `ck-code-reviewer` agent |
+| Finalize | `ck-docs-manager`, `ck-git-manager` agents |
 
 ## Process
 
@@ -78,8 +78,8 @@ Human review required at these checkpoints (skipped with `--auto`):
 2. **Scout**: Use `/ck-scout` to discover relevant files
 3. **Research** (if applicable): Gather technical context
 4. **Plan**: Create or load implementation plan
-5. **Implement**: Execute plan phases (use `fullstack-developer` agent in parallel mode)
-6. **Simplify**: `code-simplifier` agent refines implemented code for clarity
+5. **Implement**: Execute plan phases (use `ck-fullstack-developer` agent in parallel mode)
+6. **Simplify**: `ck-code-simplifier` agent refines implemented code for clarity
 7. **Test**: Run tests and validate
 8. **Review**: Code review with quality gates
 9. **Finalize**: Update docs, commit changes

package/prompts/ck-fix-fast.prompt.md

@@ -28,7 +28,7 @@ If user chooses "Switch to /ck-fix", run `/ck-fix ${input}` immediately — do N
 <issues>${input}</issues>
 
 ## Workflow
-1. Activate `debug` and `problem-solving` skills to find the root cause.
+1. Activate `ck-debug` and `ck-problem-solving` skills to find the root cause.
 2. Implement the fix.
 3. Test the fix and make sure it works.
 4. If there are issues or failed tests, repeat from step 1.

package/prompts/ck-fix-hard.prompt.md

@@ -36,8 +36,8 @@ If user chooses "Switch to /ck-fix", run  immediately — do NOT ask user to re-
 
 ### Fix the issue
 
-Use `sequential-thinking` skill to break complex problems into sequential thought steps.
-Use `problem-solving` skills to tackle the issues.
+Use `ck-sequential-thinking` skill to break complex problems into sequential thought steps.
+Use `ck-problem-solving` skills to tackle the issues.
 
 1. Investigate and find the root cause of the issues.
 2. Research about the root causes on the internet (if needed).

package/prompts/ck-plan-fast.prompt.md

@@ -39,7 +39,7 @@ Check the `## Plan Context` section in the injected context:
 - If "Plan: none" → Create new plan using naming from `## Naming` section.
 
 ## Workflow
-Use `planner` agent to:
+Use `ck-planner` agent to:
 1. If creating new: Create directory using `Plan dir:` from `## Naming` section, then run `node $HOME/.copilot/scripts/set-active-plan.cjs {plan-dir}`
    If reusing: Use the active plan path from Plan Context.
    Make sure you pass the directory path to every agent during the process.

package/prompts/ck-plan-hard.prompt.md

@@ -44,12 +44,12 @@ Check the `## Plan Context` section in the injected context:
    If reusing: Use the active plan path from Plan Context.
    Make sure you pass the directory path to every agent during the process.
 2. Follow strictly to the "Plan Creation & Organization" rules of `planning` skill.
-3. Use multiple `researcher` agents (max 2 agents) in parallel to research for this task:
+3. Use multiple `ck-researcher` agents (max 2 agents) in parallel to research for this task:
    Each agent research for a different aspect of the task and are allowed to perform max 5 tool calls.
 4. Analyze the codebase by reading `codebase-summary.md`, `code-standards.md`, `system-architecture.md` and `project-overview-pdr.md` file.
    **ONLY PERFORM THIS FOLLOWING STEP IF `codebase-summary.md` is not available or older than 3 days**: Use `/scout <instructions>` slash command to search the codebase for files needed to complete the task.
-5. Main agent gathers all research and scout report filepaths, and pass them to `planner` agent with the prompt to create an implementation plan of this task.
-6. Main agent receives the implementation plan from `planner` agent, and ask user to review the plan
+5. Main agent gathers all research and scout report filepaths, and pass them to `ck-planner` agent with the prompt to create an implementation plan of this task.
+6. Main agent receives the implementation plan from `ck-planner` agent, and ask user to review the plan
 
 ## Post-Plan Validation (Optional)
 

package/prompts/ck-plan-red-team.prompt.md

@@ -69,7 +69,7 @@ Available lenses (select per Step 2):
 
 ### Step 4: Spawn Reviewers
 
-Launch reviewers simultaneously using `code-reviewer` agents in parallel.
+Launch reviewers simultaneously using `ck-code-reviewer` agents in parallel.
 
 **Each reviewer prompt MUST include:**
 1. This override: `"IGNORE your default code-review instructions. You are reviewing a PLAN DOCUMENT, not code. There is no code to lint, build, or test. Focus exclusively on plan quality."`

package/prompts/ck-review.prompt.md

@@ -21,26 +21,26 @@ Think harder to scan the codebase and analyze it follow the Orchestration Protoc
 
 ### Research
 
-* Use 2 `researcher` agents in parallel to search up to max 5 sources for the user's request, idea validation, best practices, challenges, and find the best possible solutions.
+* Use 2 `ck-researcher` agents in parallel to search up to max 5 sources for the user's request, idea validation, best practices, challenges, and find the best possible solutions.
 * Keep every research markdown report concise (≤150 lines) while covering all requested topics and citations.
 * Use `/ck-scout` slash command to search the codebase for files needed to complete the task
 
 ### Code Review
 
-* After finishing, use multiple `code-reviewer` agents in parallel to review code. 
+* After finishing, use multiple `ck-code-reviewer` agents in parallel to review code. 
 * If there are any issues, duplicate code, or security vulnerabilities, ask main agent to improve the code and repeat the "Testing" process until all tests pass. 
 * When all tests pass, code is reviewed, the tasks are completed, report back to user with a summary of the changes and explain everything briefly, ask user to review the changes and approve them.
 * **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
 
 ### Plan
-* Use `planner` agent to analyze reports from `researcher` and `scout` agents to create an improvement plan following the progressive disclosure structure:
+* Use `ck-planner` agent to analyze reports from `ck-researcher` and `ck-scout` agents to create an improvement plan following the progressive disclosure structure:
   - Create a directory using naming pattern from `## Naming` section.
   - Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
   - For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
 
 ### Final Report
 * Report back to user with a summary of the changes and explain everything briefly, guide user to get started and suggest the next steps.
-* Ask the user if they want to commit and push to git repository, if yes, use `git-manager` agent to commit and push to git repository.
+* Ask the user if they want to commit and push to git repository, if yes, use `ck-git-manager` agent to commit and push to git repository.
 
 **REMEMBER**:
 - Always verify generated assets meet design requirements before proceeding.

package/prompts/ck-test.prompt.md

@@ -4,7 +4,7 @@ description: 'Run tests locally and analyze the summary report'
 tools: ['execute/runInTerminal', 'execute/getTerminalOutput', 'execute/runTests', 'execute/testFailure', 'read/problems']
 ---
 
-Use the `tester` agent to run tests locally and analyze the summary report.
+Use the `ck-tester` agent to run tests locally and analyze the summary report.
 
 **IMPORTANT**: **Do not** start implementing.
 

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

@@ -0,0 +1,294 @@
+---
+name: ck-agent-browser
+description: AI-optimized browser automation CLI with context-efficient snapshots. Use for long autonomous sessions, self-verifying workflows, video recording, and cloud browser testing (Browserbase).
+license: Apache-2.0
+argument-hint: "[url or task]"
+---
+
+# agent-browser Skill
+
+Browser automation CLI designed for AI agents. Uses "snapshot + refs" paradigm for 93% less context than Playwright MCP.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g agent-browser
+
+# Download Chromium (one-time)
+agent-browser install
+
+# Linux: include system deps
+agent-browser install --with-deps
+
+# Verify
+agent-browser --version
+```
+
+## Core Workflow
+
+The 4-step pattern for all browser automation:
+
+```bash
+# 1. Navigate
+agent-browser open https://example.com
+
+# 2. Snapshot (get interactive elements with refs)
+agent-browser snapshot -i
+# Output: button "Sign In" @e1, textbox "Email" @e2, ...
+
+# 3. Interact using refs
+agent-browser fill @e2 "user@example.com"
+agent-browser click @e1
+
+# 4. Re-snapshot after page changes
+agent-browser snapshot -i
+```
+
+## When to Use (vs chrome-devtools)
+
+| Use agent-browser | Use chrome-devtools |
+|-------------------|---------------------|
+| Long autonomous AI sessions | Quick one-off screenshots |
+| Context-constrained workflows | Custom Puppeteer scripts needed |
+| Video recording for debugging | WebSocket full frame debugging |
+| Cloud browsers (Browserbase) | Existing workflow integration |
+| Multi-tab handling | Need Sharp auto-compression |
+| Self-verifying build loops | Session with auth injection |
+
+**Token efficiency:** ~280 chars/snapshot vs 8K+ for Playwright MCP.
+
+## Command Reference
+
+### Navigation
+```bash
+agent-browser open <url>       # Navigate to URL
+agent-browser back             # Go back
+agent-browser forward          # Go forward
+agent-browser reload           # Reload page
+agent-browser close            # Close browser
+```
+
+### Analysis (Snapshot)
+```bash
+agent-browser snapshot         # Full accessibility tree
+agent-browser snapshot -i      # Interactive elements only (recommended)
+agent-browser snapshot -c      # Compact output
+agent-browser snapshot -d 3    # Limit depth
+agent-browser snapshot -s "nav" # Scope to CSS selector
+```
+
+### Interactions (use @refs from snapshot)
+```bash
+agent-browser click @e1        # Click element
+agent-browser dblclick @e1     # Double-click
+agent-browser fill @e2 "text"  # Clear and fill input
+agent-browser type @e2 "text"  # Type without clearing
+agent-browser press Enter      # Press key
+agent-browser hover @e1        # Hover over element
+agent-browser check @e3        # Check checkbox
+agent-browser uncheck @e3      # Uncheck checkbox
+agent-browser select @e4 "opt" # Select dropdown option
+agent-browser scroll @e1       # Scroll element into view
+agent-browser scroll down 500  # Scroll page by pixels
+agent-browser drag @e1 @e2     # Drag from e1 to e2
+agent-browser upload @e5 file.pdf  # Upload file
+```
+
+### Information Retrieval
+```bash
+agent-browser get text @e1     # Get text content
+agent-browser get html @e1     # Get HTML
+agent-browser get value @e2    # Get input value
+agent-browser get attr @e1 href  # Get attribute
+agent-browser get title        # Page title
+agent-browser get url          # Current URL
+agent-browser get count "li"   # Count elements
+agent-browser get box @e1      # Bounding box
+```
+
+### State Checks
+```bash
+agent-browser is visible @e1   # Check visibility
+agent-browser is enabled @e1   # Check if enabled
+agent-browser is checked @e3   # Check if checked
+```
+
+### Media
+```bash
+agent-browser screenshot           # Capture viewport
+agent-browser screenshot --full    # Full page
+agent-browser screenshot -o ss.png # Save to file
+agent-browser pdf -o page.pdf      # Export PDF
+agent-browser record start         # Start video recording
+agent-browser record stop          # Stop and save video
+agent-browser record restart       # Restart recording
+```
+
+### Wait Conditions
+```bash
+agent-browser wait @e1                    # Wait for element
+agent-browser wait --text "Success"       # Wait for text to appear
+agent-browser wait --url "/dashboard"     # Wait for URL pattern
+agent-browser wait --load                 # Wait for page load
+agent-browser wait --idle                 # Wait for network idle
+agent-browser wait --fn "() => window.ready"  # Wait for JS condition
+```
+
+### Browser Configuration
+```bash
+agent-browser viewport 1920 1080   # Set viewport size
+agent-browser device "iPhone 14"   # Emulate device
+agent-browser geolocation 40.7 -74.0  # Set geolocation
+agent-browser offline true         # Enable offline mode
+agent-browser headers '{"X-Custom":"val"}'  # Set headers
+agent-browser credentials user pass  # HTTP auth
+agent-browser color-scheme dark    # Set color scheme
+```
+
+### Storage Management
+```bash
+agent-browser cookies              # List cookies
+agent-browser cookies set name=val # Set cookie
+agent-browser cookies clear        # Clear cookies
+agent-browser storage local        # Get localStorage
+agent-browser storage session      # Get sessionStorage
+agent-browser state save auth.json # Save browser state
+agent-browser state load auth.json # Load browser state
+```
+
+### Network Control
+```bash
+agent-browser network route "**/*.jpg" --abort    # Block requests
+agent-browser network route "**/api/*" --body '{"data":[]}'  # Mock response
+agent-browser network unroute "**/*.jpg"          # Remove specific route
+agent-browser network requests                    # List intercepted requests
+```
+
+### Semantic Finding
+```bash
+agent-browser find role button           # Find by ARIA role
+agent-browser find text "Submit"         # Find by text content
+agent-browser find label "Email"         # Find by label
+agent-browser find placeholder "Search"  # Find by placeholder
+agent-browser find testid "login-btn"    # Find by data-testid
+agent-browser find first "button"        # First matching element
+agent-browser find last "li"             # Last matching element
+agent-browser find nth 2 "li"            # Nth element (0-indexed)
+```
+
+### Advanced
+```bash
+agent-browser tabs                 # List tabs
+agent-browser tab new              # New tab
+agent-browser tab 2                # Switch to tab
+agent-browser tab close            # Close current tab
+agent-browser frame 0              # Switch to frame
+agent-browser dialog accept        # Accept dialog
+agent-browser dialog dismiss       # Dismiss dialog
+agent-browser eval "document.title"  # Execute JS
+agent-browser highlight @e1        # Highlight element visually
+agent-browser mouse move 100 200   # Move mouse to coordinates
+agent-browser mouse down           # Mouse button down
+agent-browser mouse up             # Mouse button up
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--session <name>` | Named session for parallel testing |
+| `--json` | JSON output for parsing |
+| `--headed` | Show browser window |
+| `--cdp <port>` | Connect via Chrome DevTools Protocol |
+| `-p <provider>` | Cloud browser provider |
+| `--proxy <url>` | Proxy server |
+| `--headers <json>` | Custom HTTP headers |
+| `--executable-path` | Custom browser binary |
+| `--extension <path>` | Load browser extension |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_BROWSER_SESSION` | Default session name |
+| `AGENT_BROWSER_PROVIDER` | Cloud provider (e.g., browserbase) |
+| `AGENT_BROWSER_EXECUTABLE_PATH` | Browser binary location |
+| `AGENT_BROWSER_EXTENSIONS` | Comma-separated extension paths |
+| `AGENT_BROWSER_STREAM_PORT` | WebSocket streaming port |
+| `AGENT_BROWSER_HOME` | Custom installation directory |
+| `AGENT_BROWSER_PROFILE` | Browser profile directory |
+| `BROWSERBASE_API_KEY` | Browserbase API key |
+| `BROWSERBASE_PROJECT_ID` | Browserbase project ID |
+
+## Common Patterns
+
+### Form Submission
+```bash
+agent-browser open https://example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3  # Submit button
+agent-browser wait url "/dashboard"
+```
+
+### State Persistence (Auth)
+```bash
+# Save authenticated state
+agent-browser open https://example.com/login
+# ... login steps ...
+agent-browser state save auth.json
+
+# Reuse in future sessions
+agent-browser state load auth.json
+agent-browser open https://example.com/dashboard
+```
+
+### Video Recording (Debugging)
+```bash
+agent-browser open https://example.com
+agent-browser record start
+# ... perform actions ...
+agent-browser record stop  # Saves to recording.webm
+```
+
+### Parallel Sessions
+```bash
+# Terminal 1
+agent-browser --session test1 open https://example.com
+
+# Terminal 2
+agent-browser --session test2 open https://example.com
+```
+
+## Cloud Browsers (Browserbase)
+
+For CI/CD or environments without local browser:
+
+```bash
+# Set credentials
+export BROWSERBASE_API_KEY="your-api-key"
+export BROWSERBASE_PROJECT_ID="your-project-id"
+
+# Use cloud browser
+agent-browser -p browserbase open https://example.com
+```
+
+See `references/browserbase-cloud-setup.md` for detailed setup.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Command not found | Run `npm install -g agent-browser` |
+| Chromium missing | Run `agent-browser install` |
+| Linux deps missing | Run `agent-browser install --with-deps` |
+| Session stale | Close browser: `agent-browser close` |
+| Element not found | Re-run `snapshot -i` after page changes |
+
+## Resources
+
+- [GitHub Repository](https://github.com/vercel-labs/agent-browser)
+- [Official Documentation](https://github.com/vercel-labs/agent-browser#readme)
+- [Browserbase Docs](https://docs.browserbase.com/)