@ia-qa/qa-discovery 0.1.1 → 0.2.0

package/README.md

@@ -6,7 +6,8 @@
 
 It answers *what is there*. It does not yet tell you what to test, and it never returns a pass/fail verdict: this is reconnaissance, and pretending otherwise would be the most useful-looking lie a tool like this could tell.
 
-**Where this is going.** Reconnaissance is step one of a longer goal: reproduce what a senior QA engineer does when handed an unfamiliar app — work out what it is *for*, where it would hurt most if it broke, and produce a prioritised test plan you can question line by line. Every stage after this one reads the capture below and must cite it, because a plan nobody can interrogate is a plan nobody can trust. See [ROADMAP.md](./ROADMAP.md) for the arc and for what this will deliberately never become.
+**Where this is going.** Reconnaissance is step one of a longer goal: reproduce what a senior QA engineer does when handed an unfamiliar app — work out what it is *for*, where it would hurt most if it broke, and produce a prioritised test plan you can question line by line. Every stage after this one reads the capture below and must cite it, because a plan nobody can interrogate is a plan nobody can trust. `ROADMAP.md`, shipped in this package, has the arc and what this will deliberately never become.
+The tutorial is at [ia-qa.com/devtools/qa-discovery/tutorial](https://www.ia-qa.com/devtools/qa-discovery/tutorial).
 
 ```bash
 npx @ia-qa/qa-discovery scan https://your-app.example.com --save --report --open
@@ -16,6 +17,29 @@ npx @ia-qa/qa-discovery scan https://your-app.example.com --save --report --open
 
 ▶ **[See the full report](https://www.ia-qa.com/media/discover-report-full.png)** — one self-contained HTML file, written by `--report`. That is `ia-qa.com` scanned by its own tool, and it found something: all 37 of its input fields carry no `data-testid`, no `id` and no `name`, so any test written against them can only use a positional selector.
 
+## Which verb answers which question
+
+| Your question | Verb |
+|---|---|
+| what is even in this app? | `scan` — pages, headings, forms, fields, real API calls |
+| my app is behind a login | `login` — a visible browser, you log in, the session is reused |
+| most of the inputs are behind a menu or a tab | `scan --deep` — opens them one level and captures what they reveal |
+| **what does my test suite not test?** | **`coverage`** — the gap, ranked; needs `@ia-qa/self-healing` and one watched run |
+| what changed since last time? | `history` |
+| what is each entry point *for*, and how sensitive? | `ia-qa-discover-ai classify` (optional, your own key) |
+
+`ia-qa-discover <verb> --help` for flags. Nothing here emits a verdict and nothing here gates
+CI: a page count is not coverage, and a gap is a decision for a human.
+
+**Same operations for an AI agent** — one contract served twice, never a simplified view for
+one of them. `ia-qa-discover-mcp` exposes `scan_app`, `coverage_map`, `classify_app` and
+`discovery_history`. `login` is deliberately not a tool: it waits for a person at a browser.
+
+> **New here?** The [step-by-step tutorial](https://www.ia-qa.com/devtools/qa-discovery/tutorial)
+> walks the whole thing from an app you have never seen, with no jargon — first scan, login
+> wall, and "what does my suite not test" (same text as `TUTORIAL.md`, shipped in this
+> package). This README is the short reference.
+
 ---
 
 ## What a real session looks like
@@ -211,6 +235,32 @@ It refuses under CI and without a TTY: it waits for a person twice over, so a pi
 
 The file it produces holds live cookies — whoever has it is logged in as you. The path is announced before the browser opens, `.ia-qa-discovery/.gitignore` is written on the way out, and nothing here uploads it.
 
+### `coverage`
+
+**What your test suite does not test.** The one thing neither package can say alone: this one knows what exists, `@ia-qa/self-healing` knows where your suite actually went.
+
+```bash
+npx ia-qa-discover coverage
+```
+
+Reads local files only — no browser, no network, no argument. It compares the pages this scan found against the pages your suite was **observed** visiting, and ranks the gap by what each page takes as input: credentials, writes, required fields, API calls. The factors *are* the ranking — there is no score, because a single number invites tuning and hides that a page ranks high for a reason you may consider irrelevant.
+
+It also reports **depth**: how many of each visited page's contracted elements your tests actually name. Named is not asserted — a test that clicks a button names it without checking anything, and nothing on disk can tell the two apart, so this never says "tested".
+
+**It needs a suite that was watched running.** That means `@ia-qa/self-healing` installed, `ia-qa-heal map`, and one `ia-qa-heal run`. Without it you get a refusal that names the command, not a number: a contract means somebody configured a page, and only a watched run means a test went there. "No measurement" and "zero coverage" are different sentences, and only one of them would be true.
+
+**No percentage, ever.** A `34%` reads as code coverage — a ratio over a denominator a compiler guarantees. Here the denominator is uncertain by construction: a login wall, an app that navigates without `<a href>`, the page cap, states nothing opened. Counts and page names only, always beside what the scan could not see.
+
+Writes `.ia-qa-discovery/coverage-map.json` (committable, diffable) and refreshes `_overview.md`. `--report [file.html] [--open]` for the branded dossier, `--json` for the map on stdout.
+
+**Closing a line.** A gap list that never shrinks stops being read. Declare pages you deliberately do not test in `outOfScope` in `config.json` — same glob dialect as self-healing's `volatile`:
+
+```json
+{ "outOfScope": ["legal-*", "styleguide"] }
+```
+
+They stay **counted and named** as out of scope, never silently dropped, and nothing is ever added to that list on its own.
+
 ### `history`
 
 The trend no single scan can reconstruct: pages, forms, API surface, and what changed run over run.
@@ -290,6 +340,20 @@ They are two halves of the same loop, and neither replaces the other.
 
 ⚠️ **`scan` and `map` are not the same operation.** `map` writes a page *contract* — every interactive element by role and accessible name, for repairing broken locators. `scan` writes a *surface* — pages, headings, inputs, API calls, for deciding what to test. Do not expect one to produce the other.
 
+### `scan` vs `ia-qa-heal discover` — the one that actually gets confused
+
+Self-healing has its own crawling verb, and the names do not make the difference obvious. They answer different questions, and if yours is the first one you do **not** need this package:
+
+| | `ia-qa-heal discover` | `ia-qa-discover scan` |
+|---|---|---|
+| Answers | *Which routes are missing from my `config.pages`?* | *What does this app take as input, and where would testing start?* |
+| Gives you | `{ name, url }` candidates | the surface behind each URL |
+| Then what | `--apply` appends to `config.json` | you know what there is to test |
+
+Measured on the same four pages of ia-qa.com: `discover` returns **4 `{name, url}` pairs**; `scan` returns those four pages plus **159 headings, 3 input fields with their captured labels, 9 observed API calls**, and the verdict that none of the three fields can be located durably. That is not a richer rendering of the same data — it is a different dataset.
+
+**So: if you only want to fill `config.pages`, use `ia-qa-heal discover` and stop there.** Reach for `scan` when you need to know what the pages *contain*, or when you have no suite at all — which is the case self-healing's own README opens by excluding.
+
 **Discovery → healing.** Once you know the routes, hand them to healing and start writing tests against contracts:
 
 ```bash
@@ -299,7 +363,16 @@ ia-qa-heal init                                       # then map it for test mai
 
 `config.pages` here has the same `{ name, url }` shape as self-healing's, and both packages resolve page names through the *same* function (`pageNameFromUrl`), so a page called `checkout` in one is `checkout` in the other. The two sets of artifacts line up 1:1.
 
-**Healing → discovery.** Healing knows what your suite *covers*. Discovery knows what *exists*. The gap between them is your real coverage — and neither tool can tell you that alone.
+**Healing → discovery — and the gap is computed, not just described.** Healing knows what your suite *covers*; discovery knows what *exists*. When a project already has `.ia-qa/mapping/`, `scan` ends by stating the difference:
+
+```
+🔗 This project also uses `ia-qa-heal`: it holds contracts for 3 page(s), this scan found 4.
+   2 page(s) exist here with no contract: `all-tools`, `resources`
+   That is the gap between what the app has and what the suite holds — not a verdict:
+   a page with no contract may be deliberately out of scope. You decide which.
+```
+
+Comparable only because both packages resolve page names through the *same* `pageNameFromUrl`. It is **not** a verdict and this package gates nothing — an uncovered page may be out of scope on purpose. A contracted page this scan did not reach is reported as a limit of the scan (`--max`, crawl reach, session), never as a page that disappeared. On a project with no `.ia-qa/`, nothing is printed at all.
 
 **Sessions are interchangeable.** Both consume a Playwright `storageState`, so a session from either `login` verb works for the other: `ia-qa-discover scan --session ../.ia-qa/session.json`.
 
@@ -315,6 +388,7 @@ A dependency-free JSON-RPC 2.0 stdio server exposing the **same** operations the
 
 - `scan_app` — crawl and capture. Check `loginWall` and `hrefBlind` in the result before reporting coverage.
 - `classify_app` — the optional BYOK layer below, for an agent. The key is read from an environment variable **named** in the call (`api_key_env`); a raw key is never a tool argument.
+- `coverage_map` — what the suite does **not** test. Returns `measured: false` with a typed `reason` when no run was ever watched: report that as *no measurement*, never as "the suite covers nothing".
 - `discovery_history` — the trend.
 
 `login` is deliberately **not** a tool: it waits for a person at a browser, which an agent cannot be. Every path and URL an agent supplies is checked against the project root and the configured origin.

package/TUTORIAL.md

@@ -0,0 +1,433 @@
+# QA Discovery — the complete beginner's guide
+
+You have been handed a web application. There is no documentation, no test plan, and possibly
+nobody left who built it. Your job is to test it.
+
+This guide walks the whole thing, with no jargon. By the end you will have a written record of
+what the app contains, what it takes as input, what it calls — and, if you already have a test
+suite, a ranked list of the pages nobody tests.
+
+---
+
+## Table of contents
+
+1. [Is this for me?](#1-is-this-for-me)
+2. [The 30-second mental model](#2-the-30-second-mental-model)
+3. [Before you start](#3-before-you-start)
+4. [Path A — I use an AI agent](#4-path-a--i-use-an-ai-agent)
+5. [Path B — I use a terminal](#5-path-b--i-use-a-terminal)
+6. [Reading what it wrote](#6-reading-what-it-wrote)
+7. [The four ways a page count lies](#7-the-four-ways-a-page-count-lies)
+8. [What my suite does not test](#8-what-my-suite-does-not-test)
+9. [Doing this every week](#9-doing-this-every-week)
+10. [Optional: what is each entry point *for*?](#10-optional-what-is-each-entry-point-for)
+11. [Troubleshooting](#11-troubleshooting)
+
+---
+
+## 1. Is this for me?
+
+**Yes, if** you are looking at an app and cannot yet answer *"what is in it?"* — a new job, an
+inherited project, an acquisition, an audit, a QA engineer parachuted onto a team.
+
+**Yes, if** you have some tests and no idea how much of the app they miss.
+
+**No, if** your question is *"my tests broke, which selector moved?"*. That is a different tool
+in the same family: [`@ia-qa/self-healing`](https://www.npmjs.com/package/@ia-qa/self-healing).
+They work together — section 8 is exactly where they meet.
+
+**One thing this tool refuses to do:** give you a pass or a fail. It is reconnaissance. It
+reports what it observed and, just as carefully, what it could **not** see. A tool like this
+that pretended to a verdict would be telling the most useful-looking lie available to it.
+
+---
+
+## 2. The 30-second mental model
+
+Three ideas and you have it.
+
+**It writes down what it sees, and nothing else.** A page's title, its headings, every input,
+every API call the browser really made. If the app does not state something, it stays absent —
+never guessed, never filled in with something plausible.
+
+**Every number says what it does not measure.** "9 of 9 pages captured" is meaningless if six
+of them were the login screen. So a count never travels alone: it comes with the login wall it
+hit, the links it could not follow, the cap it stopped at.
+
+**It runs on your machine.** A headless browser it brings itself, so `localhost`, a staging box
+or an app behind a VPN all work. Nothing is uploaded. The one exception is an optional, separate
+command in section 10, which uses *your* API key and announces exactly what it sends before it
+sends it.
+
+---
+
+## 3. Before you start
+
+You need **Node.js 18 or newer**. That is all — the browser comes with the package.
+
+```bash
+node --version
+```
+
+### 💡 "I don't want to download another browser"
+
+If you already run Playwright, you already have one and it will be reused. If you do not, the
+first run downloads Chromium once (~130 MB) into a shared cache and never again.
+
+---
+
+## 4. Path A — I use an AI agent
+
+If you drive Claude Code, Cursor, Windsurf, VS Code + Copilot or any MCP-capable agent, it can
+run all of this for you.
+
+### Step 4.1 — Add the server to your agent
+
+Claude Code:
+
+```bash
+claude mcp add qa-discovery -- npx -y @ia-qa/qa-discovery ia-qa-discover-mcp
+```
+
+Or, for any client that reads a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "qa-discovery": {
+      "command": "npx",
+      "args": ["-y", "@ia-qa/qa-discovery", "ia-qa-discover-mcp"]
+    }
+  }
+}
+```
+
+### Step 4.2 — Restart the agent, then ask
+
+> Scan https://your-app.example.com and tell me what is in it.
+
+The agent calls `scan_app`, gets the capture back, and reads it. Four tools are available to
+it: `scan_app`, `coverage_map`, `classify_app` and `discovery_history` — the same operations
+the terminal has, with the same guarantees.
+
+### Step 4.3 — The one thing your agent cannot do
+
+**It cannot log you in.** `login` opens a visible browser and waits for a human twice: once at
+the browser, once at the keyboard. That is not something an agent can perform, so it is
+deliberately not exposed as a tool. When the scan reports a login wall, the agent will ask
+*you* to run this, in your own terminal:
+
+```bash
+npx @ia-qa/qa-discovery login
+```
+
+Then ask it to scan again.
+
+---
+
+## 5. Path B — I use a terminal
+
+### Step 5.1 — Install
+
+```bash
+npm i -D @ia-qa/qa-discovery
+```
+
+Or run it without installing anything:
+
+```bash
+npx @ia-qa/qa-discovery scan https://your-app.example.com --save
+```
+
+### Step 5.2 — Your first scan
+
+```bash
+npx ia-qa-discover scan https://your-app.example.com --save --report --open
+```
+
+- `--save` remembers the URL, so later runs are just `ia-qa-discover scan`.
+- `--report` writes a single self-contained HTML file you can send to anyone.
+- `--open` opens it.
+
+What you get on screen:
+
+```console
+Discovering pages from https://app.example.com…
+🌐 Using bundled Chromium (shared Playwright cache)
+  visited / (2 links)
+  visited /terms (1 links)
+Found 3 page(s). Capturing…
+  ✔ home
+  ✔ terms
+  ✔ policy-cookies
+
+✔ 3 of 3 page(s) captured
+
+⚠  This app has a login (home), and no session was used.
+   What you have is the PUBLIC surface only — whatever is behind the login was never reached.
+```
+
+**Read that warning before you read the number.** "3 of 3" looks complete and is not.
+
+### Step 5.3 — Behind a login
+
+```bash
+npx ia-qa-discover login
+```
+
+A visible browser opens. You log in **yourself** — SSO, MFA, a consent screen, a magic link, a
+device check: all of them work, because the tool models none of them. Nothing is typed for you
+and no credential is read or stored.
+
+What is saved is the browser session, in `.ia-qa-discovery/session.json`. **That file holds live
+cookies: whoever has it is logged in as you.** The tool says so before opening the browser and
+writes a `.gitignore` next to it so a commit cannot carry it away.
+
+Already have a session? An authenticated Playwright suite usually writes one in `globalSetup`:
+
+```bash
+npx ia-qa-discover scan --session playwright/.auth/user.json
+```
+
+Then scan again — this time it goes behind the wall.
+
+### Step 5.4 — Most of the inputs are behind a click
+
+A loaded page is *one state* of a page. Menus, tabs, accordions and dialogs hide the rest.
+
+```bash
+npx ia-qa-discover scan --deep
+```
+
+This opens each control one level down and captures what it reveals. Every field found this way
+records **how to reach it** — the click path — because telling you to test a field without
+telling you how to get to it is useless.
+
+Two things keep this safe: every non-GET request is blocked for the whole walk, so a click
+cannot change anything on the server, and URLs that act (`/logout`, `/delete`…) are never
+followed.
+
+It costs roughly twice the scan time. Even without it, the tool always tells you how many
+controls *could* reveal more — a page with 64 clickable controls and 2 visible fields must not
+report those 2 as its input surface.
+
+---
+
+## 6. Reading what it wrote
+
+```
+.ia-qa-discovery/
+  config.json              # baseUrl, crawl settings, declared pages, out-of-scope pages
+  history.jsonl            # one line per scan — the trend no single run can show
+  session.json             # only if you ran `login`. Live cookies: gitignored automatically
+  capture/
+    surface.json           # the machine-readable index
+    _overview.md           # ← start here as a human
+    home.json              # one file per page
+    …
+```
+
+**Open `_overview.md` first.** It is the same scan, written to be read — by you, or by an LLM
+using it as context. It leads with what was *not* measured, then the pages, their forms and
+fields, and the API calls.
+
+Commit `capture/`. It is small, deterministic text, and committing it is what makes the next
+section possible.
+
+Three things a real scan found on a real app, each traceable to an observation:
+
+- All 9 pages shared one `<title>` — the tab, the history and a screen reader cannot tell them
+  apart.
+- `GET /api/integration/status` answered **401** and `/api/billing/payment-history` **404**, on
+  a valid session.
+- Every field on the login form had no `id`, no `name`, no `data-testid` — so any test written
+  against it can only use a positional selector, which breaks the day a field is inserted above.
+
+---
+
+## 7. The four ways a page count lies
+
+This is the most useful section in this guide. Each of these produced a confident, wrong number
+before it was caught, and each is now stated out loud.
+
+**1. The login wall.** Pages still showing a login form were captured — you measured the wall,
+not the app. Worse: an app whose catch-all route renders the login page answers HTTP 200 at
+*every* URL, so the count looks like a success. → run `login`.
+
+**2. No `<a href>` to follow.** Discovery follows links. An app navigating with React Router's
+`navigate()` or a button's `onClick` exposes none, so an 11-route app reports "1 of 1 found".
+→ declare the routes you know in `config.json` → `pages`; they are scanned *in addition* to the
+crawl.
+
+**3. Inputs outside a `<form>`.** Modern apps wrap nothing. A scan that only walked `<form>`
+tags reported "0 fields" on an app with 464 inputs. → handled automatically now; the fields are
+listed with the heading they sit under.
+
+**4. The page cap.** `--max` stops the run, and pages known-but-not-visited are counted and
+named rather than silently dropped. → raise `--max`.
+
+**The rule underneath all four:** every counter this tool prints must be able to say what it
+does *not* measure. If you ever see a number here with no caveat beside it, that is a bug worth
+reporting.
+
+---
+
+## 8. What my suite does not test
+
+This is where the two packages meet, and it is the one question neither can answer alone.
+
+Discovery knows **what exists**. `@ia-qa/self-healing` knows **where your suite actually went** —
+because it can watch the suite run. Put the two together and you get the sentence that matters:
+
+```console
+$ npx ia-qa-discover coverage
+
+📊 Your suite visits 4 of the 27 pages this scan found · 23 not tested
+
+   Not tested — ranked by what the scan observed on each page:
+     · login     —  takes credentials · writes · has required input · 2 inputs · 1 API call
+     · checkout  —  writes · 1 input · 1 API call
+     · profile   —  has required input · 4 inputs
+
+   This is not a verdict: a page nobody tests may be deliberately out of scope.
+
+   📐 Depth — your suite names 12 of 380 contracted elements. Named, not asserted.
+
+   What this does NOT measure:
+     ⚠ 2 known page(s) were cut by the page cap (--max) and are not in these totals.
+```
+
+### What you need first
+
+```bash
+npm i -D @ia-qa/self-healing
+npx ia-qa-heal init      # declare your pages and your test command
+npx ia-qa-heal map       # capture the app's contracts
+npx ia-qa-heal ingest    # inventory what your tests name
+npx ia-qa-heal run       # runs your suite with capture on — this is the step that matters
+```
+
+That last command is the whole point: it runs your suite and records **which pages it actually
+loaded**. Until that has happened, `coverage` shows you no number at all — it tells you there is
+nothing to measure yet and names the command. A page having a contract only proves somebody
+configured it; only a watched run proves a test went there.
+
+### Three words to read carefully
+
+**"Not tested" is not a verdict.** A page nobody tests may be deliberately out of scope. You
+decide, and section 9 shows how to write that decision down.
+
+**"Named" is not "asserted".** The depth line counts elements your tests *designate*. A test
+that clicks a button names it without checking anything, and nothing on disk can tell the two
+apart — so the tool never says "tested".
+
+**There is no percentage, and there never will be.** A `34%` reads as code coverage, which is a
+ratio over a denominator a compiler guarantees. Here the denominator is uncertain by
+construction — the login wall, the links nobody could follow, the cap, the states nothing
+opened. A percentage over that would be a comforting number with its caveats stripped off, which
+is precisely how a team stops testing something. You get counts and page names.
+
+`--report` writes the HTML version, `--json` the machine-readable map, and
+`.ia-qa-discovery/coverage-map.json` is written every time — commit it and watch the gap move.
+
+---
+
+## 9. Doing this every week
+
+A discovery is a perishable snapshot. The value is in re-running it.
+
+```bash
+npx ia-qa-discover scan       # same command; an unchanged app must diff clean
+npx ia-qa-discover history
+```
+
+```console
+2026-09-04T12:19:39Z  9/9 pages  +9 -1 ~0   300df55 (main)
+2026-09-04T12:35:06Z  9/9 pages  +0 -0 ~0   (no change)  300df55 (main)
+```
+
+### Closing a line you have decided about
+
+A gap list that never shrinks stops being read. By the third week, 23 pages reported identically
+every time is noise, and the two that started mattering are lost in it.
+
+So write the decision down, in `.ia-qa-discovery/config.json`:
+
+```json
+{
+  "baseUrl": "https://app.example.com",
+  "outOfScope": ["legal-*", "styleguide"]
+}
+```
+
+Those pages stay **counted and named** as out of scope. They are never silently dropped, and
+nothing is ever added to that list on its own — a page leaves the gap because a person wrote it
+down in a file a reviewer can see.
+
+---
+
+## 10. Optional: what is each entry point *for*?
+
+Everything above is deterministic and local. This section is neither, and it is a separate
+binary so that it cannot be run by accident.
+
+```bash
+npx ia-qa-discover-ai classify
+```
+
+It reads the capture you already have — **no browser, your app is never touched** — and asks a
+model, with **your** API key, what each form and field is for and how sensitive it is.
+
+**It is the only thing in this package that sends anything anywhere, and it says so before it
+does**, listing exactly what goes: the page URL, title, description, up to 25 headings, the
+observed API calls, and each field's name, type, label and selector. Read that notice before
+running it on a private or authenticated app.
+
+Two guarantees make the output usable:
+
+- **Every claim cites the capture, and the citation is checked** before the line is kept. A
+  claim pointing at something that does not exist is dropped, and the drop is reported.
+- **The model can refuse.** "Not enough evidence" is a real answer, listed separately — an LLM
+  asked to classify will otherwise always classify, and that is how confident nonsense ships.
+
+The check proves the *premise*, never the *conclusion*: a model can cite a real password field
+and still call the page a checkout. So the sentence and the confidence are always shown, never
+the label alone.
+
+Without a key, nothing changes: every command above behaves exactly as it does today.
+
+---
+
+## 11. Troubleshooting
+
+**"Found 1 page" on an app I know has twenty.** Section 7, case 2 — the app navigates without
+links. Declare the routes in `config.json` → `pages`.
+
+**Everything is the login page.** Section 7, case 1. Run `login`, then scan again.
+
+**`login` says it refuses.** It refuses without a terminal and under CI, because it waits for a
+person twice. That is also why an AI agent cannot run it. For a pipeline, point `--session` at a
+`storageState` your own setup writes.
+
+**"Nothing to show yet" from `coverage`.** Your suite has never been watched running. Run
+`npx ia-qa-heal run`. This is not zero coverage — it is no measurement, which is why no number
+is shown.
+
+**"No test suite is being tracked here."** `coverage` needs `@ia-qa/self-healing`. Without it,
+scanning and classification work exactly as before; reach and depth are not computed at all.
+
+**The scan is slow.** Lower `--max`, lower `--depth`, or drop `--deep`. A deep scan costs about
+twice a normal one.
+
+**A field has no name in the report.** The app labels it nowhere — no `<label>`, no
+`aria-label`, no placeholder. That is a finding about the app, not about the scan: a screen
+reader cannot announce it either.
+
+---
+
+## Where to go next
+
+- [README.md](./README.md) — the short reference, every flag.
+- [ROADMAP.md](./ROADMAP.md) — where this is going, and what it will deliberately never become.
+- [`@ia-qa/self-healing`](https://www.npmjs.com/package/@ia-qa/self-healing) — once tests exist,
+  the tool that keeps them alive when selectors move.

package/dist/cli/args.js

@@ -22,6 +22,7 @@ exports.KNOWN_FLAGS = {
     ],
     login: ['--url', '--session'],
     history: ['--json', '--limit'],
+    coverage: ['--json', '--report', '--open'],
 };
 function rejectUnknownFlags(command, args) {
     const known = exports.KNOWN_FLAGS[command];

package/dist/cli/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AAsBA,gDAQC;AA9BD,sGAAsG;AACzF,QAAA,WAAW,GAAsC;IAC5D,IAAI,EAAE;QACJ,SAAS;QACT,OAAO;QACP,aAAa;QACb,eAAe;QACf,WAAW;QACX,cAAc;QACd,cAAc;QACd,QAAQ;QACR,eAAe;QACf,qBAAqB;QACrB,QAAQ;QACR,QAAQ;QACR,UAAU;QACV,QAAQ;KACT;IACD,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;IAC7B,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC/B,CAAC;AAEF,SAAgB,kBAAkB,CAAC,OAAe,EAAE,IAAc;IAChE,MAAM,KAAK,GAAG,mBAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAChC,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,yBAAyB,OAAO,kDAAkD,CAAC,CAAC;IACxH,CAAC;AACH,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AAuBA,gDAQC;AA/BD,sGAAsG;AACzF,QAAA,WAAW,GAAsC;IAC5D,IAAI,EAAE;QACJ,SAAS;QACT,OAAO;QACP,aAAa;QACb,eAAe;QACf,WAAW;QACX,cAAc;QACd,cAAc;QACd,QAAQ;QACR,eAAe;QACf,qBAAqB;QACrB,QAAQ;QACR,QAAQ;QACR,UAAU;QACV,QAAQ;KACT;IACD,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;IAC7B,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC9B,QAAQ,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC;CAC3C,CAAC;AAEF,SAAgB,kBAAkB,CAAC,OAAe,EAAE,IAAc;IAChE,MAAM,KAAK,GAAG,mBAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAChC,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,yBAAyB,OAAO,kDAAkD,CAAC,CAAC;IACxH,CAAC;AACH,CAAC"}

package/dist/cli/coverage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `ia-qa-discover coverage` — what the suite tests, what the app has, and the gap.
+ *
+ * **A verb, not a flag on `scan`.** It reads local files only and opens no browser; making
+ * it a flag would force a full re-crawl of the application to read two files already on
+ * disk. It is also opt-in for a reason that matters more: `scan` must stay silent about the
+ * sibling package, because a cross-reference that fires on the ordinary run is advertising,
+ * and this package treats a message that fires on the good case as a defect. Here the user
+ * asked, so the premise of their own command is what is missing — that is an answer.
+ *
+ * **Plug-and-play has a precise test here**: in a project that already has `.ia-qa/` and
+ * `.ia-qa-discovery/`, the bare verb produces the map with no argument and no question.
+ *
+ * Exit code is 0 on a refusal as well as on a gap. A missing optional prerequisite is not a
+ * failure of anything, and a coverage gap is a decision for a human — gating on it would
+ * make this the verdict discovery has spent its whole design refusing to emit.
+ */
+export declare const COVERAGE_FILENAME = "coverage-map.json";
+export declare function coverageMapPath(cwd?: string): string;
+export declare function runCoverage(args: string[]): Promise<void>;