web-tester-for-claude 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haroon Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,651 @@
+# web-tester-for-claude
+
+> Let your coding agent **see and verify** the web changes it makes. web-tester
+> drives your dev site, captures everything to one report, and runs a whole
+> flow in a **single model turn** — not a dozen turn-by-turn tool calls.
+
+web-tester wraps Chromium with a single, opinionated capture pipeline: every
+console line, every network request, every page error, every step screenshot,
+the whole video, the full DOM if you ask for it — into one self-contained
+HTML report and one structured `result.json` per run. The agent reads back only
+the slices it needs, so the **edit → verify → edit loop stays cheap and fast**
+even across many steps.
+
+It's intentionally a *toolkit*, not a pipeline. There is no LLM stage, no
+test generation, no judging. You (or an AI agent like Claude Code) decide
+what to look at; `web-tester` just makes it cheap to look.
+
+```bash
+# Quick verify a change — fail on any 5xx, assert text is visible, in ~6s
+npx web-tester-for-claude inspect "/products/widget" \
+  --step settle --quick \
+  --expect "text=Add to Cart" \
+  --fail-on http-5xx
+
+# Drive a flow, capture state at every step
+npx web-tester-for-claude inspect "/products/widget" \
+  --step settle \
+  --step screenshot:initial \
+  --step "click:button:has-text(\"Add to Cart\")" \
+  --step wait:networkidle \
+  --step goto:/cart \
+  --step screenshot:cart
+
+# Bulk-sweep many URLs in parallel
+npx web-tester-for-claude sweep --sitemap --filter '^/products/' --concurrency 4 \
+  --fail-on http-5xx
+```
+
+---
+
+## Why web-tester
+
+You can drive Playwright yourself, of course. web-tester earns its weight in
+three ways that show up every day:
+
+1. **Disk-as-cache report shape.** One run captures everything to
+   `.web-tester/runs/<id>/`, and the CLI prints the path to a self-contained
+   `report.html`. AI agents read `result.json` selectively
+   (`jq '.steps[3].network'`) instead of pulling every byte of browser
+   state back into their conversation context. For "reproduce this bug,
+   tell me what happened" tasks this uses **5–10× fewer tokens** than
+   piping DOM snapshots back through stdout.
+2. **One step grammar.** No heredoc Playwright scripts to maintain.
+   `--step click:…`, `--step fill:…=…`, `--step wait:url-contains:…` —
+   composable, copy-pasteable from a recipe, no boilerplate.
+3. **Knowledge files travel with the repo.** Drop project quirks into
+   `.web-tester/instructions/*.md` and any future session — yours or your
+   AI agent's — gets them as a warm start instead of re-discovering them.
+
+The HTML report has a sticky video player with speed presets, a step
+timeline with screenshot + console/network slices, lightboxed full-page
+screenshots, and collapsible global logs. Open it first; the JSON is for
+programmatic reads.
+
+---
+
+## Why a CLI, and not an MCP server?
+
+[Microsoft's Playwright MCP](https://github.com/microsoft/playwright-mcp) is
+excellent for *live, interactive* browser control — the agent decides each
+click as it goes. web-tester is deliberately a **CLI** instead, because a
+coding agent's job isn't to click around live; it's to **verify a change it
+just made**, repeatedly, per project. A CLI fits that better in three ways an
+MCP server structurally can't:
+
+- **It learns the project over time.** Everything lives in `.web-tester/` —
+  recipes, instructions, a route map, journeys — and *grows* as you use it. The
+  next session gets a warm start instead of rediscovering your site. An MCP
+  server is stateless per project; it remembers nothing between runs.
+- **It produces artifacts.** One run writes a self-contained `report.html`
+  (video + step timeline) and a structured `result.json` you can diff, attach
+  to a PR, or hand to CI. MCP returns everything into the conversation and
+  it's gone.
+- **It barely touches context.** MCP returns a full page snapshot into the
+  conversation on *every* step; those tokens pile up and never leave. web-tester
+  runs the whole flow in one process and hands back a compact verdict — the
+  agent reads `result.json` slices only if it needs them.
+
+### Measured: tokens, round-trips, and cost
+
+The same task, run each way — counting what enters the model's context, the
+model round-trips, and the resulting **token cost** ([methodology](#methodology)):
+
+![web-tester vs Playwright MCP — tokens into context per task](docs/mcp-comparison.svg)
+
+| Task | Tool | Input tok | Output tok | Round-trips | Cost / run | Per 1,000 runs |
+|---|---|--:|--:|--:|--:|--:|
+| **TodoMVC**<br>add 3, complete 1, filter | Playwright MCP | ~1,240 | ~600 | 6 | $0.013 | $12.70 |
+| | **web-tester** | **~300** | ~150 | **1** | **$0.003** | **$3.16** · 4× less |
+| **Hacker News**<br>verify front page | Playwright MCP | ~10,100 | ~100 | 1 | $0.032 | $31.80 |
+| | **web-tester** | **~220** | ~150 | 1 | **$0.003** | **$2.90** · 11× less |
+
+Cost is at Claude Sonnet 4.6 list price ($3 / $15 per 1M input / output tokens)
+and scales linearly with whatever model you run (≈1.7× at Opus 4.8 rates). Input
+tokens are measured; output is a modest per-round-trip estimate.
+
+Two honest caveats: **raw browser time is comparable** (same engine — the time
+that matters is *model round-trips*, not browser speed), and these numbers
+*under*-count MCP — we reproduced its payload with Playwright's aria snapshot,
+which omits the per-node `[ref]` metadata MCP also sends, and we bill each
+context token only once (a real agent loop re-sends the growing context every
+turn, so MCP's snapshots get re-billed; prompt caching offsets some of that).
+The single Hacker News snapshot alone is ~10k tokens.
+
+### And it compounds on reruns
+
+The bigger win isn't the first run — it's the *second*. Playwright MCP has no
+project memory: every rerun re-explores the page from scratch, at full cost.
+web-tester saves the flow on the first run (`inspect … --save-journey todomvc`)
+as a **~500-byte plain-text recipe** — just the URL, the steps, and the
+assertions. Not HTML, not snapshots; the big `report.html`/video stay in the
+disposable `runs/` folder and are never reused. Every rerun is then one command
+(`web-tester journey todomvc`) that replays those steps live — no snapshots, no
+re-deriving selectors. So the cost gap widens with every repeat:
+
+![Cumulative cost across 5 reruns of the same task](docs/mcp-cost.svg)
+
+| | Run 1 (fresh) | each rerun | cost after 5 runs |
+|---|---|---|---|
+| **Playwright MCP** | $0.013 · 6 round-trips | $0.013 · 6 round-trips | **$0.064 · 30 round-trips** |
+| **web-tester** | $0.003 · 1 round-trip (+saves the journey) | $0.002 · 1 round-trip | **$0.012 · 5 round-trips** |
+
+That's the whole point of a per-project CLI: it *accumulates*. Recipes,
+journeys, and the route map become the project's test memory — the agent does
+the expensive exploration once and replays it for free, while a stateless MCP
+server pays full price every time.
+
+**The two pair well, they don't compete.** Use Playwright MCP for open-ended,
+exploratory clicking; use web-tester to verify changes cheaply, sweep pages,
+and build the project's test memory. web-tester can even hand MCP a logged-in
+session (its saved storage state) when you want to drive an authenticated app
+by hand.
+
+<sub><a name="methodology"></a>**Methodology:** tasks run against
+`demo.playwright.dev/todomvc` and `news.ycombinator.com`, June 2026. MCP input =
+the accessibility snapshot returned per action (captured via Playwright's
+`ariaSnapshot()` on the same live pages); web-tester input = the CLI's printed
+summary; a rerun = `web-tester journey todomvc` against a saved journey. Output
+tokens are a modest per-round-trip estimate. Dollar cost uses Claude Sonnet 4.6
+list pricing ($3 / $15 per 1M input / output). Tokens ≈ characters ÷ 4.
+Benchmark: [`docs/bench.js`](docs/bench.js); charts:
+[`docs/make-charts.js`](docs/make-charts.js).</sub>
+
+---
+
+## Install
+
+```bash
+npx web-tester-for-claude help          # zero-install, runs the latest from npm
+```
+
+Or as a project dev dep so the version is pinned:
+
+```bash
+npm install -D web-tester-for-claude
+npx web-tester-for-claude help
+```
+
+The first run will fetch Playwright's Chromium binary on demand if it's not
+already on disk (`npx playwright install chromium` to do it explicitly).
+
+---
+
+## Quick start
+
+```bash
+# 1. Interactive setup: scaffolds .web-tester/, writes a Claude Code skill +
+#    CLAUDE.md section, saves your base URL. (Bare `npx web-tester-for-claude` on a fresh
+#    project runs this automatically.)
+npx web-tester-for-claude init
+
+# 2. Start your dev server
+npm run dev    # whatever your dev command is
+
+# 3. Map the running site → preset + recipes + journey drafts, all auto-generated
+npx web-tester-for-claude map
+
+# 4. Verify a single URL works end-to-end
+npx web-tester-for-claude inspect / \
+  --step settle --quick \
+  --expect "selector=main" \
+  --fail-on http-5xx
+```
+
+The CLI prints the absolute path to `report.html` at the end of every run —
+open it in a browser. Run artifacts land in `.web-tester/runs/` in your project
+(override with `WEB_TESTER_RUNS_DIR`).
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init` | Scaffold `.web-tester/` and wire the agent-instructions section into your `CLAUDE.md` / `AGENTS.md`. Run once per project. |
+| `map` | Crawl your running site, classify every page, and auto-generate a sweep preset, smoke recipes, and form journey drafts. |
+| `inspect <url>` | Drive one page, optionally with `--step …`, capture everything. |
+| `sweep` | Run inspect concurrently across many URLs (one Chromium, N contexts). |
+| `journey <name>` | Run a saved JSON journey from `.web-tester/journeys/<name>.json`. |
+| `journey` (no arg) | List available journeys. |
+| `impact` | Diff-aware advisory run — match changed files against rules in `.web-tester/impact-rules.json` and run the indicated sweeps/journeys. **Always exits 0.** |
+| `kb` / `kb <topic>` | List or print a `.md` file in `.web-tester/instructions/` (or `.web-tester/`). |
+| `help` | Full reference. |
+
+Every command targets `http://localhost:3000` by default. Point at anything
+else with `WEB_TESTER_BASE_URL=…`.
+
+---
+
+## Setup — `web-tester init`
+
+The **first time** you run web-tester in a project, it drops into an
+interactive setup (you can also run it explicitly any time):
+
+```bash
+npx web-tester-for-claude          # first run → guided setup
+npx web-tester-for-claude init     # or run setup explicitly
+```
+
+It asks a few questions (each with a sensible default — just press Enter):
+your dev server base URL, which agent file to write, how eagerly Claude
+should reach for web-tester, whether to generate a Claude Code skill, and
+whether to install Chromium now. Then it writes:
+
+- **`.web-tester/`** — starter `impact-rules.json`, `urls-smoke.txt`, an
+  example journey, `instructions/` recipes, and a `config.json` holding your
+  base URL (so commands work without setting `WEB_TESTER_BASE_URL`). Run
+  artifacts go in `.web-tester/runs/`, gitignored automatically.
+- **`.claude/skills/web-tester/SKILL.md`** — a [Claude Code
+  skill](https://docs.claude.com/en/docs/claude-code/skills) so Claude can
+  drive web-tester natively (auto-invoked for runtime-behavior questions, or
+  on demand via `/web-tester`), with the right `Bash(npx web-tester-for-claude *)`
+  permissions pre-approved.
+- **`CLAUDE.md`** (or `AGENTS.md`) — a marker-fenced agent-instructions block
+  teaching *when* to reach for web-tester. Re-running replaces it in place;
+  your surrounding notes are untouched.
+- **`.claude/settings.local.json`** — your `WEB_TESTER_AUTO_USE` preference,
+  merged in without clobbering existing settings.
+
+Everything is idempotent — existing files are skipped (settings and config are
+merged, never overwritten). Run non-interactively in CI with `--yes`.
+
+| Flag | Purpose |
+|---|---|
+| `-y, --yes` | Non-interactive; accept all defaults. |
+| `--base-url <url>` | Set the dev server base URL. |
+| `--auto-use <on\|ask\|off>` | How eagerly Claude should reach for web-tester. |
+| `--no-skill` | Don't generate the Claude Code skill. |
+| `--no-agent` / `--agent-file <p>` | Skip, or target a specific agent file. |
+| `--install-browser` | Fetch Chromium during setup. |
+| `--force` | Overwrite existing scaffolded files. |
+
+---
+
+## Mapping a site — `web-tester map`
+
+Point `map` at your running dev server and it crawls the site, classifies
+every page, and writes a ready-to-use coverage starter kit — no hand-authoring:
+
+```bash
+npx web-tester-for-claude map                       # crawl from BASE_URL (uses sitemap.xml if present)
+npx web-tester-for-claude map /docs                 # crawl just the /docs subtree
+npx web-tester-for-claude map --no-sitemap --depth 2  # follow links only, two hops deep
+```
+
+It discovers pages two ways: it seeds from `sitemap.xml` when one exists, and
+follows same-origin links breadth-first. Each page is classified (`home`,
+`list`, `detail`, `form`, `auth`, `search`, `content`) and collapsed by route
+template (`/products/12` and `/products/34` → `/products/:id`, capped per
+template so a big catalog can't dominate). From that it generates, into
+`.web-tester/`:
+
+- **`urls-map.txt`** — one representative path per route, annotated with the
+  strongest expectation pack each page satisfied. Sweep it with
+  `web-tester sweep --preset map --fail-on http-5xx`.
+- **`instructions/recipes.md`** — a copy-paste `inspect` one-liner per page
+  type, in a marker-fenced block that `map` refreshes on each run.
+- **`journeys/*.json`** — a draft journey per distinct form found (fields
+  pre-filled with sample values). Review the selectors, values, and add
+  expectations before relying on them.
+
+Plus an HTML site map (`runs/map-<id>/map.html`) with a screenshot, status,
+and link count per route.
+
+| Flag | Purpose |
+|---|---|
+| `--limit <n>` | Max pages to fetch (default 50). |
+| `--depth <n>` | Max link hops when crawling (default 3; ignored for sitemap seeds). |
+| `--per-template <n>` | Max pages fetched per route template (default 3). |
+| `--max-journeys <n>` | Cap on generated journey drafts (default 12). |
+| `--no-sitemap` | Don't seed from `sitemap.xml`; follow links only. |
+| `--sitemap <url>` | Use a specific sitemap URL. |
+| `--filter` / `--exclude <regex>` | Keep / drop matching paths. |
+| `--no-screenshots` | Skip per-page screenshots (faster). |
+| `--force` | Overwrite existing generated journeys. |
+
+Everything `map` writes is yours to edit — it's a starting point that turns a
+cold project into a covered one in one command.
+
+---
+
+## What lands in `runs/<id>/`
+
+| File | Contents |
+|---|---|
+| `report.html` | **Self-contained HTML report.** Open this first. |
+| `result.json` | Full structured report — same data as the HTML. Programmatic reads. |
+| `video/page@<hash>.webm` | Screen recording (omit with `--no-video` or `--quick`). |
+| `initial.png` / `initial-full.png` | Viewport + full-page after first load. |
+| `final.png` / `final-full.png` | Viewport + full-page after last step. |
+| `steps/NN-<label>.png` | One screenshot per step. |
+| `initial.html` / `final.html` | Page HTML (only if `--html`). |
+| `console.json`, `network.json` | Raw streams (also embedded in `result.json`). |
+
+`--quick` is the most useful flag: no video, no full-page screenshots, no
+HTML capture, no AI summary. Pair with `--expect` / `--fail-on` for a real
+pass/fail gate in 5–10s.
+
+---
+
+## Step grammar
+
+`--step` can be repeated. Steps run sequentially, with their own screenshot
+plus the slice of console / network / page-errors produced *during* that step.
+
+```
+goto:<url>                          navigate (absolute or path)
+reload                              reload current page
+wait:<load|domcontentloaded|networkidle>
+wait:<ms>                           sleep N ms
+wait:<selector>                     wait for selector
+wait:text=<exact text>              wait for matching text
+wait:url-stable[=<ms>]              wait until URL changes at least once then
+                                    stays still for <ms> (default 250)
+wait:url-contains:<sub>[@<ms>]      wait until URL contains <sub>
+                                    (use @ not = so <sub> can include '=')
+settle[:<ms>]                       wait for data-attr-selected-label to
+                                    populate on any [data-attr-name] element.
+                                    Fast-paths in ~3s if none are present.
+                                    Apps without data-attrs should prefer
+                                    'wait:networkidle'.
+click:<selector>                    click (Playwright locator; supports CSS
+                                    and :has-text())
+hover:<selector>
+fill:<selector>=<value>             native input
+react-fill:<selector>=<value>       React-controlled input (calls the native
+                                    value setter + dispatches synthetic
+                                    input/change/blur events)
+press:<selector>=<key>              keyboard press
+select:<selector>=<value>           native <select>
+scroll:<top|bottom|<px>>
+screenshot[:<name>]                 viewport screenshot
+screenshot-full[:<name>]            full-page screenshot
+eval:<JS expression>                run in page context; result attached to step
+```
+
+For long step chains, drop them in a JSON file and pass `--steps-file flow.json`:
+
+```json
+["settle", "screenshot:initial", "click:button:has-text(\"Submit\")",
+ "wait:networkidle", "goto:/thanks"]
+```
+
+---
+
+## Verdict & assertions
+
+Use these to turn a run into a real pass/fail gate.
+
+| Flag | Purpose |
+|---|---|
+| `--fail-on <list>` | Comma-sep kinds that flip `ok` to false: `page-errors`, `console-errors`, `4xx`, `5xx`. Exit code 1 on any trigger. |
+| `--expect <kind>=<value>` | (Repeatable) final-page assertion. Kinds: `text=…`, `no-text=…`, `selector=…`, `no-selector=…`, `attr=<Name>:<value>`. |
+| `--persist <ms>` | Re-check every `--expect` after waiting `<ms>`. **Both** checks must pass — catches transient state (a toast that flashes for 1s then disappears). |
+
+```bash
+# Don't trust a single check for derived state. --persist re-validates.
+npx web-tester-for-claude inspect /pricing \
+  --step settle --quick \
+  --expect "text=$49/mo" \
+  --persist 2500 \
+  --fail-on http-5xx
+```
+
+---
+
+## Deeper capture — `--deep`
+
+When a one-line console message isn't enough, add `--deep` to `inspect`. It
+turns on three heavier signals that are off by default:
+
+- **Request + response bodies** for XHR/fetch/document requests (textual
+  content only, truncated). The bug is often *in the payload* — a `200` that
+  returns `{"error":"out of stock"}` looks fine until you read the body.
+- **Local scope at every uncaught exception.** web-tester attaches a Chrome
+  DevTools Protocol debugger, pauses on each throw, dumps the throwing
+  function's local + closure variables, and resumes immediately. Instead of
+  just `TypeError: cannot read 'id' of undefined`, you get
+  `local: userId=42, cart={ items: 3, total: 9.99 }` at the throw site.
+- **Unhandled promise rejections**, which the normal `pageerror` stream
+  misses entirely.
+
+```bash
+npx web-tester-for-claude inspect /checkout \
+  --deep --quick \
+  --step "click:button:has-text(\"Pay\")" \
+  --step wait:networkidle
+```
+
+The CLI prints the exceptions with their scope; the full dump (and bodies)
+land in `result.json` under `deepErrors`, `unhandledRejections`, and each
+`network.entries[].responseBody`. The debugger pauses add overhead, so reach
+for `--deep` when you're diagnosing a specific failure, not on every run.
+
+---
+
+## Authentication
+
+Most real flows live behind a login. web-tester drives the login **once** and
+reuses the session, so gated pages work without logging in every run.
+
+```bash
+# 1. Run your login flow with --save-session
+web-tester inspect /login \
+  --step "fill:input[name=email]=test@example.com" \
+  --step "fill:input[name=password]=your-test-password" \
+  --step "click:button[type=submit]" \
+  --step "wait:url-contains:/dashboard" \
+  --save-session
+
+# 2. Every later inspect / sweep / journey is now authenticated automatically.
+web-tester inspect /account --quick --expect "text=Sign out"
+
+# Force a logged-out run any time:
+web-tester inspect / --no-session
+```
+
+`--save-session` writes the browser session — cookies + localStorage — to
+`~/.web-tester/session.json`. That file is **machine-local**: it lives in your
+home directory, not the repo, and is never committed. It's saved only after a
+clean run (so a failed login can't overwrite a good session), and refreshed
+automatically on later runs so rotating tokens keep working. You can save the
+login as a journey (`--save-journey login`) and re-authenticate with
+`web-tester journey login --save-session`.
+
+> ⚠️ **Use test credentials only — at your own risk.**
+>
+> Anything you put in a `--step`, a saved journey, or otherwise hand to
+> web-tester is **visible to the AI agent** driving it. Credentials written
+> into a step are stored in **plain text** in `.web-tester/journeys/*.json`,
+> which is committed to your repo. The saved session in
+> `~/.web-tester/session.json` grants access to anything that account can reach.
+>
+> Never use production, personal, or privileged accounts. Use a **disposable
+> test account** scoped to a safe environment, and treat anything reachable
+> with it as exposed. You assume all responsibility for credentials, tokens,
+> and actions taken with them.
+
+---
+
+## `.web-tester/` — your project's recipes
+
+Everything project-specific lives in `.web-tester/` at your project root.
+All files are optional; commands fail gracefully when they're missing.
+
+```
+.web-tester/
+  impact-rules.json        # rules for `web-tester impact`
+  urls-<name>.txt          # URL preset for `web-tester sweep --preset <name>`
+  journeys/<name>.json     # saved flows for `web-tester journey <name>`
+  instructions/*.md        # knowledge base (or .web-tester/*.md flat for
+                           # small projects)
+```
+
+### `impact-rules.json`
+
+Each rule names a set of path globs and what to run if any changed file
+matches. `web-tester impact` reads `git diff` against `origin/main` (or
+`--base <ref>`) and executes matched rules. **Advisory only — never blocks
+your push.**
+
+```json
+{
+  "rules": [
+    {
+      "name": "Auth code changed — full sign-up journey",
+      "when_changed_any": ["src/auth/**", "src/pages/api/auth/**"],
+      "journey": "signup"
+    },
+    {
+      "name": "Shared layout changed — sweep top pages",
+      "when_changed_any": ["src/components/Layout/**"],
+      "sweep": {
+        "urls": ["/", "/pricing", "/docs"],
+        "packs": ["homepage"]
+      }
+    }
+  ]
+}
+```
+
+### `urls-<name>.txt`
+
+Newline-separated URLs/paths. `#` comments allowed. Per-URL `#pack=<name>`
+annotations apply the named expectation pack on top of anything global.
+
+```
+# urls-smoke.txt
+/                          #pack=homepage
+/pricing
+/docs                      #pack=has-h1 #pack=has-main
+```
+
+### `journeys/<name>.json`
+
+Bundles a URL + step chain + assertions for `web-tester journey <name>`.
+
+```json
+{
+  "description": "User signs up, lands on dashboard",
+  "url": "/signup",
+  "steps": [
+    "settle",
+    "fill:input[name=email]=test@example.com",
+    "fill:input[name=password]=hunter2",
+    "click:button[type=submit]",
+    "wait:url-contains:/dashboard"
+  ],
+  "expectations": ["text=Welcome", "selector=[data-test=dashboard]"],
+  "failOn": "http-5xx"
+}
+```
+
+### `instructions/*.md`
+
+Plain-English notes on your project's quirks. Run `web-tester kb` to list
+them, `web-tester kb <topic>` to print one. AI agents read these instead of
+re-discovering domain knowledge by grepping your source.
+
+---
+
+## Built-in expectation packs
+
+Pass `--pack <name>` to apply one to every URL in a sweep, or annotate
+URLs in a `urls-*.txt` file with `#pack=<name>`.
+
+| Pack | Asserts |
+|---|---|
+| `homepage` | `<header>` + `<footer>` present |
+| `static` | `<header>` + `<footer>` present |
+| `category` | `<header>` + `<footer>` + an internal anchor inside `<main>` containing an `<img>` |
+| `has-main` | `<main>` present |
+| `has-h1` | `<h1>` present |
+
+Add project-specific packs in `src/inspector/packs.ts` (PRs welcome for
+genuinely generic patterns) or wrap web-tester with your own pre-flight
+script that injects `--expect …` flags.
+
+---
+
+## Environment
+
+| Var | Default | Purpose |
+|---|---|---|
+| `WEB_TESTER_BASE_URL` | `http://localhost:3000` | Resolves bare paths to absolute URLs. |
+| `GOTO_TIMEOUT_MS` | `30000` | Initial `page.goto` timeout. |
+| `STEP_TIMEOUT_MS` | `15000` | Per-step action timeout. |
+| `SETTLE_TIMEOUT_MS` | `30000` | `settle` step ceiling. |
+
+`.env` files in the cwd are loaded automatically (via `dotenv`).
+
+---
+
+## Report shape (excerpt)
+
+```jsonc
+{
+  "runId": "2026-06-04T17-12-03",
+  "ok": false,
+  "video": "video/page@abc….webm",
+  "requestedUrl": "http://localhost:3000/products/widget",
+  "finalUrl": "http://localhost:3000/cart",
+  "title": "Cart | Acme",
+  "durationMs": 8423,
+  "failedSteps": 0,
+  "verdictTriggers": [],
+  "initial": { "screenshot": "initial.png", "attrs": [] },
+  "final":   { "screenshot": "final.png",   "attrs": [] },
+  "console": { "totals": { "error": 1, "log": 14 }, "entries": [] },
+  "network": { "count": 23, "failedCount": 1, "entries": [] },
+  "pageErrors": [],
+  "steps": [
+    {
+      "index": 1,
+      "step": { "kind": "click", "selector": "button:has-text(\"Submit\")" },
+      "label": "click button:has-text(\"Submit\")",
+      "ok": true,
+      "durationMs": 412,
+      "url": "http://localhost:3000/products/widget",
+      "screenshot": "steps/01-click.png",
+      "console": [],
+      "network": [{ "method": "POST", "url": ".../cart", "status": 200, "durationMs": 187 }],
+      "pageErrors": []
+    }
+  ]
+}
+```
+
+---
+
+## What it is *not*
+
+- Not an LLM pipeline: `map` generates scaffolding **deterministically** from
+  what it observes in the browser — no model picks your assertions. (The
+  optional `--summary` is the one exception, and it's off by default.)
+- Not a judge: nothing decides whether a result is good or bad.
+- Not a test runner: there are no `expect()` calls, no pass/fail beyond
+  the literal "did the steps execute, did the `--expect` flags hold" gate.
+
+What `map` writes is a *starting point* — the meaningful assertions, the
+which-flows-matter decisions, the weighing of a finding all still belong to
+you, or to your AI agent reading the report.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. Run the type check:
+
+```bash
+npm run tsc
+```
+
+The codebase is intentionally small (~3K LOC) and TypeScript with no
+runtime deps beyond `playwright`, `tsx`, and `dotenv`. Keep it that way.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).