@ranger-testing/ranger-cli 1.1.6 → 2.0.0

package/build/skills/ranger/SKILL.md

@@ -1,105 +1,105 @@
 ---
 name: ranger
-description: "Ranger's core development workflow for building e2e features. Use this skill for ANY feature development, implementation, or code changes that touches UI. Automatically tracks progress with checklist items, verifies implementations in the browser, and generates completion reports with evidence. Start every coding task by checking for existing features to resume."
+description: "Ranger's core development workflow for building e2e features. Use this skill for ANY feature development, implementation, or code changes that touches UI. Automatically tracks progress with scenarios, verifies implementations in the browser, and generates completion reports with evidence. Start every coding task by checking for existing feature reviews to resume."
 ---
 
 # Ranger Skill
 
 **IMPORTANT: At the start of any session, run `ranger update` first to ensure you have the latest CLI and skills.**
 
-This skill covers three workflows for Ranger feature tracking:
+This skill covers three workflows for Ranger feature review tracking:
 
 ## Supported Workflows
 
 | Workflow | When to Use | Required Reading |
 |----------|-------------|------------------|
-| **Resuming a Feature** | Starting a session | **MUST read [start.md](./start.md)** |
-| **Creating a Feature** | Starting new UI work | **MUST read [create.md](./create.md)** |
-| **Verifying a Feature** | After implementing UI changes | **MUST read [verify.md](./verify.md)** |
+| **Resuming a Feature Review** | Starting a session | **MUST read [start.md](./start.md)** |
+| **Creating a Feature Review** | Starting new UI work | **MUST read [create.md](./create.md)** |
+| **Verifying a Feature Review** | After implementing UI changes | **MUST read [verify.md](./verify.md)** |
 | **Addressing Feedback** | After reviewer leaves comments | **MUST read [feedback.md](./feedback.md)** |
 
 ---
 
-# Workflow 1: Resuming a Feature
+# Workflow 1: Resuming a Feature Review
 
 **MANDATORY: Read [start.md](./start.md) at the start of any session.**
 
 Use this workflow when:
 - Starting a new coding session
 - Returning to existing work
-- Before creating a new feature (always check first!)
+- Before creating a new feature review (always check first!)
 
 ### Quick Start
 
 ```bash
-# List features to find one to resume
-ranger feature list
+# List feature reviews to find one to resume
+ranger list
 
-# Resume a specific feature by ID
-ranger feature resume <id>
+# Resume a specific feature review by ID
+ranger resume <id>
 
-# Verify a checklist item (starts at base URL)
-ranger verify-feature --task "<description of what to verify>"
+# Verify a scenario (starts at base URL)
+ranger go --scenario <N> --notes "<description of what to verify>"
 
 # Verify starting on a specific page
-ranger verify-feature --start-path /dashboard --task "<description>"
+ranger go --scenario <N> --start-path /dashboard --notes "<description>"
 
-# Add a checklist item if scope expanded (be detailed!)
-ranger feature add-checklist-item "User navigates to /settings, clicks 'Edit Profile', updates display name, clicks Save, sees success toast, refreshes page, and confirms the new name persists"
+# Add a scenario if scope expanded (be detailed!)
+ranger add-scenario "User navigates to /settings, clicks 'Edit Profile', updates display name, clicks Save, sees success toast, refreshes page, and confirms the new name persists"
 ```
 
 ---
 
-# Workflow 2: Creating a Ranger Feature
+# Workflow 2: Creating a Ranger Feature Review
 
-**MANDATORY: Read [create.md](./create.md) before creating any feature.**
+**MANDATORY: Read [create.md](./create.md) before creating any feature review.**
 
 Use this workflow when:
-- Starting new feature development
+- Starting new feature review development
 - Planning UI changes
-- `ranger feature show` found no match
-- The feature you are developin is not found in `ranger feature list`
+- `ranger show` found no match
+- The feature review you are developing is not found in `ranger list`
 
 ### Quick Start
 
 ```bash
-ranger feature create "<name>" \
+ranger create "<name>" \
   --description "<description>" \
-  -c "<E2E checklist item 1>" \
-  -c "<E2E checklist item 2>"
+  -c "<E2E scenario 1>" \
+  -c "<E2E scenario 2>"
 ```
 
-### Critical: Checklist Items Are E2E Tests
+### Critical: Scenarios Are E2E Tests
 
-Checklist items are **E2E test scenarios**, NOT implementation tasks.
+Scenarios are **E2E test flows**, NOT implementation tasks.
 
 ❌ **WRONG:** `"Add login form validation"` (implementation task)
 ❌ **WRONG:** `"API returns 200"` (backend task)
 ✅ **RIGHT:** `"User can log in with valid credentials and see dashboard"` (E2E flow)
 
-**You MUST read [create.md](./create.md) for full guidance on writing checklist items.**
+**You MUST read [create.md](./create.md) for full guidance on writing scenarios.**
 
 ---
 
-# Workflow 3: Verifying a Ranger Feature
+# Workflow 3: Verifying a Ranger Feature Review
 
-**MANDATORY: Read [verify.md](./verify.md) before verifying any checklist item.**
+**MANDATORY: Read [verify.md](./verify.md) before verifying any scenario.**
 
 Use this workflow when:
-- You've implemented code for a checklist item
+- You've implemented code for a scenario
 - Ready to verify the implementation works in a browser
 
 ### Quick Start
 
 ```bash
-# Verify a checklist item
-ranger verify-feature --task "<description of what to verify>"
+# Verify a scenario
+ranger go --scenario <N> --notes "<description of what to verify>"
 ```
 
 The verification agent will:
 1. Execute the task in a real browser
-2. Evaluate if the checklist item is satisfied
-3. Mark the item as verified, partial, blocked, or failed
+2. Evaluate if the scenario is satisfied
+3. Mark the scenario as verified, partial, blocked, or failed
 4. Capture evidence (screenshots, traces)
 
 **You MUST read [verify.md](./verify.md) for full guidance on verification.**
@@ -108,21 +108,21 @@ The verification agent will:
 
 # Workflow 4: Addressing Reviewer Feedback
 
-**MANDATORY: Read [feedback.md](./feedback.md) when items have reviewer comments.**
+**MANDATORY: Read [feedback.md](./feedback.md) when scenarios have reviewer comments.**
 
 Use this workflow when:
-- `ranger feature show` displays items with comment badges
-- Items show as v2/v3 (revised after reviewer feedback)
-- `ranger feature resume` warns about unaddressed comments
+- `ranger show` displays scenarios with comment badges
+- Scenarios show as v2/v3 (revised after reviewer feedback)
+- `ranger resume` warns about unaddressed comments
 
 ### Quick Start
 
 ```bash
-# See all reviewer comments across items
-ranger feature get-feedback
+# See all reviewer comments across scenarios
+ranger get-review
 
-# After fixing code, re-verify the item
-ranger verify-feature --item <N>
+# After fixing code, re-verify the scenario
+ranger go --scenario <N>
 ```
 
 The verification agent automatically receives reviewer comments, so it will check that each concern was addressed.
@@ -133,7 +133,7 @@ The verification agent automatically receives reviewer comments, so it will chec
 
 Once you're done verifying, and just before stopping the session, share the feature review link with the user:
 
-> Feature explored! All checklist items have been tested.
+> Feature explored! All scenarios have been tested.
 > **Link to feature review:** https://dashboard.ranger.net/features/{feature_id}
 
 ---
@@ -142,10 +142,10 @@ Once you're done verifying, and just before stopping the session, share the feat
 
 ```
 ┌───────────────────────────────────────┐
-│  1. RESUME OR CREATE FEATURE          │  ◀── MUST READ start.md, create.md
-│     • ranger feature list             │
-│     • ranger feature resume <id>      │
-│     • OR ranger feature create        │
+│  1. RESUME OR CREATE FEATURE REVIEW   │  ◀── MUST READ start.md, create.md
+│     • ranger list             │
+│     • ranger resume <id>      │
+│     • OR ranger create        │
 └───────────────────┬───────────────────┘
                     │
                     ▼
@@ -163,15 +163,15 @@ Once you're done verifying, and just before stopping the session, share the feat
         │   └───────┬───────┘   │
         │           │           │
         │           ▼           │
-        │     More items?       │
+        │   More scenarios?     │
         │       YES ─┘          │
         │                       │
         └───────────┬───────────┘
                     │ NO (all verified)
                     ▼
         ┌───────────────────────┐
-        │  Feature sent for     │
-        │  review               │
+        │  Feature review sent  │
+        │  for human review     │
         └───────────┬───────────┘
                     │
                     ▼
@@ -182,7 +182,7 @@ Once you're done verifying, and just before stopping the session, share the feat
              ▼           ▼
         ┌─────────┐  ┌──────────────────────┐
         │  Done!  │  │ 4. ADDRESS FEEDBACK  │  ◀── MUST READ feedback.md
-        └─────────┘  │  • get-feedback      │
+        └─────────┘  │  • get-review      │
                      │  • fix code           │
                      │  • re-verify          │
                      └──────────┬───────────┘
@@ -196,21 +196,22 @@ Once you're done verifying, and just before stopping the session, share the feat
 
 | Command | Purpose |
 |---------|---------|
-| `ranger feature list` | List features (check before creating) |
-| `ranger feature resume <id>` | Resume a specific feature |
-| `ranger feature show` | Show current feature status |
-| `ranger feature create` | Create new feature with checklist |
-| `ranger feature add-checklist-item` | Add a checklist item to active feature |
-| `ranger feature get-feedback` | See reviewer comments on items |
-| `ranger verify-feature` | Verify checklist item in browser |
+| `ranger list` | List feature reviews (check before creating) |
+| `ranger resume <id>` | Resume a specific feature review |
+| `ranger show` | Show current feature review status |
+| `ranger create` | Create new feature review with scenarios |
+| `ranger add-scenario` | Add a scenario to active feature review |
+| `ranger edit-scenario` | Edit a scenario description on the active feature review |
+| `ranger get-review` | See reviewer comments on scenarios |
+| `ranger go` | Verify scenario in browser |
 
 # Key Principles
 
 1. **Read the docs first** - start.md before resuming, create.md before creating, verify.md before verifying
-2. **Always list first** - Run `ranger feature list` at session start before creating new features
-3. **Checklist items are E2E tests** - Not TODO lists, not backend tasks. BE DESCRIPTIVE and unambiguous when detailing the flow to cover.
+2. **Always list first** - Run `ranger list` at session start before creating new feature reviews
+3. **Scenarios are E2E tests** - Not TODO lists, not backend tasks. BE DESCRIPTIVE and unambiguous when detailing the flow to cover.
 4. **Verify after implementing** - Don't skip browser verification
-5. **Link to dashboard** - Whenever you are mentioning a feature, send out the full URL instead of just the feature ID (e.g. https://dashboard.ranger.net/features/{feature_id})
+5. **Link to dashboard** - Whenever you are mentioning a feature review, send out the full URL instead of just the feature ID (e.g. https://dashboard.ranger.net/features/{feature_id})
 
 ---
 
@@ -220,6 +221,6 @@ Once you're done verifying, and just before stopping the session, share the feat
 
 If you encounter authentication issues:
 
-1. **Check your environments**: Run `ranger env ls` to see all configured environments and their details
-2. **Switch environments**: Use `ranger use <env-name>` to switch to a different environment
-3. **Refresh auth**: Run `ranger env update <env-name>` to re-capture authentication for an environment (user will need to help with that)
+1. **Check your profiles**: Run `ranger profile ls` to see all configured profiles and their details
+2. **Switch profiles**: Use `ranger profile use <profile-name>` to switch to a different profile
+3. **Refresh auth**: Run `ranger profile update <profile-name>` to re-capture authentication for a profile (user will need to help with that)

package/build/skills/ranger/create.md

@@ -1,47 +1,47 @@
-# Creating a New Feature
+# Creating a New Feature Review
 
-Create a feature when starting new work that doesn't have an existing feature to resume.
+Create a feature review when starting new work that doesn't have an existing feature review to resume.
 
 ## Basic Command
 
 ```bash
-ranger feature create "<feature name>" \
+ranger create "<feature review name>" \
   --description "<description>" \
-  -c "<checklist item 1>" \
-  -c "<checklist item 2>"
+  -c "<scenario 1>" \
+  -c "<scenario 2>"
 ```
 
-Use multiple `-c` flags for multiple checklist items. Each item can contain commas.
+Use multiple `-c` flags for multiple scenarios. Each scenario can contain commas.
 
 ## What Gets Captured Automatically
 
-When you create a feature, the CLI automatically captures:
+When you create a feature review, the CLI automatically captures:
 - **Git repo URL** - From `git remote get-url origin`
 - **Git branch** - From current branch name
 - **Created timestamp**
 - **Your organization** - From API token
 
-This enables `ranger feature list` to filter features by git context later.
+This enables `ranger list` to filter feature reviews by git context later.
 
-## Writing Good Checklist Items
+## Writing Good Scenarios
 
-**CRITICAL: Checklist items are E2E test scenarios, NOT a TODO list.**
+**CRITICAL: Scenarios are E2E test flows, NOT a TODO list.**
 
-Ranger verifies checklist items by running them in a real browser. Each item must describe a **complete user journey** that can be tested through the UI.
+Ranger verifies scenarios by running them in a real browser. Each scenario must describe a **complete user journey** that can be tested through the UI.
 
 ### Key Principles
 
 **Brevity is paramount.** Testing takes developer time. Your job is to identify only the most critical user flows—not to exhaustively cover every scenario.
 
-1. **Start minimal** - Propose **1 item** for most features, **2 items max** for large features. You can always add more later if needed.
+1. **Start minimal** - Propose **1 scenario** for most features, **2 scenarios max** for large features. You can always add more later if needed.
 2. **High-level flows only** - Describe the key user journey at a high level. Don't get granular unless explicitly asked.
-3. **E2E flows only** - Each item is a test a QA engineer would run in the browser
+3. **E2E flows only** - Each scenario is a test a QA engineer would run in the browser
 4. **Must be UI-testable** - No backend-only work, no code changes, no infrastructure tasks
 5. **Happy path focus** - Describe the successful user journey, not edge cases
 
 The goal is to quickly validate that the core functionality works—not to build a comprehensive test suite.
 
-### What Checklist Items Are NOT
+### What Scenarios Are NOT
 
 ❌ **NOT a TODO list** - Don't list implementation tasks
 ```
@@ -64,7 +64,7 @@ Bad: "Form has 3 fields"
 Bad: "Error message is red"
 ```
 
-### What Checklist Items ARE
+### What Scenarios ARE
 
 ✅ **Complete E2E user flows** that a QA tester would execute:
 
@@ -102,28 +102,28 @@ Good: "User can create a new project, invite a team member, and see them in the
 1. User can navigate to Reports, click Export, select CSV format, and download the file
 ```
 
-### When to Use Multiple Items
+### When to Use Multiple Scenarios
 
-**Default to 1 item.** Only propose 2 items if the feature genuinely requires distinct user journeys.
+**Default to 1 scenario.** Only propose 2 scenarios if the feature genuinely requires distinct user journeys.
 
-- Adding a button? **1 item** - the complete flow of using it
-- Login + signup? **2 items** - these are separate user journeys with different entry points
-- Full CRUD? **Start with 1-2 items** - test the core flow first (e.g., create + view), add more only if asked
+- Adding a button? **1 scenario** - the complete flow of using it
+- Login + signup? **2 scenarios** - these are separate user journeys with different entry points
+- Full CRUD? **Start with 1-2 scenarios** - test the core flow first (e.g., create + view), add more only if asked
 
 **Do not** try to cover every permutation. Start high-level, and the developer can request additional coverage if needed.
 
 ## Complete Example
 
-**Simple feature (1 item):**
+**Simple feature (1 scenario):**
 ```bash
-ranger feature create "Add Export Button" \
+ranger create "Add Export Button" \
   --description "Add export functionality to the reports page" \
   -c "Navigate to Reports page, click the new Export button, select CSV format, and verify the file downloads"
 ```
 
-**Larger feature (multiple items):**
+**Larger feature (multiple scenarios):**
 ```bash
-ranger feature create "User Authentication" \
+ranger create "User Authentication" \
   --description "Login and signup flows for the web app" \
   -c "Go to login page and sign in with valid credentials, verify redirect to dashboard" \
   -c "Go to signup page and create new account, verify welcome email and successful login"
@@ -132,9 +132,9 @@ ranger feature create "User Authentication" \
 ## Output
 
 ```
-Creating feature...
+Creating feature review...
 
-✅ Feature created: feat_01abc123
+✅ Feature review created: feat_01abc123
 
 🔄 User Authentication (feat_01abc123)
    Status: in_progress
@@ -143,16 +143,16 @@ Creating feature...
    Branch: feature/auth
    Created: 1/21/2026, 10:30:00 AM
 
-   Checklist:
+   Scenarios:
    1. ⬜ Go to login page and sign in...
    2. ⬜ Go to signup page and create...
 
-➡️  Set as active feature
+➡️  Set as active feature review
 ```
 
 ## After Creation
 
-The new feature is automatically set as the active feature. You can now:
+The new feature review is automatically set as the active feature review. You can now:
 
-1. Start implementing the first checklist item
-2. View status with `ranger feature show`
+1. Start implementing the first scenario
+2. View status with `ranger show`

package/build/skills/ranger/feedback.md

@@ -1,34 +1,37 @@
 # Addressing Reviewer Feedback
 
-When a reviewer leaves comments on checklist items, a new version (v2) of the item is created to incorporate the feedback. The reviewer's comments were left on the **previous version** (v1), but they are the reason this v2 item exists. Use this workflow to understand what the reviewer wants, fix the code, and re-verify.
+When a reviewer leaves comments on scenarios, a new version (v2) of the scenario is created to incorporate the feedback. The reviewer's comments were left on the **previous version** (v1), but they are the reason this v2 scenario exists. Use this workflow to understand what the reviewer wants, fix the code, and re-verify.
 
-v2+ items inherit comments from their parent version. Run `get-feedback` to see them.
+v2+ scenarios inherit comments from their parent version. Run `get-review` to see them.
 
 ## When This Applies
 
-- Items show as v2/v3 with `[has reviewer feedback]` tag
-- `ranger feature resume` prints a warning about unaddressed comments
+- Scenarios show as v2/v3 with `[has reviewer feedback]` tag
+- `ranger resume` prints a warning about unaddressed comments
 
 ## Step 1: Read the Feedback
 
 ```bash
-ranger feature get-feedback
+ranger get-review
 ```
 
-This shows ALL reviewer comments across all items, including:
+This shows ALL reviewer comments across all scenarios, including:
 - The specific comment content and who wrote it
 - The previous version description (what changed from v1 to v2)
 - The expected flow from prior verification (canonical flow)
+- **Annotated screenshots** — when a reviewer annotated a screenshot, the image is downloaded locally and the annotation coordinates are shown
 
 ### Example Output
 
 ```
 📋 Feedback for: User Authentication (feat_abc123)
 
-Item 1: "User can log in" (v2) — 2 unaddressed comments (from previous version)
+Scenario 1: "User can log in" (v2) — 2 unaddressed comments (from previous version)
   Previous version: "User can log in with email"
-  This item was created to address the following reviewer feedback:
-  💬 Jane (Feb 5): "Password field should show/hide toggle"
+  This scenario was created to address the following reviewer feedback:
+  💬 Jane (Feb 5): "This button is misaligned"
+     📷 Screenshot: /path/to/.ranger/feedback-images/comment_abc123.png
+     📍 Annotation: point at (0.45, 0.32)
   💬 Bob (Feb 5): "Error message not visible on failed login"
   Expected flow:
     1. Navigate to /login
@@ -36,29 +39,34 @@ Item 1: "User can log in" (v2) — 2 unaddressed comments (from previous version
     3. Click Submit
     4. Verify dashboard appears
 
-Item 2: "Dashboard loads" — 0 comments
+Scenario 2: "Dashboard loads" — 0 comments
   ✅ No feedback to address
 ```
 
+### Reading Annotated Screenshots
+
+When the output includes `📷 Screenshot:` lines with a local file path, **use the `Read` tool on that file path** to see the screenshot the reviewer was commenting on. The `📍 Annotation:` line shows the normalized (0-1) coordinates where the reviewer placed their comment — this tells you exactly where on the screen the reviewer is pointing. Use both the visual screenshot and the coordinates to understand the spatial context of the feedback.
+
 ## Step 2: Fix the Code
 
 For each unaddressed comment:
 1. Read the comment carefully — what is the reviewer asking for?
-2. Look at the "previous version" description to understand what changed
-3. If a canonical flow is provided, that's the expected user journey to verify against
-4. Make the code changes that address each concern
+2. If a screenshot path is shown (`📷 Screenshot:`), **read the image file** to see what the reviewer sees. Correlate the annotation coordinates with the comment text to understand exactly which UI element the reviewer is referring to.
+3. Look at the "previous version" description to understand what changed
+4. If a canonical flow is provided, that's the expected user journey to verify against
+5. Make the code changes that address each concern
 
 ## Step 3: Re-verify
 
 ```bash
-ranger verify-feature --item <N>
+ranger go --scenario <N>
 ```
 
 The verification agent **automatically receives the reviewer comments** in its prompt. It will specifically check that each reviewer concern was addressed in the current implementation.
 
 ## Key Points
 
-- Always run `get-feedback` **before** making code changes — understand what the reviewer wants first
-- v2+ items inherit their parent's comments — those comments are the reason this version exists
-- The verify-feature command auto-injects feedback into the browser agent's prompt, so you don't need to manually include comments in your `--task` description
+- Always run `get-review` **before** making code changes — understand what the reviewer wants first
+- v2+ scenarios inherit their parent's comments — those comments are the reason this version exists
+- The go command auto-injects feedback into the browser agent's prompt, so you don't need to manually include comments in your `--notes` description
 - Address ALL unaddressed comments before re-verifying — partial fixes may result in another review round