@ia-qa/qa-discovery 0.3.0 → 0.5.0

package/dist/planView.js

@@ -0,0 +1,345 @@
+"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.PLAN_STALE_CAVEAT = exports.PLAN_CAVEAT = void 0;
+exports.planPath = planPath;
+exports.loadPlan = loadPlan;
+exports.buildPlanView = buildPlanView;
+exports.planHeadline = planHeadline;
+exports.scopeLine = scopeLine;
+exports.outsideScopeLine = outsideScopeLine;
+exports.renderPlanTerminal = renderPlanTerminal;
+exports.renderPlanMarkdown = renderPlanMarkdown;
+exports.renderPlanHtml = renderPlanHtml;
+exports.planFor = planFor;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const plan_1 = require("./ai/plan");
+function planPath(cwd = (0, config_1.baseDir)()) {
+    return path.join(cwd, config_1.CONFIG_DIR, plan_1.PLAN_FILENAME);
+}
+/**
+ * Read the plan, or null when there is none.
+ *
+ * A file whose `schema` is not the one this build understands is treated as absent rather
+ * than parsed optimistically: a report rendering fields it guessed at is worse than a report
+ * with no plan section.
+ */
+function loadPlan(file = planPath()) {
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed?.schema !== plan_1.PLAN_SCHEMA || typeof parsed.pages !== 'object' || !parsed.pages)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the page was captured after it was read. */
+function isStale(page, readAt) {
+    if (!page?.capturedAt)
+        return false;
+    const captured = Date.parse(page.capturedAt);
+    const read = Date.parse(readAt);
+    if (Number.isNaN(captured) || Number.isNaN(read))
+        return false;
+    return captured > read;
+}
+/**
+ * Pair a plan document with the capture on disk now.
+ *
+ * `order` is the coverage map's ranking when there is one. Pages it does not name keep their
+ * alphabetical place after it — a page the model read and the ranking never mentioned is
+ * still shown, never dropped to make the list tidy.
+ */
+function buildPlanView(doc, pages, order = []) {
+    const byName = new Map(pages.map((p) => [p.page, p]));
+    const rank = new Map(order.map((name, i) => [name, i]));
+    const out = [];
+    for (const [name, outcome] of Object.entries(doc.pages)) {
+        if (!byName.has(name))
+            continue; // a reading of a page that is no longer captured
+        const row = { page: name, stale: isStale(byName.get(name), doc.readAt) };
+        if (outcome?.status === 'read' || outcome?.status === 'unclear')
+            row.reading = outcome.reading;
+        else if (outcome?.status === 'dropped')
+            row.dropped = { reason: outcome.dropped.reason };
+        else if (outcome?.status === 'failed')
+            row.failed = outcome.reason;
+        out.push(row);
+    }
+    out.sort((a, b) => {
+        const ra = rank.has(a.page) ? rank.get(a.page) : Number.MAX_SAFE_INTEGER;
+        const rb = rank.has(b.page) ? rank.get(b.page) : Number.MAX_SAFE_INTEGER;
+        return ra - rb || a.page.localeCompare(b.page);
+    });
+    const candidates = pages.filter(plan_1.isReadable);
+    const seen = new Set(out.filter((p) => !p.failed).map((p) => p.page));
+    // A document written before `targeted` existed can only say what it holds.
+    const targeted = new Set(doc.targeted ?? Object.keys(doc.pages));
+    const notRead = candidates.filter((p) => targeted.has(p.page) && !seen.has(p.page)).map((p) => p.page).sort();
+    const outsideScope = candidates.filter((p) => !targeted.has(p.page)).map((p) => p.page).sort();
+    return {
+        model: doc.model,
+        readAt: doc.readAt,
+        scope: doc.scope,
+        pages: out,
+        notRead,
+        outsideScope,
+        nothingToRead: pages.length - candidates.length,
+        staleCount: out.filter((p) => p.stale).length,
+        readTotal: out.filter((p) => p.reading && !p.reading.unclear).length,
+        unclearTotal: out.filter((p) => p.reading?.unclear).length,
+        droppedTotal: out.filter((p) => p.dropped).length,
+        failedTotal: out.filter((p) => p.failed).length,
+    };
+}
+/**
+ * The one-line summary every renderer puts at the top.
+ *
+ * It leads with what was read and immediately qualifies it: a bare "12 pages read" is the
+ * confident number this package spends its design refusing to print.
+ */
+function planHeadline(v) {
+    const bits = [`${v.readTotal} page${v.readTotal === 1 ? '' : 's'} read`];
+    if (v.unclearTotal > 0)
+        bits.push(`${v.unclearTotal} unclear`);
+    if (v.droppedTotal > 0)
+        bits.push(`${v.droppedTotal} dropped`);
+    if (v.failedTotal > 0)
+        bits.push(`${v.failedTotal} failed`);
+    if (v.notRead.length > 0)
+        bits.push(`${v.notRead.length} not read`);
+    if (v.staleCount > 0)
+        bits.push(`${v.staleCount} stale`);
+    return bits.join(' · ');
+}
+/**
+ * The caveat, deliberately narrow.
+ *
+ * The tool already drops a reading whose citation does not resolve, so telling the reader to
+ * re-check everything would be alarm fatigue — a warning that fires on the good rows is one
+ * people learn to skip. It names the residual risk instead, and the one thing a reader might
+ * otherwise assume: that the model had a say in the order.
+ */
+exports.PLAN_CAVEAT = 'Each line below is a MODEL reading of the capture, not an observation of your app. Every one ' +
+    'cites something this tool resolved in the capture and checked; a reading whose citation did not ' +
+    'exist was dropped before you saw it. 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. Nothing here ranks ' +
+    'anything: the order is the one `ia-qa-discover coverage` measured, and this gates nothing.';
+exports.PLAN_STALE_CAVEAT = 'These pages were re-captured after they were read, so the sentence describes a version of the ' +
+    'page that is no longer on disk. Re-run `ia-qa-discover-ai plan` before relying on them.';
+/** What the scope means, stated wherever the plan is shown. */
+function scopeLine(v) {
+    return v.scope === 'uncovered'
+        ? 'Read: the pages `ia-qa-discover coverage` found that no test visits.'
+        : 'Read: every page in the capture — no tracked suite here, so there is no untested list to narrow to.';
+}
+/**
+ * What was left out, and why — never as a shortfall.
+ *
+ * Under `uncovered` the answer is good news (a test visits them), so wording it like the
+ * `notRead` list would turn a covered app into a report of a half-read one.
+ */
+function outsideScopeLine(v) {
+    if (v.outsideScope.length === 0)
+        return null;
+    const names = v.outsideScope.join(', ');
+    return v.scope === 'uncovered'
+        ? `${v.outsideScope.length} page(s) your suite already visits were not read: ${names}. Add --all to read them too.`
+        : `${v.outsideScope.length} page(s) were not part of this run: ${names}.`;
+}
+function readingLine(p) {
+    if (p.failed)
+        return `✘ not read — ${p.failed}`;
+    if (p.dropped)
+        return `✘ reading dropped — ${p.dropped.reason}`;
+    if (!p.reading)
+        return '—';
+    const conf = ` (confidence ${p.reading.confidence.toFixed(2)})`;
+    if (p.reading.unclear)
+        return `🤔 unclear — ${p.reading.purpose}${conf}`;
+    return `${p.reading.purpose}${p.reading.impact ? ` · If it breaks: ${p.reading.impact}` : ''}${conf}`;
+}
+function renderPlanTerminal(v) {
+    const lines = [`\n🤖 ${planHeadline(v)}  ·  ${v.model}`, `   ${scopeLine(v)}`];
+    if (v.pages.length === 0) {
+        lines.push(`\n   Nothing was read.`);
+    }
+    else {
+        lines.push('');
+        for (const p of v.pages) {
+            lines.push(`   · ${p.page}${p.stale ? '  ⏳ stale' : ''}`);
+            lines.push(`     ${readingLine(p)}`);
+        }
+    }
+    if (v.notRead.length > 0) {
+        lines.push(`\n   Not read (${v.notRead.length}): ${v.notRead.join(', ')}`);
+    }
+    const outside = outsideScopeLine(v);
+    if (outside)
+        lines.push(`\n   ${outside}`);
+    if (v.nothingToRead > 0) {
+        lines.push(`   ${v.nothingToRead} page(s) had nothing to cite — no title, no heading, no field. ` +
+            `Never sent, and not a gap.`);
+    }
+    if (v.staleCount > 0)
+        lines.push(`\n   ⏳ ${exports.PLAN_STALE_CAVEAT}`);
+    lines.push(`\n   ${exports.PLAN_CAVEAT}`);
+    return lines.join('\n');
+}
+function renderPlanMarkdown(v) {
+    const out = ['## What a model reads these pages as', '', `${planHeadline(v)} — \`${v.model}\`.`, '', scopeLine(v), ''];
+    if (v.pages.length > 0) {
+        out.push('| Page | A model\'s reading | Confidence |', '| --- | --- | --- |');
+        for (const p of v.pages) {
+            const conf = p.reading ? p.reading.confidence.toFixed(2) : '—';
+            const text = p.failed
+                ? `not read — ${p.failed}`
+                : p.dropped
+                    ? `reading dropped — ${p.dropped.reason}`
+                    : p.reading
+                        ? `${p.reading.unclear ? '**unclear** — ' : ''}${p.reading.purpose}${p.reading.impact ? ` **If it breaks:** ${p.reading.impact}` : ''}`
+                        : '—';
+            out.push(`| \`${p.page}\`${p.stale ? ' ⏳' : ''} | ${text.replace(/\|/g, '\\|')} | ${conf} |`);
+        }
+        out.push('');
+    }
+    if (v.notRead.length > 0)
+        out.push(`Not read: ${v.notRead.map((p) => `\`${p}\``).join(', ')}`, '');
+    const outsideMd = outsideScopeLine(v);
+    if (outsideMd)
+        out.push(outsideMd, '');
+    if (v.nothingToRead > 0) {
+        out.push(`${v.nothingToRead} page(s) had nothing to cite and were never sent — not a gap.`, '');
+    }
+    if (v.staleCount > 0)
+        out.push(`⏳ ${exports.PLAN_STALE_CAVEAT}`, '');
+    out.push(exports.PLAN_CAVEAT, '');
+    return out.join('\n');
+}
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/**
+ * One counter tile, in the report's own language.
+ *
+ * Counts only — the rule `coverageView` states and this section inherits: no percentage
+ * anywhere, because the denominator here is what somebody chose to read, not something a
+ * compiler guarantees.
+ */
+function stat(n, label) {
+    return `<div class="stat"><div class="n">${n}</div><div class="l">${esc(label)}</div></div>`;
+}
+function renderPlanHtml(v) {
+    const rows = v.pages
+        .map((p) => {
+        // The state of a row is a pill, not a prefix buried in prose: it is the first thing
+        // worth seeing, and `unclear` in particular must not read like an ordinary answer.
+        const pills = [
+            p.failed ? '<span class="pill fail">not read</span>' : '',
+            p.dropped ? '<span class="pill fail">dropped</span>' : '',
+            p.reading?.unclear ? '<span class="pill warn">unclear</span>' : '',
+            p.stale ? '<span class="pill warn">stale</span>' : '',
+        ]
+            .filter(Boolean)
+            .join(' ');
+        // Each branch escapes its own strings and returns finished markup. An earlier shape
+        // built the text first and escaped it afterwards "unless it already was" — one
+        // condition away from putting a model's sentence into the page as HTML.
+        const body = p.failed
+            ? esc(p.failed)
+            : p.dropped
+                ? esc(p.dropped.reason)
+                : p.reading
+                    ? esc(p.reading.purpose) +
+                        (p.reading.impact ? `<div class="note" style="margin-top:6px">If it breaks: ${esc(p.reading.impact)}</div>` : '')
+                    : '—';
+        // Deliberately NOT coloured by band. A green 0.90 would read as "this page is fine",
+        // which is a verdict — and this section issues none.
+        const conf = p.reading ? p.reading.confidence.toFixed(2) : '—';
+        return (`<tr><td><code>${esc(p.page)}</code>${pills ? `<div style="margin-top:5px">${pills}</div>` : ''}</td>` +
+            `<td>${body}</td><td class="muted">${esc(conf)}</td></tr>`);
+    })
+        .join('\n');
+    const tiles = [
+        stat(v.readTotal, 'read'),
+        v.unclearTotal > 0 ? stat(v.unclearTotal, 'unclear') : '',
+        v.droppedTotal > 0 ? stat(v.droppedTotal, 'dropped') : '',
+        v.failedTotal > 0 ? stat(v.failedTotal, 'failed') : '',
+        v.notRead.length > 0 ? stat(v.notRead.length, 'not read') : '',
+        v.staleCount > 0 ? stat(v.staleCount, 'stale') : '',
+    ]
+        .filter(Boolean)
+        .join('');
+    return [
+        '<section class="plan">',
+        // The same label its sibling carries. Everything above this line in the report is a
+        // literal observation; the pill is what says this one is not.
+        '<h2>What a model reads these pages as <span class="pill info">model-read</span></h2>',
+        `<p class="headline">${esc(scopeLine(v))}</p>`,
+        `<div class="stats">${tiles}</div>`,
+        `<p class="note">Read by <code>${esc(v.model)}</code> · ${esc(v.readAt)}</p>`,
+        v.pages.length > 0
+            ? `<div class="scroll"><table><thead><tr><th>Page</th><th>What someone comes here to do</th><th>Confidence</th></tr></thead><tbody>\n${rows}\n</tbody></table></div>`
+            : '<p class="note">Nothing was read.</p>',
+        v.notRead.length > 0
+            ? `<p class="note">Not read: ${v.notRead.map((p) => `<code>${esc(p)}</code>`).join(', ')}</p>`
+            : '',
+        outsideScopeLine(v) ? `<p class="note">${esc(outsideScopeLine(v))}</p>` : '',
+        v.nothingToRead > 0
+            ? `<p class="note">${v.nothingToRead} page(s) had nothing to cite and were never sent — not a gap.</p>`
+            : '',
+        v.staleCount > 0 ? `<div class="callout"><span class="cl-label">stale</span>${esc(exports.PLAN_STALE_CAVEAT)}</div>` : '',
+        // A callout, not a footnote. It is the sentence that keeps this section from being read
+        // as a measurement, so it gets the weight the report gives a warning.
+        `<div class="callout" style="margin-top:14px"><span class="cl-label">model reading</span>${esc(exports.PLAN_CAVEAT)}</div>`,
+        '</section>',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/**
+ * The whole read-and-pair step, for a caller that has pages and wants the section. Returns
+ * null when there is no plan — the normal case, and every renderer must be complete without
+ * one.
+ */
+function planFor(pages, order = [], file = planPath()) {
+    const doc = loadPlan(file);
+    return doc ? buildPlanView(doc, pages, order) : null;
+}
+//# sourceMappingURL=planView.js.map

package/dist/planView.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-qa/qa-discovery",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Deterministic surface reconnaissance for an unknown web app — crawl, capture, diff. No LLM, no hosting: runs entirely on your machine, with a local MCP server for agents.",
   "keywords": [
     "qa",
@@ -35,6 +35,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "TUTORIAL.md",
     "ROADMAP.md"
@@ -49,7 +50,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@ia-qa/self-healing": "^1.8.0"
+    "@ia-qa/self-healing": "^1.19.0"
   },
   "peerDependencies": {
     "playwright": ">=1.40.0"

package/skills/ia-qa-discover/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: ia-qa-discover
+description: >-
+  Find out what a web application contains when no test suite exists yet — its pages, forms,
+  fields and the API calls they make — and state what an existing suite does NOT test. Use
+  when asked to explore an unknown app, to plan testing for one, to list its entry points, or
+  to answer "which pages are untested". Requires @ia-qa/qa-discovery (`ia-qa-discover`). Runs
+  entirely on the user's machine; the optional `-ai` binary is the only part that sends
+  anything anywhere.
+---
+
+# ia-qa-discover — read the capture, never re-crawl
+
+## 1. The capture is on disk. Read it before opening anything.
+
+`ia-qa-discover scan` writes `.ia-qa-discovery/capture/<page>.json`, one file per page:
+
+```json
+{
+  "page": "checkout", "url": "https://app/checkout", "capturedAt": "2026-09-19T…",
+  "meta": { "title": "Checkout", "description": "…" },
+  "headings": [{ "level": 1, "text": "Your order" }],
+  "forms": [{ "method": "post", "hasSubmit": true,
+             "fields": [{ "name": "card", "type": "text", "label": "Card number",
+                          "required": true, "stableSelector": true }] }],
+  "looseFields": [], "apiCalls": [{ "method": "POST", "urlPattern": "/api/pay", "status": 200 }]
+}
+```
+
+Most questions are answered by reading those files and `capture/_overview.md`. Re-running a
+scan costs minutes and a browser; reading costs nothing. Scan again only when the app has
+changed since `capturedAt`.
+
+| Path | What it is |
+|---|---|
+| `.ia-qa-discovery/capture/` | one JSON per page + `_overview.md` (the human index) |
+| `.ia-qa-discovery/capture/surface.json` | the manifest, including **what the scan could not see** |
+| `.ia-qa-discovery/coverage-map.json` | the gap, once `coverage` has run |
+| `.ia-qa-discovery/classification.json`, `plan.json` | the optional model readings, if any |
+| `.ia-qa-discovery/history.jsonl` | one line per scan |
+
+## 2. Which verb answers which question
+
+| The user's question | Verb |
+|---|---|
+| "what is even in this app?" | `scan <url> --save` |
+| "most of the inputs are behind a menu or a tab" | `scan --deep` — opens disclosures one level and captures what they reveal |
+| "the app is behind a login" | the human runs `ia-qa-heal login` (from `@ia-qa/self-healing`), then `scan --session .ia-qa/session.json`. **You cannot log in** (§4.1) |
+| **"what does my test suite not test?"** | `coverage` — needs `@ia-qa/self-healing` **and** one watched run (§3) |
+| "what changed since last time?" | `history` |
+| "what is each entry point FOR?" | `ia-qa-discover-ai classify` — optional, BYOK (§5) |
+| "what does somebody come to this page to DO?" | `ia-qa-discover-ai plan` — optional, BYOK (§5) |
+| "write me a starting spec for an untested page" | `generate` — scaffolding only; the assertions stay human |
+
+Exact flags: `ia-qa-discover <verb> --help`. Do not guess them from this file.
+`scan`, `coverage`, `history` and both `-ai` verbs take `--json`. Prefer it over parsing prose.
+
+## 3. This tool issues NO verdict, and that is the point
+
+Nothing here exits non-zero because of what it found. A gap is a decision with a human's name
+on it — an uncovered page may be deliberately out of scope.
+
+**`coverage` refuses rather than guesses**, with a typed reason. Report the refusal as *no
+measurement*, never as a finding:
+
+| `reason` | What it means | What the human does |
+|---|---|---|
+| `no-surface` | nobody has scanned this app | `ia-qa-discover scan` |
+| `no-healing` | no suite is tracked here | install `@ia-qa/self-healing`, then `map` |
+| `no-run` | contracts exist, no run was ever watched | `ia-qa-heal run`, or `ia-qa-pal tour --suite` |
+
+`measured: false` is **not** "the suite covers nothing". Saying that is the single worst
+sentence this tool can cause to be written.
+
+## 4. Never do this
+
+1. **Never run `ia-qa-discover login` or `ia-qa-heal login`.** They open a visible browser and
+   wait for a person, twice over: in your shell that is a hung command. Give the human the
+   command instead. The same goes for `ia-qa-heal ui`.
+2. **Never present a contract, or a configured page, as proof a page is tested.** A contract
+   means somebody configured that page. Only capture-during-run proves a test went there.
+3. **Never report a page count as coverage.** Read `surface.json` → `coverage` first: a login
+   wall (`loginWall`), an app that navigates without `<a href>` (`hrefBlind`) and the page cap
+   (`droppedByCap`) each make the surface look smaller than it is. State those beside any total.
+4. **Never treat `writeCalls` as evidence a page writes.** A scan never submits anything, so a
+   non-GET it observed fired at page load — measured on a real corpus, 10 of 10 were analytics
+   beacons. It is in the output as a fact and is deliberately not a ranking factor.
+5. **`named` is not `asserted`.** The depth figure says the suite *names* N contracted elements.
+   A test that clicks a button names it without checking anything.
+6. **Never call the `-ai` layer a gate.** It emits no verdict, and `unclear` / `refused` are
+   answers needing a person, not a retry. A `failed` page means the model call did not succeed
+   — say so; it is not a finding about the app.
+7. **Never widen `capture.safeQueryParams`** to make a scan "work". The deny rule on
+   `token`, `password`, `session`, `auth`, `jwt`, `email`, `key` exists so a reset link pasted
+   into `scan` does not end up in files the user commits.
+8. **Never edit `config.json` to add a page you have not seen in a capture.** `discover --apply`
+   (heal) and the config are the human's; propose, do not write.
+
+## 5. What leaves the machine
+
+Nothing, except: requests to the app the user asked you to scan (same origin, GET only, never
+a `/logout` or `/delete` URL), and — only if the user opted in — `ia-qa-discover-ai` calling
+**their own** LLM provider.
+
+The two `-ai` verbs announce what they send *before* they send it, on stderr, in every mode.
+Read that announcement to the user before running either on a private or authenticated app.
+`plan` sends strictly less than `classify`: no selectors, no observed API calls, and not the
+headings the whole app repeats.
+
+## 6. Setting up the BYOK key — ask, never invent
+
+Both `-ai` verbs need a provider key. The key **never** goes in a file.
+
+1. Ask the user which provider they have a key for: `anthropic`, `openai`, `google`, or
+   `openai-compatible` — that last one is a *shape*, not a vendor: DeepSeek, Groq, Mistral,
+   OpenRouter, Together, vLLM and Ollama all serve the same endpoint, and it needs a
+   `baseUrl`. A `localhost` URL there means the call never leaves their machine.
+   `ia-qa-discover-ai models` lists the models each one takes. Never pick for them.
+2. **Prefer the machine's credential store.** Give them the command; they run it themselves,
+   in their own terminal — it asks for the value and refuses an argument or a pipe:
+
+   ```bash
+   npx -p @ia-qa/self-healing ia-qa-heal secret set MY_KEY_NAME
+   ```
+
+   You can confirm it resolves without ever seeing it: `ia-qa-heal secret check MY_KEY_NAME`.
+   **There is no command that prints a stored value, and you must not go looking for one.**
+   The point of the store is that the value stops being ambient — it is no longer in the
+   environment every process you launch inherits.
+
+3. Otherwise — or in CI, where there is no store and no person — ask them to export it in
+   their own shell and to tell you the **variable name**, never the key. If they paste the key
+   to you anyway, tell them to rotate it.
+
+4. Write only the reference into `.ia-qa-discovery/config.json`:
+
+```json
+"ai": { "provider": "openai", "model": "gpt-4o-mini",
+        "apiKey": { "source": "keychain", "key": "MY_KEY_NAME" } }
+```
+
+`"source": "env"` is the same shape with the variable name, for CI.
+
+5. `--dry-run` first: it shows exactly what would be sent, and to whom, without a key and
+   without calling anything. Show that to the user before the real run.
+
+That file is committed. A value there is a leaked credential, and the CLI refuses it — it
+detects a key-shaped string where a variable name belongs, prints it masked, and tells the
+user to rotate it. Do not work around that refusal.
+
+The CLI reads `process.env` only and never loads `.env` files. If their key lives in `.env`:
+`npx dotenv-cli -- ia-qa-discover-ai plan`.
+
+Through the MCP server the same rule holds: `api_key_env` takes the **name** of a variable on
+that machine. A raw key is never a tool argument — a tool call can be logged and replayed.
+
+## 7. The two siblings, and where the line is
+
+`@ia-qa/self-healing` (`ia-qa-heal`) repairs an **existing** suite's locators. This package
+describes an app that may have **no** suite. They share the session file and the page-naming
+rule, and they hand off in exactly two places: when `ingest` finds no test file, and when
+`coverage` needs a watched run. `@ia-qa/pal` (`ia-qa-pal`) runs the whole round for a team.
+
+`scan` and `map` are **not** the same operation: `map` writes a contract (every interactive
+element, to repair broken locators); `scan` writes a surface (what exists and what it takes as
+input, to decide what to test when there is no suite yet).