new changes

qa/README.md

@@ -37,7 +37,32 @@ exactly those screenshots and API calls, and the report must show them.
 
 ## 2. Automate it with Claude Code
 
-From the repo root, use the prompt in
+**The quick way — the `qa` tool.** It assembles a *grounded* generation prompt
+(your card + the app model + the conventions) so Claude never guesses selectors,
+routes, or endpoints:
+
+```bash
+npm run qa:index                       # build the app-model grounding index (do once / after UI changes)
+node scripts/qa-tool.mjs list          # list scenario cards
+node scripts/qa-tool.mjs prompt BOOK-012   # print the grounded prompt — paste into Claude Code
+node scripts/qa-tool.mjs run    BOOK-012   # run the card's tests + open the evidence report
+```
+
+`npm run qa:index` reads the codebase and writes
+[`app-model.md`](app-model.md) / `app-model.json`: the routes, page objects,
+API endpoints, areas and accounts that actually exist. `prompt` embeds that plus
+the card and [`e2e/CLAUDE.md`](../e2e/CLAUDE.md) into one ready-to-paste ask, so
+the generated test is correct by construction. `run` wraps `run-tests.ps1` for
+the card's layer and opens the evidence.
+
+Generation stays human-in-the-loop: the tool prepares the grounded ask and runs
+the result; you (with Claude Code) write and review the test.
+
+**Prefer a screen?** `npm run qa:ui` opens a small local web UI (localhost:9500)
+over the same commands: pick a card, copy its grounded prompt, hit **Run tests**,
+and see the evidence report inline. Same engine, nicer front door.
+
+**Or by hand:** use the template in
 [`generate-test.prompt.md`](generate-test.prompt.md) with your card id. Claude
 reads the card and the conventions in [`e2e/CLAUDE.md`](../e2e/CLAUDE.md) and
 generates the spec using our page objects and fixtures.