@ia-qa/qa-discovery 0.3.0 → 0.5.0

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const HELP = "ia-qa-discover \u2014 deterministic surface reconnaissance for a web app\n\nF1 of QA Discovery: crawl an app's same-origin pages and capture what each one\nis structurally about \u2014 title, headings, forms, and observed API calls. No\nLLM, no verdict: this is recon, not a gate. Runs entirely on your machine;\nnothing is uploaded anywhere.\n\n[FOR AI AGENTS] You are driving this for a human. Run `scan` to capture the\napp's surface, then read .ia-qa-discovery/capture/surface.json (the index) and\nthe per-page files it points at \u2014 that is the evidence for anything you\nreport about this app. Never assert a page's purpose or risk from the URL\nalone; ground it in the captured meta/headings/forms/apiCalls. Never read a\npage count as coverage: if scan warns that pages still show a login form, you\nmeasured the wall, not the app. You CANNOT run `login` \u2014 it waits for a human\nat a browser; ask them to run it, then scan again.\n`coverage` answers \"what does their suite NOT test\" \u2014 but only from a suite that was\nwatched running (one `ia-qa-heal run`, or one `ia-qa-pal tour --suite`). If it says there is no\nmeasurement, report that, never \"the suite covers nothing\": a contract means someone\nconfigured a page, only a watched run means a test went there.\n\nUsage:\n  ia-qa-discover login                     Open a visible browser, log in by hand, keep the\n                                             session (.ia-qa-discovery/session.json) for scan\n                                             to reuse. The general answer to a login wall: it\n                                             models nothing, so SSO, MFA, a consent screen or\n                                             a magic link all work \u2014 you do them.\n                                             Needs a terminal, refuses under CI. The file holds\n                                             live cookies: gitignored, stays on this machine.\n                                              --url <path>   page to open (default: your baseUrl)\n                                              --session <f>  where to write it\n                                           Already have a storageState (a Playwright globalSetup\n                                           writes one)? Skip this verb: point scan at it with\n                                           --session <file> or \"session\" in config.json.\n  ia-qa-discover scan [url]                Crawl same-origin pages from <url> (or the saved\n                                             baseUrl) and capture each page's structure.\n                                             Writes .ia-qa-discovery/capture/, diffs against\n                                             the previous run, appends history.jsonl.\n                                              --depth <n>              crawl link-depth (default 2)\n                                              --max <n>                page cap (default 60)\n                                              --deep                   also open menus, tabs and dialogs one level\n                                                                       down and capture the fields they reveal. Every\n                                                                       non-GET request is blocked for the duration,\n                                                                       so a click cannot mutate anything server-side.\n                                              --deep-budget <n>        max controls clicked per page (default 60)\n                                              --no-sitemap             do not read sitemap.xml / robots.txt\n                                              --no-reveal              do not open menus/dropdowns for hidden links\n                                              --strict-host            treat www./apex as different hosts\n                                              --session <file>         reuse an existing storageState (login) file\n                                              --no-network             skip API/network-call capture this run\n                                              --network-threshold <n>  shared-call promotion threshold 0-1 (default 0.6)\n                                              --save                   persist this baseUrl to config.json\n                                              --json                   machine-readable summary on stdout\n                                              --report [file.html]     branded ia-qa.com HTML dossier of the\n                                                                       app (default ia-qa-discover-report.html)\n                                              --open                   open that report in the browser\n  ia-qa-discover coverage                  What your test suite does NOT test. Compares the\n                                             pages this scan found against the pages your suite\n                                             was OBSERVED visiting, ranks the gap by what each\n                                             page takes as input, and writes coverage-map.json.\n                                             Reads local files only \u2014 no browser, no network.\n                                             Needs one watched run of your suite \u2014\n                                             \"ia-qa-heal run\" or \"ia-qa-pal tour --suite\":\n                                             without a watched run there is no measurement, and\n                                             it says so instead of showing a number.\n                                             Declare pages you deliberately do not test in\n                                             \"outOfScope\" in config.json \u2014 they stay counted\n                                             and named, never silently dropped.\n                                              --json                   machine-readable map on stdout\n                                              --report [file.html]     branded HTML dossier with the gap\n                                                                       (default ia-qa-discover-coverage.html)\n                                              --open                   open that report in the browser\n  ia-qa-discover history                   Recorded scan runs \u2014 pages/forms/API-surface trend.\n                                              --json   --limit <n> (default 500)\n  ia-qa-discover version                   Print the installed version (also --version, -v)\n  ia-qa-discover help                      Show this help\n\nGlobal:\n  --config <dir>                           Resolve .ia-qa-discovery/ under <dir> instead of the\n                                             current directory. Also IAQA_DISCOVERY_CONFIG_DIR=<dir>.\n";
+declare const HELP = "ia-qa-discover \u2014 deterministic surface reconnaissance for a web app\n\nF1 of QA Discovery: crawl an app's same-origin pages and capture what each one\nis structurally about \u2014 title, headings, forms, and observed API calls. No\nLLM, no verdict: this is recon, not a gate. Runs entirely on your machine;\nnothing is uploaded anywhere.\n\n[FOR AI AGENTS] You are driving this for a human. Run `scan` to capture the\napp's surface, then read .ia-qa-discovery/capture/surface.json (the index) and\nthe per-page files it points at \u2014 that is the evidence for anything you\nreport about this app. Never assert a page's purpose or risk from the URL\nalone; ground it in the captured meta/headings/forms/apiCalls. Never read a\npage count as coverage: if scan warns that pages still show a login form, you\nmeasured the wall, not the app. You CANNOT run `login` \u2014 it waits for a human\nat a browser; ask them to run it, then scan again.\n`coverage` answers \"what does their suite NOT test\" \u2014 but only from a suite that was\nwatched running (one `ia-qa-heal run`, or one `ia-qa-pal tour --suite`). If it says there is no\nmeasurement, report that, never \"the suite covers nothing\": a contract means someone\nconfigured a page, only a watched run means a test went there.\n\nUsage:\n  ia-qa-discover login                     Open a visible browser, log in by hand, keep the\n                                             session (.ia-qa-discovery/session.json) for scan\n                                             to reuse. The general answer to a login wall: it\n                                             models nothing, so SSO, MFA, a consent screen or\n                                             a magic link all work \u2014 you do them.\n                                             Needs a terminal, refuses under CI. The file holds\n                                             live cookies: gitignored, stays on this machine.\n                                              --url <path>   page to open (default: your baseUrl)\n                                              --session <f>  where to write it\n                                           Already have a storageState (a Playwright globalSetup\n                                           writes one)? Skip this verb: point scan at it with\n                                           --session <file> or \"session\" in config.json.\n  ia-qa-discover scan [url]                Crawl same-origin pages from <url> (or the saved\n                                             baseUrl) and capture each page's structure.\n                                             Writes .ia-qa-discovery/capture/, diffs against\n                                             the previous run, appends history.jsonl.\n                                              --depth <n>              crawl link-depth (default 2)\n                                              --max <n>                page cap (default 60)\n                                              --deep                   also open menus, tabs and dialogs one level\n                                                                       down and capture the fields they reveal. Every\n                                                                       non-GET request is blocked for the duration,\n                                                                       so a click cannot mutate anything server-side.\n                                              --deep-budget <n>        max controls clicked per page (default 60)\n                                              --no-sitemap             do not read sitemap.xml / robots.txt\n                                              --no-reveal              do not open menus/dropdowns for hidden links\n                                              --strict-host            treat www./apex as different hosts\n                                              --session <file>         reuse an existing storageState (login) file\n                                              --no-network             skip API/network-call capture this run\n                                              --network-threshold <n>  shared-call promotion threshold 0-1 (default 0.6)\n                                              --save                   persist this baseUrl to config.json\n                                              --json                   machine-readable summary on stdout\n                                              --report [file.html]     branded ia-qa.com HTML dossier of the\n                                                                       app (default ia-qa-discover-report.html)\n                                              --open                   open that report in the browser\n  ia-qa-discover coverage                  What your test suite does NOT test. Compares the\n                                             pages this scan found against the pages your suite\n                                             was OBSERVED visiting, ranks the gap by what each\n                                             page takes as input, and writes coverage-map.json.\n                                             Reads local files only \u2014 no browser, no network.\n                                             Needs one watched run of your suite \u2014\n                                             \"ia-qa-heal run\" or \"ia-qa-pal tour --suite\":\n                                             without a watched run there is no measurement, and\n                                             it says so instead of showing a number.\n                                             Declare pages you deliberately do not test in\n                                             \"outOfScope\" in config.json \u2014 they stay counted\n                                             and named, never silently dropped.\n                                              --json                   machine-readable map on stdout\n                                              --report [file.html]     branded HTML dossier with the gap\n                                                                       (default ia-qa-discover-coverage.html)\n                                              --open                   open that report in the browser\n  ia-qa-discover generate [page\u2026]           A starting Playwright suite for the pages nothing\n                                             tests \u2014 one file per page, into its own directory.\n                                             Every locator names an element the healing contract\n                                             holds, so the file is REPAIRED when the app moves\n                                             instead of going red. A field with no test id, id or\n                                             name is left out and says so: its selector would be\n                                             positional, which nobody can test reliably.\n                                             Proposals \u2014 nothing is added to your suite, and the\n                                             assertions stay yours (the app declares what it\n                                             accepts, never what it promises).\n                                             With no page, it generates for the coverage gap.\n                                              --out <dir>   where to write (default\n                                                            .ia-qa-discovery/generated/)\n                                              --force       replace files already there\n                                              --json        machine-readable summary on stdout\n  ia-qa-discover skill                     This CLI's agent instructions: the verb for each\n                                             question, what every refusal means, and what an\n                                             agent must never do. Read them before driving\n                                             anything else here.\n                                              --print       write them to stdout and stop\n                                              --install     write .claude/skills/ia-qa-discover/\n                                              --user        into ~/ instead of this project\n                                              --dir <d>     into another project root\n                                              --force       overwrite an edited copy\n  ia-qa-discover history                   Recorded scan runs \u2014 pages/forms/API-surface trend.\n                                              --json   --limit <n> (default 500)\n  ia-qa-discover version                   Print the installed version (also --version, -v)\n  ia-qa-discover help                      Show this help\n\nGlobal:\n  --config <dir>                           Resolve .ia-qa-discovery/ under <dir> instead of the\n                                             current directory. Also IAQA_DISCOVERY_CONFIG_DIR=<dir>.\n";
 declare function verbHelp(command: string | undefined): string | null;
 declare function main(): Promise<void>;
 export { HELP, verbHelp, main };

package/dist/cli/index.js

@@ -10,6 +10,8 @@ const scan_1 = require("./scan");
 const login_1 = require("./login");
 const history_1 = require("./history");
 const coverage_1 = require("./coverage");
+const generate_1 = require("./generate");
+const skill_1 = require("./skill");
 // dist/cli/ → package root; npm ships package.json in every tarball.
 const VERSION = require('../../package.json').version;
 const HELP = `ia-qa-discover — deterministic surface reconnaissance for a web app
@@ -83,6 +85,30 @@ Usage:
                                               --report [file.html]     branded HTML dossier with the gap
                                                                        (default ia-qa-discover-coverage.html)
                                               --open                   open that report in the browser
+  ia-qa-discover generate [page…]           A starting Playwright suite for the pages nothing
+                                             tests — one file per page, into its own directory.
+                                             Every locator names an element the healing contract
+                                             holds, so the file is REPAIRED when the app moves
+                                             instead of going red. A field with no test id, id or
+                                             name is left out and says so: its selector would be
+                                             positional, which nobody can test reliably.
+                                             Proposals — nothing is added to your suite, and the
+                                             assertions stay yours (the app declares what it
+                                             accepts, never what it promises).
+                                             With no page, it generates for the coverage gap.
+                                              --out <dir>   where to write (default
+                                                            .ia-qa-discovery/generated/)
+                                              --force       replace files already there
+                                              --json        machine-readable summary on stdout
+  ia-qa-discover skill                     This CLI's agent instructions: the verb for each
+                                             question, what every refusal means, and what an
+                                             agent must never do. Read them before driving
+                                             anything else here.
+                                              --print       write them to stdout and stop
+                                              --install     write .claude/skills/ia-qa-discover/
+                                              --user        into ~/ instead of this project
+                                              --dir <d>     into another project root
+                                              --force       overwrite an edited copy
   ia-qa-discover history                   Recorded scan runs — pages/forms/API-surface trend.
                                               --json   --limit <n> (default 500)
   ia-qa-discover version                   Print the installed version (also --version, -v)
@@ -158,9 +184,15 @@ async function main() {
         case 'coverage':
             await (0, coverage_1.runCoverage)(rest);
             break;
+        case 'generate':
+            await (0, generate_1.runGenerate)(rest);
+            break;
         case 'history':
             await (0, history_1.runHistory)(rest);
             break;
+        case 'skill':
+            await (0, skill_1.runSkill)(rest);
+            break;
         case 'version':
         case '--version':
         case '-v':

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/skill.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `ia-qa-discover skill` — install this CLI's agent instructions.
+ *
+ * The markdown is the payload; the verb is the load-bearing half. Agents load skills from
+ * `.claude/skills/`, never from `node_modules`, so a `SKILL.md` that only ships in the
+ * tarball is a copy of the doctrine nobody reads.
+ *
+ * The implementation is `@ia-qa/self-healing`'s, imported rather than copied: three packages
+ * needing the identical verb is exactly the case where a third copy starts drifting — and it
+ * would drift in the file whose whole subject is "the instructions must reach the agent".
+ * Only the name, the binary and this package's root differ.
+ */
+export declare const SKILL_NAME = "ia-qa-discover";
+export declare const skillSourcePath: () => string;
+export declare const readSkill: () => string;
+export declare const skillTargetDir: (opts: {
+    user?: boolean;
+    dir?: string;
+}) => string;
+export declare const runSkill: (args: string[]) => Promise<void>;

package/dist/cli/skill.js

@@ -0,0 +1,63 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSkill = exports.skillTargetDir = exports.readSkill = exports.skillSourcePath = exports.SKILL_NAME = void 0;
+const path = __importStar(require("path"));
+const self_healing_1 = require("@ia-qa/self-healing");
+/**
+ * `ia-qa-discover skill` — install this CLI's agent instructions.
+ *
+ * The markdown is the payload; the verb is the load-bearing half. Agents load skills from
+ * `.claude/skills/`, never from `node_modules`, so a `SKILL.md` that only ships in the
+ * tarball is a copy of the doctrine nobody reads.
+ *
+ * The implementation is `@ia-qa/self-healing`'s, imported rather than copied: three packages
+ * needing the identical verb is exactly the case where a third copy starts drifting — and it
+ * would drift in the file whose whole subject is "the instructions must reach the agent".
+ * Only the name, the binary and this package's root differ.
+ */
+exports.SKILL_NAME = 'ia-qa-discover';
+const verb = (0, self_healing_1.createSkillVerb)({
+    name: exports.SKILL_NAME,
+    cli: 'ia-qa-discover',
+    // `dist/cli/` and `src/cli/` are both two levels under the package root, so this resolves
+    // from the published build and from the sources under test alike.
+    packageRoot: path.join(__dirname, '..', '..'),
+});
+exports.skillSourcePath = verb.skillSourcePath;
+exports.readSkill = verb.readSkill;
+exports.skillTargetDir = verb.skillTargetDir;
+exports.runSkill = verb.runSkill;
+//# sourceMappingURL=skill.js.map

package/dist/cli/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/cli/skill.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAA6B;AAC7B,sDAAsD;AAEtD;;;;;;;;;;;GAWG;AACU,QAAA,UAAU,GAAG,gBAAgB,CAAC;AAE3C,MAAM,IAAI,GAAG,IAAA,8BAAe,EAAC;IAC3B,IAAI,EAAE,kBAAU;IAChB,GAAG,EAAE,gBAAgB;IACrB,0FAA0F;IAC1F,kEAAkE;IAClE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC;CAC9C,CAAC,CAAC;AAEU,QAAA,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;AACvC,QAAA,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;AAC3B,QAAA,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;AACrC,QAAA,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC"}

package/dist/cli-ai/index.d.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { CLASSIFICATION_FILENAME, CLASSIFICATION_SCHEMA } from '../ai/classify';
 export { CLASSIFICATION_SCHEMA, CLASSIFICATION_FILENAME };
-declare const HELP = "ia-qa-discover-ai \u2014 optional BYOK classification for a discovery capture\n\nWhat each entry point your app exposes is FOR, and how sensitive what it handles\nis. Reads .ia-qa-discovery/capture/ offline \u2014 it never opens a browser and never\ntouches your application. Your key, your model, your machine.\n\nEvery classification carries a sentence you read and a path into the capture that\nthis tool resolves and checks before keeping it. A claim that cites nothing, cites\nsomething that does not exist, or misdescribes what it cites, is DROPPED and the\ndrop is reported. That check proves the premise, never the conclusion: only you\ncan say whether the reading follows.\n\nNothing here is a gate. `ia-qa-discover` works fully without a key.\n\nUsage:\n  ia-qa-discover-ai classify              Classify every entry point in the capture.\n                                            --page <name>  just this page\n                                            --json         machine-readable output\n                                            --dry-run      show what would be sent, call nothing\n  ia-qa-discover-ai models                List the providers and models you can configure\n  ia-qa-discover-ai version               Print the installed version\n  ia-qa-discover-ai help                  Show this help\n\nConfigure it in .ia-qa-discovery/config.json:\n\n  \"ai\": {\n    \"provider\": \"anthropic\",\n    \"model\": \"claude-haiku-4-5\",\n    \"apiKey\": { \"source\": \"env\", \"key\": \"ANTHROPIC_API_KEY\" }\n  }\n\nThe key itself never goes in that file \u2014 only the name of the variable holding it.\n\nGlobal:\n  --config <dir>   Resolve .ia-qa-discovery/ under <dir> instead of the current directory\n";
+declare const HELP = "ia-qa-discover-ai \u2014 optional BYOK classification for a discovery capture\n\nWhat each entry point your app exposes is FOR, and how sensitive what it handles\nis. Reads .ia-qa-discovery/capture/ offline \u2014 it never opens a browser and never\ntouches your application. Your key, your model, your machine.\n\nEvery classification carries a sentence you read and a path into the capture that\nthis tool resolves and checks before keeping it. A claim that cites nothing, cites\nsomething that does not exist, or misdescribes what it cites, is DROPPED and the\ndrop is reported. That check proves the premise, never the conclusion: only you\ncan say whether the reading follows.\n\n`plan` sends strictly LESS than `classify`: no selectors and no observed API calls ever\nleave for it. Each verb announces exactly what goes, before it goes.\n\nNothing here is a gate, and nothing here reorders anything a deterministic verb measured.\n`ia-qa-discover` works fully without a key.\n\nUsage:\n  ia-qa-discover-ai classify              Classify every entry point in the capture.\n                                            --page <name>  just this page\n                                            --json         machine-readable output\n                                            --dry-run      show what would be sent, call nothing\n  ia-qa-discover-ai plan                  What someone comes to each page to DO, and what\n                                          they cannot do if it breaks \u2014 in business words.\n                                          Reads the pages your suite does not visit, from\n                                          `ia-qa-discover coverage`; every page when there\n                                          is no suite to compare against.\n                                            --all          every readable page, tested or not\n                                            --page <name>  just this page\n                                            --report [f]   branded HTML report (+ --open)\n                                            --json         machine-readable output\n                                            --dry-run      show what would be sent, call nothing\n  ia-qa-discover-ai models                List the providers and models you can configure\n  ia-qa-discover-ai version               Print the installed version\n  ia-qa-discover-ai help                  Show this help\n\nConfigure it in .ia-qa-discovery/config.json:\n\n  \"ai\": {\n    \"provider\": \"anthropic\",\n    \"model\": \"claude-haiku-4-5\",\n    \"apiKey\": { \"source\": \"env\", \"key\": \"ANTHROPIC_API_KEY\" }\n  }\n\nThe key itself never goes in that file \u2014 only the name of the variable holding it.\n\nGlobal:\n  --config <dir>   Resolve .ia-qa-discovery/ under <dir> instead of the current directory\n";
 declare function runClassify(args: string[]): Promise<void>;
+declare function runPlan(args: string[]): Promise<void>;
 declare function main(): Promise<void>;
-export { HELP, main, runClassify };
+export { HELP, main, runClassify, runPlan };

package/dist/cli-ai/index.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = exports.CLASSIFICATION_FILENAME = exports.CLASSIFICATION_SCHEMA = void 0;
 exports.main = main;
 exports.runClassify = runClassify;
+exports.runPlan = runPlan;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const self_healing_1 = require("@ia-qa/self-healing");
@@ -45,6 +46,12 @@ const citations_1 = require("../citations");
 const classify_1 = require("../ai/classify");
 Object.defineProperty(exports, "CLASSIFICATION_FILENAME", { enumerable: true, get: function () { return classify_1.CLASSIFICATION_FILENAME; } });
 Object.defineProperty(exports, "CLASSIFICATION_SCHEMA", { enumerable: true, get: function () { return classify_1.CLASSIFICATION_SCHEMA; } });
+const plan_1 = require("../ai/plan");
+const planView_1 = require("../planView");
+const coverage_1 = require("../coverage");
+const scan_1 = require("../cli/scan");
+const htmlReport_1 = require("../htmlReport");
+const sharedCalls_1 = require("../sharedCalls");
 const taxonomy_1 = require("../taxonomy");
 const overviewFile_1 = require("../overviewFile");
 /**
@@ -71,13 +78,27 @@ something that does not exist, or misdescribes what it cites, is DROPPED and the
 drop is reported. That check proves the premise, never the conclusion: only you
 can say whether the reading follows.
 
-Nothing here is a gate. \`ia-qa-discover\` works fully without a key.
+\`plan\` sends strictly LESS than \`classify\`: no selectors and no observed API calls ever
+leave for it. Each verb announces exactly what goes, before it goes.
+
+Nothing here is a gate, and nothing here reorders anything a deterministic verb measured.
+\`ia-qa-discover\` works fully without a key.
 
 Usage:
   ia-qa-discover-ai classify              Classify every entry point in the capture.
                                             --page <name>  just this page
                                             --json         machine-readable output
                                             --dry-run      show what would be sent, call nothing
+  ia-qa-discover-ai plan                  What someone comes to each page to DO, and what
+                                          they cannot do if it breaks — in business words.
+                                          Reads the pages your suite does not visit, from
+                                          \`ia-qa-discover coverage\`; every page when there
+                                          is no suite to compare against.
+                                            --all          every readable page, tested or not
+                                            --page <name>  just this page
+                                            --report [f]   branded HTML report (+ --open)
+                                            --json         machine-readable output
+                                            --dry-run      show what would be sent, call nothing
   ia-qa-discover-ai models                List the providers and models you can configure
   ia-qa-discover-ai version               Print the installed version
   ia-qa-discover-ai help                  Show this help
@@ -143,6 +164,19 @@ async function resolveAi() {
     // names `ia-qa-heal`, its CLI path and `.ia-qa/config.json`, and sending
     // someone here to a different tool's config is worse than no help at all.
     // Everything else (AWS SSM) still delegates: one secret path, not two.
+    // The value where a NAME belongs. Refused before the lookup, and never echoed: the
+    // "not set" message below would otherwise print the key into the terminal and into any
+    // log that captured it. One rule, imported — heal owns it, both packages apply it.
+    if (typeof ai.apiKey === 'string' || (0, self_healing_1.looksLikeSecret)(String(ai.apiKey.key ?? ''))) {
+        const shown = typeof ai.apiKey === 'string' ? String(ai.apiKey) : String(ai.apiKey.key);
+        console.error(`❌ ai.apiKey holds what looks like the key itself (${(0, self_healing_1.maskSecret)(shown)}), not the name of a variable.\n\n` +
+            `   ${config_1.CONFIG_DIR}/config.json is committed: a value here is a leaked credential, so it is\n` +
+            `   refused rather than used. Put the value in your environment and name it:\n` +
+            `     "apiKey": { "source": "env", "key": "${provider.keyEnv}" }\n\n` +
+            `   Then rotate the one you pasted — assume it is already in your git history.`);
+        process.exitCode = 2;
+        return null;
+    }
     if (ai.apiKey.source === 'env' && !process.env[ai.apiKey.key]) {
         console.error(`❌ Environment variable "${ai.apiKey.key}" is not set, so there is no key to call ${provider.label} with.\n\n` +
             `   This CLI reads process.env only — it never loads .env files, so a key that lives\n` +
@@ -154,7 +188,7 @@ async function resolveAi() {
     }
     try {
         const apiKey = await (0, self_healing_1.resolveSecret)(ai.apiKey);
-        return { provider: provider.id, model: ai.model, apiKey };
+        return { provider: provider.id, model: ai.model, apiKey, ...(ai.baseUrl ? { baseUrl: ai.baseUrl } : {}) };
     }
     catch (e) {
         console.error(`❌ ${e instanceof Error ? e.message : String(e)}`);
@@ -215,10 +249,10 @@ async function runClassify(args) {
     }
     // "Offline" above means no browser, and on its own it reads as "nothing leaves".
     // stderr in every mode, `--json` included — a security announcement, not decoration.
-    console.error((0, classify_1.egressNotice)(ai.provider, ai.model, withEntryPoints.length));
+    console.error((0, classify_1.egressNotice)(ai.provider, ai.model, withEntryPoints.length, false, ai.baseUrl));
     const perPage = {};
     for (const page of withEntryPoints) {
-        const result = await (0, classify_1.classifyPage)(page, index, { provider: ai.provider, model: ai.model, apiKey: ai.apiKey });
+        const result = await (0, classify_1.classifyPage)(page, index, { provider: ai.provider, model: ai.model, apiKey: ai.apiKey, baseUrl: ai.baseUrl });
         perPage[page.page] = result;
         if (!json) {
             if (result.failed) {
@@ -316,6 +350,233 @@ async function runClassify(args) {
     console.log(`\nWritten to ${file}`);
     console.log(`Every kept claim cites the capture. Read the "why" and the evidence before acting on it.`);
 }
+/**
+ * Which pages `plan` reads, and why — the one decision this verb makes on its own.
+ *
+ * The question it answers is "what would it cost if this page broke", which is only worth
+ * asking about pages nothing tests. So when a coverage map can be computed, the untested
+ * list IS the target, in its order. When it cannot — no suite tracked here, or one never
+ * watched running — the honest fallback is every readable page, said out loud: a discovery
+ * user with no suite is exactly the population this package exists for, and refusing them
+ * the verb because a sibling package is absent would be the cross-reference-as-advertising
+ * defect in its most expensive form.
+ */
+function planTargets(pages, all) {
+    const readable = pages.filter(plan_1.isReadable);
+    if (all)
+        return { scope: 'all', order: [], targets: readable, because: '--all: every readable page, tested or not.' };
+    const config = (() => {
+        try {
+            return (0, config_1.loadConfig)();
+        }
+        catch {
+            return null;
+        }
+    })();
+    const outcome = (0, coverage_1.computeCoverage)({
+        captureDirPath: (0, config_1.captureDir)(),
+        healingDirPath: path.join((0, config_1.baseDir)(), coverage_1.HEALING_DIR),
+        scope: config?.outOfScope,
+    });
+    if (!outcome.ok) {
+        return {
+            scope: 'all',
+            order: [],
+            targets: readable,
+            because: `No coverage map here (${outcome.refusal.reason}), so there is no untested list to narrow to — ` +
+                `reading every page instead. \`ia-qa-discover coverage\` explains what would produce one.`,
+        };
+    }
+    const order = outcome.map.uncovered.map((u) => u.page);
+    const rank = new Map(order.map((name, i) => [name, i]));
+    return {
+        scope: 'uncovered',
+        order,
+        // Sorted into the ranking, not merely filtered by it. The line below claims "in its
+        // order", and a run that read them in directory order while saying so would be the
+        // smallest possible version of a message that does not describe what happened — it also
+        // decides which pages are already read when someone interrupts a long run.
+        targets: readable
+            .filter((p) => rank.has(p.page))
+            .sort((a, b) => rank.get(a.page) - rank.get(b.page)),
+        because: `The ${order.length} page(s) \`coverage\` found that no test visits, in its order.`,
+    };
+}
+/**
+ * The same branded dossier `scan --report` writes, from the verb that produced the reading.
+ *
+ * Its own function rather than a flag threaded through `scan`: after `plan`, the report is
+ * the natural place to look, and telling someone to re-run a crawl to see a file assembled
+ * from what is already on disk is the kind of instruction that never gets followed. Nothing
+ * is recomputed — `renderScanReport` is handed the capture and the view, and the plan
+ * section is rendered by the same module as the terminal.
+ */
+function writePlanReport(wanted, view, open) {
+    const surface = (0, coverage_1.loadSurface)((0, config_1.captureDir)());
+    if (!surface?.manifest?.coverage)
+        return null;
+    const index = (0, citations_1.loadCaptureIndex)();
+    const shared = index.shared ?? {
+        schema: sharedCalls_1.SHARED_CALLS_SCHEMA,
+        capturedAt: surface.manifest.capturedAt,
+        sourcePages: 0,
+        threshold: 0,
+        calls: [],
+    };
+    const file = path.resolve(process.cwd(), wanted);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, (0, htmlReport_1.renderScanReport)({
+        manifest: surface.manifest,
+        pages: surface.pages,
+        shared,
+        ...surface.manifest.coverage,
+        plan: view,
+    }), 'utf8');
+    if (open)
+        (0, scan_1.openInBrowser)(file);
+    return file;
+}
+async function runPlan(args) {
+    const json = args.includes('--json');
+    const dryRun = args.includes('--dry-run');
+    const all = args.includes('--all');
+    const only = flag(args, '--page');
+    const index = (0, citations_1.loadCaptureIndex)();
+    if (index.pages.size === 0) {
+        console.error(`❌ No capture in ${path.relative(process.cwd(), (0, config_1.captureDir)()) || (0, config_1.captureDir)()}.\n` +
+            `   Run \`ia-qa-discover scan\` first — this reads a capture, it does not make one.`);
+        process.exitCode = 2;
+        return;
+    }
+    const captured = [...index.pages.values()];
+    const { scope, order, targets, because } = planTargets(captured, all);
+    const pages = targets.filter((p) => !only || p.page === only);
+    if (only && pages.length === 0) {
+        const known = captured.map((p) => p.page);
+        console.error(known.includes(only)
+            ? `❌ Page "${only}" is in the capture but not in this run's targets (${because ?? ''}).\n` +
+                `   Add --all to read it anyway.`
+            : `❌ No page "${only}" in the capture. Have: ${known.join(', ')}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (pages.length === 0) {
+        // Not a failure and not an empty document: there is genuinely nothing to ask about.
+        const line = scope === 'uncovered'
+            ? `Nothing to read: every page this scan found is already visited by your suite.\n` +
+                `   Add --all to read the tested pages too.`
+            : `Nothing to read: no page in this capture carries a title, a heading or a field to cite.`;
+        if (json)
+            console.log(JSON.stringify({ schema: plan_1.PLAN_SCHEMA, scope, pages: {}, totals: { read: 0, unclear: 0, dropped: 0, failed: 0 }, written: false }, null, 2));
+        else
+            console.log(`\n${line}`);
+        return;
+    }
+    const names = captured.map((p) => p.page);
+    // Computed once, over EVERY captured page — not over the targets. A heading is the app's
+    // shell because the app repeats it, and a narrowed target list would make the same heading
+    // look page-specific.
+    const shell = (0, plan_1.shellHeadings)(captured);
+    if (dryRun) {
+        console.log(`Would read ${pages.length} page(s) of the ${captured.length} captured:`);
+        for (const p of pages)
+            console.log(`  ${p.page}`);
+        if (because)
+            console.log(`  (${because})`);
+        const declared = ((0, config_1.configExists)() ? (0, config_1.loadConfig)().ai : undefined) ?? {};
+        const provider = (0, self_healing_1.findProvider)(declared.provider ?? '');
+        if (provider)
+            console.log((0, plan_1.planEgressNotice)(provider.id, declared.model ?? '(no model set)', pages.length, true));
+        console.log(`Nothing was called. Drop --dry-run to run it.`);
+        return;
+    }
+    const ai = await resolveAi();
+    if (!ai)
+        return;
+    if (!json) {
+        console.log(`🤖 ${ai.provider}/${ai.model} · ${pages.length} page(s)`);
+        if (because)
+            console.log(`   ${because}`);
+        console.log(`   Reading the capture offline. Your app is not touched.`);
+    }
+    // "Offline" above means no browser, and on its own it reads as "nothing leaves".
+    console.error((0, plan_1.planEgressNotice)(ai.provider, ai.model, pages.length, false, ai.baseUrl));
+    const perPage = {};
+    for (const page of pages) {
+        const outcome = await (0, plan_1.readPage)(page, index, { provider: ai.provider, model: ai.model, apiKey: ai.apiKey, baseUrl: ai.baseUrl }, names, shell);
+        perPage[page.page] = outcome;
+        if (!json) {
+            const mark = outcome.status === 'read' ? '✓' : outcome.status === 'unclear' ? '🤔' : outcome.status === 'dropped' ? '✘' : '✘';
+            const detail = outcome.status === 'read' || outcome.status === 'unclear'
+                ? outcome.reading.purpose
+                : outcome.status === 'dropped'
+                    ? outcome.dropped.reason
+                    : outcome.reason;
+            console.log(`  ${page.page.padEnd(22)} ${mark} ${detail}`);
+        }
+    }
+    const totals = {
+        read: Object.values(perPage).filter((o) => o.status === 'read').length,
+        unclear: Object.values(perPage).filter((o) => o.status === 'unclear').length,
+        dropped: Object.values(perPage).filter((o) => o.status === 'dropped').length,
+        failed: Object.values(perPage).filter((o) => o.status === 'failed').length,
+    };
+    // A call that did not happen is not a page with nothing on it. Reported before any total,
+    // and it sets a non-zero exit — the same rule `classify` pays: with an invalid key, "0
+    // read" must never be indistinguishable from an app with nothing to say.
+    if (totals.failed > 0) {
+        const failed = Object.entries(perPage).filter(([, o]) => o.status === 'failed');
+        console.error(`\n❌ ${totals.failed} of ${pages.length} page(s) could not be read at all:`);
+        for (const [name, o] of failed.slice(0, 5))
+            console.error(`   ${name}: ${o.reason}`);
+        if (failed.length > 5)
+            console.error(`   …and ${failed.length - 5} more.`);
+        console.error(`   Nothing is wrong with your app or your capture — the model call did not succeed.`);
+        process.exitCode = 2;
+        if (totals.failed === pages.length) {
+            // Nothing to WRITE: a document of failures would overwrite a good previous reading
+            // with the record of a bad key. Not writing is not a reason to say nothing, so
+            // `--json` still gets its document on stdout.
+            if (json) {
+                console.log(JSON.stringify({ schema: plan_1.PLAN_SCHEMA, readAt: new Date().toISOString(), model: `${ai.provider}/${ai.model}`, scope, totals, pages: perPage, written: false }, null, 2));
+            }
+            return;
+        }
+    }
+    const document = {
+        schema: plan_1.PLAN_SCHEMA,
+        readAt: new Date().toISOString(),
+        model: `${ai.provider}/${ai.model}`,
+        scope,
+        targeted: pages.map((p) => p.page),
+        totals,
+        pages: perPage,
+    };
+    const file = path.join((0, config_1.baseDir)(), config_1.CONFIG_DIR, plan_1.PLAN_FILENAME);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(document, null, 2) + '\n', 'utf8');
+    // `plan.json` is not where anyone looks. `_overview.md` is, and `scan` wrote it before
+    // this reading existed — so it is rewritten here, the only moment the reading is not
+    // stale. A refusal is reported, never swallowed.
+    const refreshed = (0, overviewFile_1.refreshOverview)();
+    if (!refreshed.ok)
+        console.error(`\n⚠  _overview.md was not updated: ${refreshed.reason}`);
+    const view = (0, planView_1.buildPlanView)(document, captured, order);
+    const wantedReport = (0, scan_1.reportPath)(args, 'ia-qa-discover-plan.html');
+    const reportFile = wantedReport ? writePlanReport(wantedReport, view, args.includes('--open')) : null;
+    if (wantedReport && !reportFile) {
+        console.error(`\n⚠  No HTML report: this capture predates coverage being recorded in surface.json, so the\n` +
+            `   report cannot state what the scan could not see. Re-run \`ia-qa-discover scan\`.`);
+    }
+    if (json) {
+        console.log(JSON.stringify({ ...document, overview: refreshed.ok ? refreshed.file : null, report: reportFile }, null, 2));
+        return;
+    }
+    console.log((0, planView_1.renderPlanTerminal)(view));
+    console.log(`\nWritten to ${file}`);
+    if (reportFile)
+        console.log(`Report:    ${reportFile}`);
+}
 async function main() {
     const argv = process.argv.slice(2);
     const ci = argv.indexOf('--config');
@@ -331,6 +592,9 @@ async function main() {
         case 'classify':
             await runClassify(rest);
             break;
+        case 'plan':
+            await runPlan(rest);
+            break;
         case 'models':
             console.log((0, self_healing_1.renderModelList)());
             break;