Developer runs agent
       ↓
Agent reads source folder → understands page structure
       ↓
Gemini generates contextually valid dummy inputs
       ↓
Playwright opens localhost URL + fills inputs + navigates
       ↓
On validation error → extract error from DOM → Gemini corrects inputs → retry (up to 3x)
       ↓
Output: terminal narration + screenshots + markdown report + Playwright trace

git clone <this repo>
cd walkthrough-agent
npm install
npx playwright install chromium
cp .env.example .env
# Add your GEMINI_API_KEY to .env

# Analyze + generate inputs + run browser walkthrough
npx walkthrough-agent --url http://localhost:3000/signup --folder ./src/app/signup

# DOM-only mode (no source folder needed)
npx walkthrough-agent --url http://localhost:3000/login

# Analyze only — print PageAnalysis + InputMap, no browser
npx walkthrough-agent --url http://localhost:3000/signup --folder ./src --analyze-only

# Override entry file detection
npx walkthrough-agent --url http://localhost:3000 --folder ./src --entry App.tsx

# Adjust max retries
npx walkthrough-agent --url http://localhost:3000/signup --folder ./src --retries 5

output/run-2026-01-15-143022/
  report.md           ← walkthrough narrative
  trace.zip           ← Playwright trace (open at trace.playwright.dev)
  screenshots/
    01-page-load.png
    02-fill-email.png
    03-submit.png
    04-result.png

{
  "mcpServers": {
    "walkthrough-agent": {
      "command": "node",
      "args": ["/path/to/walkthrough-agent/dist/server.js"],
      "env": { "GEMINI_API_KEY": "your-key-here" }
    }
  }
}

Walkthrough Agent
──────────────────────────────────────────────────

Analyzing ./src/app/signup ...
   Entry file: page.tsx
   Found: email, password, confirm-password, submit
   Validation rules: valid email, min 8 chars, must match password

Generating inputs...
   email                → alex.morgan@testmail.dev
   password             → Walkthrough#42
   confirm-password     → Walkthrough#42

Output directory: output/run-2026-01-15-143022

   Opening http://localhost:3000/signup
    Page loaded
    email filled
    password filled
    confirm-password filled

   Submitting...
    Error detected: "Password must contain a special character"
    Retry 1/3 — correcting inputs...
    Submission successful

──────────────────────────────────────────────────
Screenshot(s) saved: 6 files in output/run-.../screenshots
Report saved:        output/run-.../report.md
Trace saved:         output/run-.../trace.zip