@ia-qa/qa-discovery 0.4.0 → 0.5.0

package/README.md

@@ -27,13 +27,23 @@ npx -p @ia-qa/qa-discovery ia-qa-discover scan https://your-app.example.com --sa
 | **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) |
+| what does somebody come to this page to **do**? | `ia-qa-discover-ai plan` (optional, your own key) |
+
+**Driving this with an AI agent?** One command gives it the whole doctrine — the verb for
+each question, what every refusal means, and what it must never do:
+
+```bash
+ia-qa-discover skill --print      # read it
+ia-qa-discover skill --install    # drop it in .claude/skills/, where agents actually look
+```
 
 `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.
+one of them. `ia-qa-discover-mcp` exposes `scan_app`, `coverage_map`, `classify_app`,
+`plan_pages` 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
@@ -414,6 +424,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.
+- `plan_pages` — the other BYOK question: what somebody comes to each page **to do**. Same key handling, and it sends **less** — no selectors, no observed API calls. Defaults to the pages `coverage_map` says no test visits, in that tool's order. Ranks nothing, gates nothing; a `failed` page is a failed call, never a finding about the app.
 - `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.
 
@@ -428,8 +439,15 @@ Everything above is deterministic and never leaves your machine. This one binary
 ```bash
 ia-qa-discover-ai classify --dry-run   # see exactly what would be sent, and to whom
 ia-qa-discover-ai classify
+
+ia-qa-discover-ai plan --dry-run       # the other question, and a smaller payload
+ia-qa-discover-ai plan --report --open
 ```
 
+Two verbs, two questions, and **`plan` sends strictly less than `classify`**: no selectors and
+no observed API calls ever leave for it. Each announces its own payload, derived from the
+function that builds it, so neither can promise less than it sends.
+
 It reads the capture **offline** — it opens no browser and never touches your app again — and asks a model what each entry point is *for* (`authentication`, `payment`, `search`, `data-entry`…) and how sensitive what it handles is. The vocabulary is closed and versioned: a label outside it is rejected before anything else is checked.
 
 **Every claim cites the capture, and every citation is resolved and checked.** A classification whose evidence does not exist, or does not say what it was claimed to say, is dropped before you see it, and the drop is reported. That proves the *premise*, never the conclusion — a model can cite a real password field and still be wrong about what the page is for — so read the `why` and the confidence, not the label alone.
@@ -441,6 +459,12 @@ Configure it in `.ia-qa-discovery/config.json` — the file holds the *name* of
 ```json
 "ai": { "provider": "anthropic", "model": "claude-haiku-4-5",
         "apiKey": { "source": "env", "key": "ANTHROPIC_API_KEY" } }
+
+// or any OpenAI-compatible endpoint — DeepSeek, Groq, Mistral, OpenRouter, vLLM,
+// or a model on your own machine, in which case nothing leaves it at all:
+"ai": { "provider": "openai-compatible", "model": "deepseek-chat",
+        "baseUrl": "https://api.deepseek.com/v1",
+        "apiKey": { "source": "keychain", "key": "DEEPSEEK_KEY" } }
 ```
 
 Before the first request it prints what leaves and where it goes:
@@ -467,6 +491,62 @@ rewrite — it is your file — so `scan` warns instead.
 
 Read that list before pointing it at an authenticated or private app. The result lands in `.ia-qa-discovery/classification.json` **and** in `_overview.md`, which is rewritten so the reading appears next to the capture it was made from.
 
+### `plan` — what somebody comes to this page to do
+
+`classify` answers what an entry point *is*, against a closed vocabulary. `plan` answers a
+different question, on a different axis: **what is a person trying to do here, and what can
+they no longer do if it breaks** — in the words of whoever uses the app, not a developer's.
+
+It exists because that axis is the one nothing else in this ecosystem can reach. The
+deterministic half reports what an app *accepts* — fields, types, required, what moved.
+Nothing in a DOM states that this form is how a locked-out customer gets back in. Neither
+layer is a subset of the other, which is why one never ranks above the other.
+
+```bash
+ia-qa-discover-ai plan                 # the pages `coverage` says no test visits, in its order
+ia-qa-discover-ai plan --all           # every readable page, tested or not
+ia-qa-discover-ai plan --report --open # the same branded dossier `scan --report` writes
+```
+
+By default it reads exactly the untested pages from `ia-qa-discover coverage`, **in the order
+that verb ranked them** — so an interrupted run has read the ones that mattered most. With no
+suite tracked here there is no untested list to narrow to, and it reads every page and says
+so rather than refusing: a project with no tests is the one this package exists for.
+
+Four properties, and each is tested:
+
+- **It sends less than `classify`** — no selectors, no observed API calls. The most sensitive
+  half of a capture, and technical noise for a question that is not technical.
+- **Every reading cites the capture** and is dropped if the citation does not resolve, exactly
+  like a classification. A path the prompt never offered is refused *before* resolution, so
+  citing an API call — which this verb does not send — cannot happen.
+- **The shell is not a page's content.** Headings repeated across the app (a footer's `Legal`,
+  `Contact`, `Tools`) are dropped from the payload, using the same threshold `autoLayout`
+  uses. Measured before the change: a page whose whole interest was `🗂️ Environment Manager`
+  had its reading propped up by three footer links — citations that resolve, and support
+  nothing. A page whose *every* heading is shared keeps them all: the exclusion narrows the
+  evidence, it never makes a page unreadable.
+- **At least one citation must carry the subject** — a level-1 or level-2 heading, a form, or
+  a field. A reading standing entirely on nav labels is dropped. The rule is skipped on a page
+  that offers no such anchor, because a rule nobody can satisfy would punish a page for its own
+  markup.
+- **It ranks nothing and gates nothing.** The order is `coverage`'s measurement; this adds a
+  labelled line beside it, never a row to it.
+- **The origin travels with the artifact.** `plan.json` carries the model and the timestamp,
+  one module renders the terminal, `_overview.md` and the HTML report, a page re-captured
+  after it was read is marked **stale**, and the report's footer stops saying "no LLM".
+
+A model that cannot tell answers `unclear`: kept, labelled, never silently dropped — the
+capture may genuinely not say, and a proposal nobody can anchor is still worth reading as
+long as it is marked as one.
+
+**Its honest limit**, measured on a real run of 8 pages: the reading is worth most where the
+deterministic half is blind — a page with no form at all, whose headings name the stake — and
+thins out on content pages, where "somebody comes here to read the articles" repeats the
+capture back. Read the confidence and the citations, not the sentence alone. After the two
+rules above, that same run produced **0 citations pointing at the footer or the nav**, against
+three on a single page before them.
+
 ---
 
 ## Library

package/ROADMAP.md

@@ -84,7 +84,7 @@ be understood.
 
 | Stage | The question it answers | Status |
 |---|---|---|
-| **Value and personas** (F0) | Who uses this app, for what, and where would it hurt most if it broke? | not built |
+| **Value and personas** (F0) | Who uses this app, for what, and where would it hurt most if it broke? | partly shipped — see `plan` below |
 | **Surface reconnaissance** (F1) | What pages exist, what do they take as input, what do they call? | ✅ shipped (0.1.0) |
 | **Component classification** (F2) | What is each entry point *for*, and how sensitive is what it handles? | in progress |
 | **Zones and synthesis** (F2.5) | How do the pages group into functional areas, and what is the app as a whole? | not built |
@@ -218,9 +218,31 @@ navigation graph), then a grounded synthesis on top. Reconciles with the value s
 
 ## Value and personas (F0) — *the game changer, built with care*
 
-Who uses this app, for what, and where the moment of truth is. This is the stage that makes
-the output a senior's plan instead of a classified inventory, and the one whose claims are
-hardest to check — so it is scheduled as **careful** work, not as later work.
+**A first, deliberately narrow slice shipped: `ia-qa-discover-ai plan`.** It answers the
+value question for **one page at a time** — what somebody comes here to do, and what they can
+no longer do if it breaks — and nothing beyond that. No personas, no app-level framing, no
+"moment of truth": those are the claims the validation protocol below exists to gate, and
+none of them is made.
+
+Why this slice was safe to ship first, in the terms this file uses everywhere else:
+
+- It **produces no executable artifact**, so a wrong reading cannot become a broken test.
+- Every reading **cites the capture** and is dropped when the citation does not resolve —
+  the same mechanism as classification, on a per-page claim small enough for that check to
+  mean something.
+- It **ranks nothing**: the order is `coverage`'s measurement, and the model never adds a row
+  to it. That is the difference between commenting on a measurement and replacing one.
+- It sends **less** than `classify` — no selectors, no observed API calls.
+
+Measured limit, from a real 8-page run: the reading is worth most on a page the deterministic
+half is blind to (no fields at all, the stake living in the headings) and is near-tautological
+on content pages. That asymmetry is itself an argument for keeping this stage per-page until
+the protocol below exists.
+
+What remains unbuilt is the hard half — who the users are, and where the moment of truth is.
+This is the stage that makes the output a senior's plan instead of a classified inventory, and
+the one whose claims are hardest to check — so it is scheduled as **careful** work, not as
+later work.
 
 **It needs a validation protocol before it needs code.** Classification can be checked in seconds
 against the capture; this cannot. Label a handful of real apps by hand, compare the stage's

package/TUTORIAL.md

@@ -30,7 +30,8 @@ suite, a ranked list of the pages nobody tests.
 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)
+11. [Optional: what does somebody come here to *do*?](#11-optional-what-does-somebody-come-here-to-do)
+12. [Troubleshooting](#12-troubleshooting)
 
 ---
 
@@ -90,6 +91,20 @@ first run downloads Chromium once (~130 MB) into a shared cache and never again.
 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.0 — Give it the instructions first
+
+Before the server, one command. It costs nothing and removes most of the back-and-forth:
+
+```bash
+npx -p @ia-qa/qa-discovery ia-qa-discover skill --install
+```
+
+That writes `.claude/skills/ia-qa-discover/SKILL.md` — which verb answers which question, what
+each refusal means (`no-surface`, `no-healing`, `no-run` are three different sentences), what
+it must never do, and how to set an API key up without ever holding one. Agents read
+`.claude/skills/`, never `node_modules`, so the file has to land there to exist at all.
+Use `--print` to read it yourself first, or `--user` to install it for every project.
+
 ### Step 4.1 — Add the server to your agent
 
 Claude Code:
@@ -420,7 +435,75 @@ Without a key, nothing changes: every command above behaves exactly as it does t
 
 ---
 
-## 11. Troubleshooting
+## 11. Optional: what does somebody come here to *do*?
+
+Section 10 asks what an entry point **is**. This asks something a DOM cannot answer at all:
+**what is a person trying to do on this page, and what can they no longer do if it breaks.**
+
+```bash
+npx ia-qa-discover-ai plan
+```
+
+With no flags it reads exactly the pages section 8 said no test visits, **in the order that
+verb ranked them**. If you stop it halfway, the pages it already read are the ones that
+mattered most. No suite tracked yet? It reads every page and tells you that is what it did —
+you are the reader this package was written for.
+
+What you get, per page:
+
+```
+· devtools-environments
+  A person comes here to switch API keys and model configurations for different
+  environments like development, production and staging. · If it breaks: that person
+  cannot change or manage the API keys and model configurations. (confidence 0.90)
+```
+
+That page has **zero form fields**. The deterministic half could only say `nothing observed
+says it matters (2 API calls)` — it had nothing to observe. This is the gap the layer exists
+for, and the honest flip side is that on a page of articles the same model writes "somebody
+comes here to read the articles", which repeats the capture back at you. **Read the
+confidence and the citations, not the sentence.**
+
+### It sends less than `classify`, deliberately
+
+No selectors and no observed API calls leave for this question — the most sensitive half of a
+capture, and technical noise for a question about people. The notice it prints before the
+first request is derived from the function that builds the payload, so it cannot promise less
+than it sends.
+
+**Your footer does not leave either.** Headings that appear across your whole app — `Legal`,
+`Contact`, a nav title — are the shell, not this page's content, and they are dropped from
+what goes. That started as a privacy-shaped decision and turned out to be a quality one: on a
+real run, the reading of a page whose whole interest was `🗂️ Environment Manager` had been
+propped up by three footer links. They resolve, so nothing rejected them, and they support
+nothing. On the same run after the change: **zero citations pointing at a footer or a nav.**
+
+And a reading has to stand on something: at least one citation must be a level-1 or level-2
+heading, a form, or a field. One built entirely out of nav labels is dropped — unless the page
+offers no such anchor at all, in which case the rule is skipped rather than punishing the page
+for its own markup.
+
+### Three things it will not do
+
+- **It will not rank anything.** The order is the one `coverage` measured. A model reordering
+  a measured list has stopped commenting on a measurement and started replacing it.
+- **It will not gate.** Nothing here has an exit code that fails a build.
+- **It will not hide its origin.** `plan.json` carries the model and the time it ran;
+  `_overview.md` and the HTML report show the section labelled `model-read`; a page
+  re-captured *after* it was read is marked **stale**; and the report's footer stops claiming
+  the document is LLM-free, because it no longer is.
+
+If the capture genuinely does not say, the model answers `unclear` — kept and labelled, never
+quietly dropped.
+
+```bash
+npx ia-qa-discover-ai plan --all            # the tested pages too
+npx ia-qa-discover-ai plan --report --open  # the branded dossier, in a browser
+```
+
+---
+
+## 12. 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`.

package/dist/ai/classify.d.ts

@@ -2,6 +2,7 @@ import type { AiProvider } from '@ia-qa/self-healing';
 import type { PageCapture } from '../capture/page';
 import { type ToolTrigger } from '../taxonomy';
 import { type CaptureIndex, type Citation, type CitationVerdict } from '../citations';
+import { providerError, type ModelOptions } from './model';
 /**
  * F2 — classify each entry point, offline, from F1's capture.
  *
@@ -12,22 +13,18 @@ import { type CaptureIndex, type Citation, type CitationVerdict } from '../citat
  * **On duplication, stated because this project punishes silent drift:** the
  * provider/model catalogue is imported from `@ia-qa/self-healing` rather than
  * copied — there must not be a third model list in this repo. The HTTP transport
- * below *is* a second implementation, because self-healing does not export its
- * own (`callModel` is internal). Any change to a provider's request shape owes an
- * edit here as well as there.
+ * now lives in `./model.ts`, which is a second implementation of something
+ * self-healing keeps internal (`callModel`); it moved out of this file when a
+ * second BYOK verb arrived, so the cost stays at two copies instead of three.
+ * Any change to a provider's request shape owes an edit there as well as in
+ * self-healing.
  */
 /** The document  writes, and the two strings a later stage keys on. */
 export declare const CLASSIFICATION_SCHEMA = "qa-discovery-classification@1";
 export declare const CLASSIFICATION_FILENAME = "classification.json";
-export interface ClassifyOptions {
-    provider: AiProvider;
-    model: string;
-    apiKey: string;
-    /** Injected in tests; defaults to the global fetch. */
-    fetchFn?: typeof fetch;
-    timeoutMs?: number;
-    temperature?: number;
-}
+/** The transport's options, named for this verb. One shape for every BYOK caller. */
+export type ClassifyOptions = ModelOptions;
+export { providerError };
 /** One thing on a page that takes input, addressed by a path a citation can resolve. */
 export interface EntryPoint {
     /** e.g. `pages/checkout.json#forms[0]` or `pages/checkout.json#looseFields[2]` */
@@ -125,9 +122,9 @@ export declare function collect(raws: Partial<Classification>[], index: CaptureI
  * What leaves this machine, said before it leaves — the one thing that makes
  * "everything is local except the model call" a promise rather than a claim.
  *
- * It lives beside `HOSTS` on purpose: the notice names the very constant
- * `buildRequest` sends to, so a new provider cannot be reachable while the
- * notice still lists three. And it is derived from `buildPrompt` — every line
+ * It resolves the host through `egressHost` rather than naming one of its own: the notice names the
+ * very constant `buildRequest` sends to, so a new provider cannot be reachable
+ * while the notice still lists three. And it is derived from `buildPrompt` — every line
  * below is a field that function actually puts in the payload; adding one there
  * owes a line here.
  *
@@ -146,27 +143,7 @@ export declare function collect(raws: Partial<Classification>[], index: CaptureI
  * the token here. The word "full" is gone from that line for the same reason the
  * allowlist is named: the two statements must not contradict each other.
  */
-export declare function egressNotice(provider: AiProvider, model: string, pages: number, planned?: boolean): string;
-/**
- * What the provider itself said went wrong.
- *
- * Found by execution, not review: a Gemini key that is simply wrong comes back
- * **400**, not 401 — so the previous message read `refused the call with HTTP
- * 400`, said nothing about the key, and left the one person who could fix it in
- * sixty seconds with nothing to go on. Mapping more status codes by hand is the
- * wrong shape of fix (the list rots, and it is different per provider); the
- * providers already answer the question in the body, and all three happen to
- * use the same `{error:{message}}` envelope.
- *
- * Two guards. The body is untrusted text that lands in a terminal and in
- * `classification.json`, so it is capped and flattened. And anything shaped like
- * a credential is redacted before it is printed — a provider that echoes the
- * request back would otherwise put the user's own key in a file they commit.
- */
-export declare function providerError(res: {
-    status: number;
-    text: () => Promise<string>;
-}): Promise<string>;
+export declare function egressNotice(provider: AiProvider, model: string, pages: number, planned?: boolean, baseUrl?: string): string;
 /**
  * One page in, validated classifications out. Returns an empty result rather
  * than throwing on a network failure, an unparseable reply or an empty page:

package/dist/ai/classify.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLASSIFICATION_FILENAME = exports.CLASSIFICATION_SCHEMA = void 0;
+exports.providerError = exports.CLASSIFICATION_FILENAME = exports.CLASSIFICATION_SCHEMA = void 0;
 exports.entryPointsOf = entryPointsOf;
 exports.offeredPaths = offeredPaths;
 exports.buildPrompt = buildPrompt;
@@ -8,10 +8,11 @@ exports.parseClassifications = parseClassifications;
 exports.validate = validate;
 exports.collect = collect;
 exports.egressNotice = egressNotice;
-exports.providerError = providerError;
 exports.classifyPage = classifyPage;
 const taxonomy_1 = require("../taxonomy");
 const citations_1 = require("../citations");
+const model_1 = require("./model");
+Object.defineProperty(exports, "providerError", { enumerable: true, get: function () { return model_1.providerError; } });
 /**
  * F2 — classify each entry point, offline, from F1's capture.
  *
@@ -22,14 +23,15 @@ const citations_1 = require("../citations");
  * **On duplication, stated because this project punishes silent drift:** the
  * provider/model catalogue is imported from `@ia-qa/self-healing` rather than
  * copied — there must not be a third model list in this repo. The HTTP transport
- * below *is* a second implementation, because self-healing does not export its
- * own (`callModel` is internal). Any change to a provider's request shape owes an
- * edit here as well as there.
+ * now lives in `./model.ts`, which is a second implementation of something
+ * self-healing keeps internal (`callModel`); it moved out of this file when a
+ * second BYOK verb arrived, so the cost stays at two copies instead of three.
+ * Any change to a provider's request shape owes an edit there as well as in
+ * self-healing.
  */
 /** The document  writes, and the two strings a later stage keys on. */
 exports.CLASSIFICATION_SCHEMA = 'qa-discovery-classification@1';
 exports.CLASSIFICATION_FILENAME = 'classification.json';
-const DEFAULTS = { timeoutMs: 30000, temperature: 0 };
 /**
  * The citable units of a page.
  *
@@ -140,28 +142,7 @@ function buildPrompt(page, entryPoints) {
 }
 /** Pull the JSON object out of a model reply, tolerating fences and prose around it. */
 function parseClassifications(text) {
-    if (!text || typeof text !== 'string')
-        return null;
-    const attempts = [text];
-    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
-    if (fenced)
-        attempts.push(fenced[1]);
-    const first = text.indexOf('{');
-    const last = text.lastIndexOf('}');
-    if (first !== -1 && last > first)
-        attempts.push(text.slice(first, last + 1));
-    for (const candidate of attempts) {
-        try {
-            const parsed = JSON.parse(candidate.trim());
-            const list = Array.isArray(parsed) ? parsed : parsed?.classifications;
-            if (Array.isArray(list))
-                return list;
-        }
-        catch {
-            /* try the next shape */
-        }
-    }
-    return null;
+    return (0, model_1.parseJsonList)(text, 'classifications');
 }
 /**
  * Validate one classification against the closed taxonomy, then against the
@@ -241,19 +222,14 @@ function collect(raws, index, offered) {
     }
     return { taxonomyVersion: taxonomy_1.TAXONOMY_VERSION, kept, refused, dropped };
 }
-// ── Provider transport ───────────────────────────────────────────────────────
-const HOSTS = {
-    anthropic: 'api.anthropic.com',
-    openai: 'api.openai.com',
-    google: 'generativelanguage.googleapis.com',
-};
+// ── What leaves this machine ─────────────────────────────────────────────────
 /**
  * What leaves this machine, said before it leaves — the one thing that makes
  * "everything is local except the model call" a promise rather than a claim.
  *
- * It lives beside `HOSTS` on purpose: the notice names the very constant
- * `buildRequest` sends to, so a new provider cannot be reachable while the
- * notice still lists three. And it is derived from `buildPrompt` — every line
+ * It resolves the host through `egressHost` rather than naming one of its own: the notice names the
+ * very constant `buildRequest` sends to, so a new provider cannot be reachable
+ * while the notice still lists three. And it is derived from `buildPrompt` — every line
  * below is a field that function actually puts in the payload; adding one there
  * owes a line here.
  *
@@ -272,125 +248,21 @@ const HOSTS = {
  * the token here. The word "full" is gone from that line for the same reason the
  * allowlist is named: the two statements must not contradict each other.
  */
-function egressNotice(provider, model, pages, planned = false) {
+function egressNotice(provider, model, pages, planned = false, baseUrl) {
+    // The host it will REALLY reach. Throws when a configurable provider was given no URL —
+    // before anything is announced, because a notice printing `undefined` reads as a checked fact.
+    const host = (0, model_1.egressHost)(provider, baseUrl);
     const n = `${pages} page${pages === 1 ? '' : 's'}`;
-    return (`\n   🌐 ${planned ? 'Would send' : 'Sending'} ${n} to ${HOSTS[provider]}  (${provider} · ${model}) — your key, your account.\n` +
+    return (`\n   🌐 ${planned ? 'Would send' : 'Sending'} ${n} to ${host}  (${provider} · ${model}) — your key, your account.\n` +
         `      Leaves this machine: each page's URL, title and description, up to 25 headings,\n` +
         `      every observed API call (method, normalised path, status), and each form field's name,\n` +
         `      type, label and selector. Headings and labels are live text from your app.\n` +
         `      Query values are stripped at capture EXCEPT an allowlist that includes \`q\` — a search\n` +
         `      term reaches the model as typed (\`capture.safeQueryParams\` in config.json narrows it).\n` +
         `      Does NOT leave: page HTML, screenshots, cookies or your session file, your test files,\n` +
-        `      your API key (sent as a header to ${HOSTS[provider]} only).\n` +
+        `      your API key (sent as a header to ${host} only).\n` +
         `      ${planned ? '' : 'Ctrl-C to stop. '}Deterministic \`ia-qa-discover\` sends nothing, ever.\n`);
 }
-function buildRequest(provider, model, apiKey, prompt, temperature) {
-    if (provider === 'anthropic') {
-        const body = { model, max_tokens: 4096, messages: [{ role: 'user', content: prompt }] };
-        if (temperature !== undefined)
-            body.temperature = temperature;
-        return {
-            url: `https://${HOSTS.anthropic}/v1/messages`,
-            headers: { 'content-type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
-            body,
-        };
-    }
-    if (provider === 'openai') {
-        const body = { model, messages: [{ role: 'user', content: prompt }] };
-        if (temperature !== undefined)
-            body.temperature = temperature;
-        return {
-            url: `https://${HOSTS.openai}/v1/chat/completions`,
-            headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
-            body,
-        };
-    }
-    const body = { contents: [{ parts: [{ text: prompt }] }] };
-    if (temperature !== undefined)
-        body.generationConfig = { temperature };
-    return {
-        url: `https://${HOSTS.google}/v1beta/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(apiKey)}`,
-        headers: { 'content-type': 'application/json' },
-        body,
-    };
-}
-function extractText(provider, data) {
-    if (provider === 'anthropic')
-        return data?.content?.[0]?.text ?? '';
-    if (provider === 'openai')
-        return data?.choices?.[0]?.message?.content ?? '';
-    return data?.candidates?.[0]?.content?.parts?.[0]?.text ?? '';
-}
-async function attempt(opts, prompt, temperature) {
-    const fetchFn = opts.fetchFn ?? globalThis.fetch;
-    if (typeof fetchFn !== 'function')
-        return null;
-    const req = buildRequest(opts.provider, opts.model, opts.apiKey, prompt, temperature);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULTS.timeoutMs);
-    try {
-        return await fetchFn(req.url, {
-            method: 'POST',
-            headers: req.headers,
-            body: JSON.stringify(req.body),
-            signal: controller.signal,
-        });
-    }
-    catch {
-        return null; // network error or timeout — never throws at the caller
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/**
- * What the provider itself said went wrong.
- *
- * Found by execution, not review: a Gemini key that is simply wrong comes back
- * **400**, not 401 — so the previous message read `refused the call with HTTP
- * 400`, said nothing about the key, and left the one person who could fix it in
- * sixty seconds with nothing to go on. Mapping more status codes by hand is the
- * wrong shape of fix (the list rots, and it is different per provider); the
- * providers already answer the question in the body, and all three happen to
- * use the same `{error:{message}}` envelope.
- *
- * Two guards. The body is untrusted text that lands in a terminal and in
- * `classification.json`, so it is capped and flattened. And anything shaped like
- * a credential is redacted before it is printed — a provider that echoes the
- * request back would otherwise put the user's own key in a file they commit.
- */
-async function providerError(res) {
-    const status = `HTTP ${res.status}`;
-    // Kept alongside the provider's own words, not replaced by them: a 401 with
-    // an empty body still has exactly one likely cause, and an existing test went
-    // red the moment this hint was dropped — correctly.
-    const hint = res.status === 401 || res.status === 403 ? ' Check the API key.' : '';
-    let body = '';
-    try {
-        body = await res.text();
-    }
-    catch {
-        return `${status}.${hint}`;
-    }
-    let message = '';
-    try {
-        const parsed = JSON.parse(body);
-        message = parsed?.error?.message ?? parsed?.message ?? '';
-    }
-    catch {
-        message = body;
-    }
-    message = String(message).replace(/\s+/g, ' ').trim();
-    // sk-…, AIza…, ghp_…, and any long opaque run that could be a secret.
-    message = message.replace(/\b(?:sk-|AIza|ghp_|gsk_)[A-Za-z0-9_\-]{8,}/g, '[redacted]');
-    if (!message)
-        return `${status}.${hint}`;
-    if (message.length > 200)
-        message = message.slice(0, 200) + '…';
-    if (hint && !/[.!?…]$/.test(message))
-        message += '.';
-    return `${status} — ${message}${hint}`;
-}
 /**
  * One page in, validated classifications out. Returns an empty result rather
  * than throwing on a network failure, an unparseable reply or an empty page:
@@ -411,25 +283,10 @@ async function classifyPage(page, index, opts) {
         return empty();
     const prompt = buildPrompt(page, entryPoints);
     const offered = offeredPaths(page, entryPoints);
-    // The newest models reject sampling params outright (Anthropic Opus 4.8 /
-    // Sonnet 5, OpenAI reasoning models) with a 400. Rather than maintain a
-    // capability matrix, send temperature and retry once without it — the same
-    // trick, and the same reasoning, as self-healing's resolver.
-    let res = await attempt(opts, prompt, opts.temperature ?? DEFAULTS.temperature);
-    if (res && res.status === 400)
-        res = await attempt(opts, prompt, undefined);
-    if (!res)
-        return empty(`No reply from ${opts.provider} — network error or timeout.`);
-    if (!res.ok)
-        return empty(`${opts.provider} refused the call: ${await providerError(res)}`);
-    let text;
-    try {
-        text = extractText(opts.provider, await res.json());
-    }
-    catch {
-        return empty(`Could not read ${opts.provider}'s reply as JSON.`);
-    }
-    const raws = parseClassifications(text);
+    const call = await (0, model_1.callModel)(opts, prompt);
+    if (!call.ok)
+        return empty(call.reason);
+    const raws = parseClassifications(call.text);
     if (!raws)
         return empty(`${opts.provider} replied, but not with the JSON that was asked for.`);
     return collect(raws, index, offered);