@ranger-testing/ranger-cli 1.0.13 → 1.1.0

package/README.md

@@ -10,40 +10,45 @@ npm install -g @ranger-testing/ranger-cli
 
 ## Quick Start
 
-1. Get your API token from [dashboard.ranger.net/settings](https://dashboard.ranger.net/settings)
+Go to [dashboard.ranger.net/cli](https://dashboard.ranger.net/cli) to get started.
 
-2. Initialize Ranger in your project:
-```bash
-ranger start <your-api-token>
-```
+## Claude Code Plugin
 
-3. Add an environment (e.g., local, staging, prod):
-```bash
-ranger add env local
-```
+The Ranger plugin for Claude Code is installed automatically when you run `ranger start`. You can choose to install it at the user level (available in all projects) or project level (shared with team via git).
+
+The plugin provides:
+- **Auto-firing hooks** - Automatically loads Ranger context at session start
+- **Feature tracking** - Track feature development with verifiable checklist items
+
+To check plugin status, run `ranger status`.
+
+### Manual Plugin Installation
+
+If you need to install the plugin manually (e.g., skipped during setup or installing on a new machine):
 
-4. Install skills for Claude Code (run this in the directory where you want to use Ranger):
 ```bash
-ranger skillup
-```
+# Add the marketplace (one-time)
+claude plugin marketplace add ranger-testing/trailhead
 
-5. Start using Ranger skills in Claude Code! For example:
-```
-/bug-bash test the new feature on this branch
-/e2e-test-recommender recommend tests for this new feature
+# Install to user scope (available in all projects)
+claude plugin install ranger@trailhead --scope user
+
+# Or install to project scope (shared with team via git)
+claude plugin install ranger@trailhead --scope project
 ```
 
 ## Commands
 
 ### `ranger start <token>`
 
-Initialize Ranger in your project. Get your token from [dashboard.ranger.net/settings](https://dashboard.ranger.net/settings).
+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)
+- Prompts to install the Claude Code plugin (user or project scope)
+- Prompts to add an environment and install skills
 
 ```bash
 ranger start rngr_abc123...
@@ -51,10 +56,9 @@ ranger start rngr_abc123...
 
 ### `ranger skillup`
 
-Install Ranger skills for Claude Code. This command installs AI agents that help with testing and bug hunting:
+Install Ranger skills for Claude Code. This command installs AI agents that help with feature development:
 
-- **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.
+- **ranger** - Installed if you have an API token AND an active environment. Tracks feature development with browser verification.
 
 Skills are installed to `.claude/skills/` and can be invoked in Claude Code conversations.
 
@@ -64,7 +68,7 @@ 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.
+Run this command after `ranger start` and `ranger add env` to install all available skills.
 
 ### `ranger add env <env-name>`
 
@@ -86,12 +90,20 @@ Switch to a different environment.
 ranger use staging
 ```
 
-### `ranger update env <env-name>`
+### `ranger env update <env-name>`
 
 Update authentication for an existing environment (re-capture cookies/storage).
 
 ```bash
-ranger update env staging
+ranger env update staging
+```
+
+### `ranger env ls`
+
+List all configured environments.
+
+```bash
+ranger env ls
 ```
 
 ### `ranger update`
@@ -104,6 +116,14 @@ ranger update
 
 This command updates the globally installed `@ranger-testing/ranger-cli` package and reinstalls skills to ensure compatibility.
 
+### `ranger status`
+
+Show Ranger status including version, Claude Code plugin status, installed skills, and configured environments.
+
+```bash
+ranger status
+```
+
 ### `ranger config`
 
 Manage browser configuration for environments (userAgent, headers, etc.).
@@ -124,7 +144,7 @@ ranger config set ci header.Authorization '${AUTH_TOKEN}'
 ranger config set ci headless true
 ```
 
-**Environment variable substitution**: Values like `${VAR_NAME}` are stored as-is and resolved at runtime when `verify-in-browser` runs.
+**Environment variable substitution**: Values like `${VAR_NAME}` are stored as-is and resolved at runtime.
 
 #### `ranger config get <env> <key>`
 
@@ -156,16 +176,6 @@ Remove a config value.
 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).
@@ -177,17 +187,19 @@ Create a new feature with a checklist. Automatically captures git context (repo
 ```bash
 ranger feature create "User Authentication" \
   --description "Login, signup, and password reset flows" \
-  --checklist "Login works,Signup creates account,Password reset sends email"
+  -c "Login works" \
+  -c "Signup creates account" \
+  -c "Password reset sends email"
 ```
 
 #### `ranger feature list`
 
-List all features with status.
+List all features with session status.
 
 ```bash
 ranger feature list                    # All features
-ranger feature list --status in_progress
 ranger feature list --current-branch   # Features for current git branch
+ranger feature list --limit 20         # Show more results
 ```
 
 #### `ranger feature show [id]`
@@ -199,66 +211,22 @@ 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`
-
-Find and use a feature matching the current git context (repo + branch).
-
-```bash
-ranger feature resume
-```
-
-#### `ranger feature block [id]`
+#### `ranger feature resume [id]`
 
-Mark a feature as blocked.
+Resume a specific feature by ID. Use `ranger feature list` first to find features.
 
 ```bash
-ranger feature block --reason "Waiting for API changes"
+ranger feature list                    # List features (filter with --current-branch)
+ranger feature resume feat_abc123      # Resume the feature
 ```
 
-#### `ranger feature manage`
+#### `ranger feature add-checklist-item <description>`
 
-Manage checklist items. Can be used interactively (for humans) or with flags (for agents/automation).
+Add a checklist item to a feature.
 
-**Interactive mode** (no flags):
 ```bash
-ranger feature manage
-# Shows menu to add, edit, block, cancel, or reset items
-```
-
-**Non-interactive mode** (with flags - agent-friendly):
-```bash
-# Add a new checklist item
-ranger feature manage --add "New checklist item description"
-
-# Edit an item's description (1-based index)
-ranger feature manage --edit 1 --description "Updated description"
-
-# Block an item with reason
-ranger feature manage --block 2 --reason "Bug found in login flow"
-
-# Cancel an item with reason
-ranger feature manage --cancel 3 --reason "Descoped to v2"
-
-# Reset an item to pending
-ranger feature manage --reset 2
-```
-
-#### `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 feature add-checklist-item "User can reset password"
+ranger feature add-checklist-item "Admin can view all users" --id feat_abc123
 ```
 
 ### `ranger verify-feature`
@@ -267,15 +235,15 @@ Verify a checklist item in the browser. Requires an active feature.
 
 ```bash
 ranger verify-feature \
-  --url "http://localhost:3000/login" \
   --task "Log in with valid credentials and verify redirect to dashboard"
 ```
 
+The URL is derived from your active environment's `baseUrl` setting.
+
 Options:
-- `--url` (required): URL to navigate to
+- `--env`: Environment to use (defaults to active environment)
 - `--task`: Task description (defaults to checklist item description)
 - `--item <index>`: Verify specific item by index (1-based)
-- `--new-item <description>`: Create and verify a new item
 
 ### `ranger clean`
 
@@ -285,6 +253,15 @@ Remove all Ranger artifacts from the project (`.ranger/`, `.mcp.json` entries).
 ranger clean
 ```
 
+### `ranger auth encrypt <env>`
+
+Encrypt auth.json for an environment to allow safe git storage.
+
+```bash
+ranger auth encrypt local     # Encrypts .ranger/local/auth.json -> auth.json.enc
+ranger auth encrypt ci        # Encrypts .ranger/ci/auth.json -> auth.json.enc
+```
+
 ## Configuring agents.md
 
 Create or update `.claude/agents.md` in your project to help Claude Code understand your environment setup. This file should include:
@@ -309,90 +286,6 @@ Example `.claude/agents.md`:
 
 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
-```
-
-Or ask Claude:
-
-> "What e2e tests should I add for my recent changes?"
-
-### 5. Direct Browser Verification
-
-Use the `verify-in-browser` command directly for quick UI checks:
-
-```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"
-```
-
-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
@@ -421,12 +314,8 @@ ranger clean
 
 ### "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.
+Run `ranger use <env-name>` to set an active environment.
 
 ### Authentication expired
 
-Run `ranger update env <env-name>` to refresh authentication cookies/storage.
+Run `ranger env update <env-name>` to refresh authentication cookies/storage.