@ranger-testing/ranger-cli 1.0.14 → 1.1.1

package/README.md

@@ -2,394 +2,157 @@
 
 The Ranger CLI sets up your project to use Ranger's AI-powered testing tools with Claude Code.
 
-## Installation
+## Getting Started
 
-```bash
-npm install -g @ranger-testing/ranger-cli
-```
-
-## Quick Start
-
-Go to [dashboard.ranger.net/cli](https://dashboard.ranger.net/cli) to get started.
-
-## Claude Code Plugin
-
-For the best experience with Claude Code, install the Ranger plugin. Run these commands **inside Claude Code**:
-
-```
-/plugin marketplace add ranger-testing/trailhead
-/plugin install ranger@trailhead
-```
-
-The plugin provides:
-- **Auto-firing hooks** - Automatically loads Ranger context at session start
-- **MCP tools** - Access to Ranger's test management and browser verification tools
-- **Feature tracking** - Track feature development with verifiable checklist items
-
-> **Note:** The plugin requires the CLI to be configured. Run `ranger start <token>` in a regular terminal first.
-
-## Commands
-
-### `ranger start <token>`
-
-Initialize Ranger in your project. Get your token from [dashboard.ranger.net/cli](https://dashboard.ranger.net/cli).
-
-This command:
-- Validates your API token
-- Creates `.mcp.json` with the Ranger MCP server configuration
-- Creates the `.ranger/` directory for environment configs
-- Creates `.ranger/.gitignore` to exclude local environment (contains auth state)
-
-```bash
-ranger start rngr_abc123...
-```
-
-### `ranger skillup`
-
-Install Ranger skills for Claude Code. This command installs AI agents that help with testing and bug hunting:
-
-- **e2e-test-recommender** - Installed if you have an API token. Analyzes code changes and suggests end-to-end tests.
-- **bug-bash** - Installed if you have an API token AND an active environment. Explores new features via browser to find bugs.
-
-Skills are installed to `.claude/skills/` and can be invoked in Claude Code conversations.
-
-```bash
-ranger skillup
-```
-
-**Important:** Run this command in the directory where you want to use Ranger skills. Skills are installed relative to your current working directory.
-
-Run this command after `ranger start` and again after `ranger add env` to install all available skills.
-
-### `ranger add env <env-name>`
-
-Add a new environment configuration. You'll be prompted to:
-- Manually authenticate into your app to save session (if needed)
-- Log in via browser (captures auth cookies/storage)
-
-```bash
-ranger add env local
-ranger add env staging
-ranger add env prod
-```
-
-### `ranger use <env-name>`
-
-Switch to a different environment.
+### Step 1: Install Ranger
 
 ```bash
-ranger use staging
+npm install -g @ranger-testing/ranger-cli
 ```
 
-### `ranger env update <env-name>`
-
-Update authentication for an existing environment (re-capture cookies/storage).
+### Step 2: Get Your Token
 
-```bash
-ranger env update staging
-```
+Go to [dashboard.ranger.net/cli](https://dashboard.ranger.net/cli) to get your API token.
 
-### `ranger update`
+### Step 3: Initialize Your Project
 
-Update Ranger CLI to the latest version.
+In your project repo (must be a git repository), run:
 
 ```bash
-ranger update
+ranger start <your-token>
 ```
 
-This command updates the globally installed `@ranger-testing/ranger-cli` package and reinstalls skills to ensure compatibility.
+This will guide you through setup. If you skipped any steps, run them manually:
 
-### `ranger config`
+- Add a browser environment for verification:
+  ```bash
+  ranger add env local
+  ```
+- Install Claude Code skills:
+  ```bash
+  ranger skillup
+  ```
+- Install the Claude Code plugin:
+  ```bash
+  claude plugin marketplace add ranger-testing/trailhead
+  claude plugin install ranger@trailhead --scope user
+  ```
 
-Manage browser configuration for environments (userAgent, headers, etc.).
+## Using Ranger with Claude
 
-#### `ranger config set <env> <key> <value>`
+Once set up, here's the typical workflow:
 
-Set a config value. Supports dot notation for nested keys.
+1. Start a Claude Code session in your project
+2. In your Claude Code session, run `/ranger:enable` to activate Ranger
+3. Enter plan mode with `/plan` to begin planning your feature
+4. Accept the plan - Ranger tracks your feature automatically
+5. Watch Ranger verify your feature in the browser
 
-```bash
-# Set user agent
-ranger config set ci userAgent "Mozilla/5.0 (CI Bot)"
+Ranger stays enabled on your branch across sessions. Use `/ranger:disable` to turn it off.
 
-# Set custom headers
-ranger config set ci header.X-Test-Mode "true"
-ranger config set ci header.Authorization '${AUTH_TOKEN}'
+**Note:** Commands starting with `/` (like `/ranger:enable`, `/plan`, `/ranger:disable`) are slash commands entered inside the Claude Code chat interface. Terminal commands like `ranger start` are run in your shell.
 
-# Run browser in headless mode (useful for CI)
-ranger config set ci headless true
-```
+## Commands Reference
 
-**Environment variable substitution**: Values like `${VAR_NAME}` are stored as-is and resolved at runtime when `verify-in-browser` runs.
+### Setup Commands
 
-#### `ranger config get <env> <key>`
+| Command | Description |
+|---------|-------------|
+| `ranger start <token>` | Initialize Ranger in your project |
+| `ranger status` | Show Ranger status and configuration |
+| `ranger update` | Update Ranger CLI to latest version |
+| `ranger clean` | Remove all Ranger artifacts from project |
 
-Get a config value.
+### Environment Commands
 
-```bash
-ranger config get ci userAgent
-# Mozilla/5.0 (CI Bot)
-```
+| Command | Description |
+|---------|-------------|
+| `ranger add env <name>` | Add a new browser environment |
+| `ranger use <name>` | Switch to a different environment |
+| `ranger env ls` | List all configured environments |
+| `ranger env update <name>` | Re-capture auth for an environment |
 
-#### `ranger config list <env>`
+### Config Commands
 
-List all config for an environment.
+| Command | Description |
+|---------|-------------|
+| `ranger config set <env> <key> <value>` | Set a config value |
+| `ranger config get <env> <key>` | Get a config value |
+| `ranger config list <env>` | List all config for an environment |
+| `ranger config unset <env> <key>` | Remove a config value |
 
-```bash
-ranger config list ci
-# userAgent: Mozilla/5.0 (CI Bot)
-# headless: true
-# headers:
-#   X-Test-Mode: true
-#   Authorization: ${AUTH_TOKEN}
-```
+## Detailed Command Reference
 
-#### `ranger config unset <env> <key>`
+### `ranger feature create`
 
-Remove a config value.
-
-```bash
-ranger config unset ci header.X-Test-Mode
-```
-
-### `ranger verify-in-browser --url <url> --task <task>`
-
-Verify a UI flow in an isolated browser session. Returns structured results with any issues found.
-
-```bash
-ranger verify-in-browser \
-  --url "http://localhost:3000/login" \
-  --task "Enter valid credentials and verify successful login"
-```
-
-### Feature Tracking Commands
-
-Track feature development progress with verifiable checklist items. Each item can be verified in the browser with evidence (screenshots, traces, conversation logs).
-
-#### `ranger feature create <name>`
-
-Create a new feature with a checklist. Automatically captures git context (repo URL, branch).
+Create a new feature with checklist items:
 
 ```bash
 ranger feature create "User Authentication" \
-  --description "Login, signup, and password reset flows" \
-  -c "Login works" \
-  -c "Signup creates account" \
-  -c "Password reset sends email"
+  --description "Login and signup flows" \
+  -c "User can log in" \
+  -c "User can sign up"
 ```
 
-#### `ranger feature list`
-
-List all features with session status.
+### `ranger feature list`
 
 ```bash
 ranger feature list                    # All features
 ranger feature list --current-branch   # Features for current git branch
 ```
 
-#### `ranger feature show [id]`
-
-Show feature details. Uses active feature if no ID provided.
-
-```bash
-ranger feature show
-ranger feature show feat_abc123
-```
-
-#### `ranger feature use <id>`
-
-Set the active feature.
-
-```bash
-ranger feature use feat_abc123
-```
-
-#### `ranger feature resume [id]`
-
-Find and use a feature matching the current git context (repo + branch). If multiple features match, prompts for selection.
-
-Optionally pass a feature ID to resume directly (bypasses search/prompt - useful for automation).
-
-```bash
-ranger feature resume                  # Search by git context
-ranger feature resume feat_abc123      # Resume specific feature directly
-```
-
-#### `ranger feature report [id]`
-
-Generate a markdown report with all verification evidence.
-
-```bash
-ranger feature report                  # Uses active feature
-ranger feature report feat_abc123
-ranger feature report --output ./my-report.md
-```
-
 ### `ranger verify-feature`
 
-Verify a checklist item in the browser. Requires an active feature.
+Verify checklist items in the browser:
 
 ```bash
 ranger verify-feature \
+  --item 1 \
   --task "Log in with valid credentials and verify redirect to dashboard"
+
+# Start on a specific page instead of the base URL
+ranger verify-feature \
+  --start-path /dashboard \
+  --task "Verify dashboard shows user stats"
 ```
 
-The URL is derived from your active environment's `baseUrl` setting.
+The URL is derived from your active environment's `baseUrl` setting. Use `--start-path` to append a path.
 
 Options:
-- `--env`: Environment to use (defaults to active environment)
+- `--item <index>`: Checklist item to verify by index (1-based, required in non-interactive mode)
 - `--task`: Task description (defaults to checklist item description)
-- `--item <index>`: Verify specific item by index (1-based)
+- `--env`: Environment to use (defaults to active environment)
+- `--start-path`: Path to start on (e.g., `/dashboard`)
 
-### `ranger clean`
+### `ranger config`
 
-Remove all Ranger artifacts from the project (`.ranger/`, `.mcp.json` entries).
+Configure browser settings for environments:
 
 ```bash
-ranger clean
-```
-
-## Configuring agents.md
-
-Create or update `.claude/agents.md` in your project to help Claude Code understand your environment setup. This file should include:
-
-- **Environment URLs** - Which URLs correspond to which environments
-- **Product context** - What each environment is used for
-
-Example `.claude/agents.md`:
-
-```markdown
-## Environments
-
-- `localhost:4000` - Customer-facing product (main app)
-- `localhost:3000` - Internal admin dashboard
-- `staging.example.com` - Staging environment
-
-## Notes
-
-- Use the `local` environment for development testing
-- Staging requires VPN access
-```
-
-This helps Ranger skills understand where to test and what each environment represents.
-
-## Using with Claude Code
-
-Once Ranger is set up, you can use it with Claude Code in several ways:
-
-### 1. Ranger MCP Tools
-
-After running `ranger start`, the Ranger MCP server is configured in your project. Claude Code can use these tools:
-
-- `mcp__ranger__get_product_docs` - Get your product's sitemap and entity documentation
-- `mcp__ranger__get_test_suite` - List all tests in your test suite
-- `mcp__ranger__get_test_details` - Get details for a specific test
-- `mcp__ranger__create_draft_test` - Create a new draft test
-- `mcp__ranger__generate_test_plan` - Generate a test plan with steps
-
-### 2. Browser Tools (after `ranger add env`)
-
-Once you add an environment, Claude Code can interact with your app via browser:
-
-- `mcp__ranger-browser__browser_navigate` - Navigate to a URL
-- `mcp__ranger-browser__browser_snapshot` - Get page accessibility snapshot
-- `mcp__ranger-browser__browser_click` - Click an element
-- `mcp__ranger-browser__browser_type` - Type text
-- `mcp__ranger-browser__browser_fill_form` - Fill form fields
-- And more...
-
-### 3. Bug Bash Skill
-
-The **bug-bash** skill explores new features to find bugs. Invoke it in Claude Code:
-
-```
-/bug-bash
-```
-
-Or ask Claude to explore your changes:
-
-> "Explore the new settings page I just built and look for bugs"
-
-The bug-bash skill will:
-1. Analyze your git diff to understand what changed
-2. Generate exploration ideas based on the changes
-3. Systematically test flows using `ranger verify-in-browser`
-4. Report any issues found with severity levels
-
-### 4. E2E Test Recommender Skill
-
-The **e2e-test-recommender** skill analyzes your code changes and suggests end-to-end tests. Invoke it:
-
-```
-/e2e-test-recommender
+ranger config set ci headless true
+ranger config set ci userAgent "Mozilla/5.0 (CI Bot)"
+ranger config set ci header.Authorization '${AUTH_TOKEN}'
 ```
 
-Or ask Claude:
+Environment variables like `${AUTH_TOKEN}` are resolved at runtime, not when the config is set.
 
-> "What e2e tests should I add for my recent changes?"
+## Claude Code Plugin
 
-### 5. Direct Browser Verification
+The `ranger start` command attempts to install the plugin automatically. However, installation may be skipped or fail.
 
-Use the `verify-in-browser` command directly for quick UI checks:
+To install manually:
 
 ```bash
-# Verify login works
-ranger verify-in-browser \
-  --url "http://localhost:3000/login" \
-  --task "Log in with test@example.com / password123, verify dashboard loads"
-
-# Verify form validation
-ranger verify-in-browser \
-  --url "http://localhost:3000/signup" \
-  --task "Submit form with empty email, verify error message appears"
+claude plugin marketplace add ranger-testing/trailhead
+claude plugin install ranger@trailhead --scope user
 ```
 
-The command returns:
-- `success`: Whether the flow completed without issues
-- `summary`: Description of what happened
-- `issues`: Array of problems found (BLOCKER, MAJOR, MINOR)
-- Exit code 0 for success, 1 for issues found
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `MCP_SERVER_URL` | Override the default Ranger MCP server URL |
-| `ANTHROPIC_API_KEY` | Required for publishing skills to Anthropic API |
-
-## Example Workflow
-
-```bash
-# Set up Ranger
-ranger start rngr_your_token_here
-
-# Add your local development environment
-ranger add env local
-# (Browser opens, log in if needed, close when done)
-
-# Install skills for Claude Code
-ranger skillup
-
-# Now use Claude Code to test your app
-# Claude can now browse your app, find bugs, and suggest tests!
-
-# When switching to test staging:
-ranger add env staging
-ranger use staging
-
-# Clean up when done
-ranger clean
-```
+Check status with `ranger status`.
 
 ## Troubleshooting
 
-### "No active environment" error
-
-Run `ranger use <env-name>` to set an active environment before using `verify-in-browser`.
-
-### "Ranger Browser MCP not configured" error
-
-Run `ranger add env <name>` to configure browser access for an environment.
-
-### Authentication expired
+**"No active environment" error**
+Run `ranger use <env-name>` to set an active environment.
 
-Run `ranger env update <env-name>` to refresh authentication cookies/storage.
+**Authentication expired**
+Run `ranger env update <env-name>` to refresh auth.