diff --git a/.gitignore b/.gitignore
index 6b4f793..f4d1956 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ venv/
 # Inputs / outputs
 inventory.xlsx
 analysis_output_*.xlsx
+impact_report_*.html
 ~$*.xlsx
 
 # Inventory / output folders (contents are local data, not source)
diff --git a/.specify/feature.json b/.specify/feature.json
index d0debff..f7e88b1 100644
--- a/.specify/feature.json
+++ b/.specify/feature.json
@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/005-self-uninstall"
+  "feature_directory": "specs/006-api-inventory-check"
 }
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index 4b17fa1..0847787 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,20 +1,27 @@
 <!--
 Sync Impact Report
 ==================
-Version change: 2.0.0 → 2.1.0
-Rationale: Relaxed Principle II so that installing as a `uv` tool is the *primary, recommended*
-           distribution rather than the *sole* one: a `pip install .` from a source checkout
-           (into a virtual environment) is now a supported fallback for environments where `uv`
-           cannot be installed. This adds an allowance without removing or redefining a principle
-           (no bespoke installers return), so the bump is MINOR. The Technology & Data Constraints
-           Distribution bullet was updated to match. README and docs/index.html document the
-           no-uv path. This constitution's own version is independent of the product version.
+Version change: 2.1.0 → 2.2.0
+Rationale: Enacted as a prerequisite of spec 006 (inventory-driven vulnerability check via the
+           Cisco PSIRT API). Four changes, none of which removes or redefines a principle, so the
+           bump is MINOR. (1) Principle IV now states the *substance* of the undecided result —
+           it must be labelled undecided and never guessed — while allowing each mode the clearest
+           label for its own report; `Indeterminate` (advisory-driven) and `Needs review`
+           (inventory-driven) are both conforming. The same principle now also makes explicit what
+           was previously only implied: a "not affected" determination MUST rest on positive
+           confirmation, not on the absence of a result. (2) Source of truth admits Cisco's PSIRT
+           openVuln advisory API alongside ERP pages and CSAF JSON. (3) Networking admits
+           `apix.cisco.com` and `id.cisco.com`, scoped, with an explicit note on what is sent.
+           (4) Inputs/outputs records the `impact_report_*.html` report the new mode writes.
+           This constitution's own version is independent of the product version.
 
 Modified principles:
-  - II. Cross-Platform Parity (uv is now primary/recommended; pip-from-source added as a supported fallback)
+  - IV. Conservative & Traceable Analysis (undecided label is mode-appropriate but mandatory;
+    "not affected" now explicitly requires positive confirmation; PSIRT API added as traceable
+    source data; AI-normalization clause scoped to modes that use AI)
 Added sections: (none)
 Modified sections:
-  - Technology & Data Constraints (Distribution bullet notes the pip-from-source fallback)
+  - Technology & Data Constraints (Source of truth, Networking, Inputs/outputs bullets)
 Removed sections: (none)
 
 Templates requiring updates:
@@ -22,8 +29,12 @@ Templates requiring updates:
   - .specify/templates/spec-template.md ✅ aligned (no constitution references)
   - .specify/templates/tasks-template.md ✅ aligned (no constitution references)
 
-Follow-up TODOs: (none)
+Follow-up TODOs: README.md and docs/index.html must document the new mode, its Cisco credential
+           prerequisite, and its HTML output before spec 006 merges (Documentation quality gate).
 
+Previous version 2.1.0 (2026-07-18): relaxed Principle II so a `uv` tool install is the primary,
+recommended distribution rather than the sole one, adding `pip install .` from a source checkout
+as a supported fallback; Technology & Data Constraints Distribution bullet updated to match. MINOR.
 Previous version 2.0.0 (2026-07-18): redefined Principle II for uv-tool distribution (dropped the
 install.py/run.py/.venv mandate); updated Principle V (per-user config secrets) and Technology &
 Data Constraints (uv-based updates, working-folder I/O). Enacted spec 004 (FR-024). MAJOR.
@@ -83,14 +94,26 @@ the tool debuggable and honest about what it did.
 ### IV. Conservative & Traceable Analysis (NON-NEGOTIABLE)
 Impact determinations MUST NOT overstate risk. When the available data is insufficient
 to decide — for example when impact depends on runtime configuration the inventory does
-not track — the result MUST be `Indeterminate`, never a guess. Every determination MUST
-be traceable to official Cisco source data (the ERP page and each advisory's CSAF JSON);
-the tool MUST NOT invent advisory facts. AI-derived output MUST be normalized and
-validated before it reaches the report.
+not track, or when the authoritative source does not recognize a device's software
+release or hardware platform — the result MUST be labelled as undecided, never guessed.
+The label MUST be unambiguous within the report it appears in; `Indeterminate` in the
+advisory-driven analysis and `Needs review` in the inventory-driven check are both
+conforming. A determination that a device is *not* affected MUST rest on positive
+confirmation from official Cisco source data, never on the mere absence of a result; an
+undecided device MUST NOT be presented as unaffected. Every determination MUST be
+traceable to official Cisco source data (an ERP page, an advisory's CSAF JSON, or Cisco's
+PSIRT advisory API); the tool MUST NOT invent advisory facts. Where a mode uses AI to
+reach a determination, that output MUST be normalized and validated before it reaches the
+report.
 
 Rationale: People act on these reports to protect firewalls. A false "Not Affected" is
 dangerous and a fabricated "Affected" erodes trust; conservative, source-anchored
-results are the only acceptable posture.
+results are the only acceptable posture. Each mode may choose the clearest label for its
+own report, but the substance is fixed: an undecidable device is never presented as safe,
+and safety is asserted only when the source data affirms it. The positive-confirmation
+rule exists because an authoritative source can return "nothing found" both for a device
+that is genuinely clean and for one it cannot recognize at all — treating those alike
+would silently convert a data-quality problem into a clean bill of health.
 
 ### V. Secrets Hygiene & Data Locality
 API keys and other secrets MUST live only in the per-user configuration file (or in
@@ -115,16 +138,28 @@ a personal credential; leaking either is a direct harm.
   `--update` is uv-specific and does not apply on that path. The product version is single-sourced
   from the committed `VERSION` file into the package metadata at build time.
 - Source of truth: Cisco Event Response (ERP) pages and official advisory CSAF JSON
-  fetched from `sec.cloudapps.cisco.com`. No scraped or cached-as-authoritative
-  alternatives.
+  fetched from `sec.cloudapps.cisco.com`, and Cisco's PSIRT openVuln advisory API — the
+  same published data that backs Cisco's public Software Checker — for release- and
+  platform-scoped advisory lookups and for the platform/release catalogues those lookups
+  are validated against. Catalogues MUST be retrieved from Cisco rather than hardcoded, so
+  newly published releases and platforms are picked up without a tool release. No scraped
+  or cached-as-authoritative alternatives.
 - AI provider: FueliX (OpenAI-compatible Chat Completions endpoint) accessed over the
   standard library, using the current default model configured in `fuelix.py`.
 - Inputs/outputs: the inventory is a user-provided `.xlsx` (sheet `FW_List`) located in the
-  current working folder; reports are written as timestamped `analysis_output_*.xlsx` files
-  into an `output/` folder inside that same working folder. Header matching MUST stay
-  tolerant of minor naming variation.
+  current working folder; reports are written into an `output/` folder inside that same
+  working folder as timestamped files — `analysis_output_*.xlsx` for the advisory-driven
+  analysis and `impact_report_*.html` for the inventory-driven check. An HTML report MUST be
+  a single self-contained file that renders with no network access, so it survives being
+  emailed or archived. Reports MUST never be overwritten. Header matching MUST stay tolerant
+  of minor naming variation.
 - Networking: the analyzer itself contacts only `sec.cloudapps.cisco.com` (Cisco
-  ERP/CSAF) and `api.fuelix.ai` (AI). Version and update checks additionally contact
+  ERP/CSAF), `api.fuelix.ai` (AI), `apix.cisco.com` (Cisco PSIRT advisory data and
+  platform/release catalogues) and `id.cisco.com` (short-lived access token for that API).
+  To the Cisco advisory API the tool MUST send only the derived product family, hardware
+  platform and software release being checked — never a firewall name or any other inventory
+  identifier — keeping that disclosure strictly smaller than what the AI endpoint receives.
+  Version and update checks additionally contact
   GitHub — `api.github.com` and `github.com` — solely to discover the latest published
   release; they send no inventory or secrets and MUST be best-effort and time-bounded so
   they never block a run. Updating is delegated to `uv`, which reinstalls the tool from the
@@ -190,4 +225,4 @@ Compliance is verified at review time. Dependent Spec Kit artifacts (plan, spec,
 tasks templates and their generated documents) MUST remain consistent with the principles
 above; the Constitution Check in the planning workflow enforces this on each feature.
 
-**Version**: 2.1.0 | **Ratified**: 2026-07-14 | **Last Amended**: 2026-07-18
+**Version**: 2.2.0 | **Ratified**: 2026-07-14 | **Last Amended**: 2026-07-25
diff --git a/README.md b/README.md
index 7f8f75d..f52bf3a 100644
--- a/README.md
+++ b/README.md
@@ -28,12 +28,14 @@ Windows, and Linux**.
 | - | ----------- | ------------- |
 | 1 | **uv** (recommended) — or just **Python 3.9+** | It manages Python for you. Not sure if you have it? See [Get uv](#get-uv) below — check first, install only if needed. Can't install uv? See [Install without uv](#install-without-uv-python-only) — you only need Python. |
 | 2 | **Git** | The uv install command below pulls the tool straight from GitHub, so Git must be installed first. Not sure if you have it? See [Get Git](#get-git) below. |
-| 3 | **A FueliX API key** | Get yours from <https://dev.fuelix.ai> — each person needs their own (steps below). |
-| 4 | **Your firewall inventory** as an Excel `.xlsx` file in the folder you run from | You build this yourself (format below). |
-| 5 | **Internet access** to `sec.cloudapps.cisco.com` and `api.fuelix.ai` | Usually already available; corporate proxies can block these. |
+| 3 | **A FueliX API key** — for advisory mode | Get yours from <https://dev.fuelix.ai> — each person needs their own (steps below). |
+| 4 | **Cisco PSIRT API credentials** — for inventory mode (`--api`) | A client ID and client secret from <https://developer.cisco.com/psirt/> — each person needs their own. |
+| 5 | **Your firewall inventory** as an Excel `.xlsx` file in the folder you run from | You build this yourself (format below). |
+| 6 | **Internet access** to `sec.cloudapps.cisco.com` and `api.fuelix.ai`, plus `apix.cisco.com` and `id.cisco.com` for `--api` | Usually already available; corporate proxies can block these. |
 
-> Your API key is stored once, per user, via `caia --config`. The
-> tool will refuse to analyze until a key is configured, and it points you to `--config`.
+> Every credential is stored once, per user, via `caia --config`. You only need the ones
+> for the mode you use: **advisory mode** needs the FueliX key, **inventory mode** needs the
+> Cisco credentials. Each mode refuses to run without its own, and points you at `--config`.
 
 ### Get uv
 
@@ -186,6 +188,62 @@ on it behaves exactly like the uv install — use it as described in [Run it](#r
 
 ## Run it
 
+There are **two modes**, and they answer opposite questions. Pick the one that matches what
+you're asking:
+
+| | Advisory mode (default) | Inventory mode (`--api`) |
+| --- | --- | --- |
+| **Question** | "Given this advisory, which of my firewalls are affected?" | "Given my inventory, which firewalls are vulnerable right now, and to what?" |
+| **You supply** | An ERP or advisory link | Nothing but the inventory |
+| **Answer comes from** | AI reading the advisory's text | Cisco's own published data — no AI |
+| **Output** | `analysis_output_<timestamp>.xlsx` | `impact_report_<timestamp>.html` |
+| **Needs** | FueliX API key | Cisco PSIRT client ID + secret |
+
+The output formats differ because the reports are read differently. The spreadsheet is one
+row per advisory, which suits a per-advisory review. The HTML report is one row per firewall
+with clickable advisory links, collapsible detail and filtering — which is what a
+fleet-wide worklist needs, and what a spreadsheet handles badly once a single device has
+dozens of advisories against it.
+
+### Inventory mode — check everything at once
+
+`cd` into the folder holding your inventory, then:
+
+```bash
+caia --api
+```
+
+No link needed. The tool asks Cisco which published advisories apply to each firewall's
+software release on its exact hardware model, then writes
+**`impact_report_<date>_<time>.html`** into the **`output`** folder. Open it in any browser.
+
+Every firewall gets exactly one status:
+
+| Status | Meaning |
+| ------ | ------- |
+| **Impacted** | Cisco lists at least one advisory for that release on that model. The report shows each advisory's severity, its CVEs, a link to Cisco, and **the release that fixes it**. |
+| **Not impacted** | Cisco confirmed it recognises both the release *and* the model, and lists no advisories. |
+| **Needs review** | No trustworthy answer was possible — and the report says why. Never a claim of safety. |
+
+**`Needs review` is the one to pay attention to.** It usually means the inventory disagrees
+with Cisco's data — a release Cisco has retired as end-of-support, or a model/release pair
+Cisco never shipped (e.g. ASA 9.18 on 5500-X hardware). The tool names which, so the row
+becomes a data-quality fix rather than a mystery. A device that could not be checked is
+never reported as safe.
+
+Two limits are stated in every report, and worth knowing up front:
+
+- Cisco's data holds **no advisories published before January 2022** for ASA, FMC, FTD and
+  FXOS. An `Impacted` list is not exhaustive, and `Not impacted` is narrower than it looks.
+- A verdict does **not** know whether a vulnerable feature is switched on. `Impacted` means
+  "listed as affected", not "exploitable".
+
+A run paces itself to stay inside Cisco's request quota, so a large inventory takes a few
+minutes; progress is printed as it goes. Add `--dry-run` to see exactly what would be asked
+without contacting Cisco at all.
+
+### Advisory mode — check one advisory
+
 `cd` into the folder that holds your inventory `.xlsx`, then:
 
 ```bash
@@ -274,7 +332,7 @@ delete that file yourself if you want it gone.
 
 ---
 
-## Configuration (your API key)
+## Configuration (your API keys)
 
 `caia --config` stores your settings in a per-user file, so every run
 in any folder can find them:
@@ -291,17 +349,44 @@ The file is `KEY=value` and looks like this (you may edit it by hand):
 FUELIX_API_KEY=your-key-here
 FUELIX_MODEL=claude-sonnet-5
 FUELIX_BASE_URL=https://api.fuelix.ai/v1
+CISCO_CLIENT_ID=your-cisco-client-id
+CISCO_CLIENT_SECRET=your-cisco-client-secret
 ```
 
-- **`FUELIX_API_KEY`** (required) — your personal key from the Dev Portal (steps below).
+- **`FUELIX_API_KEY`** — your personal key from the Dev Portal (steps below). Needed by
+  advisory mode only.
 - **`FUELIX_MODEL`** (optional) — chosen from a menu during `--config`; default `claude-sonnet-5`.
 - **`FUELIX_BASE_URL`** (optional) — the API endpoint; **not** prompted by `--config`. Change it
   only by editing the file or setting the environment variable, and only if told to.
+- **`CISCO_CLIENT_ID`** / **`CISCO_CLIENT_SECRET`** — your personal Cisco PSIRT API
+  credentials (steps below). Needed by inventory mode (`--api`) only.
+
+`--config` walks through everything in one pass and **every prompt is skippable** — press
+Enter to leave a value alone. If you only ever use one mode, you never have to invent a
+credential for the other. Each mode checks only its own credentials at run time.
+
+Two details of the Cisco prompts worth knowing:
+
+- The **client ID is shown as you type or paste it** (it identifies the application; it isn't
+  a secret), while the **client secret is never displayed**. After you enter the secret the
+  tool confirms *how many characters* it captured — so a truncated paste is obvious without
+  the value ever appearing on screen.
+- `--config` then **checks the credentials against Cisco** before saving and tells you
+  whether they work. If Cisco rejects them you see Cisco's own reason and nothing is saved.
+  If Cisco simply can't be reached — a proxy or connectivity problem — it says so plainly and
+  offers to save them unverified, so an outage never blocks setup.
 
 Precedence for every setting is **environment variable → config file → built-in default**, so
-`FUELIX_API_KEY` / `FUELIX_MODEL` / `FUELIX_BASE_URL` in the environment still work for
-automation. On macOS/Linux the config file is created owner-only (`chmod 600`). Keep it private
-— it contains your key.
+the same names in the environment still work for automation. On macOS/Linux the config file is
+created owner-only (`chmod 600`). Keep it private — it contains your keys.
+
+### Getting your Cisco PSIRT API credentials
+
+1. Go to **<https://developer.cisco.com/psirt/>** and sign in with your Cisco account.
+2. Register an application to get a **client ID** and **client secret** for the openVuln API.
+3. Copy both, and paste them when `caia --config` asks.
+
+Each person uses **their own** credentials — don't share them.
 
 ### Getting your FueliX API key
 
diff --git a/VERSION b/VERSION
index ccbccc3..276cbf9 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.2.0
+2.3.0
diff --git a/brds/003-api-inventory-check.md b/brds/003-api-inventory-check.md
new file mode 100644
index 0000000..f44c00f
--- /dev/null
+++ b/brds/003-api-inventory-check.md
@@ -0,0 +1,342 @@
+# Business Requirements Document (BRD): Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+## Document Control
+
+| Field             | Value                                                        |
+| ----------------- | ------------------------------------------------------------ |
+| BRD ID            | BRD-003                                                      |
+| Title             | Inventory-Driven Vulnerability Check via the Cisco PSIRT API (`caia --api`) |
+| Author            | Ali Bahaloo / TELUS Digital                                  |
+| Status            | Draft                                                        |
+| Version           | 0.1.0                                                        |
+| Created           | 2026-07-25                                                   |
+| Last updated      | 2026-07-25                                                   |
+| Related documents | Repo: https://github.com/xavient/cisco-advisory-impact-agent · BRD-001 (Self-Update Mechanism): `brds/001-auto-updater.md` · BRD-002 (Self-Uninstall Command): `brds/002-uninstall.md` · Constitution: `.specify/memory/constitution.md` · Cisco PSIRT openVuln API: https://developer.cisco.com/docs/psirt/ · Cisco Software Checker: https://sec.cloudapps.cisco.com/security/center/softwarechecker.x |
+
+## 1. Executive Summary
+
+Today the tool answers one question: *given this Cisco advisory, which of my firewalls are affected?* It requires an analyst to already have an advisory or Event Response link in hand, and it reaches that answer by having an AI read the advisory's prose and compare it against the inventory. This BRD defines a second, complementary mode — `caia --api` — that answers the inverse and more operationally useful question: *given my whole inventory, which firewalls are vulnerable right now, and to what?* It asks Cisco's own PSIRT API directly, per device, using the same data the public Cisco Software Checker uses, and produces a self-contained, timestamped HTML report listing every device with a verdict of **Impacted**, **Not impacted**, or **Needs review**, plus the advisories that justify each Impacted verdict. Because Cisco supplies the answer, this mode needs no AI judgement and no advisory URL.
+
+## 2. Business Context & Problem Statement
+
+The existing flow is advisory-driven and reactive. It only runs when someone notices an advisory or Event Response worth checking, and it is limited to the advisories that ERP references. Nobody can currently ask "what is my exposure across the fleet today?" without checking every device by hand in Cisco's web Software Checker — a per-device, point-and-click exercise across a ~1,000-row inventory.
+
+Consequences today:
+
+- **No fleet-wide view.** Exposure is only ever assessed one advisory at a time. There is no run that says "here is every vulnerable firewall we own." Gaps persist simply because no advisory prompted a check.
+- **Manual checking does not scale.** The web Software Checker requires selecting a product, a hardware platform, and a release for each device. At inventory scale this is not done, so it is not done at all.
+- **The verdict depends on AI interpretation.** The current mode has an AI read "Vulnerable Products" prose and infer version overlap. Cisco publishes the authoritative per-platform, per-release answer directly, including the release that fixes each issue. Deriving it by inference where an authoritative source exists adds avoidable uncertainty to a security decision.
+- **No remediation target.** The current report says which firewalls are affected but not what to upgrade to. Cisco's API returns the first fixed release for every finding.
+- **Inventory data quality is invisible.** A feasibility spike against the real inventory found that **15 of 70 rows could not be answered at all** — versions Cisco has purged as end-of-support, and model/release combinations Cisco never shipped (for example ASA 9.18 on ASA 5500-X hardware, and FTD 7.4.0 on an ISA-3000). Those rows look identical to "no advisories found." A check that reports them as safe is worse than no check, and today nothing surfaces them.
+
+The cost is unmeasured fleet exposure, remediation work that is scheduled from incomplete information, and a standing risk that a data-quality problem in the inventory is silently read as a clean bill of health.
+
+## 3. Business Objectives & Goals
+
+- **G1** — Let an analyst assess the entire firewall inventory against Cisco's published vulnerability data in a single command, without needing an advisory link.
+- **G2** — Base each verdict on Cisco's authoritative per-platform, per-release answer rather than on inference, so findings are reproducible and defensible.
+- **G3** — Never present an unanswerable device as safe: distinguish "Cisco says this is clean" from "we could not determine this," and say why.
+- **G4** — Give each finding an actionable remediation target — the release that fixes it — and a direct route to the published advisory.
+- **G5** — Produce a report that can be read, shared, and acted on without a spreadsheet tool, and that preserves a durable per-run record.
+- **G6** — Be transparent about what the check does and does not cover, so its output is never over-trusted.
+- **G7** — Add this mode without changing the behaviour of the existing advisory-driven analysis.
+
+## 4. Stakeholders & Users
+
+| Stakeholder / user | Role in this product | What they need from it |
+| ------------------ | -------------------- | ---------------------- |
+| Security / network analyst | Primary user | A fleet-wide answer in one command; per-device advisories with the release that fixes them; confidence that "Not impacted" means Cisco said so |
+| Firewall / patching engineer | Downstream actor | A worklist they can prioritise — which devices, which advisories, which target release — reachable without hunting through Cisco's site |
+| Team lead / security manager | Reviewer, reporting | A shareable per-run snapshot of fleet exposure and its trend; visibility into how much of the inventory could not be assessed |
+| Inventory owner | Indirect | Notification that specific inventory rows carry models or releases Cisco does not recognise, so the source data can be corrected |
+| IT / security review | Reviewer | Assurance that Cisco credentials are handled like existing secrets, and that externally-supplied advisory content cannot compromise the generated report |
+| Support / help desk | Indirect | A self-explanatory report that reduces "what does this mean?" questions |
+
+## 5. Scope
+
+### 5.1 In Scope
+
+- A command-line option, `caia --api`, that checks the firewall inventory against Cisco's published advisory data per device, instead of analysing a supplied advisory or Event Response link.
+- Assigning every inventory row exactly one verdict: **Impacted**, **Not impacted**, or **Needs review**.
+- Reconciling the inventory's software-release strings with Cisco's canonical release format, so releases recorded in operational shorthand are still matched.
+- Determining each device's Cisco hardware platform from its inventory model, using the set of platforms Cisco publishes at run time.
+- Detecting and reporting, as **Needs review** with a stated reason, every case where a trustworthy verdict cannot be reached — an unrecognised release, a release Cisco never shipped on that model, a model that cannot be identified, or an incomplete response from Cisco.
+- Producing one self-contained, timestamped HTML report per run in the tool's output folder, listing every analysed device with its original inventory columns, its verdict, and the advisories behind an Impacted verdict.
+- Presenting, for each advisory, its identifier, title, severity, a link to the published advisory, and the release that first fixes it.
+- Letting a reader of the report filter and sort by verdict and by the inventory's priority column, and expand or collapse the advisory detail for a device.
+- Stating in the report what the check covered — run time, inventory file, per-verdict counts — and the known limits of Cisco's data.
+- Extending the tool's existing `caia --config` flow to prompt for and store the Cisco API credentials per user, so they are captured interactively once and found by every later run from any folder — the same path by which the AI service key is already captured.
+- Checking the Cisco credentials against Cisco during `caia --config` and telling the user whether they are valid, so a wrong or truncated credential is caught at setup rather than on a later run.
+- Operating within Cisco's published request quotas for a full ~1,000-row inventory.
+
+### 5.2 Out of Scope
+
+- **Changing the existing advisory-driven mode.** Running the tool without `--api` behaves exactly as it does today, including its Excel report. The two modes answer different questions and coexist.
+- **Any AI involvement in this mode.** Verdicts come from Cisco's response alone. The AI service is not called and its credential is not required for an `--api` run.
+- **Excel output, or any machine-readable export, for this mode.** v1 produces HTML only. Run-to-run comparison, dashboard ingestion, and adding tracking columns are deliberately deferred — see Open Questions.
+- **Judging whether a vulnerable feature is actually enabled.** Cisco's data does not account for enabled or disabled configuration, so an Impacted verdict means "this release on this platform is listed as affected," not "this device is exploitable." The tool discloses this rather than resolving it.
+- **Assessing non-firewall or non-Cisco inventory.** Only the Cisco product families Cisco's own checker supports are in scope; anything else becomes **Needs review**.
+- **Verifying the AI service key.** Credential verification during setup is added for the Cisco credentials only. Whether the existing AI service key should be checked the same way is a separate decision, deliberately not bundled here.
+- **Correcting the inventory.** The tool surfaces rows Cisco cannot recognise; editing the source inventory remains the inventory owner's responsibility.
+- **Retrieving advisories Cisco excludes from this data set** — notably advisories published before Cisco's per-family cut-off dates. The tool discloses the limit; it does not work around it.
+- **Automated or scheduled runs, alerting, or ticket creation.** The analyst runs the command.
+- **Opening or hosting the report.** The tool writes a file to disk; viewing and distributing it is the user's action.
+
+## 6. User Journeys *(feeds the spec's prioritized user stories)*
+
+### Journey 1 — Assess the whole inventory in one command (Priority: P1)
+
+- **Actor:** Security / network analyst with the inventory in their working folder and Cisco API credentials configured.
+- **Trigger:** They run `caia --api`.
+- **Outcome / value:** A single HTML report naming every firewall they own and whether Cisco considers it vulnerable — without needing an advisory link or an AI call.
+- **Flow:**
+  1. The analyst runs `caia --api` in the folder holding their inventory.
+  2. The tool locates and loads the inventory, reporting how many devices it will assess.
+  3. For each distinct combination of product family, hardware platform, and software release in the inventory, it asks Cisco which advisories apply.
+  4. It assigns every device a verdict of Impacted, Not impacted, or Needs review.
+  5. It writes a timestamped HTML report to the output folder and prints its location.
+- **Acceptance:**
+  - **Given** a valid inventory and configured credentials, **When** the analyst runs `caia --api`, **Then** a new timestamped HTML report is created in the output folder and its path is reported.
+  - **Given** the run completes, **When** the report is opened, **Then** every row of the source inventory appears exactly once, retaining its original columns, with exactly one verdict.
+  - **Given** Cisco returns one or more advisories for a device's platform and release, **When** the verdict is assigned, **Then** that device is Impacted and those advisories are listed against it.
+  - **Given** a report already exists for the same timestamp, **When** a new report is written, **Then** the existing report is never overwritten.
+  - **Given** the analyst runs the tool without `--api`, **When** it executes, **Then** the existing advisory-driven behaviour and its Excel report are unchanged.
+
+### Journey 2 — Never be told a device is safe when it could not be checked (Priority: P1)
+
+- **Actor:** Security / network analyst reading the report to decide what needs no action.
+- **Trigger:** The inventory contains a release or model Cisco does not recognise, or Cisco cannot be reached for a device.
+- **Outcome / value:** Unanswerable devices are called out as **Needs review** with the reason, so a data-quality problem is never mistaken for a clean device — and the reason tells the inventory owner what to fix.
+- **Flow:**
+  1. The tool asks Cisco about a device's platform and release.
+  2. Cisco reports no applicable advisories, or rejects the release, or the request fails.
+  3. The tool establishes whether Cisco recognises the release at all, and whether Cisco lists that release as shipping on that device's platform.
+  4. Only when both are confirmed and no advisories are returned does it record Not impacted; otherwise it records Needs review with a plain-language reason.
+- **Acceptance:**
+  - **Given** a device whose release Cisco does not recognise, **When** the verdict is assigned, **Then** it is Needs review and the report states that Cisco does not recognise that release.
+  - **Given** a device whose release Cisco recognises but does not list for that device's platform, **When** the verdict is assigned, **Then** it is Needs review and the report states which platforms Cisco does list for that release.
+  - **Given** a device whose model cannot be identified as a Cisco platform, **When** the verdict is assigned, **Then** it is Needs review and the report states that the model could not be identified.
+  - **Given** a request to Cisco fails or returns an incomplete answer for a device, **When** the verdict is assigned, **Then** it is Needs review and never Not impacted.
+  - **Given** Cisco confirms both the release and the platform and returns no advisories, **When** the verdict is assigned, **Then** and only then is it Not impacted.
+  - **Given** a release recorded in operational shorthand such as `9.16(4)67`, **When** it is checked, **Then** it is matched against Cisco's equivalent canonical release rather than reported as unrecognised.
+
+### Journey 3 — Act on the findings from the report (Priority: P2)
+
+- **Actor:** Firewall / patching engineer planning remediation.
+- **Trigger:** They open the HTML report produced by a run.
+- **Outcome / value:** They can narrow the report to what matters, see what each finding requires, and reach the published advisory in one click — without a spreadsheet tool or a Cisco site search.
+- **Flow:**
+  1. The engineer opens the report file.
+  2. They filter to Impacted devices and sort by the inventory's priority column.
+  3. For a device, they expand its advisories and read each one's severity and the release that fixes it.
+  4. They follow an advisory link to Cisco's published advisory for detail.
+- **Acceptance:**
+  - **Given** the report is open, **When** the engineer filters by verdict, **Then** only devices with that verdict remain visible.
+  - **Given** the report is open, **When** the engineer sorts by the inventory's priority column, **Then** rows reorder accordingly.
+  - **Given** a device with many advisories, **When** its detail is collapsed, **Then** the row stays readable, and expanding it reveals the full list.
+  - **Given** an advisory is listed, **When** the engineer reads it, **Then** its identifier, title, severity, and the release that first fixes it are shown, and its identifier links to Cisco's published advisory.
+  - **Given** the report file is opened on a machine with no network access or is viewed after being emailed, **When** it renders, **Then** its layout, filtering, and sorting still work.
+
+### Journey 4 — Set up Cisco API access once, through `caia --config` (Priority: P2)
+
+- **Actor:** Analyst running the API mode for the first time, or a team lead onboarding the team.
+- **Trigger:** They run `caia --config`, or they run `caia --api` before any Cisco credentials have been saved.
+- **Outcome / value:** The same one-command setup flow that already captures the AI service key also captures the two Cisco API credentials. The analyst pastes them into the terminal once and every later run, from any folder, finds them — no file to create, no environment to manage.
+- **Flow:**
+  1. The analyst runs `caia --config`.
+  2. The flow prompts, in one linear pass, for every credential and setting the tool uses — including the Cisco client identifier and the Cisco client secret — so each can be pasted straight into the terminal. Any prompt can be skipped by the user who does not need it.
+  3. The client identifier is prompted visibly; the client secret is not shown in readable form, and once entered the flow confirms that a value was captured and how long it was, so a failed or truncated paste is immediately obvious.
+  4. Where a value is already saved, the prompt says so and pressing Enter keeps it.
+  5. With both Cisco values in hand, the flow checks them against Cisco and reports whether they are valid before finishing.
+  6. The values are saved to the same per-user configuration the tool already uses, protected the same way, and found by later runs from any folder.
+  7. Should the analyst instead run `caia --api` with no Cisco credentials saved, the tool refuses to run, names what is missing, and points them at `caia --config`.
+- **Acceptance:**
+  - **Given** the analyst runs `caia --config`, **When** the flow runs, **Then** it prompts for both the Cisco client identifier and the Cisco client secret in addition to the settings it already collects, and saves them to the per-user configuration.
+  - **Given** the analyst is prompted for the Cisco client identifier, **When** they paste it, **Then** it is shown as they enter it; **and Given** they are prompted for the client secret, **When** they paste it, **Then** it is not shown in readable form.
+  - **Given** a secret has been entered, **When** the prompt completes, **Then** the flow confirms that a value was captured and its length, without revealing the value itself.
+  - **Given** a Cisco credential is already saved, **When** the analyst is prompted for it, **Then** the flow indicates a value exists and pressing Enter leaves it unchanged.
+  - **Given** both Cisco values have been supplied, **When** the flow checks them and Cisco accepts them, **Then** it states plainly that the credentials are valid.
+  - **Given** both Cisco values have been supplied, **When** Cisco rejects them, **Then** the flow reports the reason Cisco gave, offers to re-enter them, and does not silently save the rejected values.
+  - **Given** both Cisco values have been supplied, **When** Cisco cannot be reached at all, **Then** the flow says so distinctly from a rejection and lets the analyst save the credentials unverified with a clear warning.
+  - **Given** the analyst skipped the Cisco prompts, **When** the flow completes, **Then** no verification request is made to Cisco.
+  - **Given** verification succeeds, fails, or cannot run, **When** any message is shown, **Then** it contains no part of either credential value.
+  - **Given** Cisco credentials were saved by `caia --config`, **When** the analyst runs `caia --api` from any other folder, **Then** the run proceeds without re-entering them.
+  - **Given** the analyst only ever uses the advisory-driven mode, **When** they run `caia --config`, **Then** they can complete the flow without supplying Cisco credentials, and the existing mode still runs.
+  - **Given** the analyst only ever uses `--api`, **When** they run it, **Then** it does not require the AI service key to be configured.
+  - **Given** no Cisco credentials are saved, **When** the analyst runs `caia --api`, **Then** the tool refuses to run, names what is missing, directs them to `caia --config`, and makes no requests to Cisco.
+  - **Given** the saved credentials are rejected by Cisco, **When** a run starts, **Then** the tool reports an authentication problem distinctly from "no advisories apply" and does not emit a report of Not impacted devices.
+  - **Given** any run or configuration session, **When** it completes or fails, **Then** no credential value appears in the report, in printed output, or in a filename.
+
+### Journey 5 — Understand what the check did and did not cover (Priority: P3)
+
+- **Actor:** Team lead or reviewer receiving the report second-hand.
+- **Trigger:** They read a report they did not run.
+- **Outcome / value:** They can see when it ran, against what, how much of the inventory was answerable, and the known limits of the underlying data — so they do not over-trust it.
+- **Flow:**
+  1. The reviewer opens the report.
+  2. A summary states when the run happened, which inventory file it used, how many devices were assessed, and the count per verdict.
+  3. The same summary states the known coverage limits of Cisco's data.
+- **Acceptance:**
+  - **Given** any report, **When** it is opened, **Then** it shows the run date and time, the inventory file used, the number of devices assessed, and a count per verdict.
+  - **Given** any report, **When** it is read, **Then** it states that Cisco's data excludes advisories published before Cisco's per-family cut-off dates, and that a verdict does not account for whether a vulnerable feature is enabled.
+  - **Given** a report contains Needs review devices, **When** it is read, **Then** their number is visible in the summary and not only discoverable row by row.
+
+## 7. Business Requirements
+
+| ID    | Requirement                                                                                                                                                  | Priority |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| BR-01 | The product MUST provide a `--api` option that assesses the loaded inventory against Cisco's published advisory data per device, requiring no advisory or Event Response URL. | P1 |
+| BR-02 | The product MUST leave the existing advisory-driven mode, including its Excel report, unchanged when `--api` is not supplied.                                  | P1 |
+| BR-03 | The product MUST assign every row of the inventory exactly one verdict from: Impacted, Not impacted, Needs review.                                             | P1 |
+| BR-04 | The product MUST classify a device Impacted only when Cisco returns at least one advisory applying to that device's software release on that device's hardware platform. | P1 |
+| BR-05 | The product MUST classify a device Not impacted only when Cisco recognises both the release and the platform and returns no applicable advisories.              | P1 |
+| BR-06 | The product MUST classify a device Needs review, with a human-readable reason, whenever a trustworthy verdict cannot be established — including an unrecognised release, a release Cisco does not list for that platform, an unidentifiable model, or a failed or incomplete response. | P1 |
+| BR-07 | The product MUST NOT report a device as Not impacted when Cisco does not recognise its release or does not list that release for its platform.                  | P1 |
+| BR-08 | The product MUST reconcile inventory release strings recorded in operational shorthand with Cisco's canonical release identifiers, including releases annotated with a companion product or build suffix. | P1 |
+| BR-09 | The product MUST determine each device's Cisco hardware platform from its inventory model, and MUST obtain the valid set of platforms from Cisco at run time rather than relying on a fixed built-in list. | P1 |
+| BR-10 | The product MUST produce exactly one self-contained HTML report per run, written to the tool's output folder with a timestamped name, and MUST never overwrite an existing report. | P1 |
+| BR-11 | The report MUST list every analysed device once, retaining the inventory's original columns, alongside its verdict and — for an Impacted verdict — the advisories that justify it. | P1 |
+| BR-12 | The product MUST treat all advisory content received from Cisco as untrusted text, and MUST NOT allow that content to alter the structure, styling, or behaviour of the generated report. | P1 |
+| BR-13 | The product MUST refuse to run, with a message naming what is missing and directing the user to `caia --config`, when Cisco API credentials have not been configured, and MUST make no requests to Cisco in that case. | P1 |
+| BR-14 | The product MUST NOT expose credential values in the report, in printed output, or in any filename it creates.                                                  | P1 |
+| BR-15 | The product MUST operate within Cisco's published request quotas, and MUST NOT issue a duplicate check for devices that share the same product family, platform, and release. | P1 |
+| BR-16 | The product MUST distinguish an authentication or connectivity failure from a "no advisories apply" answer, and MUST NOT emit Not impacted verdicts derived from a failed run. | P1 |
+| BR-17 | For each listed advisory the report MUST show its identifier, title, severity, and a working link to Cisco's published advisory, and SHOULD show its CVE identifiers and the release that first fixes it. | P2 |
+| BR-18 | The report MUST let a reader filter and sort by verdict and by the inventory's priority column, and expand or collapse a device's advisory detail, without any external tool or network access. | P2 |
+| BR-19 | `caia --config` MUST prompt for the Cisco client identifier and the Cisco client secret, alongside the settings it already collects, so a user can paste both into the terminal in one guided session. | P1 |
+| BR-20 | `caia --config` MUST save the Cisco credentials to the same per-user configuration the tool already uses, protected the same way, so later runs from any folder find them without re-entry. | P1 |
+| BR-21 | `caia --config` MUST indicate when a Cisco credential is already saved and MUST leave it unchanged when the user submits an empty response, matching how it treats the existing AI service key. | P2 |
+| BR-22 | The product MUST let a user complete `caia --config` while supplying only the credentials for the mode they use, and each mode MUST require only its own credentials — `--api` MUST NOT require the AI service key, and the advisory-driven mode MUST NOT require Cisco credentials. | P1 |
+| BR-23 | `caia --config` MUST prompt for the Cisco client identifier visibly, since it is an identifier rather than a secret, and MUST NOT echo the Cisco client secret in readable form.        | P2 |
+| BR-24 | `caia --config` MUST confirm, immediately after a secret is entered, that a value was captured and how many characters it contained, so a truncated or failed paste is obvious without revealing the value. It SHOULD additionally give visible feedback while the secret is being entered (for example a masking character per keystroke) where the terminal supports it, falling back to a non-echoing prompt where it does not. | P2 |
+| BR-25 | `caia --config` MUST verify the Cisco credentials with Cisco before completing, and MUST state plainly whether they are valid.                                    | P1 |
+| BR-26 | When Cisco rejects the credentials, `caia --config` MUST show the reason Cisco gave, MUST offer to re-enter them, and MUST NOT silently save values that were rejected. | P1 |
+| BR-27 | When Cisco cannot be reached to verify, `caia --config` MUST distinguish that from a rejection and MUST allow the user to save the credentials unverified with a clear warning, so a network or proxy outage never prevents configuration. | P1 |
+| BR-28 | Verification MUST NOT display, log, or write any part of a credential value in its success, failure, or warning messages.                                          | P1 |
+| BR-29 | `caia --config` MUST attempt verification only when both Cisco values are available for the session, and MUST make no request to Cisco when the user skipped those prompts. | P2 |
+| BR-30 | The product MUST continue to honour Cisco credentials supplied through the environment, taking precedence over saved values, so automated use remains possible; `caia --config` remains the documented and expected path for a person. | P2 |
+| BR-31 | The product MUST report progress while running so a full-inventory run does not appear stalled, and MUST complete an inventory of approximately 1,000 devices within Cisco's quotas. | P2 |
+| BR-32 | The product MUST signal the outcome of the run through its process exit status so automation can distinguish a completed run from a failure.                     | P2 |
+| BR-33 | The report MUST state the run date and time, the inventory file used, the number of devices assessed, and a count per verdict.                                   | P3 |
+| BR-34 | The report MUST state the known coverage limits of Cisco's data — the per-family advisory publication cut-offs, and that a verdict does not account for whether a vulnerable feature is enabled. | P3 |
+| BR-35 | The product's documentation MUST explain that `--api` produces an HTML report while the default mode produces an Excel report, and why the two modes answer different questions. | P3 |
+| BR-36 | The product's documentation MUST list the Cisco API credentials among the prerequisites a new user obtains before first use, and MUST show `caia --config` as the way to supply them. | P3 |
+
+## 8. Success Metrics & Measurable Outcomes
+
+- **SC-01** — An analyst can assess the entire firewall inventory with a single command and no advisory link, producing one report.
+- **SC-02** — 100% of inventory rows appear in the report with exactly one verdict; no row is silently dropped.
+- **SC-03** — 0% of devices whose release or platform Cisco does not recognise are reported as Not impacted; every such device is Needs review with a stated reason.
+- **SC-04** — 100% of Needs review devices carry a reason a reader can act on without consulting the tool's authors.
+- **SC-05** — 100% of Impacted devices list at least one advisory, and every listed advisory carries a working link to Cisco's published advisory.
+- **SC-06** — Every listed advisory that Cisco supplies a fixed release for shows that release, giving the engineer a remediation target without a further lookup.
+- **SC-07** — A run against an inventory of approximately 1,000 devices completes without exceeding Cisco's request quotas and without a partial or missing report.
+- **SC-08** — Repeated runs never overwrite an earlier report; each run leaves a distinct, durable file.
+- **SC-09** — The report renders, filters, and sorts correctly when opened with no network access and after being copied or emailed to another machine.
+- **SC-10** — No credential value appears in any report, printed output, or filename across any run, successful or failed.
+- **SC-11** — A run started without Cisco credentials, or with credentials Cisco rejects, produces a clear diagnostic and no report of Not impacted devices.
+- **SC-12** — A new user can go from having their Cisco credentials in hand to a completed `--api` run using only `caia --config` and `caia --api`, without creating a file or setting an environment variable.
+- **SC-13** — A user of only one mode can configure and run that mode without supplying the other mode's credentials.
+- **SC-14** — A wrong, truncated, or expired Cisco credential is detected during `caia --config` rather than on a later run, and the user is told why.
+- **SC-15** — Configuration remains completable when Cisco cannot be reached, with the unverified state disclosed rather than the setup being blocked.
+- **SC-16** — After entering the client secret, the user can tell from the confirmation alone whether their paste landed intact, without the value being displayed.
+- **SC-17** — Every report states its coverage limits, so a reader who did not run it can judge how far to trust it.
+- **SC-18** — Running the tool without `--api` produces the same result it did before this feature existed.
+
+## 9. Assumptions
+
+- Cisco API credentials (a client identifier and secret) are obtainable by each user from Cisco's developer portal, and are the user's own to manage — mirroring how each user obtains their own AI service key today.
+- Because the tool is installed as a `uv` tool and run from arbitrary working folders, `caia --config` is in practice the only credential path a user exercises. A working-folder `.env` file is a convenience for automation that a normal install never relies on, so this feature must not require one; environment variables remain supported but are not the expected route.
+- Both Cisco credential values are short enough to paste into a terminal prompt in one action, and users will paste rather than type them.
+- The inventory keeps its current shape: one row per firewall, with a name, a model, a product-family/type, a software release, and a priority. Column-header variations continue to be tolerated as they are today.
+- The product families present in the inventory today — ASA, FTD and FMC — are the families this mode must handle first; other Cisco families Cisco's checker supports are a natural extension, and anything unsupported becomes Needs review.
+- Cisco's published data is the authority for whether a release on a platform is affected; the tool reports it rather than second-guessing it.
+- Cisco publishes, and the tool can retrieve at run time, both the set of valid hardware platforms per product family and the set of valid releases — so neither needs to be hardcoded and both can change without a tool release.
+- Devices sharing the same family, platform and release have the same verdict, so one check can serve many devices; a real inventory collapses to far fewer checks than it has rows.
+- An `--api` run makes no AI call, so it does not require the AI service credential and incurs no AI cost.
+- The report is a file the user opens themselves; the tool does not need to launch a browser.
+- One report per run is the desired behaviour; reports accumulate in the output folder as they do today.
+
+## 10. Constraints
+
+- The tool's minimal-dependency posture applies: this mode must not introduce dependencies beyond what the capability genuinely requires, and any addition is a reviewed decision.
+- Behaviour and output must be identical across Windows, macOS, and Linux.
+- Cisco's published request quotas are a hard ceiling; the design must stay within them for a full-inventory run rather than relying on the user to throttle.
+- The run requires network access to Cisco's authentication and advisory endpoints. These are additional external hosts beyond those the tool contacts today, and must be recorded as permitted destinations.
+- Credential handling must match the tool's existing posture: stored per user outside the installed code, never transmitted anywhere but the issuing service, never written to reports or logs.
+- Advisory content arrives as externally-authored markup and must never be able to influence the generated report's structure or behaviour.
+- Reports must never be overwritten; an earlier run's record must remain intact.
+- The report must be a single file that works offline, so it survives being emailed, archived, or opened behind a restrictive corporate network.
+
+## 11. Dependencies
+
+- **Input** — Cisco's PSIRT advisory service, which supplies the per-platform, per-release advisory answer, the fixed-release information, and the catalogues of valid platforms and releases. The entire verdict rests on it.
+- **Input** — Cisco's authentication service, which issues the short-lived access token each run needs.
+- **Input** — The user's firewall inventory file in the working folder, discovered and loaded exactly as the existing mode does.
+- **Input** — The user's Cisco API credentials, captured by `caia --config` into the per-user configuration (or, for automation only, supplied through the environment).
+- **Output** — The tool's output folder, where the timestamped HTML report is written.
+- **Related** — The existing inventory-loading component, whose behaviour (file discovery, column tolerance, grouping of identical devices) this mode reuses rather than duplicates.
+- **Related** — The existing per-user configuration component and its `caia --config` flow, extended to prompt for and hold the Cisco credentials alongside the AI service key. This is the single place credentials are captured and the only one a normal install uses.
+- **Related** — BRD-001 and BRD-002, whose conventions for confirmation, clear refusal, actionable errors, and exit status this mode should follow.
+
+## 12. Risks & Mitigations
+
+| Risk                                                                                                       | Impact | Likelihood | Mitigation |
+| ---------------------------------------------------------------------------------------------------------- | ------ | ---------- | ---------- |
+| A device that could not be assessed is read as safe, and remediation skips it                              | H      | H          | Three-verdict model with a mandatory reason; Not impacted requires positive confirmation of both release and platform (BR-05, BR-06, BR-07) |
+| Cisco's data excludes advisories published before its per-family cut-off, so an Impacted list is incomplete and a Not impacted verdict is narrower than it appears | H      | H          | State the limit prominently in every report; keep the existing advisory-driven mode available for older advisories (BR-27, Section 5.2) |
+| An Impacted verdict overstates risk because the vulnerable feature is not enabled on that device            | M      | H          | Disclose that verdicts do not account for configuration; frame Impacted as "listed as affected," not "exploitable" (BR-27) |
+| Inventory releases or models Cisco does not recognise produce a large Needs review population that erodes confidence in the report | M      | H          | Reconcile shorthand releases before deciding (BR-08); give each Needs review row a specific, correctable reason so the inventory can be fixed (BR-06, SC-04) |
+| Externally-authored advisory content compromises the generated report when opened in a browser              | H      | M          | Treat all Cisco-supplied content as untrusted text that cannot affect report structure or behaviour (BR-12) |
+| A new hardware platform or release appears and a fixed built-in list makes matching devices unassessable    | M      | M          | Retrieve platform and release catalogues from Cisco at run time (BR-09) |
+| Request quotas are exceeded on a large inventory, producing a partial or failed run                         | M      | M          | Collapse duplicate checks and pace requests within published quotas; verify against a full-size inventory (BR-15, BR-24, SC-07) |
+| An authentication or network failure is misread as "nothing applies," producing a falsely clean report      | H      | M          | Distinguish failure from a negative answer and suppress verdicts derived from failed requests (BR-16, SC-11) |
+| No machine-readable output means run-to-run comparison must be done by eye                                  | M      | M          | Accepted for v1 as a deliberate scope decision; recorded in Open Questions so it can be revisited once the mode is in use |
+| Two report formats across two modes confuses users about which to run                                       | L      | M          | Document why the modes differ and what each answers (BR-28) |
+| A user configures one mode's credentials and is blocked from the mode they actually wanted, or is forced to supply credentials for a mode they never use | M      | M          | Make every credential prompt skippable and gate each mode only on its own credentials (BR-21, BR-22, SC-15) |
+| A pasted credential is mistyped or truncated and the failure only surfaces mid-run as an authentication error | L      | M          | Verify the credentials against Cisco during setup and report the reason on rejection (BR-25, BR-26, SC-16); report authentication failure distinctly at run time too (BR-16, SC-11) |
+| A secret entered at a hidden prompt shows no feedback, so the user cannot tell a paste succeeded            | L      | M          | Confirm the captured length immediately after entry, and mask keystrokes where the terminal supports it (BR-24, SC-18) |
+| A network or proxy outage during setup prevents a user from configuring the tool at all                     | M      | M          | Treat unreachable-for-verification as distinct from rejected and allow saving unverified with a warning (BR-27, SC-17) |
+| Per-keystroke masking behaves inconsistently across terminals and platforms, or mishandles a paste          | M      | M          | Masking is a SHOULD with a defined fallback to a non-echoing prompt; the length confirmation is the MUST that delivers the actual assurance (BR-24) |
+| Cisco changes its data shape or endpoints, breaking the mode                                                | M      | L          | Treat an unexpected response as Needs review rather than a silent verdict; fail loudly rather than quietly (BR-06, BR-16) |
+
+## 13. Open Questions
+
+- Should an Impacted verdict optionally be passed to the AI for the judgement Cisco's data cannot make — whether the vulnerable feature is plausibly enabled — as a hybrid of the two modes? (Leaning: not in v1; keep this mode fully deterministic and AI-free.)
+- Should the two modes ever be combinable in one run, or do they remain mutually exclusive?
+- Should the tool cache Cisco's platform and release catalogues between runs to conserve quota, and if so how would a user force a refresh?
+- Should Needs review be a single verdict, or split into distinct reasons the reader can filter on independently (release unknown to Cisco / release not shipped on this model / model unrecognised / check failed)?
+- Should the report group by device, by advisory, or offer both views? The inventory-per-row layout is confirmed; an advisory-centric view may be more useful for planning a single upgrade campaign.
+- Should a run where every device ends as Needs review be treated as a failed run, or a successful run with a wholly inconclusive result?
+- Which product families beyond ASA, FTD and FMC must be supported before this is considered complete for the team's real inventory?
+- Should a future revision add a machine-readable per-run artifact to support run-to-run comparison and downstream ingestion, given v1 is HTML-only?
+- Should the existing AI service key also be verified at setup time, for symmetry with the Cisco credentials? (Out of scope here — see Section 5.2 — but a natural follow-up once the verification pattern exists.)
+
+_Resolved during BRD review:_ the verdict set is **three values** — Impacted / Not impacted / Needs review (BR-03); the output is **HTML only**, one self-contained timestamped file per run, with no Excel or machine-readable export in v1 (Section 5.2, BR-10); the existing advisory-driven mode and its Excel report are **unchanged** (BR-02); this mode makes **no AI call** (Section 5.2); Cisco credentials are captured **interactively through `caia --config`**, which is the expected and documented path — a working-folder `.env` is not relied upon, since a `uv`-tool install run from arbitrary folders never reads one (BR-19, BR-20, Section 9); the client identifier is prompted **visibly** and the client secret is **not echoed**, with a length confirmation after entry and optional keystroke masking (BR-23, BR-24); `caia --config` prompts for **all** credentials in **one linear pass**, each skippable, rather than branching on which mode the user intends to use (BR-19, BR-22); and `caia --config` **verifies the Cisco credentials against Cisco before finishing**, reporting validity plainly, distinguishing a rejection from an unreachable service (BR-25, BR-26, BR-27).
+
+## 14. Glossary
+
+| Term | Definition |
+| ---- | ---------- |
+| `caia` | The command the tool installs on the user's PATH; what users actually type. |
+| `--api` | The new option that switches the tool from analysing a supplied advisory to assessing the whole inventory against Cisco's published data. |
+| `caia --config` | The tool's existing interactive setup command, which prompts for credentials and settings and saves them per user. Extended by this BRD to also capture the Cisco client identifier and client secret. |
+| Per-user configuration | The stored credentials and settings, kept in an OS-appropriate per-user location outside the installed code and outside any working folder, so any run from any folder finds them. |
+| Cisco client identifier / client secret | The two values Cisco issues for API access. The identifier names the calling application and is not itself secret; the secret authenticates it and is handled as a secret throughout. |
+| Credential verification | The check `caia --config` performs against Cisco after collecting the credentials, to confirm they are accepted before saving — distinguishing "Cisco rejected these" from "Cisco could not be reached." |
+| Advisory-driven mode | The tool's existing behaviour: given an advisory or Event Response link, determine which inventory firewalls are affected, using AI to interpret the advisory. |
+| Inventory-driven mode | The behaviour this BRD defines: given the inventory, determine which firewalls Cisco lists as vulnerable and to what. |
+| Cisco PSIRT advisory service | Cisco's official published source of security advisory data, the same data behind Cisco's public Software Checker; the authority for every verdict in this mode. |
+| Software Checker | Cisco's public web tool that returns the advisories affecting a chosen product, hardware platform, and software release — the manual equivalent of this mode. |
+| Product family | The Cisco software line a device runs, e.g. ASA, FTD, FMC; determines how Cisco is queried. |
+| Hardware platform | The Cisco appliance series a device is, e.g. the ISA 3000 series or the Secure Firewall 3100 series; required alongside the release because the same release affects platforms differently. |
+| Release | The software version a device runs. Cisco publishes a canonical identifier that may differ in form from how the inventory records it. |
+| Advisory | A published Cisco security notice, identified by a `cisco-sa-…` identifier, carrying a severity, CVE identifiers, and the release that fixes it. |
+| Fixed release | The first Cisco release in which an advisory's vulnerability is resolved; the remediation target for an affected device. |
+| Severity | Cisco's security impact rating for an advisory — Critical, High, Medium, Low, or Informational. |
+| Impacted | Cisco lists at least one advisory as applying to that device's release on that device's platform. Not a claim that the device is exploitable. |
+| Not impacted | Cisco recognises both the release and the platform and lists no applicable advisories. |
+| Needs review | A trustworthy verdict could not be established, with a stated reason. Explicitly not a claim of safety. |
+| Coverage cut-off | The publication date before which Cisco's checker data holds no advisories for a given product family, bounding what this mode can find. |
+| Request quota | Cisco's published ceiling on how many requests an application may make per second, minute, and day. |
+| Work products | User-owned outputs and inputs — generated reports and the firewall inventory — which this mode reads or adds to but never destroys. |
diff --git a/cisco_advisory_impact_agent/analyzer.py b/cisco_advisory_impact_agent/analyzer.py
index 4831d2b..b444db6 100644
--- a/cisco_advisory_impact_agent/analyzer.py
+++ b/cisco_advisory_impact_agent/analyzer.py
@@ -15,13 +15,14 @@
 
 from __future__ import annotations
 
+import datetime as _dt
 import shutil
 import sys
 import tempfile
 from pathlib import Path
 from urllib.parse import parse_qs, urlparse
 
-from cisco_advisory_impact_agent import cisco, config, fuelix
+from cisco_advisory_impact_agent import cisco, config, fuelix, html_report, matching, psirt
 from cisco_advisory_impact_agent import inventory as inv
 from cisco_advisory_impact_agent import ui
 from cisco_advisory_impact_agent.report import write_report
@@ -314,3 +315,237 @@ def run(args):
     else:
         shutil.rmtree(temp_dir, ignore_errors=True)
     return 0
+
+
+# --------------------------------------------------------------------------- #
+# Inventory-driven run (`--api`)
+# --------------------------------------------------------------------------- #
+def _resolve_cisco_credentials():
+    """Return (client_id, client_secret) or exit with an actionable message.
+
+    Refuses before any request is made, naming exactly what is missing (FR-048). The AI
+    service key is deliberately not consulted — this mode never calls it (FR-005, FR-036).
+    """
+    client_id = config.resolve(config.CISCO_CLIENT_ID)
+    client_secret = config.resolve(config.CISCO_CLIENT_SECRET)
+    missing = [name for name, value in
+               ((config.CISCO_CLIENT_ID, client_id),
+                (config.CISCO_CLIENT_SECRET, client_secret)) if not value]
+    if missing:
+        die("No Cisco API credentials are configured: " + ", ".join(missing) + " not set.",
+            hint="Run 'caia --config' to set your Cisco client ID and client secret.\n"
+                 "Get them from https://developer.cisco.com/psirt/ (one per person).")
+    return client_id, client_secret
+
+
+def _families_in(inventory):
+    """Distinct lower-cased product families present in the inventory."""
+    seen = []
+    for device in inventory:
+        family = str(device.get("family") or "").strip().lower()
+        if family and family not in seen:
+            seen.append(family)
+    return seen
+
+
+def _load_catalogues(client, families):
+    """Fetch the platform and release catalogues Cisco publishes, per family.
+
+    Only families Cisco can answer about are fetched; anything else is resolved locally to
+    Needs review, so an inventory containing switches does not fail the run.
+    """
+    catalogues = matching.Catalogues()
+    for family in families:
+        if not matching.family_supported(family):
+            continue
+        catalogues.add_platforms(family, client.get_platforms(family))
+        catalogues.add_releases(family, client.get_os_data(family))
+    return catalogues
+
+
+def _describe_check(check):
+    os_type, alias, release = check
+    return f"{os_type}/{alias or '-'}/{release}"
+
+
+def run_api(args):
+    """Assess the whole inventory against Cisco's published advisory data.
+
+    Returns a process exit code. Writes one self-contained HTML report per run.
+    """
+    config.load_local_env()
+
+    output_dir = Path(args.output_dir) if args.output_dir else default_output_dir()
+    interactive = sys.stdin.isatty()
+
+    # 1. Credentials (skipped for a dry run, which contacts nothing).
+    if not args.dry_run:
+        client_id, client_secret = _resolve_cisco_credentials()
+
+    # 2. Inventory.
+    inv_path = resolve_inventory(args.inventory, interactive, sheet=args.sheet)
+    try:
+        inventory = inv.load_inventory(inv_path, args.sheet)
+    except inv.InventoryError as e:
+        die(str(e))
+    if not inventory:
+        die(f"Inventory {inv_path} has no firewall rows.")
+    ui.ok(f"Loaded {ui.bold(str(len(inventory)))} firewalls from {ui.bold(inv_path.name)}.")
+
+    # 3. Dry run: resolve every device to the question that would be asked, contact nothing.
+    if args.dry_run:
+        return _dry_run(inventory)
+
+    # 4. Catalogues, then one question per distinct check.
+    client = psirt.Client(client_id, client_secret)
+    ui.plain()
+    ui.system("Fetching Cisco platform and release catalogues ...")
+    try:
+        catalogues = _load_catalogues(client, _families_in(inventory))
+    except psirt.PsirtAuthError as e:
+        die(f"Cisco rejected the configured credentials: {e}",
+            hint="Re-check them with 'caia --config'.")
+    except psirt.PsirtUnreachableError as e:
+        die(f"Could not reach Cisco: {e}",
+            hint="Check your connection or proxy and try again.")
+
+    checks, unresolved = matching.build_checks(inventory, catalogues)
+    ui.ok(f"{len(inventory)} firewalls collapse to {ui.bold(str(len(checks)))} distinct "
+          f"checks.")
+    if unresolved:
+        ui.info(f"{len(unresolved)} firewall(s) need review before Cisco can be asked.")
+
+    results, partial_cause = _run_checks(client, checks)
+
+    # 5. Verdicts.
+    devices = _assemble_devices(inventory, catalogues, checks, unresolved, results)
+    summary = _build_summary(inv_path, devices, partial_cause)
+    _print_verdict_tally(summary)
+
+    # 6. Report.
+    try:
+        ensure_dirs(output_dir)
+        out = html_report.write_report(devices, summary, str(output_dir))
+    except OSError as e:
+        die(f"Could not write the report to {output_dir}: {e}",
+            hint="Check that the current folder is writable, or pass --output-dir DIR.")
+    ui.plain()
+    ui.ok("Wrote " + ui.bold(str(out)))
+    return 0
+
+
+def _dry_run(inventory):
+    """Show what a real run would ask Cisco, without contacting Cisco.
+
+    Uses the same resolution the real run uses, so devices that would never reach the API
+    are listed as such rather than shown as questions that would be asked. Alias
+    validation is skipped because that needs Cisco's live platform catalogue — so a model
+    shown here as mappable could still turn out to be one Cisco has not aliased yet.
+    """
+    ui.plain()
+    ui.system("Dry run - resolving each firewall to the check that would be made. "
+              "Cisco is not contacted.")
+
+    catalogues = matching.Catalogues()  # empty: nothing to validate an alias against
+    checks, unresolved = matching.build_checks(inventory, catalogues, validate_alias=False)
+
+    ui.plain()
+    ui.plain(ui.bold("Would ask Cisco:"))
+    for check in sorted(checks, key=lambda c: (c[0], c[1] or "", c[2])):
+        os_type, alias, release = check
+        label = f"{os_type}/{alias or '(no platform)'}/{release}"
+        count = len(checks[check])
+        ui.plain(f"  {label:<46} {ui.dim(str(count) + ' device(s)')}")
+
+    if unresolved:
+        ui.plain()
+        ui.plain(ui.bold("Would not reach Cisco - Needs review:"))
+        grouped = {}
+        for device, reason in unresolved:
+            grouped.setdefault(reason.kind, []).append(device["name"])
+        for kind in sorted(grouped):
+            names = grouped[kind]
+            shown = ", ".join(names[:4]) + (" ..." if len(names) > 4 else "")
+            ui.plain(f"  {kind:<26} {len(names):>3} device(s)  {ui.dim(shown)}")
+
+    ui.plain()
+    ui.ok(f"{len(inventory)} firewalls would produce {ui.bold(str(len(checks)))} checks"
+          + (f", with {len(unresolved)} resolved locally as Needs review" if unresolved
+             else "")
+          + ". No report written.")
+    return 0
+
+
+def _run_checks(client, checks):
+    """Ask Cisco once per check. Returns ({check: (outcome, advisories)}, partial_cause).
+
+    A failure part-way through stops further requests but keeps every answer already
+    obtained: the remaining devices become Needs review and the report is flagged partial
+    rather than the run being thrown away (FR-016).
+    """
+    results = {}
+    total = len(checks)
+    for index, check in enumerate(checks, 1):
+        ui.plain(ui.dim(f"  [{index}/{total}] {_describe_check(check)}"))
+        os_type, alias, release = check
+        try:
+            outcome, advisories = client.get_advisories(os_type, release, alias)
+        except psirt.PsirtAuthError as e:
+            return results, f"Cisco rejected the access token part-way through: {e}"
+        except psirt.PsirtUnreachableError as e:
+            return results, f"Cisco became unreachable part-way through: {e}"
+        results[check] = (outcome, advisories)
+    return results, None
+
+
+def _assemble_devices(inventory, catalogues, checks, unresolved, results):
+    """Attach a verdict, reason and advisories to every inventory row."""
+    reasons = {id(device): reason for device, reason in unresolved}
+    by_device = {}
+    for check, members in checks.items():
+        outcome, advisories = results.get(check, (None, None))
+        for device in members:
+            by_device[id(device)] = (check, outcome, advisories)
+
+    devices = []
+    for device in inventory:
+        entry = dict(device)
+        reason = reasons.get(id(device))
+        if reason is not None:
+            entry["verdict"] = matching.NEEDS_REVIEW
+            entry["reason"] = reason
+            entry["advisories"] = []
+        else:
+            check, outcome, advisories = by_device.get(id(device), (None, None, None))
+            verdict, reason = matching.verdict_from_outcome(
+                check, catalogues, outcome, advisories,
+                raw_release=device.get("version"))
+            entry["verdict"] = verdict
+            entry["reason"] = reason
+            entry["advisories"] = list(advisories or []) if verdict == matching.IMPACTED else []
+        devices.append(entry)
+    return devices
+
+
+def _build_summary(inv_path, devices, partial_cause):
+    counts = {matching.IMPACTED: 0, matching.NOT_IMPACTED: 0, matching.NEEDS_REVIEW: 0}
+    for device in devices:
+        counts[device["verdict"]] = counts.get(device["verdict"], 0) + 1
+    return {
+        "generated_at": _dt.datetime.now(),
+        "inventory_file": inv_path.name,
+        "device_count": len(devices),
+        "counts": counts,
+        "partial_cause": partial_cause,
+    }
+
+
+def _print_verdict_tally(summary):
+    counts = summary["counts"]
+    ui.plain()
+    _result_line("Impacted", str(counts.get(matching.IMPACTED, 0)), ui.green)
+    _result_line("Not impacted", str(counts.get(matching.NOT_IMPACTED, 0)), ui.gray)
+    _result_line("Needs review", str(counts.get(matching.NEEDS_REVIEW, 0)), ui.yellow)
+    if summary.get("partial_cause"):
+        ui.plain()
+        ui.warn("This run was partial: " + summary["partial_cause"])
diff --git a/cisco_advisory_impact_agent/cli.py b/cisco_advisory_impact_agent/cli.py
index 2b89b29..b80ebcc 100644
--- a/cisco_advisory_impact_agent/cli.py
+++ b/cisco_advisory_impact_agent/cli.py
@@ -64,6 +64,9 @@ def build_parser():
     ap.add_argument("--yes", "-y", dest="yes", action="store_true",
                     help="Skip confirmation prompts (for scripted/unattended use)")
     # Analysis flags (a supplied flag skips its interactive prompt — FR-025).
+    ap.add_argument("--api", action="store_true",
+                    help="Check your whole inventory against Cisco's published advisory "
+                         "data (no URL needed); writes an HTML report")
     ap.add_argument("--url", help="ERP page URL or single advisory URL (else prompted)")
     ap.add_argument("--inventory",
                     help="Path to an inventory .xlsx (else discovered in the current folder)")
@@ -231,7 +234,22 @@ def _start_of_run_update_nudge(args):
 
 
 def cmd_run(args):
+    """Dispatch to the inventory-driven check or the advisory-driven analysis.
+
+    The two are mutually exclusive: they answer different questions and produce different
+    reports, so combining them is a mistake worth naming rather than silently resolving
+    (FR-003).
+    """
+    if args.api and args.url:
+        ui.fail("--api and --url cannot be combined.")
+        ui.plain(ui.dim(
+            "--api checks your whole inventory against Cisco's published advisory data.\n"
+            "--url analyzes one advisory or ERP page against your inventory.\n"
+            "Run one or the other."))
+        return 2
     _start_of_run_update_nudge(args)
+    if args.api:
+        return analyzer.run_api(args)
     return analyzer.run(args)
 
 
diff --git a/cisco_advisory_impact_agent/config.py b/cisco_advisory_impact_agent/config.py
index 99fc3d4..0d4cdc7 100644
--- a/cisco_advisory_impact_agent/config.py
+++ b/cisco_advisory_impact_agent/config.py
@@ -21,7 +21,12 @@
 API_KEY = "FUELIX_API_KEY"
 MODEL = "FUELIX_MODEL"
 BASE_URL = "FUELIX_BASE_URL"
-KEYS = (API_KEY, MODEL, BASE_URL)
+# Cisco PSIRT API credentials, used only by the inventory-driven check (`--api`).
+# The client id is an application identifier, not a secret; the client secret is a secret
+# and is handled as one throughout (never echoed, logged, or written outside this file).
+CISCO_CLIENT_ID = "CISCO_CLIENT_ID"
+CISCO_CLIENT_SECRET = "CISCO_CLIENT_SECRET"
+KEYS = (API_KEY, MODEL, BASE_URL, CISCO_CLIENT_ID, CISCO_CLIENT_SECRET)
 
 DEFAULTS = {MODEL: fuelix.DEFAULT_MODEL, BASE_URL: fuelix.DEFAULT_BASE_URL}
 
@@ -80,7 +85,9 @@ def save(values):
     lines = [
         "# Cisco Advisory Impact Agent configuration.",
         "# Managed by `caia --config`; you may edit values by hand.",
-        "# Environment variables (FUELIX_API_KEY / FUELIX_MODEL / FUELIX_BASE_URL) override these.",
+        "# Environment variables of the same name override every value below:",
+        "#   FUELIX_API_KEY / FUELIX_MODEL / FUELIX_BASE_URL  - advisory-driven analysis",
+        "#   CISCO_CLIENT_ID / CISCO_CLIENT_SECRET            - inventory-driven check (--api)",
     ]
     for key in KEYS:
         val = values.get(key)
@@ -147,23 +154,80 @@ def load_local_env():
 # --------------------------------------------------------------------------- #
 # Interactive `--config`
 # --------------------------------------------------------------------------- #
+def _prompt_secret(label, existing_value):
+    """Hidden prompt that keeps an existing value on empty input.
+
+    Every prompt is skippable: a user of only one mode must be able to walk past the other
+    mode's credentials without inventing one (spec 006 FR-035/FR-036).
+    """
+    if existing_value:
+        ui.plain(f"{label} is already configured " + ui.dim("(hidden)."))
+        entered = ui.ask_secret(f"New {label} (press Enter to keep the current one)")
+        if not entered:
+            ui.secret_captured(label, "")
+            return existing_value
+    else:
+        entered = ui.ask_secret(f"{label} (press Enter to skip)")
+    ui.secret_captured(label, entered)
+    return entered
+
+
+def _prompt_visible(label, existing_value):
+    """Visible prompt for a non-secret identifier, keeping an existing value on empty."""
+    if existing_value:
+        ui.plain(f"{label} is already configured: " + ui.bold(existing_value))
+        entered = ui.ask(f"New {label} (press Enter to keep the current one)")
+        return entered or existing_value
+    return ui.ask(f"{label} (press Enter to skip)")
+
+
+def _verify_cisco(client_id, client_secret, interactive):
+    """Check the Cisco credentials before saving. Returns True if they may be saved.
+
+    Three outcomes, deliberately distinguished (spec 006 FR-041..FR-043):
+      * accepted   - say so plainly, save
+      * rejected   - show Cisco's reason, offer re-entry, do not silently save
+      * unreachable- say so distinctly and offer to save unverified, because a proxy
+                     outage must never leave a user with correct credentials unable to
+                     finish setup
+
+    No message here contains any part of a credential (FR-049).
+    """
+    from cisco_advisory_impact_agent import psirt
+
+    ui.plain()
+    ui.system("Checking the Cisco credentials ...")
+    try:
+        psirt.fetch_token(client_id, client_secret)
+    except psirt.PsirtAuthError as exc:
+        ui.fail(f"Cisco rejected these credentials. {exc}")
+        return False
+    except psirt.PsirtUnreachableError as exc:
+        ui.warn(f"Could not check the credentials: {exc}")
+        ui.plain(ui.dim("They have not been shown to be wrong — Cisco simply could not be "
+                        "reached. This is usually a proxy or connectivity issue."))
+        if not interactive:
+            return True
+        return ui.confirm("Save them anyway, unverified?", default=True)
+    ui.ok("Cisco accepted these credentials.")
+    return True
+
+
 def run_config():
-    """Interactively set the API key and model; persist to the per-user config file (FR-008..011)."""
+    """Interactively set every credential and setting; persist to the per-user config file.
+
+    One linear pass, every prompt skippable. Each mode gates only on its own credentials,
+    so a user of `--api` alone never has to supply an AI service key and vice versa
+    (spec 006 FR-034..FR-036).
+    """
     existing = load_file()
+    interactive = sys.stdin.isatty()
     ui.title("Configure Cisco Advisory Impact Agent")
 
-    # API key (secret). Empty input keeps the existing value.
-    if existing.get(API_KEY):
-        ui.plain("An API key is already configured " + ui.dim("(hidden)."))
-        entered = ui.ask_secret("New API key (press Enter to keep the current one)")
-        api_key = entered or existing[API_KEY]
-    else:
-        api_key = ui.ask_secret("FueliX API key")
-        while not api_key:
-            ui.warn("The API key cannot be empty.")
-            api_key = ui.ask_secret("FueliX API key")
+    # --- FueliX (advisory-driven analysis) ------------------------------------ #
+    ui.system("FueliX AI — used by the advisory-driven analysis (caia --url).")
+    api_key = _prompt_secret("FueliX API key", existing.get(API_KEY))
 
-    # Model (curated menu). A configured model not in the list is shown as current and keepable.
     current_model = existing.get(MODEL, fuelix.DEFAULT_MODEL)
     options = list(fuelix.KNOWN_MODELS)
     if current_model not in options:
@@ -175,8 +239,37 @@ def run_config():
     # Base URL is not prompted (FR-010); preserve the existing/default so the file stays editable.
     base_url = existing.get(BASE_URL, fuelix.DEFAULT_BASE_URL)
 
-    path = save({API_KEY: api_key, MODEL: model, BASE_URL: base_url})
+    # --- Cisco PSIRT API (inventory-driven check) ---------------------------- #
+    ui.plain()
+    ui.system("Cisco PSIRT API — used by the inventory-driven check (caia --api).")
+    ui.plain(ui.dim("Get your own client ID and secret from https://developer.cisco.com/psirt/"))
+    # The client ID names the calling application and is not a secret, so it is echoed:
+    # seeing it lets you confirm a paste landed. The secret is never displayed (FR-037).
+    cisco_id = _prompt_visible("Cisco client ID", existing.get(CISCO_CLIENT_ID))
+    cisco_secret = _prompt_secret("Cisco client secret", existing.get(CISCO_CLIENT_SECRET))
+
+    # Verify only when both values are available for this session (FR-044).
+    if cisco_id and cisco_secret:
+        if not _verify_cisco(cisco_id, cisco_secret, interactive):
+            ui.plain()
+            ui.warn("The Cisco credentials were not saved. Re-run "
+                    + ui.bold("caia --config") + " to enter them again.")
+            cisco_id = existing.get(CISCO_CLIENT_ID, "")
+            cisco_secret = existing.get(CISCO_CLIENT_SECRET, "")
+            path = save({API_KEY: api_key, MODEL: model, BASE_URL: base_url,
+                         CISCO_CLIENT_ID: cisco_id, CISCO_CLIENT_SECRET: cisco_secret})
+            ui.plain(ui.dim(f"Other settings were saved to {path}."))
+            return 1
+
+    path = save({API_KEY: api_key, MODEL: model, BASE_URL: base_url,
+                 CISCO_CLIENT_ID: cisco_id, CISCO_CLIENT_SECRET: cisco_secret})
     ui.plain()
     ui.ok("Saved configuration to " + ui.bold(str(path)) + ".")
     ui.plain(ui.dim("The base URL is not prompted; edit the file or set FUELIX_BASE_URL to change it."))
+    if not api_key:
+        ui.plain(ui.dim("No FueliX key was set, so the advisory-driven analysis "
+                        "(caia --url) will ask for one when you run it."))
+    if not (cisco_id and cisco_secret):
+        ui.plain(ui.dim("Cisco credentials are incomplete, so caia --api will ask for "
+                        "them when you run it."))
     return 0
diff --git a/cisco_advisory_impact_agent/html_report.py b/cisco_advisory_impact_agent/html_report.py
new file mode 100644
index 0000000..8b98418
--- /dev/null
+++ b/cisco_advisory_impact_agent/html_report.py
@@ -0,0 +1,440 @@
+"""HTML report writer for the inventory-driven check (`--api`).
+
+One self-contained file per run: all CSS and JavaScript are inlined and nothing is fetched
+at render time, so the report survives being emailed, archived, or opened behind a
+restrictive proxy with no network at all (FR-030).
+
+Escaping is load-bearing, not hygiene theatre. Every advisory Cisco returned during the
+feasibility spike carried raw HTML in its `summary` — `<a>` anchors included — so any
+Cisco-supplied value interpolated here without escaping would render externally-authored
+markup inside a security tool's own output (FR-033). Everything from Cisco goes through
+`esc()`.
+
+Standard library only (Constitution I): string composition and `html.escape`.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import html
+from pathlib import Path
+
+from cisco_advisory_impact_agent import matching as m
+
+FILENAME_PREFIX = "impact_report_"
+
+_VERDICT_CLASS = {
+    m.IMPACTED: "v-impacted",
+    m.NOT_IMPACTED: "v-clean",
+    m.NEEDS_REVIEW: "v-review",
+}
+
+# Marks shown alongside the verdict text so the table stays readable when printed in
+# greyscale or read by someone with a colour-vision deficiency (FR-029 spirit).
+_VERDICT_MARK = {
+    m.IMPACTED: "●",       # filled circle
+    m.NOT_IMPACTED: "○",   # hollow circle
+    m.NEEDS_REVIEW: "▲",   # triangle
+}
+
+
+def esc(value):
+    """Escape any value for HTML text or attribute context. Never returns None."""
+    return html.escape("" if value is None else str(value), quote=True)
+
+
+# --------------------------------------------------------------------------- #
+# Output path
+# --------------------------------------------------------------------------- #
+def report_path(output_dir, now=None):
+    """A timestamped path that does not already exist.
+
+    Never overwrites: a collision (two runs inside the same second) gets a numeric
+    suffix, mirroring how the spreadsheet report already behaves (FR-023).
+    """
+    stamp = (now or _dt.datetime.now()).strftime("%Y%m%d_%H%M%S")
+    directory = Path(output_dir)
+    path = directory / f"{FILENAME_PREFIX}{stamp}.html"
+    n = 1
+    while path.exists():
+        path = directory / f"{FILENAME_PREFIX}{stamp}_{n}.html"
+        n += 1
+    return path
+
+
+# --------------------------------------------------------------------------- #
+# Cell rendering
+# --------------------------------------------------------------------------- #
+def _columns(devices):
+    """Original inventory column titles, in the sheet's own order."""
+    for device in devices:
+        raw = device.get("raw")
+        if raw:
+            return list(raw.keys())
+    return ["FirewallName", "Model", "Firewalltype", "IOS version"]
+
+
+def _detail_cell(device):
+    """The Detail column: advisories for Impacted, the reason for Needs review."""
+    verdict = device.get("verdict")
+    if verdict == m.IMPACTED:
+        return _advisories_html(device.get("advisories") or [])
+    if verdict == m.NEEDS_REVIEW:
+        return f'<div class="reason">{esc(reason_text(device.get("reason")))}</div>'
+    return ""
+
+
+def first_fix_of(advisory):
+    """The release that first fixes an advisory, or "" when Cisco supplies none.
+
+    Never inferred. An advisory with no fixed release is rendered as having none.
+    """
+    for platform in advisory.get("platforms") or []:
+        for fix in platform.get("firstFixes") or []:
+            name = (fix or {}).get("name")
+            if name:
+                return str(name)
+    return ""
+
+
+_SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "informational": 4}
+
+
+def _advisory_sort_key(advisory):
+    sir = str(advisory.get("sir") or "").strip().lower()
+    return (_SEVERITY_ORDER.get(sir, 9), str(advisory.get("advisoryId") or ""))
+
+
+def _advisories_html(advisories):
+    """Collapsible advisory detail for an Impacted device.
+
+    The full list is always present in the document — the spike saw one device with 82
+    advisories, so the list is collapsed rather than truncated (FR-025). The fixed release
+    is given at least the prominence of the severity, because it is the field an engineer
+    acts on.
+    """
+    if not advisories:
+        return ""
+    ordered = sorted(advisories, key=_advisory_sort_key)
+    items = []
+    for adv in ordered:
+        advisory_id = esc(adv.get("advisoryId"))
+        url = esc(adv.get("publicationUrl") or "")
+        link = f'<a href="{url}" rel="noreferrer noopener">{advisory_id}</a>' if url \
+            else advisory_id
+        sir = esc(adv.get("sir") or "Unrated")
+        fix = first_fix_of(adv)
+        fix_html = (f'<span class="fix">fixed in {esc(fix)}</span>' if fix
+                    else '<span class="nofix">no fixed release published</span>')
+        cves = [c for c in (adv.get("cves") or []) if c]
+        cve_html = (f'<span class="cves">{esc(", ".join(str(c) for c in cves))}</span>'
+                    if cves else "")
+        title = esc(adv.get("advisoryTitle") or "")
+        items.append(
+            f'<li><span class="sev sev-{esc(sir.lower())}">{sir}</span> '
+            f'{link} {fix_html}<div class="advtitle">{title}</div>{cve_html}</li>'
+        )
+    count = len(ordered)
+    return (f'<details class="advisories"><summary>{count} '
+            f'advisor{"y" if count == 1 else "ies"}</summary>\n'
+            f'<ul class="advlist">{"".join(items)}</ul></details>')
+
+
+def reason_text(reason):
+    """One readable sentence explaining why a device could not be assessed.
+
+    Written for the person who has to fix it, so each sentence names the field to look at
+    and, where Cisco told us, what it does list instead. No HTTP status codes and no
+    internal identifiers leak out here (SC-004).
+    """
+    if reason is None:
+        return "Could not be assessed."
+
+    detail = reason.detail
+    kind = reason.kind
+
+    if kind == m.RELEASE_UNKNOWN:
+        raw = detail.get("raw_release") or detail.get("release") or ""
+        normalized = detail.get("release") or ""
+        shown = (f"{raw} (checked as {normalized})"
+                 if normalized and raw and normalized != raw else raw or normalized)
+        return (f"Cisco does not recognise release {shown}. Either the release is recorded "
+                "differently in the inventory, or it is an end-of-support train Cisco has "
+                "removed from its data.")
+
+    if kind == m.RELEASE_NOT_ON_PLATFORM:
+        release = detail.get("release") or ""
+        platforms = detail.get("platforms") or []
+        if platforms:
+            listed = "; ".join(platforms)
+            return (f"Cisco recognises release {release} but does not list it for this "
+                    f"model. It lists that release for: {listed}. Check whether the model "
+                    "or the release is wrong in the inventory.")
+        return (f"Cisco recognises release {release} but lists no platforms for it, so it "
+                "cannot be confirmed for this model.")
+
+    if kind == m.MODEL_UNMAPPED:
+        return (f"Model \"{detail.get('model', '')}\" could not be matched to a Cisco "
+                "hardware platform. Either the model is recorded differently in the "
+                "inventory, or Cisco does not yet publish a platform for it.")
+
+    if kind == m.FIELD_MISSING:
+        return (f"The {detail.get('field', 'required field')} is blank in the inventory, "
+                "so there is nothing to check.")
+
+    if kind == m.FAMILY_UNSUPPORTED:
+        return (f"Product family \"{detail.get('family', '')}\" is outside what this check "
+                "covers, so Cisco was not asked about this device.")
+
+    if kind == m.CHECK_INCOMPLETE:
+        return ("The check did not complete for this device, so nothing is known about it. "
+                "This is not a statement that it is unaffected — re-run to try again.")
+
+    return "Could not be assessed."
+
+
+# --------------------------------------------------------------------------- #
+# Document
+# --------------------------------------------------------------------------- #
+_CSS = """
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 2rem 1.5rem; font: 15px/1.5 -apple-system, BlinkMacSystemFont,
+       "Segoe UI", Roboto, Helvetica, Arial, sans-serif; color: #1b1b1b;
+       background: #f7f7f8; }
+h1 { margin: 0 0 .25rem; font-size: 1.5rem; }
+table { width: 100%; border-collapse: collapse; background: #fff;
+        box-shadow: 0 1px 3px rgba(0,0,0,.08); }
+th, td { padding: .5rem .65rem; text-align: left; vertical-align: top;
+         border-bottom: 1px solid #e6e6e8; font-size: .9rem; }
+th { background: #1f4e78; color: #fff; font-weight: 600; position: sticky; top: 0; }
+tbody tr:nth-child(even) { background: #fbfbfc; }
+.verdict { white-space: nowrap; font-weight: 600; }
+.v-impacted { color: #a3231d; }
+.v-clean    { color: #1e6b34; }
+.v-review   { color: #8a5a00; }
+.reason { color: #4a4a4a; }
+.advisories { color: #2b2b2b; }
+.advisories > summary { cursor: pointer; font-weight: 600; }
+.advlist { margin: .4rem 0 0; padding-left: 1.1rem; }
+.advlist li { margin-bottom: .45rem; }
+.advtitle { color: #555; font-size: .85rem; }
+.cves { color: #666; font-size: .8rem; font-family: ui-monospace, SFMono-Regular,
+        Menlo, monospace; }
+.sev { display: inline-block; min-width: 5.2em; padding: 0 .35rem; margin-right: .3rem;
+       border-radius: 3px; font-size: .75rem; font-weight: 700; text-align: center;
+       text-transform: uppercase; border: 1px solid currentColor; }
+.sev-critical { color: #7a1512; }
+.sev-high     { color: #a3231d; }
+.sev-medium   { color: #8a5a00; }
+.sev-low      { color: #4a5a6a; }
+.fix   { font-weight: 600; color: #1e6b34; }
+.nofix { font-style: italic; color: #8a5a00; }
+.controls { margin: .75rem 0 1rem; display: flex; gap: .5rem; flex-wrap: wrap;
+            align-items: center; }
+.controls button { font: inherit; font-size: .85rem; padding: .3rem .7rem; cursor: pointer;
+                   border: 1px solid #c3c7cc; border-radius: 4px; background: #fff; }
+.controls button[aria-pressed="true"] { background: #1f4e78; color: #fff;
+                                        border-color: #1f4e78; }
+.controls .spacer { flex: 1 1 auto; }
+.summary { background: #fff; border: 1px solid #e2e4e7; border-radius: 6px;
+           padding: 1rem 1.1rem; margin: 1rem 0; }
+.facts { display: flex; flex-wrap: wrap; gap: 1.5rem; margin: 0 0 .25rem; }
+.facts .fact { margin: 0; }
+.facts dt { font-size: .72rem; text-transform: uppercase; letter-spacing: .04em;
+            color: #6b7076; }
+.facts dd { margin: .1rem 0 0; font-size: 1.05rem; font-weight: 600; }
+.partial { margin: .85rem 0 0; padding: .6rem .75rem; border-radius: 4px;
+           background: #fff6e0; border: 1px solid #e8cf94; color: #6b4c00; }
+.coverage { margin-top: 1rem; border-top: 1px solid #ebedef; padding-top: .75rem; }
+.coverage h2 { font-size: .85rem; text-transform: uppercase; letter-spacing: .04em;
+               color: #6b7076; margin: 0 0 .4rem; }
+.coverage ul { margin: 0; padding-left: 1.1rem; color: #4a4a4a; font-size: .85rem; }
+.coverage li { margin-bottom: .3rem; }
+th.sortable { cursor: pointer; }
+th.sortable::after { content: " \\2195"; opacity: .55; }
+tr.hidden { display: none; }
+"""
+
+
+# Vanilla JS, inlined. No framework and no CDN: the report must filter and sort with no
+# network access, after being emailed (FR-029, FR-030).
+_JS = """
+(function () {
+  var table = document.getElementById('devices');
+  if (!table) return;
+  var tbody = table.tBodies[0];
+  var rows = Array.prototype.slice.call(tbody.rows);
+
+  function applyFilter(value, pressed) {
+    rows.forEach(function (row) {
+      var show = (value === 'all') || (row.getAttribute('data-verdict') === value);
+      row.classList.toggle('hidden', !show);
+    });
+    Array.prototype.forEach.call(
+      document.querySelectorAll('.controls button[data-filter]'),
+      function (b) { b.setAttribute('aria-pressed', String(b === pressed)); });
+  }
+
+  Array.prototype.forEach.call(
+    document.querySelectorAll('.controls button[data-filter]'),
+    function (button) {
+      button.addEventListener('click', function () {
+        applyFilter(button.getAttribute('data-filter'), button);
+      });
+    });
+
+  var expandAll = document.getElementById('expand-all');
+  if (expandAll) {
+    expandAll.addEventListener('click', function () {
+      var open = expandAll.getAttribute('aria-pressed') !== 'true';
+      Array.prototype.forEach.call(table.querySelectorAll('details'),
+        function (d) { d.open = open; });
+      expandAll.setAttribute('aria-pressed', String(open));
+    });
+  }
+
+  var ascending = {};
+  Array.prototype.forEach.call(table.querySelectorAll('th.sortable'),
+    function (header, index) {
+      header.addEventListener('click', function () {
+        var col = Array.prototype.indexOf.call(header.parentNode.cells, header);
+        var dir = ascending[col] = !ascending[col];
+        var sorted = rows.slice().sort(function (a, b) {
+          var x = (a.cells[col] || {}).textContent || '';
+          var y = (b.cells[col] || {}).textContent || '';
+          var nx = parseFloat(x), ny = parseFloat(y);
+          var cmp = (!isNaN(nx) && !isNaN(ny)) ? (nx - ny)
+                    : x.trim().localeCompare(y.trim());
+          return dir ? cmp : -cmp;
+        });
+        sorted.forEach(function (row) { tbody.appendChild(row); });
+      });
+    });
+})();
+"""
+
+
+def _document(title, body):
+    return (
+        "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n"
+        "<meta charset=\"utf-8\">\n"
+        "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n"
+        f"<title>{esc(title)}</title>\n"
+        f"<style>{_CSS}</style>\n"
+        "</head>\n<body>\n"
+        f"{body}\n"
+        f"<script>{_JS}</script>\n"
+        "</body>\n</html>\n"
+    )
+
+
+def _controls(devices):
+    counts = {}
+    for device in devices:
+        verdict = device.get("verdict") or m.NEEDS_REVIEW
+        counts[verdict] = counts.get(verdict, 0) + 1
+    buttons = [('all', f"All ({len(devices)})", "true")]
+    for verdict in (m.IMPACTED, m.NEEDS_REVIEW, m.NOT_IMPACTED):
+        buttons.append((verdict, f"{verdict} ({counts.get(verdict, 0)})", "false"))
+    html_buttons = "".join(
+        f'<button type="button" data-filter="{esc(value)}" aria-pressed="{pressed}">'
+        f'{esc(label)}</button>'
+        for value, label, pressed in buttons)
+    return ('<div class="controls">' + html_buttons
+            + '<span class="spacer"></span>'
+            + '<button type="button" id="expand-all" aria-pressed="false">'
+              'Expand all advisories</button>'
+            + '</div>')
+
+
+def _table(devices):
+    columns = _columns(devices)
+    # Every original column is sortable, so "sort by priority" needs no special case.
+    head = "".join(f'<th class="sortable">{esc(c)}</th>' for c in columns)
+    head += '<th class="sortable">Impact Status</th><th>Detail</th>'
+
+    rows = []
+    for device in devices:
+        raw = device.get("raw") or {}
+        verdict = device.get("verdict") or m.NEEDS_REVIEW
+        cells = "".join(f"<td>{esc(raw.get(c, ''))}</td>" for c in columns)
+        mark = _VERDICT_MARK.get(verdict, "")
+        cells += (f'<td class="verdict {_VERDICT_CLASS.get(verdict, "")}">'
+                  f'{esc(mark)} {esc(verdict)}</td>')
+        cells += f"<td>{_detail_cell(device)}</td>"
+        rows.append(f'<tr data-verdict="{esc(verdict)}">{cells}</tr>')
+
+    return ('<table id="devices">\n<thead><tr>' + head + "</tr></thead>\n<tbody>\n"
+            + "\n".join(rows) + "\n</tbody>\n</table>")
+
+
+# Both statements are mandatory in every report (FR-032). They bound what any verdict here
+# can mean, and a reader who receives the report second-hand must not have to hunt for them.
+COVERAGE_NOTES = (
+    "Cisco's data holds no advisories published before its per-family cut-off dates "
+    "(January 2022 for ASA, FMC, FTD and FXOS). An Impacted list is therefore not "
+    "exhaustive, and a Not impacted verdict is narrower than it appears.",
+    "A verdict reflects whether a release is listed as affected. It does not account for "
+    "whether the vulnerable feature is enabled on the device, so Impacted means "
+    "\"listed as affected\", not \"exploitable\".",
+    "Needs review is not a statement of safety. It means no trustworthy verdict could be "
+    "reached, and each one says why.",
+)
+
+
+def _summary_html(summary, devices):
+    """Run provenance and the coverage limits, at the top of the document."""
+    counts = {}
+    for device in devices:
+        verdict = device.get("verdict") or m.NEEDS_REVIEW
+        counts[verdict] = counts.get(verdict, 0) + 1
+
+    summary = summary or {}
+    generated = summary.get("generated_at")
+    generated_text = (generated.strftime("%Y-%m-%d %H:%M:%S")
+                      if hasattr(generated, "strftime") else str(generated or "unknown"))
+    inventory_file = summary.get("inventory_file") or "unknown"
+    device_count = summary.get("device_count", len(devices))
+
+    facts = [
+        ("Run", generated_text),
+        ("Inventory", inventory_file),
+        ("Firewalls assessed", str(device_count)),
+        (m.IMPACTED, str(counts.get(m.IMPACTED, 0))),
+        (m.NOT_IMPACTED, str(counts.get(m.NOT_IMPACTED, 0))),
+        (m.NEEDS_REVIEW, str(counts.get(m.NEEDS_REVIEW, 0))),
+    ]
+    cells = "".join(
+        f'<div class="fact"><dt>{esc(label)}</dt><dd>{esc(value)}</dd></div>'
+        for label, value in facts)
+
+    partial = ""
+    if summary.get("partial_cause"):
+        partial = ('<p class="partial"><strong>This run was partial.</strong> '
+                   + esc(summary["partial_cause"])
+                   + " Firewalls that were not reached are marked Needs review; they are "
+                     "not known to be unaffected.</p>")
+
+    notes = "".join(f"<li>{esc(note)}</li>" for note in COVERAGE_NOTES)
+    return (f'<section class="summary"><dl class="facts">{cells}</dl>{partial}'
+            f'<div class="coverage"><h2>What this report does and does not cover</h2>'
+            f'<ul>{notes}</ul></div></section>')
+
+
+def render(devices, summary=None):
+    """Render the full report document as a string."""
+    body = ("<h1>Cisco Advisory Impact Report</h1>\n"
+            + _summary_html(summary, devices) + "\n"
+            + _controls(devices) + "\n"
+            + _table(devices))
+    return _document("Cisco Advisory Impact Report", body)
+
+
+def write_report(devices, summary=None, output_dir="output", now=None):
+    """Write the report and return the path written."""
+    directory = Path(output_dir)
+    directory.mkdir(parents=True, exist_ok=True)
+    path = report_path(directory, now=now)
+    path.write_text(render(devices, summary), encoding="utf-8")
+    return path
diff --git a/cisco_advisory_impact_agent/inventory.py b/cisco_advisory_impact_agent/inventory.py
index 78689e2..37d0234 100644
--- a/cisco_advisory_impact_agent/inventory.py
+++ b/cisco_advisory_impact_agent/inventory.py
@@ -22,7 +22,12 @@ class InventoryError(Exception):
 
 
 def load_inventory(path, sheet=None):
-    """Read the inventory into a list of {name, model, family, version} dicts.
+    """Read the inventory into a list of per-firewall dicts.
+
+    Each dict carries the four fields the analysis needs — name, model, family, version —
+    plus two the inventory-driven check's report needs: `priority` (used only for sorting)
+    and `raw`, an ordered mapping of the sheet's own header text to that row's values, so a
+    report can reproduce the user's original columns verbatim without re-reading the file.
 
     Column headers are matched fuzzily so minor variations (e.g. the leading space in
     " IOS version") still work. Firewalltype ASAv is folded into ASA.
@@ -44,6 +49,7 @@ def col(*names):
     ci_model = col("model")
     ci_type = col("firewalltype", "type")
     ci_ver = col("version", "ios")
+    ci_prio = col("priority")
     if ci_name is None or ci_type is None or ci_ver is None:
         raise InventoryError(
             "Inventory is missing required columns. Expected a name column, a "
@@ -51,6 +57,9 @@ def col(*names):
             f"Found headers: {rows[0]}"
         )
 
+    # The sheet's own header text, used to reproduce the user's columns in a report.
+    titles = [str(c).strip() if c is not None else "" for c in rows[0]]
+
     inv = []
     for r in rows[1:]:
         if not r or ci_name >= len(r) or r[ci_name] is None:
@@ -63,11 +72,27 @@ def col(*names):
                 "model": str(_cell(r, ci_model)).strip() if _cell(r, ci_model) else "",
                 "family": family,
                 "version": str(_cell(r, ci_ver)).strip() if _cell(r, ci_ver) else "",
+                "priority": _cell(r, ci_prio),
+                "raw": _raw_row(titles, r),
             }
         )
     return inv
 
 
+def _raw_row(titles, row):
+    """Map the sheet's header text to this row's values, preserving column order.
+
+    Blank header cells are skipped; a short row yields empty strings for the tail.
+    """
+    out = {}
+    for i, title in enumerate(titles):
+        if not title:
+            continue
+        value = _cell(row, i)
+        out[title] = "" if value is None else str(value).strip()
+    return out
+
+
 def _cell(row, idx):
     if idx is None or idx >= len(row):
         return None
diff --git a/cisco_advisory_impact_agent/matching.py b/cisco_advisory_impact_agent/matching.py
new file mode 100644
index 0000000..96d27fb
--- /dev/null
+++ b/cisco_advisory_impact_agent/matching.py
@@ -0,0 +1,349 @@
+"""Pure matching and verdict logic for the inventory-driven check (`--api`).
+
+Everything here is side-effect free and does no I/O, so the whole decision table in
+specs/006-api-inventory-check/data-model.md is provable by unit test without touching
+Cisco's API. That boundary is deliberate: this module owns the feature's safety property.
+
+The safety property (Constitution IV): a device is called `NOT_IMPACTED` only when Cisco
+positively confirmed *both* that it recognises the release and that the release runs on
+that device's platform. Every other path — an unmapped model, an unreconcilable platform
+name, a failed request, an unrecognised response — falls to `NEEDS_REVIEW`. Local
+heuristics can only ever reduce the number of `NEEDS_REVIEW` rows; none can produce a
+`NOT_IMPACTED`.
+"""
+
+from __future__ import annotations
+
+import re
+
+# --------------------------------------------------------------------------- #
+# Vocabulary
+# --------------------------------------------------------------------------- #
+IMPACTED = "Impacted"
+NOT_IMPACTED = "Not impacted"
+NEEDS_REVIEW = "Needs review"
+
+# Reason kinds attached to every NEEDS_REVIEW verdict (data-model.md § Reason).
+RELEASE_UNKNOWN = "release_unknown"
+RELEASE_NOT_ON_PLATFORM = "release_not_on_platform"
+MODEL_UNMAPPED = "model_unmapped"
+FIELD_MISSING = "field_missing"
+FAMILY_UNSUPPORTED = "family_unsupported"
+CHECK_INCOMPLETE = "check_incomplete"
+
+# Classified API outcomes. Defined here rather than in `psirt` so this module keeps no
+# dependency on anything that performs I/O; `psirt` imports these.
+HAS_ADVISORIES = "has_advisories"
+NO_DATA = "no_data"
+INVALID_VERSION = "invalid_version"
+INCOMPLETE = "incomplete"
+
+# Families Cisco's checker can answer for at all.
+SUPPORTED_FAMILIES = ("asa", "ftd", "fmc", "fxos", "ios", "iosxe", "nxos", "aci")
+
+# Families whose queries accept a platformAlias. The rest must omit it entirely
+# (research Decision 8) — FMC catalogue rows carry no platform_name at all.
+PLATFORM_FAMILIES = ("asa", "ftd", "fxos", "nxos")
+
+
+# --------------------------------------------------------------------------- #
+# Release normalisation (research Decision 6)
+# --------------------------------------------------------------------------- #
+def normalize_release(raw):
+    """Reconcile an inventory release string with Cisco's canonical dotted form.
+
+    Three ordered steps, then tidy-up:
+      1. drop any companion-product annotation after "/"  (9.20(4)7/ASDM 7.22.1 -> 9.20(4)7)
+      2. rewrite parenthetical shorthand                  (9.16(4)67           -> 9.16.4.67)
+      3. strip a trailing build suffix                    (7.4.2.1-30          -> 7.4.2.1)
+
+    Already-canonical input is returned unchanged, so the function is idempotent.
+    """
+    text = str(raw or "").strip()
+    if not text:
+        return ""
+    text = text.split("/")[0].strip()
+    text = re.sub(r"\((\d+)\)", r".\1.", text)
+    text = re.sub(r"-\d+$", "", text)
+    return re.sub(r"\.+", ".", text).strip(". ")
+
+
+# --------------------------------------------------------------------------- #
+# Model -> platform alias (research Decision 7)
+# --------------------------------------------------------------------------- #
+# Ordered; first match wins. Keyed on the hardware series, because the inventory records
+# the same platform many ways ("Firepower 3120", "Cisco Secure Firewall 3140 Threat
+# Defense"). A model that matches nothing is reported as unmapped rather than guessed.
+_ALIAS_RULES = (
+    (r"ISA[\s\-_]*3000", "ISA3000"),
+    (r"\bASA\s*55\d\d", "ASA5500X"),
+    (r"ASAv\b|Adaptive\s+Security\s+Virtual", "ASAV"),
+    (r"(?:Firepower|Secure\s+Firewall)\s*1[01]\d\d", "FPR1000"),
+    (r"(?:Firepower|Secure\s+Firewall)\s*21\d\d", "FPR2100"),
+    (r"(?:Firepower|Secure\s+Firewall)\s*31\d\d", "FWL3100"),
+    (r"(?:Firepower|Secure\s+Firewall)\s*41\d\d", "FPR4100"),
+    (r"(?:Firepower|Secure\s+Firewall)\s*9\d{3}", "FPR9000"),
+    # Virtual appliances carry no model number, so this must sit after the numbered rules.
+    (r"VMware|Virtual|\bFTDv\b|\bNGFWv\b", "FPRNGFW"),
+)
+
+# The two catalogue endpoints disagree on some display names: /platforms calls FPRNGFW
+# "Cisco Firepower NGFW Virtual" while /OS_version/OS_data calls the same platform "Cisco
+# Secure Firewall Threat Defense Virtual" (research Decision 5). This set reconciles known
+# mismatches. It is an optimisation that reduces false NEEDS_REVIEW — never a correctness
+# dependency, because an unreconcilable name fails closed in `platform_confirmed`.
+_ALIAS_NAME_EQUIVALENTS = {
+    "FPRNGFW": (
+        "Cisco Firepower NGFW Virtual",
+        "Cisco Secure Firewall Threat Defense Virtual",
+    ),
+}
+
+
+def family_takes_platform(family):
+    """True when Cisco accepts a platformAlias for this product family."""
+    return str(family or "").strip().lower() in PLATFORM_FAMILIES
+
+
+def family_supported(family):
+    """True when this mode can query Cisco about the family at all."""
+    return str(family or "").strip().lower() in SUPPORTED_FAMILIES
+
+
+def platform_alias_for(model, family):
+    """Map an inventory model to a Cisco platform alias.
+
+    Returns the alias, or None when the model matches no known series. Callers must treat
+    None as "unidentified model" (never as "no platform needed"); use
+    `family_takes_platform` to decide whether a platform is required at all.
+
+    Family-aware: the same 5500-X hardware is ASA5500X under ASA software and ASA5500
+    under FTD software, which is how Cisco's own catalogues name them.
+    """
+    text = str(model or "").strip()
+    if not text:
+        return None
+    fam = str(family or "").strip().lower()
+    for pattern, alias in _ALIAS_RULES:
+        if re.search(pattern, text, re.IGNORECASE):
+            if alias == "ASA5500X" and fam == "ftd":
+                return "ASA5500"
+            return alias
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# Catalogues (fetched from Cisco each run; indexed here)
+# --------------------------------------------------------------------------- #
+def index_platforms(rows):
+    """Index /platforms rows into {platformAlias: display name}."""
+    out = {}
+    for row in rows or []:
+        alias = (row.get("platformAlias") or "").strip()
+        if alias:
+            out[alias] = (row.get("name") or "").strip()
+    return out
+
+
+def index_releases(rows):
+    """Index /OS_version/OS_data rows into {release: set(platform names)}.
+
+    A release Cisco knows is always a key, even when it has no platform names — FMC rows
+    carry no `platform_name` field at all, so the empty set is the correct answer there
+    rather than a missing key or a crash.
+    """
+    out = {}
+    for row in rows or []:
+        release = (row.get("nos_version") or "").strip()
+        if not release:
+            continue
+        names = out.setdefault(release, set())
+        platform = (row.get("platform_name") or "").strip()
+        if platform:
+            names.add(platform)
+    return out
+
+
+class Catalogues:
+    """Per-run platform and release catalogues, keyed by family. Never persisted."""
+
+    def __init__(self):
+        self.platforms = {}   # {os_type: {alias: display name}}
+        self.releases = {}    # {os_type: {release: set(platform names)}}
+
+    def add_platforms(self, os_type, rows):
+        self.platforms[os_type] = index_platforms(rows)
+
+    def add_releases(self, os_type, rows):
+        self.releases[os_type] = index_releases(rows)
+
+    def known_alias(self, os_type, alias):
+        """True when Cisco currently offers this alias for this family.
+
+        A locally-mapped alias Cisco does not list means the model is unusable for a
+        query — e.g. the Secure Firewall 4200 series, which appears in the release
+        catalogue but has no alias yet (research Decision 9).
+        """
+        return alias in self.platforms.get(os_type, {})
+
+    def release_known(self, os_type, release):
+        return release in self.releases.get(os_type, {})
+
+    def release_platforms(self, os_type, release):
+        """Platform display names Cisco lists for a release (empty set if none)."""
+        return self.releases.get(os_type, {}).get(release, set())
+
+    def platform_confirmed(self, os_type, release, alias):
+        """True only when the release is *definitely* listed for the alias's platform.
+
+        Fails closed: if the alias cannot be reconciled to any name in the release
+        catalogue, this returns False and the caller records NEEDS_REVIEW rather than
+        falling through to NOT_IMPACTED.
+        """
+        listed = self.release_platforms(os_type, release)
+        if not listed:
+            return False
+        candidates = set(_ALIAS_NAME_EQUIVALENTS.get(alias, ()))
+        name = self.platforms.get(os_type, {}).get(alias)
+        if name:
+            candidates.add(name)
+        if not candidates:
+            return False
+        return bool(candidates & listed)
+
+
+# --------------------------------------------------------------------------- #
+# Reasons
+# --------------------------------------------------------------------------- #
+class Reason:
+    """Why a device could not be assessed. Attached to every NEEDS_REVIEW verdict."""
+
+    __slots__ = ("kind", "detail")
+
+    def __init__(self, kind, **detail):
+        self.kind = kind
+        self.detail = detail
+
+    def __eq__(self, other):
+        return (isinstance(other, Reason)
+                and self.kind == other.kind and self.detail == other.detail)
+
+    def __repr__(self):  # pragma: no cover - debugging aid
+        return f"Reason({self.kind!r}, {self.detail!r})"
+
+
+# --------------------------------------------------------------------------- #
+# Device resolution (outcome table rows 1-3, resolved locally, no request)
+# --------------------------------------------------------------------------- #
+def resolve_device(device, catalogues, validate_alias=True):
+    """Resolve a device to the Cisco query it needs, or to a local NEEDS_REVIEW reason.
+
+    Returns (check, reason) with exactly one of the two set. `check` is the
+    (os_type, platform_alias, release) tuple identifying the question to ask.
+
+    `validate_alias=False` skips the check that Cisco currently lists the mapped alias.
+    Only the offline dry run uses that, because it has no catalogues to validate against;
+    a real run always validates, so a platform Cisco has not aliased yet cannot silently
+    become a query.
+    """
+    family = str(device.get("family") or "").strip()
+    model = str(device.get("model") or "").strip()
+    release = normalize_release(device.get("version"))
+
+    # Row 1 - a required field is blank.
+    if not release:
+        return None, Reason(FIELD_MISSING, field="software release")
+    if not model and family_takes_platform(family):
+        return None, Reason(FIELD_MISSING, field="model")
+
+    # Row 2 - a family this mode cannot query.
+    if not family_supported(family):
+        return None, Reason(FAMILY_UNSUPPORTED, family=family or "(blank)")
+
+    os_type = family.lower()
+
+    # Row 3 - the model maps to no alias, or to one Cisco does not list.
+    if family_takes_platform(os_type):
+        alias = platform_alias_for(model, os_type)
+        unknown = alias is None or (validate_alias
+                                    and not catalogues.known_alias(os_type, alias))
+        if unknown:
+            return None, Reason(MODEL_UNMAPPED, model=model or "(blank)")
+    else:
+        alias = None
+
+    return (os_type, alias, release), None
+
+
+# --------------------------------------------------------------------------- #
+# Verdict derivation (outcome table rows 4-10)
+# --------------------------------------------------------------------------- #
+def verdict_from_outcome(check, catalogues, outcome, advisories=None, raw_release=None):
+    """Derive a verdict from a classified API outcome. Returns (verdict, reason).
+
+    `raw_release` is the release exactly as the inventory recorded it. It is carried into
+    the reason so a reader can see both what they wrote and what was asked for — the
+    difference is usually what tells them which field to correct.
+    """
+    os_type, alias, release = check
+    raw = raw_release if raw_release not in (None, "") else release
+
+    # Row 4 - Cisco returned advisories for this release on this platform.
+    if outcome == HAS_ADVISORIES and advisories:
+        return IMPACTED, None
+
+    # Row 5 - Cisco does not hold this release string at all.
+    if outcome == INVALID_VERSION:
+        return NEEDS_REVIEW, Reason(RELEASE_UNKNOWN, release=release, raw_release=raw)
+
+    if outcome == NO_DATA:
+        # Row 6 - "nothing found", but the release is absent from the catalogue: the
+        # negative says nothing about this device.
+        if not catalogues.release_known(os_type, release):
+            return NEEDS_REVIEW, Reason(RELEASE_UNKNOWN, release=release, raw_release=raw)
+        # Row 7 - release is real but Cisco does not list it for this platform.
+        if alias is not None and not catalogues.platform_confirmed(os_type, release, alias):
+            listed = sorted(catalogues.release_platforms(os_type, release))
+            return NEEDS_REVIEW, Reason(RELEASE_NOT_ON_PLATFORM,
+                                        release=release, platforms=listed)
+        # Row 8 - the only path to NOT_IMPACTED. Release and platform both confirmed.
+        return NOT_IMPACTED, None
+
+    # Rows 9 and 10 - auth/quota/transport failure, an unparseable body, or anything the
+    # classifier did not recognise. Never a verdict.
+    return NEEDS_REVIEW, Reason(CHECK_INCOMPLETE)
+
+
+def build_checks(devices, catalogues, validate_alias=True):
+    """Collapse devices into the distinct questions Cisco needs to be asked.
+
+    Returns (checks, unresolved) where `checks` is an ordered {check tuple: [device, ...]}
+    mapping and `unresolved` is [(device, reason), ...] for devices that never reach the
+    API. Deduplication is what makes the feature viable: the team's real 70-row inventory
+    collapses to 27 checks, so identical devices cost one request between them (FR-020).
+    """
+    checks = {}
+    unresolved = []
+    for device in devices:
+        check, reason = resolve_device(device, catalogues, validate_alias=validate_alias)
+        if reason is not None:
+            unresolved.append((device, reason))
+            continue
+        checks.setdefault(check, []).append(device)
+    return checks, unresolved
+
+
+def classify(device, catalogues, outcome=None, advisories=None):
+    """Full outcome table for one device. Returns (verdict, reason).
+
+    Rows 1-3 resolve locally (no request needed); rows 4-10 need `outcome`. A device that
+    resolves to a check but has no outcome yet is CHECK_INCOMPLETE, which is what makes a
+    partially-completed run safe.
+    """
+    check, reason = resolve_device(device, catalogues)
+    if reason is not None:
+        return NEEDS_REVIEW, reason
+    if outcome is None:
+        return NEEDS_REVIEW, Reason(CHECK_INCOMPLETE)
+    return verdict_from_outcome(check, catalogues, outcome, advisories,
+                                raw_release=device.get("version"))
diff --git a/cisco_advisory_impact_agent/psirt.py b/cisco_advisory_impact_agent/psirt.py
new file mode 100644
index 0000000..4a63fe4
--- /dev/null
+++ b/cisco_advisory_impact_agent/psirt.py
@@ -0,0 +1,281 @@
+"""Cisco PSIRT openVuln API access for the inventory-driven check (`--api`).
+
+The only module that talks to Cisco's advisory API — the counterpart of `cisco.py`
+(ERP/CSAF) and `fuelix.py` (AI). Standard library only.
+
+Two behaviours here are load-bearing and were established against the live API rather
+than from its documentation (see contracts/psirt-access.md):
+
+* Outcomes are classified from the HTTP status and `errorCode`, never from message text.
+  The published reference describes a single 200 conflating "no advisories affect this
+  release" with "version not found"; the live API separates them by status code. Both
+  shapes are handled, so the classifier survives Cisco reverting to the documented form.
+* Nothing sent to Cisco identifies a device. Only the derived product family, platform
+  alias and release go over the wire — never a firewall name (Constitution, Networking).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from cisco_advisory_impact_agent.matching import (
+    HAS_ADVISORIES,
+    INCOMPLETE,
+    INVALID_VERSION,
+    NO_DATA,
+    family_takes_platform,
+)
+
+TOKEN_URL = "https://id.cisco.com/oauth2/default/v1/token"
+API_BASE = "https://apix.cisco.com/security/advisories/v2"
+
+# Published quota is 5/second, 30/minute, 5000/day. The per-minute limit binds, so pace at
+# one request per ~2.1s (research Decision 10). Bursting to the per-second ceiling would
+# exhaust the minute budget in six seconds and then stall.
+MIN_INTERVAL = 2.1
+
+DEFAULT_TIMEOUT = 45
+
+
+class PsirtError(Exception):
+    """Base class. Messages never contain any part of a credential."""
+
+
+class PsirtAuthError(PsirtError):
+    """Cisco rejected the credentials. Distinct from unreachable — see FR-042/FR-043."""
+
+
+class PsirtUnreachableError(PsirtError):
+    """Cisco could not be reached at all (DNS, TCP, TLS, proxy, timeout)."""
+
+
+# --------------------------------------------------------------------------- #
+# Token
+# --------------------------------------------------------------------------- #
+def fetch_token(client_id, client_secret, timeout=30, opener=None):
+    """Exchange client credentials for a bearer token.
+
+    Raises PsirtAuthError when Cisco rejects them and PsirtUnreachableError when Cisco
+    cannot be reached. Keeping those apart is what lets `--config` avoid telling a user
+    behind a proxy outage that their correct credentials are invalid.
+    """
+    body = urllib.parse.urlencode({
+        "client_id": client_id,
+        "client_secret": client_secret,
+        "grant_type": "client_credentials",
+    }).encode("ascii")
+    request = urllib.request.Request(
+        TOKEN_URL, data=body,
+        headers={"Content-Type": "application/x-www-form-urlencoded",
+                 "Accept": "application/json"},
+    )
+    open_url = opener or urllib.request.urlopen
+    try:
+        with open_url(request, timeout=timeout) as response:
+            payload = json.loads(response.read().decode("utf-8", "replace"))
+    except urllib.error.HTTPError as exc:
+        raise PsirtAuthError(_auth_error_detail(exc)) from None
+    except Exception as exc:  # noqa: BLE001 - URLError, socket.timeout, ssl, proxy errors
+        raise PsirtUnreachableError(_unreachable_detail(exc)) from None
+
+    token = (payload or {}).get("access_token")
+    if not token:
+        raise PsirtAuthError("Cisco did not return an access token.")
+    return token
+
+
+def _auth_error_detail(exc):
+    """Cisco's own reason for a rejection, with no request parameters echoed back.
+
+    Token endpoints commonly reflect submitted values in error bodies, so only the two
+    known-safe description fields are surfaced (FR-049).
+    """
+    reason = ""
+    try:
+        payload = json.loads(exc.read().decode("utf-8", "replace"))
+        if isinstance(payload, dict):
+            reason = str(payload.get("error_description")
+                         or payload.get("errorMessage")
+                         or payload.get("error") or "").strip()
+    except Exception:  # noqa: BLE001 - a non-JSON or unreadable body is fine
+        reason = ""
+    code = getattr(exc, "code", "?")
+    return f"Cisco rejected the credentials (HTTP {code}){': ' + reason if reason else '.'}"
+
+
+def _unreachable_detail(exc):
+    return (f"Cisco could not be reached ({type(exc).__name__}). "
+            "This is a connectivity problem, not a credential problem.")
+
+
+# --------------------------------------------------------------------------- #
+# Client
+# --------------------------------------------------------------------------- #
+class Client:
+    """Paced, authenticated access to the three endpoints this feature needs.
+
+    One token per run, re-fetched at most once if it is rejected mid-run (a long run can
+    outlive the one-hour token). `sleep`/`clock` are injectable so tests can assert the
+    pacing without waiting.
+    """
+
+    def __init__(self, client_id, client_secret, min_interval=MIN_INTERVAL,
+                 timeout=DEFAULT_TIMEOUT, opener=None, sleep=None, clock=None):
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._min_interval = min_interval
+        self._timeout = timeout
+        self._opener = opener or urllib.request.urlopen
+        self._sleep = sleep or time.sleep
+        self._clock = clock or time.monotonic
+        self._token = None
+        self._last_request_at = None
+        self._reauth_used = False
+        self.request_count = 0
+
+    # -- internals -------------------------------------------------------- #
+    def _ensure_token(self):
+        if self._token is None:
+            self._token = fetch_token(self._client_id, self._client_secret,
+                                      timeout=self._timeout, opener=self._opener)
+        return self._token
+
+    def _pace(self):
+        """Hold to the per-minute quota before issuing a request."""
+        if self._last_request_at is not None:
+            elapsed = self._clock() - self._last_request_at
+            remaining = self._min_interval - elapsed
+            if remaining > 0:
+                self._sleep(remaining)
+        self._last_request_at = self._clock()
+
+    def _raw_get(self, path, params):
+        url = f"{API_BASE}{path}"
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        request = urllib.request.Request(
+            url, headers={"Authorization": f"Bearer {self._ensure_token()}",
+                          "Accept": "application/json"})
+        self._pace()
+        self.request_count += 1
+        with self._opener(request, timeout=self._timeout) as response:
+            status = getattr(response, "status", None) or response.getcode()
+            return status, response.read().decode("utf-8", "replace")
+
+    def _get(self, path, params):
+        """Return (status, payload). Retries once with a fresh token on a 401/403."""
+        for attempt in (1, 2):
+            try:
+                status, text = self._raw_get(path, params)
+            except urllib.error.HTTPError as exc:
+                status = getattr(exc, "code", 0)
+                if status in (401, 403) and attempt == 1 and not self._reauth_used:
+                    # The token may simply have aged out during a long run.
+                    self._reauth_used = True
+                    self._token = None
+                    continue
+                try:
+                    text = exc.read().decode("utf-8", "replace")
+                except Exception:  # noqa: BLE001
+                    text = ""
+            except PsirtError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - URLError, timeout, ssl
+                raise PsirtUnreachableError(_unreachable_detail(exc)) from None
+
+            try:
+                payload = json.loads(text) if text.strip() else {}
+            except ValueError:
+                payload = None  # unparseable -> caller classifies as INCOMPLETE
+            return status, payload
+        raise PsirtUnreachableError("Cisco could not be reached.")  # pragma: no cover
+
+    # -- catalogues ------------------------------------------------------- #
+    def get_platforms(self, os_type):
+        """Platform aliases Cisco currently offers for a family.
+
+        Returns [] for families that take no platform, so callers need no special case.
+        """
+        if not family_takes_platform(os_type):
+            return []
+        status, payload = self._get("/platforms", {"OSType": os_type})
+        if status in (401, 403):
+            raise PsirtAuthError("Cisco rejected the access token.")
+        if status != 200:
+            raise PsirtUnreachableError(
+                f"Cisco returned HTTP {status} for the platform catalogue of {os_type}.")
+        return _rows(payload, "platforms")
+
+    def get_os_data(self, os_type):
+        """Releases Cisco recognises, with the platforms each runs on."""
+        status, payload = self._get("/OS_version/OS_data", {"OSType": os_type})
+        if status in (401, 403):
+            raise PsirtAuthError("Cisco rejected the access token.")
+        if status != 200:
+            raise PsirtUnreachableError(
+                f"Cisco returned HTTP {status} for the release catalogue of {os_type}.")
+        return _rows(payload, "OSData")
+
+    # -- the advisory question -------------------------------------------- #
+    def get_advisories(self, os_type, release, platform_alias=None):
+        """Ask Cisco which advisories apply. Returns (outcome, advisories).
+
+        `platform_alias` is omitted from the query for families that do not accept one
+        (research Decision 8) — sending it would be rejected.
+        """
+        params = {"version": release}
+        if platform_alias and family_takes_platform(os_type):
+            params["platformAlias"] = platform_alias
+        status, payload = self._get(f"/OSType/{os_type}", params)
+        return classify_response(status, payload)
+
+
+def _rows(payload, wrapper_key):
+    """Accept a bare JSON list (what the API returns today) or a wrapped object."""
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, dict):
+        value = payload.get(wrapper_key)
+        if isinstance(value, list):
+            return value
+    return []
+
+
+def classify_response(status, payload):
+    """Map an HTTP status and body to (outcome, advisories).
+
+    Classification keys on the status code and `errorCode` only — never on message text,
+    which Cisco is free to reword.
+    """
+    body = payload if isinstance(payload, dict) else {}
+    error_code = str(body.get("errorCode") or "").upper()
+
+    if status == 200:
+        advisories = body.get("advisories")
+        if isinstance(advisories, list) and advisories:
+            return HAS_ADVISORIES, advisories
+        # Defensive: the published reference describes a 200 whose errorCode conflates
+        # "no advisories" with "version not found" (NO_IOS_AFFECTING_ADVISORIES_FOUND;
+        # INVALID_IOS_VERSION). Honour that shape if Cisco ever reverts to it.
+        if "INVALID" in error_code:
+            return INVALID_VERSION, []
+        if error_code or isinstance(advisories, list):
+            return NO_DATA, []
+        # A 200 carrying neither advisories nor an errorCode is a shape we do not know.
+        return INCOMPLETE, []
+
+    if status == 404:
+        if error_code == "NO_DATA_FOUND":
+            return NO_DATA, []
+        # e.g. VERSION_ID_IS_MANDATORY or an advisory id that does not exist.
+        return INCOMPLETE, []
+
+    if status == 406 and "INVALID" in error_code and "VERSION" in error_code:
+        return INVALID_VERSION, []
+
+    # 429 (quota), 5xx, and anything unrecognised are never a verdict.
+    return INCOMPLETE, []
diff --git a/cisco_advisory_impact_agent/ui.py b/cisco_advisory_impact_agent/ui.py
index 5080be2..0868fff 100644
--- a/cisco_advisory_impact_agent/ui.py
+++ b/cisco_advisory_impact_agent/ui.py
@@ -296,3 +296,20 @@ def ask_secret(label):
         raise KeyboardInterrupt
     except Exception:  # noqa: BLE001 -- e.g. no controlling terminal
         return ask(label)
+
+
+def secret_captured(label, value):
+    """Confirm a hidden value was received, revealing only how long it was.
+
+    A hidden prompt shows nothing at all as you paste, so there is no way to tell a
+    complete paste from a truncated or failed one. Reporting the character count answers
+    exactly that question without disclosing any part of the value, and it works on every
+    terminal — unlike per-keystroke masking, which needs platform-specific raw terminal
+    handling (see spec 006 research Decision 13).
+    """
+    length = len(value or "")
+    if length:
+        plain(paint("✓", _FG["green"]) + "  " + f"{label} captured "
+              + dim(f"({length} characters)"))
+    else:
+        plain(dim(f"   {label} left unchanged."))
diff --git a/docs/index.html b/docs/index.html
index 42820e2..3399c21 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -241,11 +241,14 @@
   <section class="hero">
     <span class="eyebrow"><span class="dot"></span> TELUS Digital · Security Tooling</span>
     <h1>Cisco Advisory Impact Agent</h1>
-    <p class="tagline">Know which of your firewalls a Cisco advisory actually affects.</p>
+    <p class="tagline">Know which of your firewalls Cisco's advisories actually affect.</p>
     <p class="lede">
-      Paste a Cisco <b>Event Response (ERP)</b> link. The tool pulls every referenced
-      advisory, reads its official product data, and uses AI to tell you exactly which
-      ASA/FTD devices in <b>your</b> inventory are impacted — as a ready-to-share Excel report.
+      Ask it either way round. Paste a Cisco <b>Event Response (ERP)</b> link and it pulls
+      every referenced advisory, reads its official product data, and uses AI to tell you
+      which ASA/FTD devices in <b>your</b> inventory are impacted — as a ready-to-share Excel
+      report. Or run <code>--api</code> with no link at all and it checks your
+      <b>whole inventory</b> against Cisco's published data, device by device, into an HTML
+      report that names the release fixing each finding.
     </p>
     <div class="cta">
       <a class="btn btn-primary" href="#prereqs">
@@ -271,8 +274,8 @@ <h3>AI impact analysis</h3>
       </div>
       <div class="card">
         <svg class="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M6 2h9l5 5v15H6z"/><path d="M14 2v6h6"/><path d="M9 14h6M9 17h6"/></svg>
-        <h3>Excel report</h3>
-        <p>Outputs a timestamped spreadsheet listing impacted firewalls per advisory — ready to hand off.</p>
+        <h3>Two report formats</h3>
+        <p>A timestamped spreadsheet per advisory, or — with <code>--api</code> — an HTML report covering your whole fleet, with clickable advisories and the release that fixes each one.</p>
       </div>
     </div>
   </section>
@@ -283,9 +286,10 @@ <h2><span class="num">01</span>Before you start</h2>
       <ul class="check">
         <li><b>uv</b> — <span>Astral's Python tool installer; it manages Python for you. Not sure if you have it? <a href="#get-uv">Check &amp; install it below</a>.</span></li>
         <li><b>Git</b> — <span>uv uses it to fetch the tool from GitHub. Not sure if you have it? <a href="#get-uv">Check &amp; install it below</a>.</span></li>
-        <li><b>A FueliX API key</b> — <span>each person uses their own (see “Get your key” below).</span></li>
+        <li><b>A FueliX API key</b> — <span>for advisory mode; each person uses their own (see “Get your key” below).</span></li>
+        <li><b>Cisco PSIRT API credentials</b> — <span>for inventory mode (<code>--api</code>): a client ID and secret from <a href="https://developer.cisco.com/psirt/">developer.cisco.com/psirt</a>, one per person. You only need the credentials for the mode you use.</span></li>
         <li><b>Your firewall inventory</b> — <span>an Excel <code>.xlsx</code> (sheet <code>FW_List</code>) in the folder you run from.</span></li>
-        <li><b>Internet access</b> — <span>to <code>sec.cloudapps.cisco.com</code> and <code>api.fuelix.ai</code>.</span></li>
+        <li><b>Internet access</b> — <span>to <code>sec.cloudapps.cisco.com</code> and <code>api.fuelix.ai</code>, plus <code>apix.cisco.com</code> and <code>id.cisco.com</code> for <code>--api</code>.</span></li>
       </ul>
 
       <p class="osnote" id="get-uv"><b>Get uv &amp; Git</b> — both are needed before you install the tool. First check whether each is already installed, and install only what's missing. Pick your operating system:</p>
@@ -381,16 +385,30 @@ <h2><span class="num">02</span>Install &amp; run</h2>
           no cloning, no virtual environment to activate.
         </li>
         <li>
-          <b>Configure your API key</b> (stored once, per user; used from any folder):
+          <b>Configure your credentials</b> (stored once, per user; used from any folder):
           <pre>caia --config</pre>
+          One pass through everything, and every prompt is skippable — supply only the
+          credentials for the mode you use. The Cisco client secret is never displayed;
+          after you paste it the tool confirms how many characters it captured, then checks
+          the credentials against Cisco before saving.
         </li>
         <li>
-          <b>Run it</b> from the folder that holds your inventory <code>.xlsx</code>, then paste
-          your Cisco ERP link when prompted:
+          <b>Check your whole inventory</b> — no link needed. Cisco's own published data
+          decides, so there is no AI step:
           <pre>cd /path/to/your/inventory-folder</pre>
+          <pre>caia --api</pre>
+          The report <code>impact_report_&lt;date&gt;.html</code> appears in an <code>output</code>
+          folder. Every firewall gets one status — <b>Impacted</b> (with each advisory's
+          severity, CVEs, a link to Cisco and the release that fixes it), <b>Not impacted</b>,
+          or <b>Needs review</b>. A device that could not be checked is never reported as safe;
+          the report says why instead.
+        </li>
+        <li>
+          <b>Or check a single advisory</b> from the same folder, pasting your Cisco ERP link
+          when prompted:
           <pre>caia</pre>
-          The report <code>analysis_output_&lt;date&gt;.xlsx</code> appears in an <code>output</code>
-          folder inside that same folder.
+          The report <code>analysis_output_&lt;date&gt;.xlsx</code> appears in the same
+          <code>output</code> folder.
         </li>
         <li>
           <b>Stay up to date</b> — check your version and update via uv:
diff --git a/specs/006-api-inventory-check/checklists/requirements.md b/specs/006-api-inventory-check/checklists/requirements.md
new file mode 100644
index 0000000..e254791
--- /dev/null
+++ b/specs/006-api-inventory-check/checklists/requirements.md
@@ -0,0 +1,54 @@
+# Specification Quality Checklist: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-07-25
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`
+
+### Validation record
+
+**Iteration 1** — three issues found and corrected before this checklist was marked complete:
+
+1. **Implementation detail leaked into requirements.** The first draft named HTTP status codes and the specific Cisco endpoint paths when describing how an unrecognised release is told apart from one that never shipped on a model. Rewritten as observable outcomes (FR-011, FR-012, FR-019) with the mechanism deferred to `/speckit-plan`.
+2. **Two success criteria were not measurable.** "The report is easy to act on" and "credentials are handled safely" were replaced with SC-005/SC-006 (every Impacted device lists an advisory with a working link and a fixed release) and SC-011 (no credential value in any output across successful, failed and interrupted runs).
+3. **`--api` interaction with existing flags was unspecified.** Added FR-003 (mutual exclusion with the advisory-driven mode) and FR-004 (existing inventory and output options honoured) after noticing US1 had no scenario for conflicting invocation; scenario 10 was added to US1 to cover it.
+
+**Zero `[NEEDS CLARIFICATION]` markers.** Every open question carried by BRD-003 was resolvable from the BRD's own resolutions, the project constitution, or a documented reasonable default. Each default is recorded in the spec's Assumptions section so it can be challenged. The two most consequential:
+
+- **No release substitution and no platform-agnostic fallback** (FR-013). The project's non-negotiable conservative-analysis principle supplies the default: asking Cisco about a release or platform the device does not actually have, then reporting that answer as the device's verdict, is a guess. Devices in that situation are Needs review. This is the single decision most likely to be revisited, because it produces Needs review rows for end-of-support releases Cisco has purged from its catalogue.
+- **Coverage limited to ASA, FTD and FMC first**, with any other family becoming Needs review rather than failing the run.
+
+### Items carried to `/speckit-plan`
+
+Neither blocks specification approval; both are governance work the planning phase must record:
+
+- **New external endpoints.** The mode contacts Cisco authentication and advisory hosts the analyzer does not contact today. The constitution's Technology & Data Constraints treat any additional endpoint as a reviewed change, so it needs a recorded amendment.
+- **Verdict vocabulary.** This mode uses `Needs review`; the existing mode's report and the constitution's Principle IV use `Indeterminate` for the same conservative posture. Either align the labels or record the divergence deliberately.
diff --git a/specs/006-api-inventory-check/contracts/api-run-cli.md b/specs/006-api-inventory-check/contracts/api-run-cli.md
new file mode 100644
index 0000000..6d3940c
--- /dev/null
+++ b/specs/006-api-inventory-check/contracts/api-run-cli.md
@@ -0,0 +1,118 @@
+# CLI Contract: `caia --api`
+
+## Invocation
+
+```bash
+caia --api
+caia --api --inventory PATH --sheet NAME --output-dir DIR
+caia --api --dry-run
+```
+
+`--api` selects the inventory-driven mode. It takes no argument and requires no URL.
+
+### Mode precedence
+
+Existing lifecycle flags keep their current precedence and are unaffected:
+`--version` → `--update` → `--uninstall` → `--config` → run. `--api` is a modifier of the
+*run* mode, evaluated only when no lifecycle flag is present.
+
+### Mutual exclusion
+
+`--api` and the advisory-driven mode are mutually exclusive (FR-003). Supplying `--api`
+together with `--url` is refused before any network access:
+
+- message names both flags and states that the two modes answer different questions
+- no request is made to Cisco or to the AI service
+- exit non-zero
+
+`--api` with no `--url` never prompts for a URL. The advisory-driven mode's URL prompt is
+reached only when `--api` is absent.
+
+### Flags honoured in this mode
+
+| Flag | Behaviour |
+| --- | --- |
+| `--inventory PATH` | Same as today: use this file instead of discovering one |
+| `--sheet NAME` | Same as today |
+| `--output-dir DIR` | Report destination; default `./output` |
+| `--dry-run` | Resolve every device to the check that would be made and report it; contact Cisco not at all; write no report (FR-006) |
+| `--no-update-check` | Unchanged |
+
+A fully flag-driven `caia --api --inventory ... --output-dir ...` run requires no interactive
+input (FR-004, Principle III).
+
+`--keep-temp` / `--no-keep-temp` have no effect in this mode — it downloads no advisory files.
+
+## Preconditions, in order
+
+Checked before any request to Cisco:
+
+1. **Mutual exclusion** — `--api` with `--url` → refuse, exit non-zero.
+2. **Credentials** — client identifier and client secret both resolvable (environment, then
+   per-user config; empty or whitespace-only counts as absent). Missing → name which one is
+   missing, direct the user to `caia --config`, make no request, exit non-zero (FR-047, FR-048).
+   The AI service key is **not** required and is not consulted (FR-005).
+3. **Inventory** — discovered or supplied, loadable, and containing at least one usable row.
+   Otherwise an actionable message, exit non-zero (FR-055).
+4. **Output folder** — creatable and writable. Otherwise report the attempted path, exit
+   non-zero (FR-054).
+
+## Run sequence
+
+1. Acquire an access token. Rejected credentials → report an authentication problem, distinct
+   in wording from "no advisories apply", produce no verdicts and no report, exit non-zero
+   (FR-014).
+2. Fetch the platform catalogue and release catalogue for each family present in the
+   inventory (Decision 11).
+3. Collapse devices to distinct checks (FR-020).
+4. Ask Cisco once per check, paced within quota (FR-050), reporting progress (FR-051).
+5. Derive each device's verdict from the outcome table in `data-model.md`.
+6. Write one timestamped report and print its path.
+
+## Progress output
+
+Progress must make a multi-minute run legible (FR-051): the number of devices loaded, the
+number of distinct checks to perform, and advancement through those checks. It must never
+include a credential value or any fragment of one (FR-049).
+
+## Outcomes and exit codes
+
+| Outcome | Report | Exit |
+| --- | --- | --- |
+| Completed — any mix of verdicts, including every device Needs review | written | 0 |
+| Completed partially — Cisco unreachable or quota reached mid-run; remaining devices Needs review, summary flagged partial | written | 0 |
+| `--dry-run` completed | none | 0 |
+| `--api` with `--url` | none | non-zero |
+| Credentials missing | none | non-zero |
+| Credentials rejected | none | non-zero |
+| Inventory unusable or empty | none | non-zero |
+| Output folder unwritable | none | non-zero |
+| Interrupted by operator | none | 130 |
+
+A run that produced a report is a success even when nothing could be determined (FR-053) —
+the exit status reports whether the run completed, not what the verdicts were.
+
+## Invariants (every outcome)
+
+- No credential value appears in printed output, in the report, in an error message, or in a
+  filename (FR-049).
+- No existing report is modified or overwritten (FR-023).
+- The inventory file is never written to.
+- No call is made to the AI service (FR-005).
+- Running without `--api` produces exactly what it did before this feature existed (FR-002, SC-020).
+
+## Test-observable assertions
+
+| Assertion | Maps to |
+| --- | --- |
+| `--api --url ...` exits non-zero with no network access | FR-003, US1 §10 |
+| Missing client secret → non-zero, message names it and `--config`, zero requests | FR-048, US4 §13 |
+| Missing AI key with valid Cisco credentials → run proceeds | FR-005, FR-036, US4 §12 |
+| Report path printed and file exists after a successful run | FR-022, US1 §1 |
+| Row count in report equals usable row count in inventory | FR-007, SC-002, US1 §2 |
+| Two runs in the same second produce two files | FR-023, US1 §7 |
+| N devices sharing a check produce exactly one request | FR-020, SC-008, US1 §8 |
+| Every-device-Needs-review run still exits 0 with a report | FR-053 |
+| Cisco unreachable mid-run → report written, partial flag set, exit 0 | FR-016, SC-019 |
+| `SIGINT` during checks → exit 130, no report | FR-052 |
+| `--dry-run` makes zero requests and writes no report | FR-006 |
diff --git a/specs/006-api-inventory-check/contracts/config-cli.md b/specs/006-api-inventory-check/contracts/config-cli.md
new file mode 100644
index 0000000..4423ac8
--- /dev/null
+++ b/specs/006-api-inventory-check/contracts/config-cli.md
@@ -0,0 +1,96 @@
+# CLI Contract: `caia --config` (extended for Cisco credentials)
+
+## What changes
+
+`caia --config` keeps its single linear pass and gains two prompts. It also loses one
+behaviour: the AI service key is no longer mandatory, because a user of `--api` only never
+needs one (FR-035, FR-036).
+
+| Setting | Prompt style | Before | After |
+| --- | --- | --- | --- |
+| AI service key | hidden | prompted; **empty rejected in a retry loop** | prompted; **empty allowed** (skip) |
+| AI model | menu | prompted | unchanged |
+| Cisco client identifier | **visible** | — | prompted |
+| Cisco client secret | hidden + length confirmation | — | prompted |
+| AI base URL | not prompted | preserved | unchanged |
+
+The change to the AI key prompt is a deliberate behaviour change, not an oversight: the
+current implementation loops until a non-empty value is supplied, which would force a
+`--api`-only user to invent one.
+
+## Prompt sequence and rules
+
+1. **AI service key** — hidden. Empty submission skips it. If a value is already saved, say so
+   and treat empty as "keep".
+2. **AI model** — existing curated menu, unchanged.
+3. **Cisco client identifier** — **displayed as entered** (FR-037). It names the calling
+   application and is not a secret; showing it lets the user confirm a paste landed. Empty
+   skips; empty when a value exists keeps it (FR-040).
+4. **Cisco client secret** — **not displayed in readable form** (FR-037). Immediately after
+   entry, confirm that a value was captured and how many characters it held, without revealing
+   any part of it (FR-038). Empty skips; empty when a value exists keeps it (FR-040).
+
+Every prompt is skippable. Completing the flow having supplied nothing is valid and changes
+nothing (FR-035).
+
+Per-keystroke masking is **not** implemented in this feature; the non-echoing prompt is
+FR-039's documented fallback. See research Decision 13 for why.
+
+## Verification
+
+Attempted only when **both** Cisco values are available for the session — whether newly
+entered or kept from storage. If either is absent, no request is made to Cisco (FR-044).
+
+Three distinct outcomes (FR-041, FR-042, FR-043):
+
+| Outcome | Message intent | Saved? |
+| --- | --- | --- |
+| **Accepted** | State plainly that the credentials are valid | yes |
+| **Rejected** | Surface the reason Cisco gave; offer to enter them again | not without re-entry or explicit choice |
+| **Unreachable** | State that Cisco could not be reached — explicitly *not* the same as invalid; offer to save unverified with a warning | yes, if the user chooses |
+
+Distinguishing rejection from unreachability is load-bearing. Collapsing them would present a
+proxy outage or blocked egress as "your credentials are invalid", leaving a user holding
+correct credentials with no way to finish setup. The run itself re-validates (FR-014), so
+saving unverified is safe.
+
+A non-interactive session cannot answer a re-entry prompt; there, a rejection reports and
+exits non-zero rather than looping.
+
+## Storage
+
+Saved to the existing per-user configuration file, alongside the AI settings, written with the
+same owner-only permissions and the same atomic replace the file already uses (FR-045).
+Location is unchanged and remains outside any working folder.
+
+Resolution order for every setting stays as it is today: environment variable, then config
+file, then built-in default (FR-046). `caia --config` remains the documented and expected path
+for a person; the environment remains available for automation.
+
+## Invariants
+
+- No part of any credential value is displayed, logged, or written anywhere but the config file
+  — including in verification success, failure, and warning messages (FR-049, FR-028 of the
+  BRD lineage, Principle V).
+- Cisco's error text is surfaced without echoing request parameters, since token endpoints
+  commonly reflect input back in error bodies.
+- Empty or whitespace-only input is treated as "not supplied", never sent to Cisco (FR-047).
+- The config file remains hand-editable, and its comment header is updated to mention the new
+  keys and that environment variables override them.
+- Declining or skipping everything leaves the existing file byte-identical.
+
+## Test-observable assertions
+
+| Assertion | Maps to |
+| --- | --- |
+| Both Cisco prompts appear in the flow | FR-034, US4 §1 |
+| Identifier prompt echoes; secret prompt does not | FR-037, US4 §2 |
+| After secret entry, a confirmation states the captured length and contains no fragment of the value | FR-038, SC-017, US4 §3 |
+| Empty submission with a saved value leaves it unchanged | FR-040, US4 §4 |
+| Valid credentials → explicit "valid" message | FR-041, US4 §5 |
+| Rejected credentials → Cisco's reason shown, re-entry offered, values not silently saved | FR-042, US4 §6 |
+| Unreachable Cisco → distinct message, save-unverified offered | FR-043, SC-016, US4 §7 |
+| Skipped Cisco prompts → zero requests to Cisco | FR-044, US4 §8 |
+| Empty AI key accepted; flow completes; advisory-driven mode still usable | FR-035, FR-036, US4 §11 |
+| Saved file permissions match the existing config file's | FR-045, Principle V |
+| No credential fragment in any emitted message across all three outcomes | FR-049, SC-011 |
diff --git a/specs/006-api-inventory-check/contracts/html-report.md b/specs/006-api-inventory-check/contracts/html-report.md
new file mode 100644
index 0000000..d064f86
--- /dev/null
+++ b/specs/006-api-inventory-check/contracts/html-report.md
@@ -0,0 +1,128 @@
+# Output Contract: the `--api` HTML report
+
+## File
+
+| Property | Value |
+| --- | --- |
+| Location | `<output-dir>/` — default `./output` in the working folder |
+| Name | `impact_report_<YYYYMMDD_HHMMSS>.html` |
+| Collision | Append `_1`, `_2`, … so an existing report is never overwritten (FR-023) |
+| Composition | **One file.** All CSS and JavaScript inlined; no external reference of any kind |
+
+The naming and collision behaviour deliberately mirror the existing
+`analysis_output_<timestamp>.xlsx` convention, and the distinct prefix makes the two modes'
+outputs sort separately in the same folder.
+
+## Why single-file is a requirement, not a preference
+
+FR-030 requires the report to work after being emailed and when opened with no network. That
+rules out any CDN-hosted stylesheet or table-sort library: those break offline, break behind a
+restrictive corporate proxy, and rot when the CDN moves. Inlining also keeps Principle I
+satisfied — the report needs no dependency beyond the standard library to produce.
+
+## Structure
+
+### 1. Run summary (top of document)
+
+| Element | Requirement |
+| --- | --- |
+| Run date and time | FR-031 |
+| Inventory file used | FR-031 |
+| Devices assessed | FR-031 |
+| Count per verdict — Impacted / Not impacted / Needs review | FR-031, SC-018 |
+| Partial-run notice, when applicable, naming the cause | FR-016, SC-019 |
+
+### 2. Coverage statements (adjacent to the summary, not footnoted)
+
+Both are mandatory in every report (FR-032):
+
+- Cisco's data holds no advisories published before its per-family cut-off dates (January 2022
+  for ASA/FMC/FTD/FXOS), so an Impacted list is not exhaustive and a Not impacted verdict is
+  narrower than it appears.
+- A verdict reflects whether a release is *listed as affected*; it does not account for whether
+  the vulnerable feature is enabled on the device. Impacted means "listed as affected", not
+  "exploitable".
+
+These sit with the summary because a reader who receives the report second-hand must not have
+to hunt for them (US5).
+
+### 3. Device table
+
+One row per inventory row, exactly once (FR-024, SC-002). Columns:
+
+| Column | Source |
+| --- | --- |
+| The inventory's own columns | Reproduced verbatim, unmodified |
+| Verdict | Impacted / Not impacted / Needs review |
+| Detail | Advisories (Impacted) · reason (Needs review) · empty (Not impacted) |
+
+Requirements on the table:
+
+- Filter by verdict (FR-029)
+- Sort by the inventory's priority column (FR-029)
+- Expand/collapse a device's advisory detail; collapsed rows stay readable at a glance (FR-029, US3 §3)
+- The advisory list is never silently truncated — if it is long, it is collapsed, not cut (FR-025)
+- All of the above works from the file alone, offline (FR-029, FR-030)
+
+Verdicts are distinguishable without relying on colour alone, so the report survives being
+printed or read by someone with a colour-vision deficiency.
+
+### 4. Per-advisory detail
+
+| Field | Requirement |
+| --- | --- |
+| Advisory identifier, linked to `publicationUrl` | FR-026 |
+| Title | FR-026 |
+| Severity | FR-026 |
+| Release that first fixes it, when Cisco supplies one | FR-026 |
+| CVE identifiers | FR-027 (SHOULD) |
+
+The fixed release is the field an engineer acts on, so it is presented at least as prominently
+as severity — not buried in a tooltip.
+
+A missing fixed release is rendered as absent. It is never inferred.
+
+### 5. Per-device reason (Needs review only)
+
+Rendered from the reason kinds in `data-model.md`. The `release_not_on_platform` kind names the
+platforms Cisco does list for that release (FR-012). Every reason must be actionable without
+reference to the tool's internals (SC-004) — no bare HTTP status codes, no internal identifiers.
+
+## Escaping: the load-bearing guarantee
+
+Every value that originates from Cisco is escaped at the point of interpolation (FR-033).
+This includes advisory titles, severities, CVE lists, platform names, reason detail, and
+**especially** anything derived from an advisory `summary`.
+
+This is not defensive boilerplate. All 103 distinct advisories returned during the spike
+carried raw HTML in `summary` — including `<a>` anchors pointing wherever Cisco's CMS placed
+them. Interpolating that unescaped into a file an analyst then opens in a browser would render
+externally-authored markup inside a security tool's own output. Advisory summaries are either
+escaped or tag-stripped; they are never passed through as markup.
+
+The report's own inlined JavaScript must likewise not construct markup from Cisco-supplied
+strings.
+
+## Invariants
+
+- No credential value, or fragment of one, appears anywhere in the file or its name (FR-049).
+- No content requires a network fetch to render (FR-030).
+- The file is self-consistent: the summary's counts equal the table's rows per verdict.
+- An existing report is never modified or replaced (FR-023).
+
+## Test-observable assertions
+
+| Assertion | Maps to |
+| --- | --- |
+| File exists at the contracted name pattern after a run | FR-022 |
+| Second run in the same second produces a second file; first is byte-identical | FR-023, US1 §7 |
+| Row count equals usable inventory row count | FR-024, SC-002 |
+| Summary counts per verdict equal the table's rows per verdict | FR-031 |
+| Both coverage statements present in every generated report | FR-032, US5 §2–3 |
+| An advisory `summary` containing `<script>` or `<a>` renders as text, with no live element in the DOM | FR-033 |
+| No `http://` or `https://` reference to a stylesheet, script, or font in the file | FR-030 |
+| Every Impacted device has ≥1 advisory with a `publicationUrl` link | FR-025, SC-005 |
+| Every advisory with a Cisco-supplied fixed release displays it | FR-026, SC-006 |
+| Every Needs review device has non-empty reason text | FR-028, SC-004 |
+| A `release_not_on_platform` reason names at least one platform | FR-012, US2 §2 |
+| No credential value present in the file | FR-049, SC-011 |
diff --git a/specs/006-api-inventory-check/contracts/psirt-access.md b/specs/006-api-inventory-check/contracts/psirt-access.md
new file mode 100644
index 0000000..4931494
--- /dev/null
+++ b/specs/006-api-inventory-check/contracts/psirt-access.md
@@ -0,0 +1,143 @@
+# External Interface Contract: Cisco PSIRT openVuln API
+
+The contract the tool depends on. Every behaviour recorded here was observed against the live
+API during the feasibility spike; where it differs from Cisco's published documentation, that
+is called out, because the difference is what makes FR-009 implementable.
+
+## Hosts
+
+| Host | Purpose |
+| --- | --- |
+| `id.cisco.com` | Access-token issuance |
+| `apix.cisco.com` | Advisory data and catalogues |
+
+Both are **new** external endpoints for this tool. The constitution's Technology & Data
+Constraints require an amendment before implementation — see `plan.md` § Constitution Check.
+
+## Authentication
+
+```
+POST https://id.cisco.com/oauth2/default/v1/token
+Content-Type: application/x-www-form-urlencoded
+
+client_id=<id>&client_secret=<secret>&grant_type=client_credentials
+```
+
+Observed success response fields: `access_token`, `token_type` (`Bearer`), `expires_in`
+(`3600`), `scope` (`customscope`).
+
+Presented on every subsequent request as `Authorization: Bearer <access_token>`.
+
+One token per run; re-request once if a request fails authentication mid-run (research
+Decision 2).
+
+## Endpoint 1 — advisories for a release on a platform
+
+```
+GET https://apix.cisco.com/security/advisories/v2/OSType/{osType}?version=<release>[&platformAlias=<alias>]
+```
+
+`osType` ∈ `asa` · `ftd` · `fmc` · `fxos` · `ios` · `iosxe` · `nxos` · `aci`.
+`platformAlias` applies to `asa`, `ftd`, `fxos`, `nxos` only; it must be **omitted** for the
+others (Decision 8).
+
+### Responses
+
+| Status | Body | Interpretation |
+| --- | --- | --- |
+| `200` | `{ "advisories": [ … ] }` | Advisories apply → Impacted |
+| `404` | `{ "errorCode": "NO_DATA_FOUND", … }` | Query understood, nothing returned → **candidate** clean; requires catalogue confirmation |
+| `406` | `{ "errorCode": "INVALID_ASA_VERSION" \| "INVALID_FTD_VERSION" \| … }` | Release string not in Cisco's catalogue |
+| other | — | Undetermined |
+
+> **Documentation divergence.** Cisco's reference describes a single `200` response whose
+> `errorCode` conflates "no advisories affect this release" with "version not found"
+> (`NO_IOS_AFFECTING_ADVISORIES_FOUND; INVALID_IOS_VERSION`). The live API separates them by
+> status code, as verified with three ASA queries: `9.16.4.67` → `200` (24 advisories),
+> `9.18.4.22` → `404 NO_DATA_FOUND`, `9.12.4.67` → `406 INVALID_ASA_VERSION`. The tool relies
+> on the status code and `errorCode`, never on message text.
+
+### Advisory object fields consumed
+
+`advisoryId`, `advisoryTitle`, `sir`, `cvssBaseScore`, `cves`, `publicationUrl`, and
+`platforms[]` — each entry of which carries `id`, `name`, `vulnerabilityState`, and
+`firstFixes[]` of `{id, name}`.
+
+Observed guarantees across 561 advisory-platform pairs (103 distinct advisories): every
+platform entry had `vulnerabilityState == "vulnerable"`, every one carried a `firstFixes`
+entry, and the response was scoped to the queried platform only. A returned advisory therefore
+needs no client-side applicability filtering.
+
+`summary` **contains raw HTML** in every advisory observed (tags seen: `a`, `br`, `div`, `em`,
+`li`, `p`, `section`, `span`, `strong`). It is untrusted input; see the report contract.
+
+## Endpoint 2 — platform aliases per family
+
+```
+GET https://apix.cisco.com/security/advisories/v2/platforms?OSType=<osType>
+```
+
+Returns entries of `{platformAlias, id, name}`. Observed counts: `asa` 9, `ftd` 8, `fxos` 2.
+Not supported for `fmc`.
+
+Used to validate a locally-mapped alias before it is sent (FR-019).
+
+## Endpoint 3 — release catalogue per family
+
+```
+GET https://apix.cisco.com/security/advisories/v2/OS_version/OS_data?OSType=<osType>
+```
+
+Observed row counts: `asa` 947, `ftd` 436, `fmc` 68.
+
+**Row shape is not uniform across families:**
+
+| Family | Keys present |
+| --- | --- |
+| `asa`, `ftd` | `nos_version`, `nos_type`, `platform_name` |
+| `fmc` | `nos_version`, `nos_type` — **no `platform_name`** |
+
+A release appears once per platform it runs on, so the platform set for a release is obtained
+by grouping rows on `nos_version`.
+
+## Two known inconsistencies the tool must absorb
+
+### Platform names disagree between endpoints 2 and 3
+
+Alias `FPRNGFW` is named "Cisco Firepower NGFW Virtual" by `/platforms` but the same platform
+appears as "Cisco Secure Firewall Threat Defense Virtual" in `/OS_version/OS_data`. Name
+equality across the two endpoints is therefore **not** a reliable test. The tool must fail
+closed: an unreconcilable name means the platform is *not confirmed*, yielding Needs review
+rather than falling through to Not impacted (Decision 5).
+
+### `/platforms` lags `/OS_version/OS_data`
+
+Platforms present in the release catalogue with no alias available:
+
+| Family | Unaliased platforms |
+| --- | --- |
+| `asa` | Secure Firewall 200, 1200, 4200, 6100 Series |
+| `ftd` | Secure Firewall 200, 1200, 4200, 6100 Series, Threat Defense Virtual |
+
+Cisco's own web Software Checker offers several of these in its picker, so the API's alias list
+trails its web tool. Devices on those platforms cannot be queried with a platform today and
+resolve to Needs review (`model_unmapped`). Fetching `/platforms` every run means the gap
+closes on Cisco's schedule without a tool release (Decision 11).
+
+## Quotas
+
+Published: **5 requests/second, 30/minute, 5,000/day**. Exceeding a limit returns `429`.
+
+The per-minute limit binds: pace at no more than one request every ~2.1 s (Decision 10).
+Measured: 33 requests for the real 70-row inventory in ~83 s with no throttling.
+
+A `429`, like any other unexpected status, resolves to Needs review — never to a verdict.
+
+## Coverage limits inherited from Cisco
+
+Cisco's Software Checker data — and therefore this API — holds vulnerability information for
+**ASA, FMC, FTD and FXOS only from January 2022 onward**, and for NX-OS and NX-OS in ACI mode
+from July 2019 onward. It also "does not account for enabled or disabled features".
+
+Both limits bound what any verdict from this mode can mean, and both must be stated in every
+report (FR-032).
diff --git a/specs/006-api-inventory-check/data-model.md b/specs/006-api-inventory-check/data-model.md
new file mode 100644
index 0000000..34c81e9
--- /dev/null
+++ b/specs/006-api-inventory-check/data-model.md
@@ -0,0 +1,213 @@
+# Phase 1 Data Model: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+Nothing here is persisted. Every entity is derived in memory during a run and rendered into
+the report; the only file written is the report itself. Credentials are the sole exception —
+they are read from existing per-user storage, never written by a run.
+
+---
+
+## Entities
+
+### Device (derived, one per inventory row)
+
+The unit the report is organised around. Produced by the existing inventory loader, extended
+with the fields this feature derives.
+
+| Field | Source | Notes |
+| --- | --- | --- |
+| `name` | inventory | Firewall name; reproduced verbatim in the report |
+| `model` | inventory | Raw model string, e.g. `ASA 5506`, `Cisco Firepower 3130 Threat Defense` |
+| `family` | inventory | Firewall type folded as today (`ASAv` → `ASA`) |
+| `raw_version` | inventory | Release exactly as recorded, e.g. `9.16(4)67` |
+| `priority` | inventory | Used for sorting in the report; not part of any verdict |
+| `os_type` | derived | Lower-cased family used to address Cisco, e.g. `asa`, `ftd`, `fmc` |
+| `release` | derived | Normalised release (research Decision 6), e.g. `9.16.4.67` |
+| `platform_alias` | derived | Mapped alias (Decision 7), or `None` for platform-less families, or unset when unmappable |
+| `verdict` | derived | Exactly one of the three values below |
+| `reason` | derived | Present if and only if `verdict` is Needs review |
+| `advisories` | derived | Non-empty if and only if `verdict` is Impacted |
+
+**Invariants.**
+- Every inventory row yields exactly one Device, and every Device carries exactly one verdict (FR-007, SC-002).
+- `advisories` non-empty ⟺ `verdict == Impacted` (FR-008, FR-025).
+- `reason` present ⟺ `verdict == Needs review` (FR-028, SC-004).
+- Original inventory columns are never rewritten, only annotated (FR-024).
+
+---
+
+### Check (derived, one per distinct query)
+
+The deduplication unit — what Cisco is actually asked about. Many Devices map to one Check.
+
+| Field | Notes |
+| --- | --- |
+| `os_type` | Cisco family identifier |
+| `platform_alias` | The alias, or `None` for families that take no platform |
+| `release` | Normalised release |
+| `outcome` | The classified result (see the outcome table below) |
+| `advisories` | Advisories returned, if any |
+| `devices` | Back-reference to every Device sharing this Check |
+
+**Invariants.**
+- Identity is the tuple `(os_type, platform_alias, release)`; Cisco is asked at most once per identity (FR-020, SC-008).
+- Every Device with a mappable platform and a non-empty release belongs to exactly one Check.
+- A Device that cannot produce a Check identity (unmappable model, missing field, unsupported family) never reaches the API and is resolved locally to Needs review.
+
+---
+
+### Verdict (enumeration)
+
+| Value | Meaning | Precondition |
+| --- | --- | --- |
+| `Impacted` | Cisco lists ≥1 advisory for this release on this platform | 200 with a non-empty advisory list |
+| `Not impacted` | Cisco confirmed the device is clean | 404 `NO_DATA_FOUND` **and** both confirmations of Decision 4 |
+| `Needs review` | No trustworthy verdict; asserts nothing about safety | everything else |
+
+`Not impacted` is the only verdict that requires positive confirmation of two independent
+facts. Every failure mode in the system resolves toward `Needs review`, never toward
+`Not impacted` (FR-010, SC-003).
+
+---
+
+### Reason (derived, attached to Needs review)
+
+The reason is a closed set of kinds, so it can be tested exhaustively and — later — filtered
+on. Each carries the detail a reader needs to act.
+
+| Kind | Detail carried | Reader's next step |
+| --- | --- | --- |
+| `release_unknown` | The release as recorded *and* as normalised | Correct the inventory, or accept that Cisco has purged an end-of-support train |
+| `release_not_on_platform` | The platforms Cisco *does* list for that release (FR-012) | Decide whether the model or the release is wrong |
+| `model_unmapped` | The raw model string | Add the model, or note Cisco has no alias for that platform yet |
+| `field_missing` | Which field was blank (model or release) | Fill in the inventory |
+| `family_unsupported` | The family as recorded | Out of this mode's coverage; use the advisory-driven mode |
+| `check_incomplete` | That the check did not complete | Re-run; possibly transient |
+
+**Invariant.** A reason is human-readable without reference to the tool's source or its
+authors (SC-004) — no bare status codes, no internal identifiers.
+
+---
+
+### Advisory (from Cisco, per Check)
+
+| Field | Cisco source | Used for |
+| --- | --- | --- |
+| `advisory_id` | `advisoryId` | Row label; link text |
+| `title` | `advisoryTitle` | Description (escaped) |
+| `severity` | `sir` | Severity display and ordering |
+| `cvss` | `cvssBaseScore` | Supplementary (FR-027 neighbourhood) |
+| `cves` | `cves` | CVE identifiers (FR-027) |
+| `url` | `publicationUrl` | Link to Cisco's published advisory (FR-026) |
+| `first_fix` | `platforms[].firstFixes[].name` | The remediation target (FR-026) |
+
+**Observed guarantees** (from the spike, 561 advisory-platform pairs across 103 distinct
+advisories): every returned platform entry had `vulnerabilityState == "vulnerable"` and every
+one carried a `firstFixes` entry. Cisco also scopes the response to the queried platform —
+querying `ftd`/`FWL3100` returned only "Cisco Secure Firewall 3100 Series" platform entries.
+So a returned advisory needs no further filtering to be considered applicable.
+
+**Invariants.**
+- Every field is treated as untrusted text; none may alter report structure or behaviour (FR-033).
+- `url` is rendered as a link but its value is still escaped as an attribute.
+- A missing `first_fix` is rendered as absent, never as a guess.
+
+---
+
+### PlatformCatalogue (from Cisco, per family, per run)
+
+Maps alias → display name for one family. Retrieved from `/platforms`; not persisted
+(Decision 11).
+
+| Use | Requirement |
+| --- | --- |
+| Validate a locally-mapped alias before querying | FR-019 |
+| Detect a platform Cisco has not yet aliased | Decision 9 |
+
+Absent for families that take no platform (`fmc`).
+
+---
+
+### ReleaseCatalogue (from Cisco, per family, per run)
+
+The set of releases Cisco recognises, and for platform-bearing families the platforms each
+release runs on. Retrieved from `/OS_version/OS_data`.
+
+| Use | Requirement |
+| --- | --- |
+| Distinguish "release unknown" from "release clean" | FR-011, Decision 4 |
+| Name the platforms a release *does* run on | FR-012 |
+
+**Shape warning.** Rows are **not** uniform across families: `asa` and `ftd` rows carry
+`nos_version`, `nos_type` and `platform_name`; `fmc` rows carry only `nos_version` and
+`nos_type`, with no `platform_name` key at all. Any consumer must tolerate its absence
+(Decision 8).
+
+---
+
+### RunSummary (derived, rendered once)
+
+| Field | Requirement |
+| --- | --- |
+| Run date and time | FR-031 |
+| Inventory file used | FR-031 |
+| Devices assessed | FR-031 |
+| Count per verdict | FR-031, SC-018 |
+| Partial-run flag and cause | FR-016, SC-019 |
+| Coverage statements | FR-032 |
+
+---
+
+### CiscoCredentials (read-only during a run)
+
+| Field | Storage | Handling |
+| --- | --- | --- |
+| Client identifier | Per-user config, or environment | Not a secret; echoed at its prompt (FR-037) |
+| Client secret | Per-user config, or environment | Never displayed, logged, or written anywhere but the config file (FR-049) |
+
+Resolution order is the project's existing one: environment, then per-user config file
+(FR-046). Empty or whitespace-only is treated as absent (FR-047).
+
+---
+
+## Check outcome → Verdict state map
+
+The complete decision table. Read top to bottom; the first matching row wins.
+
+| # | Condition | Verdict | Reason kind |
+| --- | --- | --- | --- |
+| 1 | Model or release blank in the inventory | Needs review | `field_missing` |
+| 2 | Family not one this mode can query | Needs review | `family_unsupported` |
+| 3 | Model maps to no alias, or to an alias absent from the live platform catalogue | Needs review | `model_unmapped` |
+| 4 | API responded 200 with ≥1 advisory | **Impacted** | — |
+| 5 | API responded 406 `INVALID_<FAMILY>_VERSION` | Needs review | `release_unknown` |
+| 6 | API responded 404 `NO_DATA_FOUND`, and the release is **absent** from the release catalogue | Needs review | `release_unknown` |
+| 7 | API responded 404 `NO_DATA_FOUND`, release present, but the platform is **not** confirmed for that release | Needs review | `release_not_on_platform` |
+| 8 | API responded 404 `NO_DATA_FOUND`, release present, platform confirmed | **Not impacted** | — |
+| 9 | Authentication rejected, quota exhausted, transport failure, or unparseable body | Needs review | `check_incomplete` |
+| 10 | Any response not covered above | Needs review | `check_incomplete` |
+
+**Notes on the table.**
+
+- Rows 1–3 are resolved locally and consume no request.
+- Row 6 exists because a `404` can be returned for a release Cisco does not hold at all, so
+  the catalogue is consulted even after a "successful" negative answer.
+- Row 7 is where the platform-name reconciliation of Decision 5 applies. If the alias cannot
+  be reconciled to a catalogue platform name, the condition is *not* confirmed and this row
+  matches — failing closed into Needs review rather than falling through to row 8.
+- Row 8 is the only path to `Not impacted`, and it requires rows 5, 6 and 7 to have all been
+  ruled out.
+- Row 9 covers the partial-run case: remaining devices take this outcome and the RunSummary
+  is flagged partial (FR-016).
+
+## Run outcome → exit status
+
+| Outcome | Report written | Exit |
+| --- | --- | --- |
+| Run completed; any mix of verdicts, including all Needs review | yes | 0 (FR-053) |
+| Run completed partially (Cisco unreachable or quota reached mid-run) | yes, flagged partial | 0 |
+| Cisco credentials unavailable | no | non-zero (FR-048) |
+| Credentials rejected at run start | no | non-zero (FR-014) |
+| Inventory unusable or empty | no | non-zero (FR-055) |
+| Output folder unwritable | no | non-zero (FR-054) |
+| `--api` combined with the advisory-driven mode | no | non-zero (FR-003) |
+| Interrupted by the operator | no | 130 (FR-052, Principle III) |
diff --git a/specs/006-api-inventory-check/plan.md b/specs/006-api-inventory-check/plan.md
new file mode 100644
index 0000000..b69b5f0
--- /dev/null
+++ b/specs/006-api-inventory-check/plan.md
@@ -0,0 +1,260 @@
+# Implementation Plan: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+**Branch**: `006-api-inventory-check` | **Date**: 2026-07-25 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `/specs/006-api-inventory-check/spec.md`
+
+## Summary
+
+Add a `caia --api` mode that inverts the tool's question: instead of "given this advisory, which
+firewalls are affected?", it asks "given my inventory, which firewalls does Cisco list as
+vulnerable, and to what?". Each device's software release and hardware platform are put to
+Cisco's PSIRT openVuln API — the same data behind Cisco's public Software Checker — and the
+answer is reported directly, so the mode needs no advisory URL and makes no AI call. Output is
+one self-contained, timestamped HTML report per run.
+
+The design's centre of gravity is the negative verdict. A feasibility spike against the team's
+real 70-row inventory found 15 rows that Cisco could not answer at all — end-of-support releases
+purged from its catalogue, and model/release pairings Cisco never shipped — and **zero** rows
+that were genuinely clean. Those 15 return the same "empty" answer as a patched device would.
+So `Not impacted` is only ever assigned when Cisco positively confirms both that it recognises
+the release and that the release runs on that model; every other path, including every failure
+mode, resolves to `Needs review` with a specific reason. Local matching heuristics (release
+normalisation, model→alias mapping) can only ever *reduce* the number of `Needs review` rows —
+they can never manufacture a `Not impacted`.
+
+Three new standard-library-only modules (`psirt.py` for API access, `matching.py` for pure
+verdict logic, `html_report.py` for rendering) plus edits to `cli.py`, `config.py` and
+`analyzer.py`. No new runtime dependency. The constitution has been amended to 2.2.0 as a
+prerequisite — admitting the two new Cisco hosts and the PSIRT API as source data, recording the
+HTML report, and reworking Principle IV so the undecided label is mode-appropriate while promoting
+this design's positive-confirmation rule into the principle itself.
+
+## Technical Context
+
+**Language/Version**: Python 3.9+ (matches `requires-python` in `pyproject.toml`)
+
+**Primary Dependencies**: None new. Standard library only — `urllib.request`/`urllib.parse`
+(token request, API calls, form encoding), `json` (responses), `html` (`escape`, for report
+rendering), `re` (release normalisation, model matching), `time` (request pacing),
+`datetime`/`pathlib` (report naming and location), `getpass` via the existing `ui.ask_secret`
+(secret prompt). Existing runtime deps (`openpyxl`, `python-dotenv`) are untouched and unused by
+the new code paths except for inventory loading.
+
+**Storage**: None added. The two Cisco credentials are stored in the existing per-user
+configuration file; catalogues are held in memory for the duration of a run and never persisted
+(research Decision 11). The only file written is the report.
+
+**Testing**: `unittest` + `unittest.mock` (existing suite under `tests/`, run via `pytest`). The
+verdict logic lives in a pure module so all ten rows of the outcome table are covered by
+table-driven tests with no network. New: `tests/test_matching.py`, `tests/test_psirt.py`,
+`tests/test_html_report.py`; extended: `tests/test_config.py` (Cisco keys, prompts,
+verification outcomes), `tests/test_cli.py` (`--api` parsing, mutual exclusion, exit codes).
+
+**Target Platform**: macOS, Windows, Linux (Constitution II).
+
+**Project Type**: Single-project CLI (installed as the `caia` console script).
+
+**Performance Goals**: Bounded by Cisco's quota, not by local work. 30 requests/minute binds →
+pace at ~1 request per 2.1 s. Real 70-row inventory: 27 checks + 5 catalogue + 1 token = 33
+requests ≈ 70 s (measured ~83 s at 2.5 s spacing). A 1,000-row inventory collapsing at the same
+ratio: ~385 checks ≈ 14 min. Pathological all-distinct 1,000 rows: ~35 min, still inside the
+5,000/day cap. Progress reporting is required precisely because these are minutes, not seconds.
+
+**Constraints**: Never assign `Not impacted` without positive confirmation (Principle IV, the
+feature's core safety property); no new runtime dependency (Principle I); identical behaviour on
+all three platforms (Principle II); report must be a single file that works offline and after
+being emailed; all Cisco-supplied content escaped at interpolation (every advisory observed
+carried raw HTML in `summary`); no credential fragment in any output; existing advisory-driven
+mode bit-for-bit unchanged.
+
+**Scale/Scope**: 3 new modules (~600–800 lines total, majority in the pure matching module and
+the report writer), 3 modified modules, 3 new test modules + 2 extended, 1 committed fixture
+inventory, docs updates in `README.md` and `docs/index.html`, and a constitution amendment. No
+new directories beyond `specs/`.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+Evaluated against the Cisco Advisory Impact Agent Constitution **v2.2.0**, which was amended as
+a prerequisite of this feature (see [Constitution amendment](#constitution-amendment-applied)
+below). All gates now pass unconditionally.
+
+- **I. Standard-Library-First & Minimal Dependencies** — PASS. No new runtime dependency. HTTP
+  via `urllib`, JSON via `json`, escaping via `html.escape`, report composed by string
+  templating. A template engine and a CDN-hosted table-sort library were both considered and
+  rejected (research Decision 12); neither is needed and the second would break the offline
+  requirement.
+
+- **II. Cross-Platform Parity** — PASS. All network and parsing code is platform-neutral;
+  `pathlib` handles report paths; the per-user config location already resolves per-OS.
+  Per-keystroke secret masking — the one place platform-specific terminal handling would have
+  been required — is deliberately **not** implemented (Decision 13): it would need `termios`/
+  `tty` on Unix and `msvcrt` on Windows plus per-platform handling of backspace, `Ctrl-C` and
+  bracketed paste, which is exactly the divergence this principle treats as a correctness bug.
+  FR-039's documented fallback (a non-echoing prompt) is used instead, and FR-038's length
+  confirmation delivers the actual assurance the user asked for on every terminal.
+
+- **III. CLI-First, Scriptable Interface** — PASS. `--api` is reachable from the CLI and works
+  fully flag-driven with `--inventory`/`--sheet`/`--output-dir`, so it needs no interactive
+  input. `--dry-run` exercises the flow with no network (FR-006), satisfying the workflow gate
+  below. Exit codes are meaningful: 0 for a completed run including an all-`Needs review` one,
+  non-zero for missing/rejected credentials, unusable inventory, unwritable output, and mode
+  conflict, 130 on interrupt. Every refusal states what failed and how to fix it.
+
+- **IV. Conservative & Traceable Analysis (NON-NEGOTIABLE)** — PASS, and this principle drove
+  the design rather than merely permitting it.
+  - *Never overstate risk*: `Impacted` is reported as "Cisco lists this release on this platform
+    as affected", explicitly not "exploitable", and the report says so (FR-032).
+  - *Insufficient data must not be a guess*: `Not impacted` requires two positive confirmations;
+    all ten failure paths in the outcome table resolve to `Needs review` (data-model.md). The
+    tool never substitutes a nearby release or drops the platform to obtain an answer (FR-013) —
+    both were considered and rejected as guesses.
+  - *Traceable to official Cisco source data*: every verdict comes from Cisco's published
+    advisory data, and each advisory carries its `publicationUrl` so a reader can verify it.
+  - *AI output normalised*: N/A by construction — this mode makes no AI call, and the amended
+    clause is now scoped to modes that use AI.
+  - *Label*: the amended principle accepts `Needs review` for the inventory-driven check
+    explicitly, and now also states the positive-confirmation rule this feature depends on —
+    "not affected" may never rest on the mere absence of a result.
+
+- **V. Secrets Hygiene & Data Locality** — PASS. Both Cisco values live only in the existing
+  per-user config file (owner-only where the OS supports it, outside any working folder) or the
+  environment; neither is ever logged, printed, or written to the report or a filename (FR-049),
+  including in verification failure messages, where Cisco's error text is surfaced without
+  echoing request parameters. The tool refuses to run when a required secret is missing (FR-048).
+  Inventory data stays local: **only** the derived triple (family, platform alias, normalised
+  release) is sent to Cisco — never a firewall name, never a whole row — which is a strictly
+  smaller disclosure than the existing mode makes to the AI endpoint. `.gitignore` already
+  excludes secrets, inventory and reports; the new `impact_report_*.html` output lands in the
+  already-ignored `output/`, to be confirmed as a task.
+
+- **Technology & Data Constraints** — PASS (as amended). The pre-amendment constraints named only
+  `sec.cloudapps.cisco.com` and `api.fuelix.ai`, and required that "adding any further external
+  endpoint the analyzer itself contacts remains a reviewed change". That review was carried out
+  and the amendment applied: `apix.cisco.com` and `id.cisco.com` are now permitted, scoped to
+  advisory data and token issuance, with an explicit constraint that only the derived
+  family/platform/release triple may be sent — never a firewall name or other inventory
+  identifier. The "Source of truth" and "Inputs/outputs" bullets were aligned in the same edit.
+
+- **Development Workflow & Quality Gates** — PASS (obligations captured as tasks). Release
+  normalisation, alias mapping and verdict derivation are inventory-matching logic and therefore
+  *must* have tests; the pure `matching.py` boundary exists to make that exhaustive and
+  network-free. `--dry-run` keeps verification cheap. `README.md` and `docs/index.html` must both
+  document the new mode, its credential prerequisite and its HTML output, mirrored in the same
+  PR. Work proceeds on `006-api-inventory-check` off `main` and merges via PR.
+
+### Constitution amendment (applied)
+
+Applied as one edit to `.specify/memory/constitution.md`, bumping **2.1.0 → 2.2.0** (MINOR:
+materially expanded guidance, no principle removed or redefined), with a Sync Impact Report and
+`Last Amended` set to 2026-07-25. Four clauses:
+
+1. **Networking** — add `apix.cisco.com` and `id.cisco.com` as endpoints the analyzer contacts,
+   scoped to advisory data and token issuance, and note that only the derived
+   family/platform/release triple is sent — no inventory identifiers.
+2. **Source of truth** — record Cisco's PSIRT advisory API alongside ERP pages and CSAF JSON as
+   official Cisco source data.
+3. **Inputs/outputs** — record that `--api` writes `impact_report_*.html` beside the existing
+   `analysis_output_*.xlsx`.
+4. **Principle IV wording** — the undecidable result now carries a mode-appropriate label, with
+   both `Indeterminate` (advisory-driven report) and `Needs review` (inventory-driven report)
+   named as conforming. The requirement itself is unchanged: an undecidable device must be
+   labelled undecidable and never guessed. The AI-normalization clause is scoped to modes that
+   use AI, since this one does not.
+
+   The amendment also **strengthens** the principle beyond what this feature strictly needed, by
+   promoting the design's central safety property into the constitution itself: a determination
+   that a device is *not* affected must rest on positive confirmation from Cisco's data, never on
+   the mere absence of a result, and an undecided device must never be presented as unaffected.
+   That rule was previously implicit. Making it explicit is what stops the next feature — or the
+   next contributor — from reintroducing the failure mode the spike found, where 15 of 70 real
+   inventory rows returned "nothing found" for reasons that had nothing to do with being clean.
+
+   The alternative — renaming this mode's verdict to `Indeterminate` — was considered and not
+   chosen, because `Needs review` states what the reader should *do*, and the reason attached to
+   it is a data-quality action item rather than an analytical dead end.
+
+**Result (pre-Phase 0)**: PASS. The amendment has been applied, so no gate is conditional and no
+principle is violated. Complexity Tracking is empty.
+
+**Re-check (post-Phase 1 design)**: PASS — unchanged, with two design decisions strengthening
+rather than weakening the gates. (a) Principle IV: research Decisions 4 and 5 make every
+heuristic fail *closed* — an unmappable model, an unreconcilable platform name, a `429`, or an
+unparseable body all land in `Needs review`, so no local guess can produce a false all-clear;
+Decision 5 also documents the observed `FPRNGFW` platform-name mismatch between two Cisco
+endpoints that would have broken a naive name comparison. (b) Principle I: the final design adds
+no dependency, and Decision 12's escaping requirement is grounded in the observation that all
+103 advisories returned during the spike carried raw HTML in `summary`. With the amendment applied
+there are no outstanding prerequisites; the remaining gate obligations (tests for matching logic,
+mirrored README/`docs/index.html` updates) are ordinary tasks. Complexity Tracking remains empty.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-api-inventory-check/
+├── plan.md                      # This file (/speckit-plan command output)
+├── research.md                  # Phase 0 output — 15 decisions, spike-verified
+├── data-model.md                # Phase 1 output — entities + outcome/exit state maps
+├── quickstart.md                # Phase 1 output — validation scenarios A–K
+├── contracts/
+│   ├── api-run-cli.md           # Phase 1 output — `caia --api` CLI contract
+│   ├── config-cli.md            # Phase 1 output — extended `caia --config` contract
+│   ├── psirt-access.md          # Phase 1 output — external Cisco API contract
+│   └── html-report.md           # Phase 1 output — report output contract
+├── checklists/
+│   └── requirements.md          # Spec quality checklist (from /speckit-specify)
+└── tasks.md                     # Phase 2 output (/speckit-tasks — NOT created by /speckit-plan)
+```
+
+### Source Code (repository root)
+
+```text
+cisco_advisory_impact_agent/
+├── psirt.py          # NEW: token acquisition, paced requests, the three endpoints,
+│                     #      status→outcome classification. Only module talking to the API.
+├── matching.py       # NEW: pure functions — release normalisation, model→alias mapping,
+│                     #      catalogue lookups, verdict derivation. No I/O.
+├── html_report.py    # NEW: single-file report rendering; escapes all Cisco content.
+├── analyzer.py       # MODIFIED: add run_api() beside run(); reuse inventory loading,
+│                     #           output-dir handling, and ui conventions.
+├── cli.py            # MODIFIED: --api flag, mutual-exclusion guard, dispatch.
+├── config.py         # MODIFIED: Cisco credential keys, two prompts, verification call-out,
+│                     #           AI key no longer mandatory.
+├── inventory.py      # REUSED unchanged: discovery, column tolerance, combo grouping.
+├── ui.py             # REUSED: ask/ask_secret/select/ok/warn/fail/info; may add a
+│                     #         secret-length confirmation helper.
+├── cisco.py          # UNTOUCHED (ERP/CSAF path).
+├── fuelix.py         # UNTOUCHED (not called in this mode).
+└── report.py         # UNTOUCHED (xlsx report for the existing mode).
+
+tests/
+├── test_matching.py     # NEW: normalisation, alias mapping, all 10 outcome rows
+├── test_psirt.py        # NEW: status→outcome classification, pacing, token reuse (mocked)
+├── test_html_report.py  # NEW: structure, counts, escaping, no external references
+├── test_config.py       # MODIFIED: Cisco keys, prompt visibility, 3 verification outcomes
+├── test_cli.py          # MODIFIED: --api parsing, mutual exclusion, exit codes
+└── fixtures/            # NEW: inventory covering every verdict path (see quickstart.md)
+
+.specify/memory/constitution.md  # DONE: amended 2.1.0 → 2.2.0 (prerequisite, already applied)
+README.md                        # MODIFIED: --api mode, Cisco credential prerequisite, HTML output
+docs/index.html                  # MODIFIED: mirror the above (Documentation gate)
+```
+
+**Structure Decision**: Single-project CLI, extending the existing one-concern-per-module
+layout. `psirt.py` parallels `cisco.py` (ERP/CSAF) and `fuelix.py` (AI) — one module per external
+service, which is the shape the project already uses. The decisive choice is splitting
+`matching.py` out as pure, I/O-free logic: every safety rule in this feature lives there, and
+that boundary is what makes the ten-row outcome table provable by unit test rather than only
+observable against Cisco's live API. `analyzer.py` gains a second flow rather than branching
+inside the existing one, keeping FR-002's "existing mode unchanged" verifiable by inspection.
+
+## Complexity Tracking
+
+> No Constitution Check violations — this section is intentionally empty. The one conditional
+> item (two new external endpoints) is a constraint that explicitly gates on review rather than
+> a violation; the review and the required amendment are recorded in the Constitution Check
+> above and carried as a prerequisite task.
diff --git a/specs/006-api-inventory-check/quickstart.md b/specs/006-api-inventory-check/quickstart.md
new file mode 100644
index 0000000..36556d1
--- /dev/null
+++ b/specs/006-api-inventory-check/quickstart.md
@@ -0,0 +1,178 @@
+# Quickstart & Validation: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+## Prerequisites
+
+- A source checkout with the test suite runnable (`pytest`).
+- For live scenarios only: a Cisco API client identifier and secret, obtained per user from
+  Cisco's developer portal. Automated validation needs neither.
+- An inventory `.xlsx` in the working folder. Scenarios below reference a fixture inventory
+  covering every verdict path; see [Fixture inventory](#fixture-inventory).
+
+## Automated validation (primary)
+
+The verdict logic is pure and must be provable without touching Cisco's API:
+
+```bash
+python -m pytest -q
+```
+
+Everything in the outcome table of [`data-model.md`](./data-model.md) is expected to be covered
+by table-driven unit tests over the matching module — release normalisation, model→alias
+mapping, catalogue lookups, and each of the ten outcome rows — with no network access. The
+report writer is likewise testable offline by rendering a fabricated result set and asserting
+against the produced file.
+
+If a change to release normalisation, alias mapping, or verdict derivation is not accompanied by
+tests, the Development Workflow gate in the constitution is not satisfied.
+
+## Offline flow check
+
+Exercise the whole run path with no credentials and no network:
+
+```bash
+caia --api --dry-run
+```
+
+Expected: devices load, each resolves to the check that *would* be made (family, platform
+alias, normalised release), nothing is sent to Cisco, no report is written, exit 0.
+
+## Live end-to-end scenarios
+
+### Scenario A — Full inventory run (US1 · P1)
+
+```bash
+caia --api
+```
+
+Expected: a device count, a distinct-check count lower than the device count, visible progress,
+then a written report path. Open the report: every inventory row appears once with exactly one
+verdict; Impacted devices list advisories with severities, links, and fixed releases.
+
+### Scenario B — Negatives are earned, not assumed (US2 · P1)
+
+Using the fixture inventory's unanswerable rows, confirm each is **Needs review** and none is
+Not impacted:
+
+| Fixture row | Expected reason |
+| --- | --- |
+| ASA 5525 @ `9.14(4)24` | Cisco does not recognise that release |
+| ASA 5515 @ `9.18(4)22` | Release recognised but not listed for that model; the platforms Cisco *does* list are named |
+| ISA-3000 @ FTD `7.4.0` | Release recognised but not listed for that model |
+| Model `Unknown Appliance 9` | Model could not be identified |
+| Blank release | Missing field named |
+
+This is the scenario that matters most. On the team's real 70-row inventory, 15 rows land here
+and **zero** are genuinely clean — a build that reports any of them Not impacted has failed,
+regardless of what else works.
+
+### Scenario C — Shorthand releases are matched (US2 · P1)
+
+Confirm `9.16(4)67` is assessed rather than reported unrecognised: it must normalise to
+`9.16.4.67` and return advisories.
+
+### Scenario D — Report is usable and portable (US3 · P2)
+
+Open the report, filter to Impacted, sort by priority, expand a device with many advisories,
+follow an advisory link. Then:
+
+```bash
+cp output/impact_report_*.html /tmp/ && open /tmp/impact_report_*.html
+```
+
+Disconnect from the network first. Expected: layout, filtering, sorting and expanding all still
+work; no element fails to load.
+
+### Scenario E — Credential setup (US4 · P2)
+
+```bash
+caia --config
+```
+
+Expected: the identifier prompt echoes; the secret prompt does not, and is followed by a
+confirmation naming the captured character count and nothing else; valid values report as valid.
+Then re-run and submit empty at each Cisco prompt — the saved values must be unchanged.
+
+### Scenario F — Rejected vs unreachable credentials (US4 · P2)
+
+Rejected — supply a deliberately wrong secret at `caia --config`. Expected: Cisco's own reason
+is shown, re-entry is offered, and the wrong value is not silently saved.
+
+Unreachable — block egress to `id.cisco.com`, then run `caia --config`. Expected: a message that
+distinguishes "could not reach Cisco" from "invalid", and an offer to save unverified with a
+warning. Setup must remain completable; a proxy outage must never make correct credentials
+unusable.
+
+### Scenario G — Refusal without credentials (US4 · P2)
+
+With no Cisco credentials in the environment or config:
+
+```bash
+caia --api
+```
+
+Expected: refusal naming which value is missing, pointing at `caia --config`, zero requests to
+Cisco, non-zero exit, no report.
+
+### Scenario H — Modes stay separate (US1 · P1)
+
+```bash
+caia --api --url https://sec.cloudapps.cisco.com/security/center/viewErp.x?alertId=ERP-75736
+```
+
+Expected: refusal stating the two modes are mutually exclusive, no requests, non-zero exit.
+
+Then confirm the existing mode is untouched:
+
+```bash
+caia --url <ERP URL>
+```
+
+Expected: identical behaviour and an `.xlsx` report, exactly as before this feature.
+
+### Scenario I — Coverage disclosure (US5 · P3)
+
+Open any report and confirm, without reading a single device row, that the summary carries the
+run timestamp, inventory filename, device count, per-verdict counts, and both coverage
+statements.
+
+### Scenario J — Interrupt (FR-052)
+
+Press `Ctrl-C` during the check phase. Expected: prompt stop, exit 130, no partial report left
+behind.
+
+### Scenario K — Untrusted advisory content (FR-033)
+
+Render a report from a fabricated result set whose advisory `summary` and `title` contain
+`<script>alert(1)</script>` and an `<a href>`. Expected: both appear as visible text; no script
+executes and no live anchor is created from that content. This is not hypothetical — every
+advisory Cisco returned during the spike carried raw HTML in `summary`.
+
+## Fixture inventory
+
+A committed fixture must cover, at minimum: one device per verdict path (Impacted, Not
+impacted, Needs review × each reason kind), one FMC row (no platform alias — different response
+shape), one row whose release uses parenthetical shorthand, one row with an `/ASDM` annotation,
+one row with a `-nn` build suffix, and two rows sharing a family/platform/release so
+deduplication is observable.
+
+## Acceptance mapping
+
+| Scenario | User story | Key requirements |
+| --- | --- | --- |
+| A | US1 | FR-001, FR-007, FR-020, FR-022, FR-051 |
+| B | US2 | FR-009, FR-010, FR-011, FR-012, SC-003 |
+| C | US2 | FR-017 |
+| D | US3 | FR-026, FR-029, FR-030 |
+| E | US4 | FR-034, FR-037, FR-038, FR-040 |
+| F | US4 | FR-041, FR-042, FR-043 |
+| G | US4 | FR-048, FR-005 |
+| H | US1 | FR-002, FR-003 |
+| I | US5 | FR-031, FR-032 |
+| J | — | FR-052 |
+| K | — | FR-033 |
+
+## Success signal
+
+The feature is validated when the automated suite passes, `--dry-run` resolves every fixture
+device without network access, and Scenarios A–K behave as described — with Scenario B treated
+as the gate: no unanswerable device may ever be labelled Not impacted.
diff --git a/specs/006-api-inventory-check/research.md b/specs/006-api-inventory-check/research.md
new file mode 100644
index 0000000..d8cdec8
--- /dev/null
+++ b/specs/006-api-inventory-check/research.md
@@ -0,0 +1,361 @@
+# Phase 0 Research: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+All findings below were verified against the live Cisco PSIRT openVuln API with real
+credentials and the team's real inventory (70 rows) during a feasibility spike, not taken
+from documentation alone. Where the API's documented behaviour and its observed behaviour
+differ, the observed behaviour is recorded and cited.
+
+---
+
+## Decision 1 — The API endpoint set, and that it *is* the Software Checker
+
+**Decision.** Use the openVuln v2 API at `https://apix.cisco.com/security/advisories/v2`
+with exactly three endpoints:
+
+| Purpose | Endpoint |
+| --- | --- |
+| Advisories for a release on a platform | `GET /OSType/{osType}?version=<release>[&platformAlias=<alias>]` |
+| Valid platform aliases per family | `GET /platforms?OSType=<osType>` |
+| Valid releases + the platforms each runs on | `GET /OS_version/OS_data?OSType=<osType>` |
+
+**Rationale.** Cisco states the API "integrates with Cisco Software Checker"; the `/OSType`
+endpoint is the programmatic form of the web checker's product + platform + release query,
+which is precisely the manual exercise this feature replaces. The other two endpoints supply
+the catalogues that let the tool tell an unrecognised release apart from a clean one
+(FR-019).
+
+**Alternatives considered.** Continuing to parse CSAF documents per advisory (what the
+existing mode does) — rejected because it inverts the wrong way: it requires knowing the
+advisory first, and it re-derives by inference an answer Cisco publishes directly. Scraping
+the web Software Checker — rejected outright; the constitution forbids scraped sources.
+
+---
+
+## Decision 2 — Authentication: client-credentials token, fetched once per run
+
+**Decision.** `POST https://id.cisco.com/oauth2/default/v1/token`, form-encoded, with
+`client_id`, `client_secret`, `grant_type=client_credentials`. Present the result as
+`Authorization: Bearer <token>` on every API call. Fetch one token per run (and per
+`--config` verification) and re-fetch once on an authentication failure mid-run.
+
+**Rationale.** Observed: `token_type=Bearer`, `expires_in=3600`, `scope=customscope`. One
+hour comfortably covers a full-inventory run (worst case ~33 min, Decision 10), so
+per-request token fetching would waste quota for no benefit. A single re-fetch on a 401
+covers the boundary case of a token expiring inside a long run.
+
+**Alternatives considered.** Caching the token across runs on disk — rejected; it is a
+bearer credential and writing it to disk multiplies exposure for at most one saved request.
+
+---
+
+## Decision 3 — The three-way outcome is carried by HTTP status, not by message text
+
+**Decision.** Classify each check from the status code and `errorCode`, never by
+string-matching the human-readable message:
+
+| Observed response | Meaning | Contributes to |
+| --- | --- | --- |
+| `200` with a non-empty `advisories` array | Cisco lists advisories for this release on this platform | **Impacted** |
+| `404` with `errorCode: NO_DATA_FOUND` | Cisco recognises the query but returns nothing | **candidate** Not impacted — requires Decision 4's confirmation |
+| `406` with `errorCode: INVALID_<FAMILY>_VERSION` | The release string is not in Cisco's catalogue | **Needs review** — release unknown |
+| Any other status, transport error, or unparseable body | Undetermined | **Needs review** — check did not complete |
+
+**Rationale.** This corrects the API documentation, which describes a *single* 200 response
+conflating "no advisories affect this release" with "version not found" under one
+`errorCode`. The live API separates them by status code — verified with
+`asa/ASA5500X/9.16.4.67` → 200 with 24 advisories, `asa/ASA5500X/9.18.4.22` → 404
+`NO_DATA_FOUND`, and `asa/ASA5500X/9.12.4.67` → 406 `INVALID_ASA_VERSION`. Had the
+documented behaviour held, FR-009 would have been unimplementable without the catalogue
+cross-check alone.
+
+**Alternatives considered.** Treating every non-200 as Needs review — rejected; it would
+make Not impacted unreachable and the report useless for confirming safety.
+
+---
+
+## Decision 4 — `404` alone never means "safe"; Not impacted needs positive confirmation
+
+**Decision.** A `404 NO_DATA_FOUND` becomes **Not impacted** only when *both* hold:
+
+1. the normalised release appears in that family's release catalogue, **and**
+2. the device's platform is confirmed present among the platforms the catalogue lists for
+   that release.
+
+If either cannot be established, the verdict is **Needs review**, with the reason naming
+which condition failed and — for condition 2 — the platforms Cisco does list.
+
+**Rationale.** This is the single most important finding of the spike. Of the team's 70
+inventory rows, 15 returned an "empty" answer, and **every one of them was a data problem
+rather than a clean device**:
+
+- 7 rows — release absent from Cisco's catalogue entirely. ASA `9.12(4)67` and `9.14(4)24`
+  normalise correctly but Cisco's 947-release ASA catalogue contains **zero** 9.12.x or
+  9.14.x entries; those trains are end-of-support and have been purged. FTD `7.3.2.3` never
+  existed (Cisco ships 7.3.0, 7.3.1, 7.3.1.1, 7.3.1.2).
+- 8 rows — release real, but never shipped on that model. `9.18.4.22`, `9.18.4.24` and
+  `9.19.1.24` are all catalogued for ISA3000, ASAv, FPR1000/2100/4100/9000 and Secure
+  Firewall 3100 — but **not** for the ASA 5500-X series, which ASA 9.18 dropped. Likewise
+  FTD `7.4.0` is catalogued only for the Secure Firewall 4200 series, not the ISA-3000 the
+  inventory pairs it with.
+
+Zero of the 70 rows were genuinely clean. Reporting those 15 as Not impacted — including
+`DCVPNCORE01` and `DCVPNCORE02` — would have been a false all-clear on a fifth of the
+fleet. Principle IV makes this non-negotiable, and this decision is how the spec's FR-009
+and FR-010 are satisfied.
+
+**Alternatives considered.** Trusting `404` as clean because "Cisco answered the question" —
+rejected on the evidence above.
+
+---
+
+## Decision 5 — Local heuristics may only *reduce* Needs review, never produce Not impacted
+
+**Decision.** Two pieces of matching logic are necessarily local: the inventory model →
+platform-alias mapping, and the reconciliation of an alias to the platform name used in the
+release catalogue. Both are structured so that **any failure degrades to Needs review**.
+Neither can turn an unconfirmed device into Not impacted.
+
+**Rationale.** This resolves the tension in FR-019 (catalogues must come from Cisco at run
+time, not a built-in list). The *catalogues* are always Cisco's; only the *matching* is
+local, and it is validated against the live catalogue — a mapped alias that is absent from
+`/platforms` for that family is treated as an unidentified model.
+
+It also contains a real hazard the spike exposed: **the two endpoints disagree on platform
+display names.** Alias `FPRNGFW` is named "Cisco Firepower NGFW Virtual" by `/platforms`,
+while the same platform appears as "Cisco Secure Firewall Threat Defense Virtual" in
+`/OS_version/OS_data`. A naive name equality check would therefore have concluded "this
+release does not run on this platform" for every FTD-virtual device — a false Needs review
+if the query 404'd, and worse, evidence that name matching cannot be the load-bearing part
+of a safety decision. Because condition 2 of Decision 4 fails *closed*, an unreconcilable
+name costs a Needs review and never a false all-clear. A small documented alias↔name
+equivalence set is therefore an optimisation that reduces noise, not a correctness
+dependency.
+
+**Alternatives considered.** Hardcoding the full platform and release catalogues — rejected;
+it violates FR-019 and would silently stop matching devices as Cisco publishes new
+platforms. Matching purely on Cisco's display names with no alias table — rejected; the
+`FPRNGFW` mismatch above shows it is unreliable.
+
+---
+
+## Decision 6 — Release normalisation: parenthetical shorthand to dotted canonical form
+
+**Decision.** Normalise each inventory release with three ordered, side-effect-free steps:
+drop any trailing companion-product annotation after `/`; rewrite `(n)` as `.n.`; strip a
+trailing `-nn` build suffix; then collapse repeated dots and trim.
+
+**Rationale.** Cisco's canonical form is dotted. Verified two ways: a real ASA/FTD advisory's
+CSAF product tree enumerates `9.8.4.33`, `9.16.4.67`, `9.19.1.24`, `7.4.2.3`; and
+`/OS_version/OS_data?OSType=asa` returns `9.16.4.92`, `9.18.1.3` and similar. The team's
+inventory records the operational `show version` shorthand instead. The transform on the
+real inventory:
+
+| Inventory | Normalised | Accepted by Cisco |
+| --- | --- | --- |
+| `9.16(4)67` | `9.16.4.67` | yes — 24 advisories returned |
+| `9.20(3)7` | `9.20.3.7` | yes — 26 advisories returned |
+| `9.20(4)` | `9.20.4` | yes — 10 advisories returned |
+| `9.20(4)7/ASDM 7.22.1` | `9.20.4.7` | yes — 10 advisories returned |
+| `7.4.2.1-30` | `7.4.2.1` | yes — 36 advisories returned |
+
+**Alternatives considered.** Falling back to a shorter release when the normalised one is
+absent (e.g. asking about `9.12.4` when `9.12.4.67` is unknown) — **rejected**, and this is
+FR-013. Asking Cisco about a release the device is not running and then reporting that answer
+as the device's verdict is exactly the guess Principle IV forbids. It would also not have
+helped the observed cases: ASA 9.12 and 9.14 are absent from the catalogue at *every* depth.
+The cost is accepted — end-of-support releases stay Needs review.
+
+---
+
+## Decision 7 — Model → platform alias mapping, validated against the live catalogue
+
+**Decision.** Map the inventory's model string to a platform alias with ordered pattern
+rules keyed on the hardware series, then require the result to be present in
+`/platforms?OSType=<family>` before use. No match, or a match Cisco does not list, →
+Needs review ("model could not be identified").
+
+The mapping must be family-aware: the same hardware carries a different alias depending on
+the software family. Verified from the live catalogues — ASA offers `ASA5500X` while FTD
+offers `ASA5500` for the same 5500-X hardware.
+
+Applied to all 22 distinct models in the real inventory, this mapped **100%** with no
+unmatched models:
+
+| Inventory model (examples) | Family | Alias |
+| --- | --- | --- |
+| `ISA-3000` | FTD | `ISA3000` |
+| `ASA 5506`, `ASA 5515`, `ASA 5525`, `ASA 5555` | ASA | `ASA5500X` |
+| `Firepower 1010`, `Firepower 1150`, `Cisco Firepower 1120 Threat Defense` | ASA / FTD | `FPR1000` |
+| `Firepower 2110`, `Firepower 2130`, `Cisco Firepower 2120 Threat Defense` | ASA / FTD | `FPR2100` |
+| `Firepower 3120`, `Cisco Secure Firewall 3140 Threat Defense` | ASA / FTD | `FWL3100` |
+| `Firepower 4110`, `Cisco Firepower 4112 Threat Defense` | ASA / FTD | `FPR4100` |
+| `Cisco Firepower Threat Defense for VMware` | FTD | `FPRNGFW` |
+| `Secure FMC 1600`, `Secure FMC 4600` | FMC | *(none — see Decision 8)* |
+
+**Alternatives considered.** Querying without a platform alias when the model cannot be
+mapped — rejected as FR-013's second clause. The "Any Platform" option does exist in the API
+and the web UI, but its answer may reflect hardware the device is not, so reporting it as
+that device's verdict would overstate or understate risk.
+
+---
+
+## Decision 8 — FMC is queried without a platform; families differ in platform support
+
+**Decision.** Only `asa`, `ftd`, `fxos` and `nxos` accept a platform alias. `fmc` (and
+`ios`, `iosxe`, `aci`) are queried by release alone, and for those families condition 2 of
+Decision 4 is satisfied by the release being catalogued.
+
+**Rationale.** Verified: `/platforms?OSType=fmc` is not a supported query, and
+`/OS_version/OS_data?OSType=fmc` returns rows carrying only `nos_version`/`nos_type` with
+**no** `platform_name` field at all — unlike the asa and ftd rows. The spike's two FMC checks
+(`7.4.2.3`, `7.4.2.4`) each returned 6 advisories with no alias supplied. Code that assumes
+`platform_name` is always present will fail on FMC.
+
+---
+
+## Decision 9 — Known coverage gap: platforms Cisco has not yet given an alias
+
+**Decision.** Accept, document in the report, and treat as Needs review: devices whose
+platform exists in the release catalogue but has no alias in `/platforms`.
+
+**Rationale.** The two catalogues are out of step. Comparing them for the families in scope:
+
+| Family | Aliases offered | Platforms in the release catalogue with **no** alias |
+| --- | --- | --- |
+| `asa` | 9 | Secure Firewall 200, 1200, 4200, 6100 Series |
+| `ftd` | 8 | Secure Firewall 200, 1200, 4200, 6100 Series, Threat Defense Virtual |
+
+Cisco's *web* Software Checker offers the newer Secure Firewall series in its platform
+picker, so the API's alias list lags its own web tool. A device on a Secure Firewall 4200,
+for example, cannot be asked about with a platform at all today. The team's current inventory
+contains none of these, so nothing is lost now — but the gap will bite as they refresh
+hardware, and it must be visible in the report rather than silently degrading. This is the
+strongest argument for fetching `/platforms` per run (Decision 11): the gap closes on
+Cisco's schedule, with no tool release needed.
+
+---
+
+## Decision 10 — Pacing: one request per ~2.1 s, deduplicated by check
+
+**Decision.** Collapse the inventory to distinct (family, alias, release) checks, ask Cisco
+once per check, and pace requests at no more than one per 2.1 seconds.
+
+**Rationale.** The published quota is 5/second, 30/minute and 5,000/day; 30/minute is the
+binding constraint at roughly one request every two seconds. Deduplication is what makes the
+feature viable — the real 70-row inventory collapses to **27 checks**, plus 5 catalogue
+requests and 1 token request: 33 requests, ~70 seconds. Measured end-to-end at 2.5 s spacing
+during the spike: ~83 seconds, no throttling.
+
+Scaling honestly: a 1,000-row inventory whose rows collapse the same way (~2.6 rows per
+check) needs ~385 checks ≈ 14 minutes. The pathological case — 1,000 rows all distinct —
+needs 1,000 checks ≈ 35 minutes, still far inside the daily cap. Both are acceptable for an
+operator-initiated run, but neither is acceptable *silently*, which is why FR-051 requires
+progress reporting.
+
+**Alternatives considered.** Bursting to the 5/second ceiling — rejected; it exhausts the
+30/minute budget in six seconds and then stalls, making progress reporting misleading and
+risking `429`s. Parallel requests — rejected for the same reason, plus it buys nothing
+against a per-minute cap.
+
+---
+
+## Decision 11 — Catalogues fetched fresh each run, not cached between runs
+
+**Decision.** Fetch `/platforms` and `/OS_version/OS_data` for each family present in the
+inventory at the start of every run. Do not persist them.
+
+**Rationale.** The cost is a fixed 5 requests regardless of inventory size — about 4% of a
+70-row run and under 2% of a realistic 1,000-row run. In exchange, a newly published release
+or a newly aliased platform (Decision 9) is picked up immediately, and there is no cache
+invalidation question, no staleness bug class, and nothing new written to the user's disk.
+Caching would trade a correctness risk for a rounding error of quota.
+
+---
+
+## Decision 12 — Report generation: standard library only, escaping is load-bearing
+
+**Decision.** Generate the HTML report with standard-library string composition and
+`html.escape`, inlining all CSS and JavaScript into a single file. Escape every
+Cisco-supplied value at the point of interpolation, including advisory titles and any
+summary text.
+
+**Rationale.** Principle I is satisfied with no new dependency — a template engine would buy
+nothing here. Escaping is not hygiene theatre: **all 103 distinct advisories returned by the
+spike carried raw HTML in their `summary` field.** The observed tag set across them is
+`a`, `br`, `div`, `em`, `li`, `p`, `section`, `span`, `strong`, and one summary begins
+literally `\r\n<p>A vulnerability in the Internet Key Exchange...`. Interpolating that into a
+file an analyst opens in a browser would render externally-authored markup, including anchor
+tags pointing wherever Cisco's CMS put them. FR-033 exists for this reason, and the safest
+form is to not render Cisco summaries as markup at all — strip or escape, never pass through.
+
+Inlining is what makes FR-030 true: no CDN reference, so the report survives being emailed,
+archived, opened offline, or opened behind a restrictive proxy.
+
+**Alternatives considered.** Jinja2 or similar — rejected under Principle I; nothing in this
+report needs it. Linking a stylesheet or a table-sort library from a CDN — rejected; it breaks
+offline use and rots.
+
+---
+
+## Decision 13 — Secret entry: length confirmation now, per-keystroke masking deferred
+
+**Decision.** Keep the existing non-echoing prompt (`ui.ask_secret`, `getpass`-backed) for
+the client secret and add an immediate confirmation of how many characters were captured.
+Do not implement per-keystroke masking in this feature; the fallback clause of FR-039 is
+satisfied by the non-echoing prompt.
+
+**Rationale.** `getpass` cannot display a masking character — it disables echo wholesale.
+Per-keystroke masking requires reading the terminal raw (`termios`/`tty` on macOS and Linux,
+`msvcrt.getwch` on Windows) and then owning backspace, `Ctrl-C`, bracketed-paste escape
+sequences and the no-TTY fallback on three platforms. That is precisely the class of
+divergence Principle II treats as a correctness bug, and it is disproportionate to the need.
+The stated need is "did my paste land?", and a length confirmation answers it exactly —
+a truncated or empty paste is obvious immediately — on every terminal, in a few lines of
+code, with no platform-specific input handling. FR-038 (the MUST) is met; FR-039 (the SHOULD)
+is met by its documented fallback.
+
+**Alternatives considered.** Raw-terminal masking now — deferred, not refused; it can be
+added later behind the same interface without changing any other behaviour. Echoing the secret
+in clear text — rejected; it is a credential.
+
+---
+
+## Decision 14 — Verify credentials at setup, distinguishing rejection from unreachability
+
+**Decision.** After collecting both Cisco values, request a token. Report three distinct
+outcomes: accepted (state they are valid), rejected (surface Cisco's own reason, offer
+re-entry, do not save), unreachable (say so explicitly and offer to save unverified with a
+warning).
+
+**Rationale.** A token request is the cheapest possible proof and costs one request against a
+5,000/day budget. Separating rejection from unreachability is not a nicety: collapsing them
+would mean a proxy outage or blocked egress presents as "your credentials are invalid",
+leaving a user with correct credentials no way to complete setup. Failing closed on
+*configuration* would be a worse outcome than saving an unverified value with a clear
+warning, since the run itself re-validates anyway (FR-014).
+
+Cisco's error body must be surfaced without echoing request parameters — token endpoints
+commonly reflect input in error responses, and FR-049 forbids any credential fragment in
+output.
+
+---
+
+## Decision 15 — Module boundaries
+
+**Decision.** Three new modules, mirroring the existing one-concern-per-module layout, plus
+edits to three existing ones:
+
+| Module | Concern |
+| --- | --- |
+| `psirt.py` (new) | Token acquisition, paced requests, the three endpoints, status→outcome classification. The only module that talks to Cisco's API. |
+| `matching.py` (new) | Pure functions: release normalisation, model→alias mapping, catalogue lookups, verdict derivation. No I/O, so it is exhaustively unit-testable. |
+| `html_report.py` (new) | Report rendering and escaping. |
+| `analyzer.py` | Add the `--api` run flow beside the existing `run()`; reuse inventory loading and output-folder handling. |
+| `config.py` | Cisco credential keys, prompts, verification call-out. |
+| `cli.py` | `--api` flag, mutual-exclusion check, dispatch. |
+
+**Rationale.** Putting the verdict logic in a pure module is the difference between a feature
+that can be tested and one that can only be tested against Cisco's live API. Every rule from
+Decisions 3–9 becomes a table-driven unit test with no network. `psirt.py` parallels the
+existing `cisco.py` (CSAF/ERP) and `fuelix.py` (AI) — one module per external service, which
+is the layout the project already uses.
diff --git a/specs/006-api-inventory-check/spec.md b/specs/006-api-inventory-check/spec.md
new file mode 100644
index 0000000..6dd4c20
--- /dev/null
+++ b/specs/006-api-inventory-check/spec.md
@@ -0,0 +1,271 @@
+# Feature Specification: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+**Feature Branch**: `006-api-inventory-check`
+
+**Created**: 2026-07-25
+
+**Status**: Draft
+
+**Input**: BRD-003 — `brds/003-api-inventory-check.md` (Inventory-Driven Vulnerability Check via the Cisco PSIRT API, `caia --api`)
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Assess the whole inventory in one command (Priority: P1)
+
+An analyst has their firewall inventory in the folder they are working in and Cisco API access already available. They run the tool with the `--api` option and nothing else. The tool loads the inventory, asks Cisco which published advisories apply to each device's software release on that device's hardware model, and writes a single timestamped HTML report naming every firewall they own alongside a verdict of Impacted, Not impacted, or Needs review. No advisory link is required and no AI service is involved.
+
+Critically, a device is only ever called Not impacted when Cisco positively confirms both that it recognises the release and that the release runs on that model. Anything else is Needs review, never a claim of safety.
+
+**Why this priority**: This is the entire point of the feature and the minimum viable slice — it turns an exercise nobody performs (checking a thousand devices by hand in a web form) into one command. It carries the safety rule for negatives because a version of this that could report an unanswerable device as safe would be more dangerous than no report at all, so that rule cannot be deferred to a later slice.
+
+**Independent Test**: Run the tool with `--api` against a fixture inventory containing devices known to be affected, devices known to be clean, and devices whose release or model Cisco does not recognise. Confirm a report is produced, every inventory row appears exactly once with exactly one verdict, affected devices list their advisories, and no unanswerable device is labelled Not impacted.
+
+**Acceptance Scenarios**:
+
+1. **Given** a valid inventory and available Cisco API access, **When** the analyst runs the tool with `--api`, **Then** a new timestamped HTML report is created in the output folder and its location is reported to the analyst.
+2. **Given** a completed run, **When** the report is opened, **Then** every row of the source inventory appears exactly once, retains its original columns, and carries exactly one verdict.
+3. **Given** Cisco returns one or more advisories for a device's release on its model, **When** the verdict is assigned, **Then** the device is Impacted and those advisories are listed against it.
+4. **Given** Cisco confirms both the release and the model and returns no applicable advisories, **When** the verdict is assigned, **Then** and only then is the device Not impacted.
+5. **Given** Cisco does not recognise a device's release, or does not list that release as running on that device's model, **When** the verdict is assigned, **Then** the device is Needs review and never Not impacted.
+6. **Given** a request to Cisco fails or returns an answer the tool cannot interpret, **When** the verdict is assigned, **Then** the device is Needs review and never Not impacted.
+7. **Given** a report already exists in the output folder, **When** a new run writes its report, **Then** the existing report is left intact and the new report is written alongside it.
+8. **Given** many devices share the same product family, model and release, **When** the run executes, **Then** Cisco is asked once for that combination and the answer is applied to every device sharing it.
+9. **Given** the analyst runs the tool without `--api`, **When** it executes, **Then** the existing advisory-driven behaviour and its spreadsheet report are unchanged.
+10. **Given** the analyst supplies both `--api` and an advisory URL, **When** the tool starts, **Then** it reports that the two modes are mutually exclusive and makes no requests.
+
+---
+
+### User Story 2 - Know exactly why a device could not be assessed (Priority: P1)
+
+An analyst reads the report to decide what needs no action, and an inventory owner reads it to find what to correct. Every Needs review device states, in plain language, which situation applies: Cisco does not recognise the release at all; Cisco recognises the release but does not list it for that model; the model could not be identified as a Cisco hardware platform; a required inventory field is missing; the product family cannot be checked; or the check did not complete. Where Cisco does list the release for other models, those models are named, so the reader can see immediately whether the inventory records the wrong model or the wrong release.
+
+**Why this priority**: A feasibility check against the real inventory found 15 of 70 rows unanswerable — end-of-support releases Cisco has purged, and model/release pairings Cisco never shipped. A bare "Needs review" on a fifth of the fleet is noise that gets ignored; a specific, correctable reason turns the same rows into an actionable data-quality worklist, and is what makes the verdict trustworthy rather than merely cautious.
+
+**Independent Test**: Run against a fixture inventory containing one device of each unanswerable kind. Confirm each is Needs review, each carries a distinct reason naming its situation, and the release-not-listed case names the models Cisco does list for that release.
+
+**Acceptance Scenarios**:
+
+1. **Given** a device whose release Cisco does not recognise at all, **When** the report is read, **Then** it states that Cisco does not recognise that release, and shows the release as recorded in the inventory.
+2. **Given** a device whose release Cisco recognises but does not list for that device's model, **When** the report is read, **Then** it says so and names the models Cisco does list for that release.
+3. **Given** a device whose model cannot be identified as a Cisco hardware platform, **When** the report is read, **Then** it states that the model could not be identified.
+4. **Given** a device whose check did not complete, **When** the report is read, **Then** it states that the check did not complete for that device.
+5. **Given** a release recorded in operational shorthand rather than Cisco's canonical form, **When** it is checked, **Then** it is reconciled to Cisco's equivalent release and assessed, not reported as unrecognised.
+6. **Given** any Needs review device, **When** the report is read, **Then** its reason is understandable without consulting the tool's authors or its source code.
+
+---
+
+### User Story 3 - Act on the findings without leaving the report (Priority: P2)
+
+A patching engineer opens the report and narrows it to what matters — Impacted devices, highest priority first. For any device they expand its advisories and see, for each, how severe it is and which release fixes it. The advisory identifier links straight to Cisco's published advisory. All of this works from the file alone, including on a machine with no network access and after the file has been emailed on.
+
+**Why this priority**: Without this the report is a list of problems rather than a worklist. It is P2 because the verdicts themselves (P1) already carry the safety-critical information; this slice is what makes acting on them efficient rather than manual.
+
+**Independent Test**: Open a report produced from a fixture run on a machine with no network connection. Filter to Impacted, sort by the inventory's priority column, expand a device with many advisories, and confirm each advisory shows severity and fixed release and that its identifier is a link to Cisco.
+
+**Acceptance Scenarios**:
+
+1. **Given** the report is open, **When** the reader filters by verdict, **Then** only devices with that verdict remain visible.
+2. **Given** the report is open, **When** the reader sorts by the inventory's priority column, **Then** the rows reorder accordingly.
+3. **Given** a device with many advisories, **When** its detail is collapsed, **Then** the device's row remains readable at a glance, and expanding it reveals the full advisory list.
+4. **Given** a listed advisory, **When** the reader looks at it, **Then** its identifier, title and severity are shown, its identifier links to Cisco's published advisory, and the release that first fixes it is shown whenever Cisco supplies one.
+5. **Given** the report file has been copied or emailed to another machine with no network access, **When** it is opened, **Then** its layout, filtering, sorting and expanding all still work.
+
+---
+
+### User Story 4 - Set up and validate Cisco API access once (Priority: P2)
+
+An analyst runs the tool's configuration command. In one linear pass it prompts for everything the tool uses, including the two Cisco API values. The client identifier is shown as they paste it; the client secret is not displayed, and immediately after entry the tool confirms that a value was captured and how many characters it held, so a truncated paste is obvious. Any prompt can be skipped by someone who does not need it. Once both Cisco values are in hand, the tool checks them against Cisco and says plainly whether they work — and if Cisco cannot be reached at all, it says that instead of calling them invalid, and lets them be saved unverified. Later runs from any folder find them without re-entry.
+
+**Why this priority**: Setup is a precondition for the feature, but it is P2 because a run can be exercised with Cisco access supplied through the environment, so the primary slice can be built and tested before the guided flow exists. Validating at setup rather than mid-run is what keeps a bad paste from being discovered as a failed run against a thousand devices.
+
+**Independent Test**: Run the configuration command with no Cisco values saved. Confirm both are prompted, the identifier echoes and the secret does not, the length confirmation appears, correct values report as valid, deliberately wrong values report Cisco's reason and offer re-entry, and an unreachable Cisco reports distinctly and permits saving unverified.
+
+**Acceptance Scenarios**:
+
+1. **Given** the analyst runs the configuration command, **When** the flow runs, **Then** it prompts for the Cisco client identifier and the Cisco client secret alongside the settings it already collects, and saves them to the per-user configuration.
+2. **Given** the analyst is prompted for the client identifier, **When** they paste it, **Then** it is displayed as entered; **and given** they are prompted for the client secret, **When** they paste it, **Then** it is not displayed in readable form.
+3. **Given** a secret has just been entered, **When** the prompt completes, **Then** the tool confirms a value was captured and how many characters it contained, without revealing the value.
+4. **Given** a Cisco value is already saved, **When** the analyst is prompted for it, **Then** the tool indicates a value exists and an empty response leaves it unchanged.
+5. **Given** both Cisco values are available, **When** Cisco accepts them, **Then** the tool states plainly that the credentials are valid.
+6. **Given** both Cisco values are available, **When** Cisco rejects them, **Then** the tool reports the reason Cisco gave, offers to enter them again, and does not silently save the rejected values.
+7. **Given** both Cisco values are available, **When** Cisco cannot be reached at all, **Then** the tool distinguishes this from a rejection and lets the analyst save the values unverified with a clear warning.
+8. **Given** the analyst skipped the Cisco prompts, **When** the flow completes, **Then** no verification request is made to Cisco.
+9. **Given** verification succeeds, fails, or cannot run, **When** any message is shown, **Then** it contains no part of either credential value.
+10. **Given** Cisco values were saved by the configuration command, **When** the analyst runs `--api` from a different folder, **Then** the run proceeds without re-entering them.
+11. **Given** the analyst uses only the advisory-driven mode, **When** they run the configuration command, **Then** they can complete it without supplying Cisco values, and that mode still runs.
+12. **Given** the analyst uses only `--api`, **When** they run it, **Then** it does not require the AI service key to be configured.
+13. **Given** no Cisco values are available, **When** the analyst runs `--api`, **Then** the tool refuses to run, names what is missing, directs them to the configuration command, and makes no requests to Cisco.
+14. **Given** the saved values are rejected by Cisco, **When** a run starts, **Then** the tool reports an authentication problem distinctly from "no advisories apply" and produces no verdicts.
+
+---
+
+### User Story 5 - Judge how far to trust a report you did not run (Priority: P3)
+
+A team lead receives a report second-hand. Before acting on it they can see when it ran, which inventory file it came from, how many devices were assessed, and the count for each verdict — including how many could not be assessed at all. The same summary states the known limits of the underlying Cisco data: that it holds no advisories published before Cisco's per-family cut-off dates, and that a verdict reflects whether a release is listed as affected, not whether a vulnerable feature is switched on.
+
+**Why this priority**: It prevents the most likely misuse of the report — treating it as a complete and exploitability-aware picture. It is P3 because the report is still correct without it; this slice makes it correctly *interpreted*.
+
+**Independent Test**: Open a report from a fixture run and confirm the summary carries the run timestamp, the inventory filename, the device count, a count per verdict, and both coverage statements — without reading any device row.
+
+**Acceptance Scenarios**:
+
+1. **Given** any report, **When** it is opened, **Then** it shows the run date and time, the inventory file used, the number of devices assessed, and a count for each verdict.
+2. **Given** any report, **When** it is read, **Then** it states that the underlying Cisco data excludes advisories published before Cisco's per-family cut-off dates.
+3. **Given** any report, **When** it is read, **Then** it states that a verdict does not account for whether a vulnerable feature is enabled on the device.
+4. **Given** a report containing Needs review devices, **When** it is read, **Then** their count is visible in the summary rather than only discoverable row by row.
+
+---
+
+### Edge Cases
+
+- **A release genuinely absent from Cisco's catalogue while a shorter form of it exists.** The tool does not substitute a different release than the device runs; the device is Needs review. A verdict obtained by asking about a release the device is not running would be a guess.
+- **A model that maps to no Cisco hardware platform.** The device is Needs review; the tool does not fall back to a platform-agnostic question whose answer could apply to hardware the device is not.
+- **A product family the mode cannot check.** Every device in that family is Needs review with that stated reason; the run still completes for the rest.
+- **An inventory row with a blank or missing release, or a blank model.** Needs review, naming the missing field.
+- **An empty inventory, or one with no usable rows.** The run stops with an actionable message rather than producing an empty report.
+- **Every device ends as Needs review.** The run is a success — a report was produced — and the summary makes the wholly inconclusive result obvious. Exit status reflects whether the run completed, not what the verdicts were.
+- **Cisco becomes unreachable partway through a run.** Devices already answered keep their verdicts; the remainder are Needs review stating the check did not complete, and the report discloses that the run was partial.
+- **Cisco's request quota is reached mid-run.** Treated as an incomplete check: remaining devices are Needs review and the report says the run was cut short.
+- **Cisco returns a response shape the tool does not recognise.** Needs review rather than a guessed verdict.
+- **A device impacted by a very large number of advisories.** The device's row stays readable and the full list remains reachable; the report does not silently truncate it.
+- **Two runs completing within the same second.** Both reports survive; neither overwrites the other.
+- **The output folder does not exist or cannot be written.** The tool reports the problem and the path it attempted, rather than losing the run's results silently.
+- **The analyst interrupts a long run.** The tool stops promptly and signals interruption through its exit status.
+- **A credential present but empty, or carrying surrounding whitespace.** Treated as not supplied rather than sent to Cisco as-is.
+- **Advisory text from Cisco containing markup or scripting.** Rendered as text; it cannot alter the report's structure or behaviour.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**Mode and invocation**
+
+- **FR-001**: The tool MUST provide an `--api` option that assesses the loaded inventory against Cisco's published advisory data per device, requiring no advisory or Event Response URL.
+- **FR-002**: The tool MUST leave the existing advisory-driven mode, including its spreadsheet report, unchanged in behaviour and output when `--api` is not supplied.
+- **FR-003**: The tool MUST treat `--api` and the advisory-driven mode as mutually exclusive, reporting an actionable message and making no requests when both are requested in one invocation.
+- **FR-004**: The `--api` mode MUST honour the tool's existing inventory-selection and output-location options, so a run can be fully flag-driven without interactive input.
+- **FR-005**: The `--api` mode MUST make no call to the AI service and MUST NOT require the AI service credential.
+- **FR-006**: The tool SHOULD offer a way to exercise an `--api` run without contacting Cisco — resolving each device to the check that would be made and reporting it — so the flow can be verified cheaply and offline.
+
+**Verdict assignment and integrity**
+
+- **FR-007**: The tool MUST assign every row of the inventory exactly one verdict from: Impacted, Not impacted, Needs review.
+- **FR-008**: The tool MUST classify a device Impacted only when Cisco returns at least one advisory applying to that device's release on that device's hardware platform.
+- **FR-009**: The tool MUST classify a device Not impacted only when Cisco positively confirms both that it recognises the release and that it lists that release for the device's hardware platform, and returns no applicable advisories.
+- **FR-010**: The tool MUST classify a device Needs review whenever a trustworthy verdict cannot be established, and MUST NOT classify such a device Not impacted.
+- **FR-011**: The tool MUST distinguish, in the reason recorded for a Needs review device, at least these situations: the release is not in Cisco's catalogue; the release is in the catalogue but not listed for that platform; the model could not be identified as a Cisco platform; a required inventory field is missing; the product family cannot be checked; and the check did not complete.
+- **FR-012**: When a release is not listed for a device's platform, the tool MUST name the platforms Cisco does list for that release.
+- **FR-013**: The tool MUST NOT substitute a different release, or a platform-agnostic question, in place of the device's actual release and platform in order to obtain a verdict.
+- **FR-014**: The tool MUST distinguish an authentication, connectivity, or quota failure from a "no advisories apply" answer, and MUST NOT derive any Not impacted verdict from a failed or incomplete exchange.
+- **FR-015**: The tool MUST treat a response it cannot interpret as Needs review rather than inferring a verdict from it.
+- **FR-016**: When a run cannot assess every device, the tool MUST still produce a report for the devices it did assess, mark the remainder Needs review, and disclose in the report that the run was partial.
+
+**Reconciling the inventory with Cisco's data**
+
+- **FR-017**: The tool MUST reconcile inventory release strings recorded in operational shorthand with Cisco's canonical release identifiers, including releases carrying a companion-product annotation or a build suffix.
+- **FR-018**: The tool MUST determine each device's Cisco hardware platform from its inventory model.
+- **FR-019**: The tool MUST obtain, from Cisco at run time rather than from a fixed built-in list, the set of valid hardware platforms per product family and the set of releases Cisco recognises together with the platforms each runs on.
+- **FR-020**: The tool MUST ask Cisco once per distinct combination of product family, hardware platform and release, and apply that answer to every device sharing the combination.
+- **FR-021**: The tool MUST continue to tolerate minor variation in the inventory's column headings, as it does today.
+
+**Report content and behaviour**
+
+- **FR-022**: The tool MUST produce exactly one self-contained report per run, readable in a web browser, written to the tool's output folder with a timestamped name.
+- **FR-023**: The tool MUST never overwrite an existing report, including when two runs complete within the same second.
+- **FR-024**: The report MUST list every analysed device exactly once, retaining the inventory's original columns, alongside its verdict.
+- **FR-025**: The report MUST list, for each Impacted device, the advisories that justify the verdict, and MUST NOT silently truncate that list.
+- **FR-026**: The report MUST show, for each listed advisory, its identifier, its title, its severity, and a link to Cisco's published advisory, and MUST show the release that first fixes it whenever Cisco supplies one.
+- **FR-027**: The report SHOULD show the CVE identifiers Cisco associates with each listed advisory.
+- **FR-028**: The report MUST state, for each Needs review device, the reason it could not be assessed.
+- **FR-029**: The report MUST let a reader filter by verdict, sort by the inventory's priority column, and expand or collapse a device's advisory detail, using the file alone with no external tool and no network access.
+- **FR-030**: The report MUST render and remain fully functional after being copied or emailed to another machine, and when opened with no network connectivity.
+- **FR-031**: The report MUST state the run date and time, the inventory file used, the number of devices assessed, and a count for each verdict.
+- **FR-032**: The report MUST state that the underlying Cisco data excludes advisories published before Cisco's per-family cut-off dates, and that a verdict does not account for whether a vulnerable feature is enabled.
+- **FR-033**: The tool MUST render all content received from Cisco as text, such that it cannot alter the report's structure, styling, or behaviour.
+
+**Credentials and configuration**
+
+- **FR-034**: The configuration command MUST prompt for the Cisco client identifier and the Cisco client secret alongside the settings it already collects, in a single linear pass.
+- **FR-035**: The configuration command MUST allow any individual prompt to be skipped, and MUST NOT require a value for a mode the user does not use.
+- **FR-036**: Each mode MUST require only its own credentials: `--api` MUST NOT require the AI service key, and the advisory-driven mode MUST NOT require Cisco credentials.
+- **FR-037**: The configuration command MUST display the Cisco client identifier as it is entered, and MUST NOT display the Cisco client secret in readable form.
+- **FR-038**: The configuration command MUST confirm, immediately after a secret is entered, that a value was captured and how many characters it contained, without revealing the value.
+- **FR-039**: The configuration command SHOULD give visible feedback while a secret is being entered where the terminal supports it, and MUST fall back to a non-displaying prompt where it does not.
+- **FR-040**: The configuration command MUST indicate when a Cisco value is already saved, and MUST leave it unchanged when the user submits an empty response.
+- **FR-041**: The configuration command MUST verify the Cisco credentials with Cisco before completing, and MUST state plainly whether they are valid.
+- **FR-042**: When Cisco rejects the credentials, the configuration command MUST report the reason Cisco gave, MUST offer to enter them again, and MUST NOT silently save the rejected values.
+- **FR-043**: When Cisco cannot be reached to verify, the configuration command MUST distinguish this from a rejection and MUST allow the values to be saved unverified with a clear warning, so a network or proxy outage never prevents configuration.
+- **FR-044**: The configuration command MUST attempt verification only when both Cisco values are available for the session, and MUST make no request to Cisco when those prompts were skipped.
+- **FR-045**: The tool MUST store the Cisco credentials in the same per-user configuration it already uses, with the same protection, so later runs from any folder find them without re-entry.
+- **FR-046**: The tool MUST continue to honour Cisco credentials supplied through the environment, taking precedence over saved values.
+- **FR-047**: The tool MUST treat an empty or whitespace-only credential as not supplied.
+- **FR-048**: The tool MUST refuse to start an `--api` run when Cisco credentials are unavailable, naming what is missing, directing the user to the configuration command, and making no requests to Cisco.
+- **FR-049**: The tool MUST NOT display, log, or write any part of a credential value — in the report, in printed output, in an error or warning message, or in any filename it creates.
+
+**Run behaviour, pacing and outcome**
+
+- **FR-050**: The tool MUST operate within Cisco's published request quotas for a full-inventory run, pacing its own requests rather than relying on the user to throttle.
+- **FR-051**: The tool MUST report progress during a run so a full-inventory run does not appear stalled.
+- **FR-052**: The tool MUST signal the outcome of a run through its exit status, distinguishing a completed run from a failure, and MUST signal interruption distinctly when the analyst stops a run.
+- **FR-053**: The tool MUST treat a run in which every device ends as Needs review as a completed run rather than a failure, provided a report was written.
+- **FR-054**: The tool MUST report an actionable message, naming the path it attempted, when the output folder cannot be created or written.
+- **FR-055**: The tool MUST stop with an actionable message, rather than producing an empty report, when the inventory has no usable rows.
+
+**Documentation**
+
+- **FR-056**: The documentation MUST explain that `--api` produces a browser-readable report while the default mode produces a spreadsheet, and why the two modes answer different questions.
+- **FR-057**: The documentation MUST list the Cisco API credentials among the prerequisites a new user obtains before first use, and MUST show the configuration command as the way to supply them.
+
+### Key Entities
+
+- **Device**: One row of the user's inventory. Carries a name, a model, a product family, a software release, and a priority. Every device receives exactly one verdict and, where applicable, a reason.
+- **Check**: A distinct combination of product family, hardware platform and release, derived from one or more devices. The unit Cisco is actually asked about, so identical devices cost one question rather than many.
+- **Verdict**: One of Impacted, Not impacted, or Needs review. Not impacted asserts that Cisco confirmed the device is clean; Needs review asserts nothing about safety and always carries a reason.
+- **Reason**: The plain-language explanation attached to a Needs review verdict, identifying which situation applies and, where relevant, the platforms Cisco does list for the release.
+- **Advisory**: A published Cisco security notice associated with a Check. Carries an identifier, a title, a severity, CVE identifiers, a link to its published page, and the release that first fixes it.
+- **Platform catalogue**: The set of hardware platforms Cisco recognises per product family, retrieved at run time, used to map an inventory model to something Cisco can be asked about.
+- **Release catalogue**: The set of releases Cisco recognises together with the platforms each runs on, retrieved at run time, used to tell an unrecognised release apart from a release that never shipped on that model.
+- **Report**: The single self-contained per-run artifact. Carries the run summary, the coverage statements, and one entry per device with its verdict, reason and advisories.
+- **Cisco credentials**: A client identifier and a client secret, held in the per-user configuration or the environment, used only to obtain access to Cisco's advisory data and never surfaced in output.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: An analyst can assess the entire firewall inventory with a single command and no advisory link, producing one report.
+- **SC-002**: 100% of inventory rows appear in the report exactly once with exactly one verdict; no row is silently dropped.
+- **SC-003**: 0% of devices whose release or model Cisco does not recognise are reported as Not impacted.
+- **SC-004**: 100% of Needs review devices carry a reason identifying which situation applies, understandable without consulting the tool's authors.
+- **SC-005**: 100% of Impacted devices list at least one advisory, and every listed advisory carries a working link to its published Cisco page.
+- **SC-006**: Every listed advisory for which Cisco supplies a fixed release shows that release, so an engineer obtains the remediation target without a further lookup.
+- **SC-007**: A run against an inventory of approximately 1,000 devices completes within Cisco's request quotas and produces a complete report.
+- **SC-008**: An inventory of approximately 1,000 devices results in substantially fewer questions to Cisco than it has rows, because identical devices are asked about once.
+- **SC-009**: Repeated runs never overwrite an earlier report; each run leaves a distinct, durable file.
+- **SC-010**: A report renders, filters, sorts and expands correctly when opened with no network access and after being copied to another machine.
+- **SC-011**: No credential value appears in any report, printed output, message, or filename, across successful, failed and interrupted runs.
+- **SC-012**: A run started without Cisco credentials, or with credentials Cisco rejects, produces a clear diagnostic and no verdicts.
+- **SC-013**: A new user can go from having their Cisco credentials in hand to a completed `--api` run using only the configuration command and the run command, without creating a file or setting an environment variable.
+- **SC-014**: A user of only one mode can configure and run that mode without supplying the other mode's credentials.
+- **SC-015**: A wrong, truncated, or expired Cisco credential is detected during configuration rather than on a later run, and the user is told why.
+- **SC-016**: Configuration remains completable when Cisco cannot be reached, with the unverified state disclosed rather than the setup being blocked.
+- **SC-017**: After entering the client secret, a user can tell from the confirmation alone whether their paste landed intact, without the value being displayed.
+- **SC-018**: Every report states its coverage limits, so a reader who did not run it can judge how far to trust it.
+- **SC-019**: A partial run is never presented as complete: the report discloses that some devices were not assessed.
+- **SC-020**: Running the tool without `--api` produces the same result it did before this feature existed.
+
+## Assumptions
+
+- **Credential source.** Because the tool is installed as a command run from arbitrary working folders, the interactive configuration command is in practice the only credential path a user exercises. A working-folder environment file is an automation convenience this feature does not rely on; environment variables remain honoured but are not the expected route.
+- **Credential ownership.** Each user obtains their own Cisco API client identifier and secret from Cisco's developer portal, exactly as each user already obtains their own AI service key. The tool does not provision or share them.
+- **Inventory shape.** The inventory keeps its current form: one row per firewall with a name, model, product family, software release and priority, in a user-provided spreadsheet located in the working folder.
+- **Families covered first.** The product families present in the inventory today — ASA, FTD and FMC — are the families this mode must handle. Devices in any family the mode cannot check become Needs review with that reason, so the run still completes; extending coverage to further families Cisco supports is a later increment.
+- **No release substitution.** When a device's release is absent from Cisco's catalogue, the tool does not fall back to asking about a shorter or nearby release. This follows the project's non-negotiable conservative-analysis principle: a verdict obtained by asking about a release the device is not running would be a guess. The device is Needs review instead — honest, but it will produce Needs review rows for end-of-support releases Cisco has purged.
+- **No platform-agnostic fallback.** Likewise, a model that maps to no Cisco platform is Needs review rather than being asked about without a platform, since a platform-agnostic answer could reflect hardware the device is not.
+- **Catalogues fetched per run.** The platform and release catalogues are retrieved fresh on each run rather than cached between runs, so a newly published release is never missed. Their cost is a small fixed number of questions independent of inventory size.
+- **Identical devices share a verdict.** Devices with the same product family, platform and release receive the same answer, so one question serves many devices and a large inventory collapses to far fewer questions than rows.
+- **Cisco is the authority.** Cisco's published data decides whether a release on a platform is affected. The tool reports that answer and does not second-guess it, which also means the mode inherits Cisco's coverage cut-offs.
+- **Impacted is not exploitability.** An Impacted verdict means the release on that platform is listed as affected. Whether the vulnerable feature is switched on is not knowable from the inventory and is out of scope; the report says so.
+- **Report is opened by the user.** The tool writes a file and reports its location; it does not launch a browser or host the report. Reports accumulate in the output folder as they do today.
+- **Verdict vocabulary.** This mode uses Needs review for an undecidable device, whereas the existing mode's report uses Indeterminate for the same underlying idea. Both express the conservative posture the project's analysis principle requires; aligning the vocabulary across the two modes, or recording the divergence deliberately, is a governance item for the planning phase rather than a change in behaviour here.
+- **New external endpoints.** This mode contacts Cisco authentication and advisory endpoints the tool does not contact today. The project's constraints treat any additional endpoint the analyzer contacts as a reviewed change, so the planning phase must record these before implementation.
+- **Offline verification.** FR-006 (exercising a run without contacting Cisco) derives from the project's existing quality gate that user-facing changes to analysis flow should be verifiable without network calls. It was not requested in the BRD, but it keeps this mode testable on the same terms as the existing one.
diff --git a/specs/006-api-inventory-check/tasks.md b/specs/006-api-inventory-check/tasks.md
new file mode 100644
index 0000000..7929b93
--- /dev/null
+++ b/specs/006-api-inventory-check/tasks.md
@@ -0,0 +1,282 @@
+---
+
+description: "Task list for spec 006 — inventory-driven vulnerability check via the Cisco PSIRT API"
+---
+
+# Tasks: Inventory-Driven Vulnerability Check via the Cisco PSIRT API
+
+**Input**: Design documents from `/specs/006-api-inventory-check/`
+
+**Prerequisites**: [plan.md](./plan.md), [spec.md](./spec.md), [research.md](./research.md), [data-model.md](./data-model.md), [contracts/](./contracts/), [quickstart.md](./quickstart.md)
+
+**Tests**: Included, and **not optional** for this feature. The constitution's Development Workflow gate requires that "changes to CSAF/ERP parsing or *inventory matching* MUST add or update tests covering the new behavior" — this feature is entirely inventory matching. `plan.md` commits to `tests/test_matching.py`, `tests/test_psirt.py`, `tests/test_html_report.py` plus extensions to `tests/test_config.py` and `tests/test_cli.py`, and `quickstart.md` names the automated suite as the primary validation.
+
+**Constitution amendment**: already applied (2.1.0 → 2.2.0, commit `cb6938a`). It is **not** a task below.
+
+**Organization**: Tasks are grouped by user story. The safety-critical logic lives in one pure, I/O-free module (`matching.py`) so all ten rows of the [outcome table](./data-model.md#check-outcome--verdict-state-map) are provable by unit test with no network. US1 is a genuinely shippable MVP; each later story is an independently testable increment on top of it.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel — a different file from other concurrent tasks, with no dependency on incomplete work
+- **[Story]**: Which user story the task belongs to (US1–US5)
+- Exact file paths are given in every task
+
+## Path Conventions
+
+Single-project CLI. Package is `cisco_advisory_impact_agent/`, tests are `tests/`, both at the repository root — per [plan.md § Project Structure](./plan.md#source-code-repository-root).
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: Establish a clean baseline and the fixtures every later phase tests against
+
+- [X] T001 Establish a green baseline: run `python -m unittest discover -s tests` from the repo root (the command CI uses; pytest is not a project dependency) and confirm the existing suite passes. Confirm no new runtime dependency is required (standard library only, per plan.md Technical Context and Constitution I).
+- [X] T002 [P] Add `impact_report_*.html` to `.gitignore` beside the existing `analysis_output_*.xlsx` entry. `/output/` is already ignored, but the explicit pattern also covers reports written elsewhere via `--output-dir` (Constitution V requires generated reports stay out of the repo).
+- [X] T003 [P] Create `tests/fixtures/__init__.py` and `tests/fixtures/inventory.py` exposing a helper that builds an in-memory/temp-dir `.xlsx` inventory covering every verdict path required by [quickstart.md § Fixture inventory](./quickstart.md#fixture-inventory): one row per reason kind, one FMC row, one parenthetical-shorthand release, one `/ASDM`-annotated release, one `-nn` build-suffix release, and two rows sharing a family/platform/release so deduplication is observable.
+- [X] T004 [P] Create `tests/fixtures/psirt_responses.py` with canned payloads copied from the spike-verified shapes in [contracts/psirt-access.md](./contracts/psirt-access.md): a token response; `/platforms` for `asa` and `ftd`; `/OS_version/OS_data` for `asa`, `ftd` and `fmc` (the `fmc` rows **must omit** `platform_name` entirely, per research Decision 8); and the four `/OSType` outcomes — `200` with advisories (including `platforms[].firstFixes` and a `summary` containing raw HTML), `404 NO_DATA_FOUND`, `406 INVALID_ASA_VERSION`, and `429`.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: The pure matching layer, the API client, credential storage, and CLI wiring. Every user story depends on these.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+### Pure matching layer — `cisco_advisory_impact_agent/matching.py` (new)
+
+- [X] T005 [P] Create `cisco_advisory_impact_agent/matching.py` with `normalize_release(raw)`: apply research Decision 6's three ordered steps — drop any trailing companion-product annotation after `/`, rewrite `(n)` as `.n.`, strip a trailing `-nn` build suffix — then collapse repeated dots and trim. Must map `9.16(4)67`→`9.16.4.67`, `9.20(4)`→`9.20.4`, `9.20(4)7/ASDM 7.22.1`→`9.20.4.7`, `7.4.2.1-30`→`7.4.2.1`.
+- [X] T006 Add `platform_alias_for(model, family)` to `cisco_advisory_impact_agent/matching.py`: ordered pattern rules per the research Decision 7 table, returning `None` for platform-less families (FMC) and a distinct "unmapped" signal otherwise. Must be family-aware — the same 5500-X hardware is `ASA5500X` under ASA and `ASA5500` under FTD.
+- [X] T007 Add catalogue index builders to `cisco_advisory_impact_agent/matching.py`: `index_platforms(rows)` → alias→display-name, and `index_releases(rows)` → release→set of platform names, grouping `/OS_version/OS_data` rows on `nos_version`. Must tolerate rows with **no** `platform_name` key (FMC) rather than raising. Include the documented alias↔catalogue-name equivalence set for the known `FPRNGFW` mismatch (research Decision 5) as a noise-reducing optimisation only — never as a correctness dependency.
+- [X] T008 Add `Verdict` and `ReasonKind` constants plus `classify(device, catalogues, api_outcome)` to `cisco_advisory_impact_agent/matching.py`, implementing all ten rows of the [outcome table](./data-model.md#check-outcome--verdict-state-map) in order. Rows 1–3 resolve locally with no request. Every unhandled or ambiguous path must fail **closed** to `Needs review`; `Not impacted` is reachable only via row 8, requiring rows 5–7 to have been ruled out (Constitution IV positive-confirmation rule, FR-009, FR-010).
+- [X] T009 [P] Add `tests/test_matching.py`: table-driven cases for `normalize_release` (every transform in T005 plus idempotence and already-canonical input), `platform_alias_for` (all 22 real-inventory models from the research Decision 7 table, the ASA/FTD asymmetry, an unmappable model, and FMC→`None`), the catalogue indexers (including the FMC no-`platform_name` shape), and **one case per row of the outcome table**. Add an explicit regression asserting that an unreconcilable platform name yields `Needs review` and never `Not impacted`.
+
+### API client — `cisco_advisory_impact_agent/psirt.py` (new)
+
+- [X] T010 [P] Create `cisco_advisory_impact_agent/psirt.py` with error types (`PsirtAuthError` for rejected credentials, `PsirtUnreachableError` for transport failure — the two must be distinguishable per FR-043) and `fetch_token(client_id, client_secret)` performing the form-encoded client-credentials POST to `https://id.cisco.com/oauth2/default/v1/token` and returning the bearer token. Exception messages must never include any part of a credential (FR-049) — Cisco's error body is surfaced without echoing request parameters.
+- [X] T011 Add paced request plumbing to `cisco_advisory_impact_agent/psirt.py`: an `Outcome` result type and a `_get(path, params)` helper that spaces requests at no more than one per ~2.1 s (research Decision 10, the binding 30/min quota), re-fetches the token **once** on an authentication failure mid-run (Decision 2), and classifies the response by status and `errorCode` — never by message text — into `HAS_ADVISORIES` / `NO_DATA` / `INVALID_VERSION` / `INCOMPLETE`, mapping `429` and any unexpected status to `INCOMPLETE`.
+- [X] T012 Add the three endpoint functions to `cisco_advisory_impact_agent/psirt.py`: `get_platforms(os_type)`, `get_os_data(os_type)` and `get_advisories(os_type, release, platform_alias=None)`. `platform_alias` must be **omitted** from the query for families that do not accept it (`fmc`, `ios`, `iosxe`, `aci`) per Decision 8.
+- [X] T013 [P] Add `tests/test_psirt.py` using `tests/fixtures/psirt_responses.py` with `urllib.request.urlopen` patched: status→`Outcome` classification for all four canned outcomes plus `429`; pacing enforced (assert the sleep interval, with time patched — no real waiting); token fetched once per run and re-fetched exactly once on an auth failure; `platform_alias` omitted for FMC; and no credential fragment present in any raised exception's text.
+
+### Credential storage — `cisco_advisory_impact_agent/config.py`
+
+- [X] T014 Add `CISCO_CLIENT_ID` and `CISCO_CLIENT_SECRET` to `cisco_advisory_impact_agent/config.py`: define the key constants, add them to `KEYS` so `save()` persists them, and update the comment header written by `save()` to name the new keys and note that environment variables override them. Ensure `resolve()` treats a whitespace-only value as absent (FR-047).
+- [X] T015 [P] Extend `tests/test_config.py`: the two new keys round-trip through `save()`/`load_file()`; `resolve()` honours environment precedence over the file for both; whitespace-only values resolve as absent; and the written file's permissions match the existing config file's (Constitution V).
+
+### CLI wiring — `cisco_advisory_impact_agent/cli.py`
+
+- [X] T016 [P] Add the `--api` mode flag to `build_parser()` in `cisco_advisory_impact_agent/cli.py`, with help text sitting beside `--url`, stating it checks the inventory against Cisco's published advisory data and needs no URL.
+- [X] T017 Route `--api` in `cisco_advisory_impact_agent/cli.py`: within `cmd_run(args)`, dispatch to `analyzer.run_api(args)` when `args.api` is set, leaving the existing advisory-driven path untouched when it is not (FR-002). `run_api` itself is implemented in US1 (T018). Confirm the existing mode-precedence chain in `_dispatch()` (version → update → uninstall → config → run) is unchanged.
+
+**Checkpoint**: The matching rules are unit-tested with no network, the API client classifies every response shape, credentials persist, and `caia --api` parses and routes.
+
+---
+
+## Phase 3: User Story 1 - Assess the whole inventory in one command (Priority: P1) 🎯 MVP
+
+**Goal**: `caia --api` loads the inventory, asks Cisco once per distinct check, assigns every device one of three verdicts — never calling an unanswerable device safe — and writes one timestamped self-contained HTML report.
+
+**Independent Test**: With `psirt` mocked from `tests/fixtures/psirt_responses.py`, run `analyzer.run_api` against the fixture inventory: assert a report file is created, every inventory row appears exactly once with exactly one verdict, a `200`-with-advisories check yields Impacted, the unanswerable fixture rows yield Needs review and **never** Not impacted, and N rows sharing a check produce exactly one request.
+
+### Implementation for User Story 1
+
+- [X] T018 [US1] Implement `run_api(args)` in `cisco_advisory_impact_agent/analyzer.py`: preconditions in the order given by [contracts/api-run-cli.md](./contracts/api-run-cli.md#preconditions-in-order) → acquire token → fetch catalogues for each family present → collapse to checks → query paced → `matching.classify` each device → write the report → print its path. Reuse the existing `resolve_inventory()`, `inv.load_inventory()`, `ensure_dirs()` and `default_output_dir()` rather than duplicating them. Make no call to `fuelix` (FR-005).
+- [X] T019 [US1] Add the mutual-exclusion guard to `cisco_advisory_impact_agent/cli.py`: `--api` supplied together with `--url` reports an actionable message naming both flags, makes **no** request to Cisco or the AI service, and returns non-zero (FR-003, US1 AS10). `--api` must never prompt for a URL.
+- [X] T020 [US1] Add the credential precondition to `run_api` in `cisco_advisory_impact_agent/analyzer.py`: resolve both Cisco values via `config.resolve()`; if either is absent, name which one, direct the user to `caia --config`, make no request, and return non-zero (FR-048). Do **not** require or read the AI service key (FR-005, FR-036).
+- [X] T021 [US1] Add check deduplication to `cisco_advisory_impact_agent/matching.py`: `build_checks(devices)` grouping devices by `(os_type, platform_alias, release)` and returning both the distinct checks and the device back-references, so one answer serves every device sharing it (FR-020, SC-008). Devices that cannot form a check identity are returned separately for local resolution.
+- [X] T022 [US1] Create `cisco_advisory_impact_agent/html_report.py` with `write_report(devices, summary, output_dir)`: emit a single self-contained file named `impact_report_<YYYYMMDD_HHMMSS>.html`, appending `_1`, `_2`, … on collision so an existing report is never overwritten (FR-022, FR-023). Render the inventory's original columns verbatim plus a verdict column. Escape **every** Cisco-supplied value with `html.escape` at the point of interpolation (FR-033) — all 103 advisories in the spike carried raw HTML in `summary`. Inline all CSS; reference no external resource (FR-030).
+- [X] T023 [US1] Add progress reporting to `run_api` in `cisco_advisory_impact_agent/analyzer.py` via the existing `ui` helpers: devices loaded, distinct checks to perform, and advancement through them (FR-051). A full-inventory run takes minutes (research Decision 10), so it must not appear stalled. Never emit a credential value (FR-049).
+- [X] T024 [P] [US1] Create `tests/test_html_report.py`: filename matches the contracted pattern; a second write in the same second produces a second file and leaves the first byte-identical; row count equals the fixture's usable row count; an advisory `title`/`summary` containing `<script>alert(1)</script>` and an `<a href>` renders as visible text with no live element; and the file contains no `http://`/`https://` reference to a stylesheet, script or font.
+- [X] T025 [P] [US1] Extend `tests/test_cli.py`: `--api` parses; `--api --url ...` exits non-zero with zero requests issued; a missing client secret exits non-zero with a message naming it and `caia --config`, having issued zero requests; and a run with valid Cisco credentials but **no** AI key proceeds.
+- [X] T026 [P] [US1] Create `tests/test_api_flow.py` exercising `analyzer.run_api` with `psirt` patched from the fixtures: every fixture row appears exactly once with exactly one verdict; a `200` check yields Impacted with its advisories attached; deduplication issues exactly one request for the shared-check rows; a run where every device is Needs review still writes a report and exits 0 (FR-053); and no fixture row that is unanswerable is ever labelled Not impacted (SC-003 — treat this assertion as the story's gate).
+
+**Checkpoint**: `caia --api` produces a trustworthy three-verdict report end to end — MVP shippable and independently testable.
+
+---
+
+## Phase 4: User Story 2 - Know exactly why a device could not be assessed (Priority: P1)
+
+**Goal**: Every Needs review device carries a specific, correctable reason — and where a release exists but not for that model, the report names the models it *does* run on.
+
+**Independent Test**: Run against the fixture inventory's unanswerable rows and assert each yields its distinct reason kind with actionable text, and that the `release_not_on_platform` case names at least one platform Cisco does list.
+
+### Implementation for User Story 2
+
+- [X] T027 [US2] Extend `classify()` in `cisco_advisory_impact_agent/matching.py` to attach a structured reason to every Needs review verdict, carrying the detail each kind requires per the [Reason table](./data-model.md#reason-derived-attached-to-needs-review): the raw *and* normalised release for `release_unknown`; the platforms Cisco does list for `release_not_on_platform` (FR-012); the raw model for `model_unmapped`; the field name for `field_missing`; the family for `family_unsupported`.
+- [X] T028 [US2] Render reasons in `cisco_advisory_impact_agent/html_report.py`: one readable sentence per reason kind, escaped, with no bare HTTP status codes and no internal identifiers (SC-004). A device whose check did not complete must read as inconclusive, never as clean.
+- [X] T029 [P] [US2] Extend `tests/test_matching.py` and `tests/test_api_flow.py` with the real-inventory-derived cases from [quickstart.md § Scenario B](./quickstart.md#scenario-b--negatives-are-earned-not-assumed-us2--p1): ASA `9.14(4)24` → `release_unknown`; ASA 5515 @ `9.18(4)22` → `release_not_on_platform` naming ≥1 platform; ISA-3000 @ FTD `7.4.0` → `release_not_on_platform`; an unrecognised model → `model_unmapped`; a blank release → `field_missing` naming the field. Assert every reason string is non-empty and contains no status code.
+
+**Checkpoint**: Needs review is an actionable data-quality worklist rather than undifferentiated noise.
+
+---
+
+## Phase 5: User Story 3 - Act on the findings without leaving the report (Priority: P2)
+
+**Goal**: The report is a worklist — filter to Impacted, sort by priority, expand a device, see severity and the release that fixes each advisory, click through to Cisco. All from the file alone, offline.
+
+**Independent Test**: Open a generated report with no network connection; filter by verdict, sort by priority, expand a device with many advisories, and confirm each advisory shows identifier, title, severity and fixed release with the identifier linked.
+
+### Implementation for User Story 3
+
+- [X] T030 [US3] Render per-advisory detail in `cisco_advisory_impact_agent/html_report.py`: identifier linked to `publicationUrl` (value escaped as an attribute), title, severity, and the release that first fixes it from `platforms[].firstFixes[].name` — presented at least as prominently as severity, since it is the field an engineer acts on. A missing fixed release renders as absent, never inferred (FR-026).
+- [X] T031 [US3] Add CVE identifiers to the advisory detail in `cisco_advisory_impact_agent/html_report.py` (FR-027).
+- [X] T032 [US3] Add inline vanilla JavaScript to `cisco_advisory_impact_agent/html_report.py` for filter-by-verdict and sort-by-priority (FR-029). No framework, no CDN reference — the report must work offline and after being emailed (FR-030). The script must not construct markup from Cisco-supplied strings (FR-033).
+- [X] T033 [US3] Add expand/collapse of a device's advisory detail in `cisco_advisory_impact_agent/html_report.py`: collapsed rows stay readable at a glance and the full list is never silently truncated — the spike saw one device with 82 advisories (FR-025, FR-029). Distinguish verdicts without relying on colour alone, so the report survives printing and colour-vision deficiency.
+- [X] T034 [P] [US3] Extend `tests/test_html_report.py`: every Impacted device has ≥1 advisory carrying a `publicationUrl` link; every advisory with a Cisco-supplied fixed release displays it; CVE identifiers render; filter and sort controls are present; a device with 80+ advisories is collapsed rather than truncated (assert all identifiers are in the document); and the file still contains no external resource reference.
+
+**Checkpoint**: The report is actionable without a spreadsheet tool or a Cisco site search.
+
+---
+
+## Phase 6: User Story 4 - Set up and validate Cisco API access once (Priority: P2)
+
+**Goal**: One `caia --config` pass captures everything, shows the identifier and hides the secret, confirms the captured length so a truncated paste is obvious, and tells the user plainly whether Cisco accepts the credentials — distinguishing a rejection from an unreachable Cisco.
+
+**Independent Test**: Run `config.run_config()` with prompts and the token request patched: assert both Cisco prompts appear, the identifier echoes and the secret does not, the length confirmation appears without revealing the value, and each of the three verification outcomes produces its distinct behaviour.
+
+### Implementation for User Story 4
+
+- [X] T035 [US4] Make every prompt in `run_config()` skippable in `cisco_advisory_impact_agent/config.py`: **remove the existing retry loop that rejects an empty AI service key** (currently `while not api_key:`) so an `--api`-only user is not forced to invent one (FR-035, FR-036). This is a deliberate behaviour change, recorded in [contracts/config-cli.md](./contracts/config-cli.md#what-changes) — not a regression. Keep the "a value is already saved, press Enter to keep" convention for every credential.
+- [X] T036 [US4] Add a secret-length confirmation helper to `cisco_advisory_impact_agent/ui.py` that reports how many characters were captured without revealing any of them, and use it after each hidden prompt in `config.py` (FR-038, SC-017). Per-keystroke masking is deliberately **not** implemented — the existing non-echoing `ask_secret` is FR-039's documented fallback (research Decision 13, Constitution II).
+- [X] T037 [US4] Add the two Cisco prompts to `run_config()` in `cisco_advisory_impact_agent/config.py`: the client identifier via the **visible** `ui.ask` (it is an identifier, not a secret) and the client secret via the **hidden** `ui.ask_secret` followed by the T036 confirmation (FR-037).
+- [X] T038 [US4] Add verification to `run_config()` in `cisco_advisory_impact_agent/config.py`: when — and only when — both Cisco values are available for the session, call `psirt.fetch_token()` (FR-044) and branch on the three outcomes per [contracts/config-cli.md](./contracts/config-cli.md#verification) — accepted → state plainly that they are valid and save; rejected (`PsirtAuthError`) → surface Cisco's reason, offer re-entry, do not silently save; unreachable (`PsirtUnreachableError`) → say so **distinctly** from a rejection and offer to save unverified with a warning, so a proxy outage never blocks setup (FR-041–FR-043). In a non-interactive session a rejection reports and exits non-zero rather than looping. No message may contain any credential fragment (FR-049).
+- [X] T039 [P] [US4] Extend `tests/test_config.py`: both Cisco prompts appear; the identifier is echoed and the secret is not; the length confirmation states the count and contains no fragment of the value; empty input with a saved value leaves it unchanged; each of the three verification outcomes behaves per contract (including that "unreachable" still permits saving); skipped Cisco prompts issue zero requests; an empty AI key completes the flow; and no credential fragment appears in any emitted message across all three outcomes.
+
+**Checkpoint**: A new user goes from credentials in hand to a validated configuration in one command.
+
+---
+
+## Phase 7: User Story 5 - Judge how far to trust a report you did not run (Priority: P3)
+
+**Goal**: The report states its own provenance and limits, so a second-hand reader can calibrate before acting.
+
+**Independent Test**: Open a generated report and confirm, without reading a single device row, that it carries the run timestamp, inventory filename, device count, per-verdict counts and both coverage statements.
+
+### Implementation for User Story 5
+
+- [X] T040 [US5] Build the run summary in `cisco_advisory_impact_agent/analyzer.py` (`run_api`) and render it at the top of the report in `cisco_advisory_impact_agent/html_report.py`: run date and time, inventory file used, devices assessed, and a count for each verdict — with the Needs review count visible in the summary rather than only discoverable row by row (FR-031, US5 AS4).
+- [X] T041 [US5] Add the partial-run notice to the summary in `cisco_advisory_impact_agent/html_report.py`, naming the cause, whenever some devices could not be assessed because Cisco became unreachable or the quota was reached mid-run (FR-016, SC-019). A partial run must never present as complete.
+- [X] T042 [US5] Render both coverage statements adjacent to the summary in `cisco_advisory_impact_agent/html_report.py` — not footnoted (FR-032): that Cisco's data holds no advisories published before its per-family cut-offs (January 2022 for ASA/FMC/FTD/FXOS), and that a verdict does not account for whether a vulnerable feature is enabled, so Impacted means "listed as affected" and not "exploitable".
+- [X] T043 [P] [US5] Extend `tests/test_html_report.py`: the summary's per-verdict counts equal the table's rows per verdict; the run timestamp, inventory filename and device count are present; both coverage statements appear in every generated report; and a partial run renders its notice while a complete run does not.
+
+**Checkpoint**: All five user stories are independently functional.
+
+---
+
+## Phase 8: Polish & Cross-Cutting Concerns
+
+**Purpose**: Cross-cutting behaviour, the Documentation quality gate, and end-to-end validation
+
+- [X] T044 Implement the partial-run and interrupt paths in `cisco_advisory_impact_agent/analyzer.py`: when Cisco becomes unreachable or the quota is reached mid-run, keep the verdicts already obtained, resolve the remainder to Needs review (`check_incomplete`), flag the summary partial, still write the report and exit 0 (FR-016); on `KeyboardInterrupt`, stop promptly, write no report, and exit `130` (FR-052, Constitution III).
+- [X] T045 Implement `--dry-run` for `--api` in `cisco_advisory_impact_agent/analyzer.py`: resolve every device to the check that *would* be made — family, platform alias, normalised release — print them, contact Cisco not at all, write no report, exit 0 (FR-006). This is the constitution's cheap-verification quality gate for this mode.
+- [X] T046 [P] Extend `tests/test_api_flow.py` for the cross-cutting paths: a mid-run failure yields a written report with the partial flag and exit 0; `KeyboardInterrupt` yields exit `130` with no report; `--dry-run` issues zero requests and writes no report; an unwritable output folder reports the attempted path and exits non-zero (FR-054); and an inventory with no usable rows exits non-zero without writing an empty report (FR-055).
+- [X] T047 [P] Update `README.md`: add the `--api` mode beside the existing usage, list the Cisco API credentials among the prerequisites with `caia --config` as the way to supply them (FR-057), explain that `--api` produces an HTML report while the default mode produces a spreadsheet and why the two answer different questions (FR-056), and state the January 2022 coverage cut-off so expectations are set before the first run.
+- [X] T048 [P] Mirror the same additions in `docs/index.html` — the Documentation quality gate requires the README and the landing page to stay consistent with each other and with the code, within the same pull request.
+- [X] T049 Run the full suite `python -m unittest discover -s tests` from the repo root and confirm every test passes (existing plus new). The existing suite passing is a constitutional merge gate.
+- [X] T050 Execute the [quickstart.md](./quickstart.md) validation: the automated suite, the `--dry-run` offline flow check, and live Scenarios A–K against real credentials. Treat **Scenario B as the gate** — if any unanswerable device is labelled Not impacted, the feature is not done regardless of what else works. Note any scenario that could not be exercised and why.
+- [X] T051 Bump `VERSION` per semantic versioning (new user-facing capability → MINOR) and confirm the value is consistent with the release runbook in `CONTRIBUTING.md`. The tag is pushed only after the pull request merges (Constitution, Versioning & releases).
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies — start immediately.
+- **Foundational (Phase 2)**: Depends on Setup (fixtures T003–T004 are what its tests run against). **Blocks all user stories.**
+- **User Stories (Phases 3–7)**: All depend on Foundational. US1 must land before US2/US3/US5 can be observed end to end (they extend its report and its classification), but each remains independently *testable* through its own assertions.
+- **Polish (Phase 8)**: Depends on the user stories being complete.
+
+### User Story Dependencies
+
+- **US1 (P1)** — Depends only on Foundational. The MVP.
+- **US2 (P1)** — Extends `classify()` and the report's reason rendering from US1. Independently testable via its own reason-kind assertions.
+- **US3 (P2)** — Extends the report's advisory rendering and interactivity from US1. Independent of US2, US4, US5.
+- **US4 (P2)** — Touches only `config.py` and `ui.py`. **Genuinely independent** of US1–US3 and can be built in parallel with them; US1 runs from environment variables until it lands.
+- **US5 (P3)** — Adds the summary block to the report. Independent of US2–US4.
+
+### Within Each Story
+
+- Implementation before its tests in the same file; tests in *different* files are marked `[P]` and can be written concurrently.
+- `matching.py` changes before the `analyzer.py`/`html_report.py` changes that consume them.
+- Story complete and checkpointed before moving to the next priority.
+
+### Parallel Opportunities
+
+Foundational splits into four independent file streams that can run concurrently:
+
+- `matching.py` — T005 → T006 → T007 → T008 (same file, so sequential among themselves)
+- `psirt.py` — T010 → T011 → T012
+- `config.py` — T014
+- `cli.py` — T016 → T017
+
+Their test files (T009, T013, T015) are separate files and parallel with each other and with the streams above.
+
+In Setup, T002/T003/T004 are three different files — fully parallel.
+
+US4 is the only story that can be developed fully in parallel with another story, because it shares no file with US1/US2/US3/US5.
+
+---
+
+## Parallel Example: Foundational Phase
+
+```bash
+# Four file streams, one developer each (or one developer, four branches of attention):
+Stream A: T005 → T006 → T007 → T008   # cisco_advisory_impact_agent/matching.py
+Stream B: T010 → T011 → T012          # cisco_advisory_impact_agent/psirt.py
+Stream C: T014                        # cisco_advisory_impact_agent/config.py
+Stream D: T016 → T017                 # cisco_advisory_impact_agent/cli.py
+
+# Then the three test files, all parallel:
+Task: "Add tests/test_matching.py"    # T009
+Task: "Add tests/test_psirt.py"       # T013
+Task: "Extend tests/test_config.py"   # T015
+```
+
+## Parallel Example: User Story 1
+
+```bash
+# After T018–T023 land, the three test files are independent:
+Task: "Create tests/test_html_report.py"   # T024
+Task: "Extend tests/test_cli.py"           # T025
+Task: "Create tests/test_api_flow.py"      # T026
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Stories 1 + 2)
+
+1. Phase 1: Setup
+2. Phase 2: Foundational — **critical, blocks everything**
+3. Phase 3: US1 — the run and the three-verdict report
+4. Phase 4: US2 — specific reasons on every Needs review device
+5. **STOP and VALIDATE**: run quickstart Scenarios A, B and C
+
+US2 is included in the MVP rather than deferred. US1 alone is safe — it never labels an unanswerable device Not impacted — but on the real inventory it would leave 15 of 70 rows carrying an undifferentiated "Needs review", which reads as noise and gets ignored. US2 is what turns those rows into a correctable worklist, and it is a small increment on top of US1.
+
+### Incremental Delivery
+
+1. Setup + Foundational → matching rules proven by unit test with no network
+2. + US1 → trustworthy verdicts and a report (shippable)
+3. + US2 → actionable reasons (**MVP**)
+4. + US3 → the report becomes a worklist
+5. + US4 → guided credential setup with validation
+6. + US5 → provenance and coverage disclosure
+7. + Polish → docs, cross-cutting paths, full validation
+
+### Parallel Team Strategy
+
+With two developers: both complete Setup + Foundational together (splitting the `matching.py` and `psirt.py` streams). Then developer A takes US1 → US2 → US3 → US5 (all touch the report and the classifier), while developer B takes US4 in parallel (only `config.py` and `ui.py`) followed by the Polish documentation tasks.
+
+---
+
+## Notes
+
+- `[P]` = different file from other concurrent tasks, no dependency on incomplete work.
+- The constitution amendment this feature required is **already applied** (2.2.0, commit `cb6938a`) and is deliberately absent from the task list.
+- Every task that changes matching or verdict logic must land with its tests in the same commit — that is a constitutional merge gate, not a preference.
+- The single assertion that matters most across the whole feature: **no unanswerable device is ever labelled Not impacted** (SC-003, Constitution IV). It appears in T009, T026 and T029, and it is the quickstart gate in T050.
+- Commit after each task or logical group; stop at any checkpoint to validate a story independently.
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..7535510
--- /dev/null
+++ b/tests/__init__.py
@@ -0,0 +1,6 @@
+"""Test package.
+
+Making `tests` a package lets test modules share fixtures via `tests.fixtures.*`.
+`python -m unittest discover -s tests` (the command CI runs) still works: unittest sees
+the package and sets the top-level directory to the repository root automatically.
+"""
diff --git a/tests/fixtures/__init__.py b/tests/fixtures/__init__.py
new file mode 100644
index 0000000..e01e34c
--- /dev/null
+++ b/tests/fixtures/__init__.py
@@ -0,0 +1 @@
+"""Test fixtures for the inventory-driven API check (spec 006)."""
diff --git a/tests/fixtures/inventory.py b/tests/fixtures/inventory.py
new file mode 100644
index 0000000..20437f2
--- /dev/null
+++ b/tests/fixtures/inventory.py
@@ -0,0 +1,72 @@
+"""Fixture inventory covering every verdict path (spec 006, quickstart.md).
+
+`write_fixture_inventory(dir)` writes an .xlsx with the same shape the real inventory has
+(sheet `FW_List`; name / model / type / version / priority columns) and one row per
+situation the outcome table in data-model.md distinguishes.
+
+The releases and models here are the real ones the feasibility spike exercised, so the
+expectations in the tests are grounded in what Cisco actually answered.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import openpyxl
+
+HEADERS = ["FirewallName", "Model", "Firewalltype", " IOS version",
+           "Priority* (1-High 3-Low)"]
+
+# (name, model, family, raw_version, priority, why-this-row-exists)
+ROWS = [
+    # --- Impacted: Cisco returns advisories -------------------------------- #
+    ("FW-IMPACT-1", "ISA-3000", "FTD", "7.4.2.3", 1),
+    # Shares (ftd, ISA3000, 7.4.2.3) with the row above -> one request for two devices.
+    ("FW-IMPACT-2", "ISA-3000", "FTD", "7.4.2.3", 2),
+    # Parenthetical shorthand must normalise to 9.16.4.67 and be assessed.
+    ("FW-SHORTHAND", "ASA 5506", "ASA", "9.16(4)67", 1),
+    # Companion-product annotation must be dropped -> 9.20.4.7.
+    ("FW-ASDM", "Firepower 4110", "ASA", "9.20(4)7/ASDM 7.22.1", 2),
+    # Build suffix must be stripped -> 7.4.2.1.
+    ("FW-BUILDSUFFIX", "Cisco Firepower 1010 Threat Defense", "FTD", "7.4.2.1-30", 3),
+    # FMC takes no platform alias and its catalogue rows carry no platform_name.
+    ("FW-FMC", "Secure FMC 1600", "FMC", "7.4.2.3", 2),
+
+    # --- Not impacted: release and platform both confirmed, no advisories --- #
+    ("FW-CLEAN", "ISA-3000", "FTD", "7.9.9", 3),
+
+    # --- Needs review: release_unknown (purged end-of-support train) -------- #
+    ("FW-RELUNKNOWN", "ASA 5525", "ASA", "9.14(4)24", 2),
+
+    # --- Needs review: release_not_on_platform ----------------------------- #
+    # ASA 9.18 dropped the 5500-X series; the release exists for other platforms.
+    ("FW-NOTONPLAT", "ASA 5515", "ASA", "9.18(4)22", 3),
+
+    # --- Needs review: model_unmapped -------------------------------------- #
+    ("FW-BADMODEL", "Unknown Appliance 9", "ASA", "9.16.4.67", 2),
+
+    # --- Needs review: field_missing --------------------------------------- #
+    ("FW-NOVERSION", "ISA-3000", "FTD", "", 1),
+    ("FW-NOMODEL", "", "FTD", "7.4.2.3", 3),
+
+    # --- Needs review: family_unsupported ---------------------------------- #
+    ("FW-BADFAMILY", "Catalyst 9300", "SWITCH", "17.9.4", 3),
+]
+
+
+def write_fixture_inventory(directory, filename="inventory.xlsx"):
+    """Write the fixture workbook into `directory` and return its Path."""
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.title = "FW_List"
+    ws.append(HEADERS)
+    for name, model, family, ver, prio in ROWS:
+        ws.append([name, model, family, ver, prio])
+    path = Path(directory) / filename
+    wb.save(path)
+    return path
+
+
+def usable_row_count():
+    """Rows the inventory loader will return (it skips rows with no name)."""
+    return len([r for r in ROWS if r[0]])
diff --git a/tests/fixtures/psirt_responses.py b/tests/fixtures/psirt_responses.py
new file mode 100644
index 0000000..19356d3
--- /dev/null
+++ b/tests/fixtures/psirt_responses.py
@@ -0,0 +1,168 @@
+"""Canned Cisco PSIRT openVuln API payloads (spec 006).
+
+Every shape here was copied from what the live API actually returned during the
+feasibility spike — see specs/006-api-inventory-check/contracts/psirt-access.md. Two
+details matter and are easy to get wrong from the documentation alone:
+
+* the `fmc` catalogue rows carry **no** `platform_name` key at all, unlike asa/ftd;
+* every advisory `summary` contains raw HTML, so the report must escape it.
+"""
+
+from __future__ import annotations
+
+TOKEN = {
+    "access_token": "fixture-token-value",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "scope": "customscope",
+}
+
+PLATFORMS = {
+    "asa": [
+        {"platformAlias": "ISA3000", "id": "1",
+         "name": "Cisco 3000 Series Industrial Security Appliances (ISA)"},
+        {"platformAlias": "ASAV", "id": "2",
+         "name": "Cisco Adaptive Security Virtual Appliance (ASAv)"},
+        {"platformAlias": "ASA5500X", "id": "3",
+         "name": "Cisco ASA 5500-X Series Firewalls"},
+        {"platformAlias": "ASASM", "id": "4", "name": "Cisco ASA Service Module"},
+        {"platformAlias": "FPR1000", "id": "5", "name": "Cisco Firepower 1000 Series"},
+        {"platformAlias": "FPR2100", "id": "6", "name": "Cisco Firepower 2100 Series"},
+        {"platformAlias": "FPR4100", "id": "7", "name": "Cisco Firepower 4100 Series"},
+        {"platformAlias": "FPR9000", "id": "8", "name": "Cisco Firepower 9000 Series"},
+        {"platformAlias": "FWL3100", "id": "9",
+         "name": "Cisco Secure Firewall 3100 Series"},
+    ],
+    "ftd": [
+        {"platformAlias": "ISA3000", "id": "1",
+         "name": "Cisco 3000 Series Industrial Security Appliances (ISA)"},
+        {"platformAlias": "ASA5500", "id": "2",
+         "name": "Cisco ASA 5500-X Series Firewalls"},
+        {"platformAlias": "FPR1000", "id": "3", "name": "Cisco Firepower 1000 Series"},
+        {"platformAlias": "FPR2100", "id": "4", "name": "Cisco Firepower 2100 Series"},
+        {"platformAlias": "FPR4100", "id": "5", "name": "Cisco Firepower 4100 Series"},
+        {"platformAlias": "FPR9000", "id": "6", "name": "Cisco Firepower 9000 Series"},
+        # /platforms calls this "NGFW Virtual" while OS_data calls the same platform
+        # "Threat Defense Virtual" — the mismatch research Decision 5 documents.
+        {"platformAlias": "FPRNGFW", "id": "7", "name": "Cisco Firepower NGFW Virtual"},
+        {"platformAlias": "FWL3100", "id": "8",
+         "name": "Cisco Secure Firewall 3100 Series"},
+    ],
+}
+
+_ASA_PLATS = [
+    "Cisco 3000 Series Industrial Security Appliances (ISA)",
+    "Cisco Adaptive Security Virtual Appliance (ASAv)",
+    "Cisco Firepower 1000 Series",
+    "Cisco Firepower 2100 Series",
+    "Cisco Firepower 4100 Series",
+    "Cisco Firepower 9000 Series",
+    "Cisco Secure Firewall 3100 Series",
+]
+
+
+def _asa_rows():
+    rows = []
+    # 9.16.4.67 runs on the 5500-X series as well (spike: 24 advisories returned).
+    for plat in _ASA_PLATS + ["Cisco ASA 5500-X Series Firewalls"]:
+        rows.append({"nos_version": "9.16.4.67", "nos_type": "ASA", "platform_name": plat})
+    # 9.18.4.22 exists but NOT for the 5500-X series (ASA 9.18 dropped that hardware).
+    for plat in _ASA_PLATS:
+        rows.append({"nos_version": "9.18.4.22", "nos_type": "ASA", "platform_name": plat})
+    for plat in ["Cisco Firepower 4100 Series", "Cisco Secure Firewall 3100 Series"]:
+        rows.append({"nos_version": "9.20.4.7", "nos_type": "ASA", "platform_name": plat})
+    # Note: no 9.14.x rows at all — that train is end-of-support and purged.
+    return rows
+
+
+def _ftd_rows():
+    rows = []
+    for plat in [
+        "Cisco 3000 Series Industrial Security Appliances (ISA)",
+        "Cisco Firepower 1000 Series",
+        "Cisco Firepower 2100 Series",
+        "Cisco Firepower 4100 Series",
+        "Cisco Secure Firewall 3100 Series",
+        # OS_data's name for the FPRNGFW platform.
+        "Cisco Secure Firewall Threat Defense Virtual",
+    ]:
+        rows.append({"nos_version": "7.4.2.3", "nos_type": "FTD", "platform_name": plat})
+    rows.append({"nos_version": "7.4.2.1", "nos_type": "FTD",
+                 "platform_name": "Cisco Firepower 1000 Series"})
+    # 7.9.9 is catalogued for the ISA 3000 but no advisory affects it -> Not impacted.
+    rows.append({"nos_version": "7.9.9", "nos_type": "FTD",
+                 "platform_name": "Cisco 3000 Series Industrial Security Appliances (ISA)"})
+    return rows
+
+
+OS_DATA = {
+    "asa": _asa_rows(),
+    "ftd": _ftd_rows(),
+    # FMC rows carry no platform_name key whatsoever.
+    "fmc": [
+        {"nos_version": "7.4.2.3", "nos_type": "FMC"},
+        {"nos_version": "7.4.2.4", "nos_type": "FMC"},
+    ],
+}
+
+
+def advisory(advisory_id="cisco-sa-asaftd-cmd-inj-ZJV8Wysm",
+             platform_name="Cisco 3000 Series Industrial Security Appliances (ISA)",
+             first_fix="7.4.3", sir="High"):
+    """One advisory object shaped like the live API's, summary HTML included."""
+    return {
+        "advisoryId": advisory_id,
+        "advisoryTitle": "Cisco Secure Firewall Command Injection Vulnerability",
+        "bugIDs": ["CSCwn12345"],
+        "cves": ["CVE-2026-20012"],
+        "cvssBaseScore": 8.6,
+        "cwe": ["CWE-78"],
+        "firstPublished": "2026-03-25T16:00:00",
+        "lastUpdated": "2026-03-25T16:00:00",
+        "publicationUrl":
+            "https://sec.cloudapps.cisco.com/security/center/content/"
+            f"CiscoSecurityAdvisory/{advisory_id}",
+        "csafUrl": "https://sec.cloudapps.cisco.com/security/center/contentjson/x.json",
+        "sir": sir,
+        "status": "Final",
+        "version": "1.0",
+        # Raw HTML, exactly as Cisco returns it. All 103 advisories in the spike did.
+        "summary": "\r\n<p>A vulnerability in the CLI of Cisco Secure Firewall could "
+                   "allow an <strong>authenticated</strong> attacker to "
+                   "<a href=\"https://example.invalid/x\">execute commands</a>.</p>",
+        "platforms": [{
+            "id": "277437",
+            "name": platform_name,
+            "firstFixes": [{"id": "306612", "name": first_fix}] if first_fix else [],
+            "vulnerabilityState": "vulnerable",
+        }],
+    }
+
+
+def advisories_response(count=2, platform_name=None, first_fix="7.4.3"):
+    """A 200 body carrying `count` advisories."""
+    plat = platform_name or "Cisco 3000 Series Industrial Security Appliances (ISA)"
+    return {"advisories": [
+        advisory(advisory_id=f"cisco-sa-fixture-{i:02d}", platform_name=plat,
+                 first_fix=first_fix, sir=("Critical" if i == 0 else "High"))
+        for i in range(count)
+    ]}
+
+
+NO_DATA_FOUND = {"errorCode": "NO_DATA_FOUND",
+                 "errorMessage": "No advisories found for the given criteria"}
+
+INVALID_ASA_VERSION = {
+    "errorCode": "INVALID_ASA_VERSION",
+    "errorMessage": "No Cisco Security Advisories affect the Cisco ASA Software release; "
+                    "ASA version not found",
+}
+
+INVALID_FTD_VERSION = {
+    "errorCode": "INVALID_FTD_VERSION",
+    "errorMessage": "No Cisco Security Advisories affect the Cisco FTD Software release; "
+                    "FTD version not found",
+}
+
+TOO_MANY_REQUESTS = {"errorCode": "TOO_MANY_REQUESTS",
+                     "errorMessage": "Rate limit exceeded"}
diff --git a/tests/test_api_flow.py b/tests/test_api_flow.py
new file mode 100644
index 0000000..255a5e0
--- /dev/null
+++ b/tests/test_api_flow.py
@@ -0,0 +1,427 @@
+"""End-to-end tests for the `--api` run flow (spec 006). No network access.
+
+`psirt.Client` is replaced with a scripted fake, so the whole path — inventory loading,
+catalogue indexing, deduplication, verdict derivation, report writing — is exercised
+against the fixture inventory.
+
+The gate assertion for this feature lives here: no device whose release or platform Cisco
+cannot confirm may ever be labelled Not impacted (SC-003, Constitution IV).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import re
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from cisco_advisory_impact_agent import analyzer
+from cisco_advisory_impact_agent import matching as m
+from cisco_advisory_impact_agent import psirt
+from tests.fixtures import psirt_responses as fx
+from tests.fixtures.inventory import ROWS, usable_row_count, write_fixture_inventory
+
+
+class FakeClient:
+    """Answers from the fixtures, recording every question asked."""
+
+    def __init__(self, *_args, fail_after=None, auth_fail=False, **_kwargs):
+        self.asked = []
+        self.fail_after = fail_after
+        self.auth_fail = auth_fail
+        self.request_count = 0
+
+    def get_platforms(self, os_type):
+        if self.auth_fail:
+            raise psirt.PsirtAuthError("Cisco rejected the credentials (HTTP 401).")
+        return fx.PLATFORMS.get(os_type, [])
+
+    def get_os_data(self, os_type):
+        return fx.OS_DATA.get(os_type, [])
+
+    def get_advisories(self, os_type, release, platform_alias=None):
+        self.asked.append((os_type, platform_alias, release))
+        self.request_count += 1
+        if self.fail_after is not None and len(self.asked) > self.fail_after:
+            raise psirt.PsirtUnreachableError("Cisco became unreachable (URLError).")
+
+        # 9.14.x is absent from Cisco's catalogue entirely -> 406-equivalent.
+        if os_type == "asa" and release.startswith("9.14."):
+            return m.INVALID_VERSION, []
+        # 9.18.4.22 is real but not for the 5500-X series -> 404-equivalent.
+        if os_type == "asa" and release == "9.18.4.22":
+            return m.NO_DATA, []
+        # A release nobody has an advisory for -> genuinely clean.
+        if release == "7.9.9":
+            return m.NO_DATA, []
+        plat_name = _platform_display_name(os_type, platform_alias)
+        return m.HAS_ADVISORIES, fx.advisories_response(2, platform_name=plat_name)["advisories"]
+
+
+def _platform_display_name(os_type, alias):
+    for row in fx.PLATFORMS.get(os_type, []):
+        if row["platformAlias"] == alias:
+            return row["name"]
+    return "Cisco Secure Firewall Management Center (FMC) Appliances"
+
+
+class _ApiRunBase(unittest.TestCase):
+    """Shared harness. Holds no test methods, so subclasses do not re-run each other's."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.workdir = Path(self._tmp.name)
+        self.inv_path = write_fixture_inventory(self.workdir)
+        self.outdir = self.workdir / "output"
+
+    def _args(self, **over):
+        base = dict(api=True, url=None, inventory=str(self.inv_path), sheet="FW_List",
+                    output_dir=str(self.outdir), dry_run=False, keep_temp=False,
+                    no_update_check=True, yes=True)
+        base.update(over)
+        return types.SimpleNamespace(**base)
+
+    @contextlib.contextmanager
+    def _run(self, client=None, creds=("id", "secret"), **over):
+        client = client or FakeClient()
+        buf = io.StringIO()
+        with mock.patch.object(analyzer.psirt, "Client", return_value=client), \
+             mock.patch.object(analyzer.config, "resolve",
+                               side_effect=lambda key, *a, **k: {
+                                   analyzer.config.CISCO_CLIENT_ID: creds[0],
+                                   analyzer.config.CISCO_CLIENT_SECRET: creds[1],
+                               }.get(key, "")), \
+             mock.patch.object(analyzer.config, "load_local_env"), \
+             mock.patch("sys.stdin.isatty", return_value=False), \
+             contextlib.redirect_stdout(buf):
+            try:
+                code = analyzer.run_api(self._args(**over))
+            except SystemExit as exc:
+                code = exc.code
+            yield code, buf.getvalue(), client
+
+    def _report(self):
+        reports = sorted(self.outdir.glob("impact_report_*.html"))
+        self.assertTrue(reports, "no report was written")
+        return reports[-1].read_text(encoding="utf-8")
+
+
+class ApiRunTests(_ApiRunBase):
+    # --- happy path ------------------------------------------------------- #
+    def test_run_writes_a_report_and_reports_its_path(self):
+        with self._run() as (code, out, _client):
+            self.assertEqual(code, 0)
+            self.assertIn("impact_report_", out)
+        self.assertTrue(list(self.outdir.glob("impact_report_*.html")))
+
+    def test_every_inventory_row_appears_exactly_once(self):
+        with self._run() as (code, _out, _client):
+            self.assertEqual(code, 0)
+        text = self._report()
+        for row in ROWS:
+            name = row[0]
+            if name:
+                self.assertEqual(text.count(f"{name}</td>"), 1, f"{name} not present once")
+
+    def test_row_count_matches_the_inventory(self):
+        with self._run():
+            pass
+        text = self._report()
+        # Body rows are the ones carrying a verdict attribute.
+        self.assertEqual(text.count("<tr data-verdict="), usable_row_count())
+
+    def test_impacted_devices_list_their_advisories(self):
+        with self._run():
+            pass
+        text = self._report()
+        self.assertIn(m.IMPACTED, text)
+        self.assertIn("cisco-sa-fixture-00", text)
+
+    # --- deduplication ---------------------------------------------------- #
+    def test_identical_devices_cost_one_request(self):
+        with self._run() as (_code, _out, client):
+            pass
+        # FW-IMPACT-1 and FW-IMPACT-2 share (ftd, ISA3000, 7.4.2.3).
+        shared = [q for q in client.asked if q == ("ftd", "ISA3000", "7.4.2.3")]
+        self.assertEqual(len(shared), 1, "shared check was asked more than once")
+
+    def test_fewer_checks_than_devices(self):
+        with self._run() as (_code, _out, client):
+            pass
+        self.assertLess(len(client.asked), usable_row_count())
+
+    def test_fmc_is_asked_without_a_platform_alias(self):
+        with self._run() as (_code, _out, client):
+            pass
+        fmc = [q for q in client.asked if q[0] == "fmc"]
+        self.assertTrue(fmc)
+        for _ost, alias, _rel in fmc:
+            self.assertIsNone(alias)
+
+    def test_shorthand_release_is_normalised_before_asking(self):
+        with self._run() as (_code, _out, client):
+            pass
+        releases = {q[2] for q in client.asked}
+        self.assertIn("9.16.4.67", releases)      # from 9.16(4)67
+        self.assertIn("9.20.4.7", releases)       # from 9.20(4)7/ASDM 7.22.1
+        self.assertIn("7.4.2.1", releases)        # from 7.4.2.1-30
+        for release in releases:
+            self.assertNotIn("(", release)
+            self.assertNotIn("/", release)
+
+    # --- the gate --------------------------------------------------------- #
+    def test_no_unanswerable_device_is_ever_labelled_not_impacted(self):
+        """SC-003. The single assertion this whole feature exists to guarantee."""
+        with self._run():
+            pass
+        text = self._report()
+        unanswerable = ["FW-RELUNKNOWN", "FW-NOTONPLAT", "FW-BADMODEL",
+                        "FW-NOVERSION", "FW-NOMODEL", "FW-BADFAMILY"]
+        for name in unanswerable:
+            row = _row_for(text, name)
+            self.assertIn(m.NEEDS_REVIEW, row, f"{name} should be Needs review")
+            self.assertNotIn(m.NOT_IMPACTED, row, f"{name} was labelled safe!")
+
+    def test_a_genuinely_clean_device_is_not_impacted(self):
+        with self._run():
+            pass
+        row = _row_for(self._report(), "FW-CLEAN")
+        self.assertIn(m.NOT_IMPACTED, row)
+
+    def test_all_needs_review_run_still_succeeds(self):
+        """FR-053: a wholly inconclusive run is a completed run, not a failure."""
+        class AllIncomplete(FakeClient):
+            def get_advisories(self, os_type, release, platform_alias=None):
+                self.asked.append((os_type, platform_alias, release))
+                return m.INCOMPLETE, []
+
+        with self._run(client=AllIncomplete()) as (code, _out, _client):
+            self.assertEqual(code, 0)
+        text = self._report()
+        self.assertIn(m.NEEDS_REVIEW, text)
+        # Assert per row: the filter controls legitimately name every verdict.
+        for row in ROWS:
+            if row[0]:
+                self.assertNotIn(m.NOT_IMPACTED, _row_for(text, row[0]))
+
+    # --- credentials ------------------------------------------------------ #
+    def test_missing_credentials_refuses_before_any_request(self):
+        client = FakeClient()
+        with self._run(client=client, creds=("", "")) as (code, out, _c):
+            self.assertNotEqual(code, 0)
+            self.assertIn("CISCO_CLIENT_ID", out)
+            self.assertIn("--config", out)
+        self.assertEqual(client.asked, [])
+        self.assertFalse(list(self.outdir.glob("*.html")))
+
+    def test_missing_secret_only_is_named(self):
+        with self._run(creds=("an-id", "")) as (code, out, _c):
+            self.assertNotEqual(code, 0)
+            self.assertIn("CISCO_CLIENT_SECRET", out)
+
+    def test_rejected_credentials_produce_no_verdicts(self):
+        with self._run(client=FakeClient(auth_fail=True)) as (code, out, _c):
+            self.assertNotEqual(code, 0)
+            self.assertIn("rejected", out.lower())
+        self.assertFalse(list(self.outdir.glob("*.html")))
+
+    def test_ai_service_key_is_never_consulted(self):
+        with mock.patch.object(analyzer, "fuelix") as fake_fuelix:
+            with self._run() as (code, _out, _c):
+                self.assertEqual(code, 0)
+            fake_fuelix.assert_not_called()
+            self.assertFalse(fake_fuelix.method_calls)
+
+    # --- credential hygiene ----------------------------------------------- #
+    def test_no_credential_value_appears_in_output_or_report(self):
+        secret = "sup3r-s3cret-value"
+        with self._run(creds=("the-client-id", secret)) as (code, out, _c):
+            self.assertEqual(code, 0)
+            self.assertNotIn(secret, out)
+        text = self._report()
+        self.assertNotIn(secret, text)
+        self.assertNotIn("the-client-id", text)
+        for path in self.outdir.glob("*"):
+            self.assertNotIn(secret, path.name)
+
+
+class CrossCuttingTests(_ApiRunBase):
+    """Partial runs, interrupt, dry run, and the failure paths (Phase 8)."""
+
+    def test_partial_run_still_writes_a_report_and_exits_zero(self):
+        """FR-016: answers already obtained are kept; the rest become Needs review."""
+        with self._run(client=FakeClient(fail_after=2)) as (code, out, client):
+            self.assertEqual(code, 0)
+            self.assertIn("partial", out.lower())
+        self.assertEqual(len(client.asked), 3)   # two answered, the third raised
+        text = self._report()
+        self.assertIn("This run was partial", text)
+        self.assertIn("did not complete", text)
+
+    def test_partial_run_never_marks_an_unreached_device_clean(self):
+        with self._run(client=FakeClient(fail_after=1)):
+            pass
+        text = self._report()
+        for row in ROWS:
+            if row[0]:
+                self.assertNotIn(m.NOT_IMPACTED, _row_for(text, row[0]))
+
+    def test_interrupt_propagates_so_the_cli_can_exit_130(self):
+        class Interrupting(FakeClient):
+            def get_advisories(self, os_type, release, platform_alias=None):
+                raise KeyboardInterrupt
+
+        with self.assertRaises(KeyboardInterrupt):
+            with self._run(client=Interrupting()):
+                pass
+        self.assertFalse(list(self.outdir.glob("*.html")), "no report on interrupt")
+
+    def test_dry_run_contacts_nothing_and_writes_nothing(self):
+        client = FakeClient()
+        with self._run(client=client, dry_run=True, creds=("", "")) as (code, out, _c):
+            self.assertEqual(code, 0)
+            self.assertIn("Cisco is not contacted", out)
+            self.assertIn("No report written", out)
+        self.assertEqual(client.asked, [])
+        self.assertFalse(list(self.outdir.glob("*.html")))
+
+    def test_dry_run_shows_the_normalised_checks(self):
+        with self._run(dry_run=True, creds=("", "")) as (_code, out, _c):
+            self.assertIn("9.16.4.67", out)      # normalised from 9.16(4)67
+            self.assertIn("ftd/ISA3000/7.4.2.3", out)
+
+    def test_dry_run_separates_checks_from_locally_resolved_devices(self):
+        """A device that would never reach Cisco must not be listed as a check."""
+        with self._run(dry_run=True, creds=("", "")) as (_code, out, _c):
+            asked, _, not_asked = out.partition("Would not reach Cisco")
+            self.assertTrue(not_asked, "expected a locally-resolved section")
+            # Blank release, blank model and an out-of-scope family produce no question.
+            for kind in ("field_missing", "family_unsupported", "model_unmapped"):
+                self.assertIn(kind, not_asked)
+            # ...and none of them appear as something Cisco would be asked.
+            for bogus in ("switch/", "/?", "ISA3000/ "):
+                self.assertNotIn(bogus, asked)
+
+    def test_dry_run_distinguishes_no_platform_from_unmapped(self):
+        with self._run(dry_run=True, creds=("", "")) as (_code, out, _c):
+            asked = out.partition("Would not reach Cisco")[0]
+            # FMC genuinely needs no platform and is asked about.
+            self.assertIn("fmc/(no platform)/", asked)
+            # An unmappable model is not asked about at all.
+            self.assertNotIn("asa/(no platform)/", asked)
+
+    def test_unwritable_output_directory_reports_the_path(self):
+        blocker = self.workdir / "blocked"
+        blocker.write_text("not a directory", encoding="utf-8")
+        with self._run(output_dir=str(blocker)) as (code, out, _c):
+            self.assertNotEqual(code, 0)
+            self.assertIn("blocked", out)
+
+    def test_empty_inventory_exits_nonzero_without_a_report(self):
+        import openpyxl
+        empty = self.workdir / "empty.xlsx"
+        wb = openpyxl.Workbook()
+        ws = wb.active
+        ws.title = "FW_List"
+        ws.append(["FirewallName", "Model", "Firewalltype", " IOS version"])
+        wb.save(empty)
+        with self._run(inventory=str(empty)) as (code, out, _c):
+            self.assertNotEqual(code, 0)
+            self.assertIn("no firewall rows", out.lower())
+        self.assertFalse(list(self.outdir.glob("*.html")))
+
+
+class ReasonDetailTests(_ApiRunBase):
+    """US2: every unanswerable device carries a specific, correctable reason."""
+
+    def _reason_row(self, name):
+        with self._run():
+            pass
+        return _row_for(self._report(), name)
+
+    def test_release_unknown_names_both_forms_of_the_release(self):
+        # ASA 9.14 is end-of-support and purged from Cisco's catalogue.
+        row = self._reason_row("FW-RELUNKNOWN")
+        self.assertIn("does not recognise release", row)
+        self.assertIn("9.14(4)24", row)        # as the inventory wrote it
+        self.assertIn("9.14.4.24", row)        # as it was checked
+
+    def test_release_not_on_platform_names_the_platforms_cisco_does_list(self):
+        row = self._reason_row("FW-NOTONPLAT")
+        self.assertIn("does not list it for this model", row)
+        self.assertIn("9.18.4.22", row)
+        # FR-012: at least one platform Cisco does list must be named.
+        self.assertIn("Cisco Firepower 1000 Series", row)
+        # ...and the platform it is NOT listed for must not appear as if it were.
+        self.assertNotIn("Cisco ASA 5500-X Series Firewalls", row)
+
+    def test_model_unmapped_names_the_model(self):
+        row = self._reason_row("FW-BADMODEL")
+        self.assertIn("could not be matched to a Cisco hardware platform", row)
+        self.assertIn("Unknown Appliance 9", row)
+
+    def test_field_missing_names_the_field(self):
+        row = self._reason_row("FW-NOVERSION")
+        self.assertIn("blank in the inventory", row)
+        self.assertIn("software release", row)
+
+    def test_family_unsupported_names_the_family(self):
+        row = self._reason_row("FW-BADFAMILY")
+        self.assertIn("outside what this check covers", row)
+        self.assertIn("SWITCH", row)
+
+    def test_check_incomplete_does_not_read_as_clean(self):
+        class AllIncomplete(FakeClient):
+            def get_advisories(self, os_type, release, platform_alias=None):
+                self.asked.append((os_type, platform_alias, release))
+                return m.INCOMPLETE, []
+
+        with self._run(client=AllIncomplete()):
+            pass
+        row = _row_for(self._report(), "FW-IMPACT-1")
+        self.assertIn("did not complete", row)
+        self.assertIn("not a statement that it is unaffected", row)
+
+    def test_every_needs_review_row_has_non_empty_reason_text(self):
+        with self._run():
+            pass
+        text = self._report()
+        for row in ROWS:
+            name = row[0]
+            if not name:
+                continue
+            chunk = _row_for(text, name)
+            if m.NEEDS_REVIEW in chunk:
+                self.assertIn('class="reason"', chunk, f"{name} has no reason block")
+                # A reason must say something beyond the generic fallback.
+                self.assertNotIn("Could not be assessed.</div>", chunk)
+
+    def test_reasons_contain_no_status_codes_or_internal_identifiers(self):
+        with self._run():
+            pass
+        text = self._report()
+        for token in ("errorCode", "NO_DATA_FOUND", "INVALID_ASA_VERSION",
+                      "HTTP 404", "HTTP 406", "release_unknown",
+                      "model_unmapped", "check_incomplete"):
+            self.assertNotIn(token, text, f"internal token {token!r} leaked into the report")
+
+
+def _row_for(html_text, device_name):
+    """The <tr> block containing a device, so per-row assertions cannot leak across rows.
+
+    Scoping matters: the report's filter controls name every verdict, so a whole-document
+    assertion about "Not impacted" would always pass or always fail regardless of the row.
+    """
+    for chunk in re.split(r"<tr\b", html_text):
+        if f"{device_name}</td>" in chunk:
+            return chunk
+    raise AssertionError(f"no row found for {device_name}")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_cli.py b/tests/test_cli.py
index fcf68f1..b8538b4 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -182,5 +182,66 @@ def test_us3_pip_or_source_message_is_clear(self):
         self.assertIn("source or pip", out.lower())
 
 
+# --------------------------------------------------------------------------- #
+# `--api` mode (spec 006)
+# --------------------------------------------------------------------------- #
+class ApiFlagTests(unittest.TestCase):
+    """Parsing and dispatch for the inventory-driven check."""
+
+    def _args(self, **over):
+        base = dict(api=False, url=None, inventory=None, sheet="FW_List",
+                    output_dir=None, dry_run=False, keep_temp=False,
+                    no_update_check=True, yes=False)
+        base.update(over)
+        return types.SimpleNamespace(**base)
+
+    def _run(self, args):
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = cli.cmd_run(args)
+        return code, buf.getvalue()
+
+    def test_api_flag_parses(self):
+        args = cli.build_parser().parse_args(["--api"])
+        self.assertTrue(args.api)
+
+    def test_api_flag_is_listed_in_help(self):
+        self.assertIn("--api", cli.build_parser().format_help())
+
+    def test_api_defaults_to_off(self):
+        self.assertFalse(cli.build_parser().parse_args([]).api)
+
+    def test_api_dispatches_to_run_api(self):
+        with mock.patch.object(cli.analyzer, "run_api", return_value=0) as run_api, \
+             mock.patch.object(cli.analyzer, "run") as run, \
+             mock.patch.object(cli, "_start_of_run_update_nudge"):
+            code, _out = self._run(self._args(api=True))
+        self.assertEqual(code, 0)
+        run_api.assert_called_once()
+        run.assert_not_called()
+
+    def test_without_api_the_existing_path_is_used(self):
+        with mock.patch.object(cli.analyzer, "run_api") as run_api, \
+             mock.patch.object(cli.analyzer, "run", return_value=0) as run, \
+             mock.patch.object(cli, "_start_of_run_update_nudge"):
+            code, _out = self._run(self._args(api=False, url="https://x/y"))
+        self.assertEqual(code, 0)
+        run.assert_called_once()
+        run_api.assert_not_called()
+
+    def test_api_with_url_is_refused_before_anything_runs(self):
+        """FR-003: the two modes answer different questions; combining them is an error."""
+        with mock.patch.object(cli.analyzer, "run_api") as run_api, \
+             mock.patch.object(cli.analyzer, "run") as run, \
+             mock.patch.object(cli, "_start_of_run_update_nudge") as nudge:
+            code, out = self._run(self._args(api=True, url="https://x/y"))
+        self.assertNotEqual(code, 0)
+        run_api.assert_not_called()
+        run.assert_not_called()
+        nudge.assert_not_called()          # not even the update check runs
+        self.assertIn("--api", out)
+        self.assertIn("--url", out)
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_config.py b/tests/test_config.py
index ee0f52c..c203bad 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -6,6 +6,8 @@
 written under a temporary directory. Run with:  python -m unittest tests.test_config
 """
 
+import contextlib
+import io
 import os
 import sys
 import tempfile
@@ -96,5 +98,286 @@ def test_save_roundtrip_and_permissions(self):
                     self.assertEqual(path.stat().st_mode & 0o777, 0o600)
 
 
+# --------------------------------------------------------------------------- #
+# Cisco PSIRT credentials (spec 006)
+# --------------------------------------------------------------------------- #
+class CiscoCredentialStorageTests(unittest.TestCase):
+    """The two Cisco values must persist and resolve exactly like the existing settings."""
+
+    def test_keys_are_managed_by_save(self):
+        self.assertIn(config.CISCO_CLIENT_ID, config.KEYS)
+        self.assertIn(config.CISCO_CLIENT_SECRET, config.KEYS)
+
+    def test_roundtrip_with_owner_only_permissions(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cfg_dir = Path(tmp) / config.APP_DIR_NAME
+            with mock.patch.object(config, "config_dir", return_value=cfg_dir), \
+                 mock.patch.object(config, "config_path", return_value=cfg_dir / "config"):
+                path = config.save({
+                    config.CISCO_CLIENT_ID: "the-client-id",
+                    config.CISCO_CLIENT_SECRET: "the-client-secret",
+                })
+                loaded = config.load_file()
+                self.assertEqual(loaded[config.CISCO_CLIENT_ID], "the-client-id")
+                self.assertEqual(loaded[config.CISCO_CLIENT_SECRET], "the-client-secret")
+                if os.name != "nt":
+                    self.assertEqual(path.stat().st_mode & 0o777, 0o600)
+
+    def test_header_documents_the_new_env_overrides(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            cfg_dir = Path(tmp) / config.APP_DIR_NAME
+            with mock.patch.object(config, "config_dir", return_value=cfg_dir), \
+                 mock.patch.object(config, "config_path", return_value=cfg_dir / "config"):
+                path = config.save({config.CISCO_CLIENT_ID: "x"})
+                text = path.read_text(encoding="utf-8")
+                self.assertIn("CISCO_CLIENT_ID", text)
+                self.assertIn("CISCO_CLIENT_SECRET", text)
+
+    def test_environment_takes_precedence_over_the_file(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "config"
+            path.write_text("CISCO_CLIENT_ID=file-id\nCISCO_CLIENT_SECRET=file-secret\n",
+                            encoding="utf-8")
+            with mock.patch.object(config, "config_path", return_value=path), \
+                 mock.patch.dict(os.environ, {"CISCO_CLIENT_ID": "env-id"}, clear=True):
+                self.assertEqual(config.resolve(config.CISCO_CLIENT_ID), "env-id")
+                self.assertEqual(config.resolve(config.CISCO_CLIENT_SECRET), "file-secret")
+
+    def test_absent_resolves_to_empty_string(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "config"
+            path.write_text("", encoding="utf-8")
+            with mock.patch.object(config, "config_path", return_value=path), \
+                 mock.patch.dict(os.environ, {}, clear=True):
+                self.assertEqual(config.resolve(config.CISCO_CLIENT_ID), "")
+                self.assertEqual(config.resolve(config.CISCO_CLIENT_SECRET), "")
+
+    def test_whitespace_only_is_treated_as_absent(self):
+        # A blank-but-present value must never be sent to Cisco as-is (FR-047).
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "config"
+            path.write_text("CISCO_CLIENT_ID=   \n", encoding="utf-8")
+            with mock.patch.object(config, "config_path", return_value=path), \
+                 mock.patch.dict(os.environ, {"CISCO_CLIENT_SECRET": "  "}, clear=True):
+                self.assertEqual(config.resolve(config.CISCO_CLIENT_ID), "")
+                self.assertEqual(config.resolve(config.CISCO_CLIENT_SECRET), "")
+
+
+class RunConfigTests(unittest.TestCase):
+    """`caia --config` prompt behaviour and Cisco credential verification (spec 006)."""
+
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.cfg_dir = Path(self._tmp.name) / config.APP_DIR_NAME
+        self.cfg_path = self.cfg_dir / "config"
+
+    @contextlib.contextmanager
+    def _session(self, *, visible=None, secrets=None, existing=None, token=None,
+                 confirm=True, isatty=True):
+        """Drive run_config with scripted prompt answers and a scripted token check."""
+        visible_answers = list(visible or [])
+        secret_answers = list(secrets or [])
+        buf = io.StringIO()
+        # `ui.ask`/`ui.ask_secret` print their own prompt label, so mocking them hides it
+        # from stdout. Record the labels instead so prompt assertions stay meaningful.
+        self.prompted = {"visible": [], "secret": []}
+
+        def fake_ask(label, default=None):
+            self.prompted["visible"].append(label)
+            return visible_answers.pop(0) if visible_answers else ""
+
+        def fake_ask_secret(label):
+            self.prompted["secret"].append(label)
+            return secret_answers.pop(0) if secret_answers else ""
+
+        def fake_fetch_token(client_id, client_secret, **_kw):
+            if isinstance(token, Exception):
+                raise token
+            return token or "a-token"
+
+        from cisco_advisory_impact_agent import psirt
+
+        with mock.patch.object(config, "config_dir", return_value=self.cfg_dir), \
+             mock.patch.object(config, "config_path", return_value=self.cfg_path), \
+             mock.patch.object(config, "load_file",
+                               return_value=dict(existing or {})), \
+             mock.patch.object(config.ui, "ask", side_effect=fake_ask), \
+             mock.patch.object(config.ui, "ask_secret", side_effect=fake_ask_secret), \
+             mock.patch.object(config.ui, "select", side_effect=lambda *a, **k: "m-1"), \
+             mock.patch.object(config.ui, "confirm", return_value=confirm), \
+             mock.patch.object(psirt, "fetch_token",
+                               side_effect=fake_fetch_token) as m_token, \
+             mock.patch.object(config.sys.stdin, "isatty", return_value=isatty), \
+             contextlib.redirect_stdout(buf):
+            code = config.run_config()
+        yield code, buf.getvalue(), m_token
+
+    def _saved(self):
+        return config.load_file.__wrapped__() if hasattr(config.load_file, "__wrapped__") \
+            else _read_cfg(self.cfg_path)
+
+    # --- prompts ---------------------------------------------------------- #
+    def test_prompts_for_both_cisco_values(self):
+        with self._session(visible=["the-id"], secrets=["fuelix-key", "the-secret"]) \
+                as (code, _out, _t):
+            self.assertEqual(code, 0)
+        self.assertTrue(any("Cisco client ID" in p for p in self.prompted["visible"]),
+                        f"visible prompts were {self.prompted['visible']}")
+        self.assertTrue(any("Cisco client secret" in p for p in self.prompted["secret"]),
+                        f"secret prompts were {self.prompted['secret']}")
+
+    def test_client_id_uses_the_visible_prompt_and_the_secret_does_not(self):
+        """FR-037: the identifier is not a secret, so showing it lets a paste be verified."""
+        with self._session(visible=["visible-client-id"],
+                           secrets=["fuelix-key", "hidden-secret-value"]) as (_c, out, _t):
+            pass
+        # The ID went through the echoing prompt; the secret through the hidden one.
+        self.assertTrue(any("Cisco client ID" in p for p in self.prompted["visible"]))
+        self.assertFalse(any("Cisco client ID" in p for p in self.prompted["secret"]))
+        self.assertTrue(any("Cisco client secret" in p for p in self.prompted["secret"]))
+        self.assertFalse(any("Cisco client secret" in p for p in self.prompted["visible"]))
+        # And the secret value itself never reaches the terminal.
+        self.assertNotIn("hidden-secret-value", out)
+
+    def test_an_already_saved_client_id_is_displayed(self):
+        with self._session(visible=[], secrets=[],
+                           existing={config.CISCO_CLIENT_ID: "saved-client-id",
+                                     config.CISCO_CLIENT_SECRET: "saved-secret"}) \
+                as (_c, out, _t):
+            self.assertIn("saved-client-id", out)
+            self.assertNotIn("saved-secret", out)
+
+    def test_secret_entry_confirms_the_captured_length(self):
+        secret = "0123456789"
+        with self._session(visible=["id"], secrets=["k", secret]) as (_c, out, _t):
+            self.assertIn("10 characters", out)
+            self.assertNotIn(secret, out)
+
+    def test_empty_input_keeps_an_existing_value(self):
+        existing = {config.API_KEY: "old-key",
+                    config.CISCO_CLIENT_ID: "old-id",
+                    config.CISCO_CLIENT_SECRET: "old-secret"}
+        with self._session(visible=[], secrets=[], existing=existing) as (code, out, _t):
+            self.assertEqual(code, 0)
+            self.assertIn("left unchanged", out)
+        saved = _read_cfg(self.cfg_path)
+        self.assertEqual(saved[config.API_KEY], "old-key")
+        self.assertEqual(saved[config.CISCO_CLIENT_ID], "old-id")
+        self.assertEqual(saved[config.CISCO_CLIENT_SECRET], "old-secret")
+
+    def test_empty_fuelix_key_is_accepted(self):
+        """FR-035/FR-036: an --api-only user must not be forced to invent an AI key."""
+        with self._session(visible=["the-id"], secrets=["", "the-secret"]) \
+                as (code, out, _t):
+            self.assertEqual(code, 0)
+        saved = _read_cfg(self.cfg_path)
+        self.assertNotIn(config.API_KEY, saved)
+        self.assertEqual(saved[config.CISCO_CLIENT_SECRET], "the-secret")
+
+    def test_skipping_cisco_entirely_still_completes(self):
+        with self._session(visible=[], secrets=["fuelix-key"]) as (code, _out, m_token):
+            self.assertEqual(code, 0)
+            m_token.assert_not_called()          # FR-044: no request when skipped
+        saved = _read_cfg(self.cfg_path)
+        self.assertEqual(saved[config.API_KEY], "fuelix-key")
+
+    # --- verification ----------------------------------------------------- #
+    def test_valid_credentials_are_reported_as_valid(self):
+        with self._session(visible=["id"], secrets=["k", "s"]) as (code, out, m_token):
+            self.assertEqual(code, 0)
+            m_token.assert_called_once()
+            self.assertIn("accepted", out.lower())
+
+    def test_rejected_credentials_show_ciscos_reason_and_are_not_saved(self):
+        from cisco_advisory_impact_agent import psirt
+        err = psirt.PsirtAuthError("Cisco rejected the credentials (HTTP 401): "
+                                   "invalid_client")
+        with self._session(visible=["bad-id"], secrets=["k", "bad-secret"],
+                           token=err) as (code, out, _t):
+            self.assertNotEqual(code, 0)
+            self.assertIn("rejected", out.lower())
+            self.assertIn("invalid_client", out)
+            self.assertIn("--config", out)
+        saved = _read_cfg(self.cfg_path)
+        self.assertNotIn(config.CISCO_CLIENT_SECRET, saved)
+        self.assertNotIn(config.CISCO_CLIENT_ID, saved)
+
+    def test_rejection_preserves_previously_saved_cisco_values(self):
+        from cisco_advisory_impact_agent import psirt
+        existing = {config.CISCO_CLIENT_ID: "good-old-id",
+                    config.CISCO_CLIENT_SECRET: "good-old-secret"}
+        with self._session(visible=["new-bad-id"], secrets=["k", "new-bad-secret"],
+                           existing=existing,
+                           token=psirt.PsirtAuthError("rejected")) as (code, _out, _t):
+            self.assertNotEqual(code, 0)
+        saved = _read_cfg(self.cfg_path)
+        self.assertEqual(saved[config.CISCO_CLIENT_ID], "good-old-id")
+        self.assertEqual(saved[config.CISCO_CLIENT_SECRET], "good-old-secret")
+
+    def test_unreachable_is_distinct_from_rejected_and_can_be_saved(self):
+        """FR-043: a proxy outage must never block configuration."""
+        from cisco_advisory_impact_agent import psirt
+        err = psirt.PsirtUnreachableError("Cisco could not be reached (URLError). "
+                                         "This is a connectivity problem, not a "
+                                         "credential problem.")
+        with self._session(visible=["id"], secrets=["k", "s"], token=err,
+                           confirm=True) as (code, out, _t):
+            self.assertEqual(code, 0)
+            self.assertIn("could not", out.lower())
+            self.assertNotIn("rejected", out.lower())
+        saved = _read_cfg(self.cfg_path)
+        self.assertEqual(saved[config.CISCO_CLIENT_SECRET], "s")
+
+    def test_unreachable_declined_does_not_save(self):
+        from cisco_advisory_impact_agent import psirt
+        with self._session(visible=["id"], secrets=["k", "s"],
+                           token=psirt.PsirtUnreachableError("offline"),
+                           confirm=False) as (code, _out, _t):
+            self.assertNotEqual(code, 0)
+        saved = _read_cfg(self.cfg_path)
+        self.assertNotIn(config.CISCO_CLIENT_SECRET, saved)
+
+    def test_unreachable_in_a_non_interactive_session_saves_without_prompting(self):
+        from cisco_advisory_impact_agent import psirt
+        with self._session(visible=["id"], secrets=["k", "s"],
+                           token=psirt.PsirtUnreachableError("offline"),
+                           isatty=False) as (code, _out, _t):
+            self.assertEqual(code, 0)
+        self.assertEqual(_read_cfg(self.cfg_path)[config.CISCO_CLIENT_SECRET], "s")
+
+    # --- hygiene ---------------------------------------------------------- #
+    def test_no_credential_fragment_in_any_verification_message(self):
+        from cisco_advisory_impact_agent import psirt
+        secret = "leak-me-if-you-can"
+        outcomes = [None,
+                    psirt.PsirtAuthError("rejected"),
+                    psirt.PsirtUnreachableError("offline")]
+        for token in outcomes:
+            with self.subTest(token=type(token).__name__):
+                with self._session(visible=["the-client-id"], secrets=["k", secret],
+                                   token=token) as (_code, out, _t):
+                    self.assertNotIn(secret, out)
+
+    def test_saved_file_keeps_owner_only_permissions(self):
+        with self._session(visible=["id"], secrets=["k", "s"]):
+            pass
+        if os.name != "nt":
+            self.assertEqual(self.cfg_path.stat().st_mode & 0o777, 0o600)
+
+
+def _read_cfg(path):
+    """Parse the on-disk config file without going through config.load_file (mocked)."""
+    result = {}
+    if not path.exists():
+        return result
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            key, value = line.split("=", 1)
+            result[key.strip()] = value.strip()
+    return result
+
+
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_html_report.py b/tests/test_html_report.py
new file mode 100644
index 0000000..06f54f4
--- /dev/null
+++ b/tests/test_html_report.py
@@ -0,0 +1,326 @@
+"""Tests for the HTML report writer (spec 006). No network access.
+
+The escaping tests here are not boilerplate: every advisory Cisco returned during the
+feasibility spike carried raw HTML in its `summary`, so unescaped interpolation would
+render externally-authored markup inside the tool's own output.
+"""
+
+from __future__ import annotations
+
+import re
+import tempfile
+import unittest
+from pathlib import Path
+
+from cisco_advisory_impact_agent import html_report as hr
+from cisco_advisory_impact_agent import matching as m
+from tests.fixtures import psirt_responses as fx
+
+
+def _device(name="fw-1", verdict=m.IMPACTED, reason=None, advisories=None, priority=1,
+            model="ISA-3000", version="7.4.2.3"):
+    return {
+        "name": name, "model": model, "family": "FTD", "version": version,
+        "priority": priority,
+        "raw": {"FirewallName": name, "Model": model, "Firewalltype": "FTD",
+                " IOS version": version, "Priority* (1-High 3-Low)": priority},
+        "verdict": verdict, "reason": reason,
+        "advisories": advisories if advisories is not None else [],
+    }
+
+
+class FilenameTests(unittest.TestCase):
+    def test_name_matches_the_contracted_pattern(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = hr.write_report([_device()], None, tmp)
+            self.assertRegex(path.name, r"^impact_report_\d{8}_\d{6}(_\d+)?\.html$")
+
+    def test_a_second_report_in_the_same_second_does_not_overwrite(self):
+        import datetime as dt
+        fixed = dt.datetime(2026, 7, 25, 12, 0, 0)
+        with tempfile.TemporaryDirectory() as tmp:
+            first = hr.write_report([_device()], None, tmp, now=fixed)
+            original = first.read_bytes()
+            second = hr.write_report([_device(name="fw-2")], None, tmp, now=fixed)
+            self.assertNotEqual(first, second)
+            self.assertTrue(first.exists() and second.exists())
+            self.assertEqual(first.read_bytes(), original, "first report was modified")
+
+    def test_output_directory_is_created(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            target = Path(tmp) / "nested" / "output"
+            path = hr.write_report([_device()], None, str(target))
+            self.assertTrue(path.exists())
+
+
+class StructureTests(unittest.TestCase):
+    def test_every_device_appears_once(self):
+        devices = [_device(name=f"fw-{i}") for i in range(7)]
+        text = hr.render(devices)
+        # Body rows are the ones carrying a verdict; the header row has none.
+        self.assertEqual(text.count("<tr data-verdict="), 7)
+        for i in range(7):
+            self.assertEqual(text.count(f"fw-{i}</td>"), 1)
+
+    def test_original_inventory_columns_are_reproduced(self):
+        text = hr.render([_device()])
+        for title in ("FirewallName", "Model", "Firewalltype", "IOS version",
+                      "Priority* (1-High 3-Low)"):
+            self.assertIn(hr.esc(title), text)
+
+    def test_verdict_column_present_for_each_verdict(self):
+        devices = [
+            _device(name="a", verdict=m.IMPACTED, advisories=[fx.advisory()]),
+            _device(name="b", verdict=m.NOT_IMPACTED),
+            _device(name="c", verdict=m.NEEDS_REVIEW,
+                    reason=m.Reason(m.RELEASE_UNKNOWN, release="9.14.4.24")),
+        ]
+        text = hr.render(devices)
+        for verdict in (m.IMPACTED, m.NOT_IMPACTED, m.NEEDS_REVIEW):
+            self.assertIn(verdict, text)
+
+    def test_verdicts_are_distinguishable_without_colour(self):
+        # Survives greyscale printing and colour-vision deficiency.
+        text = hr.render([
+            _device(name="a", verdict=m.IMPACTED, advisories=[fx.advisory()]),
+            _device(name="b", verdict=m.NOT_IMPACTED),
+            _device(name="c", verdict=m.NEEDS_REVIEW, reason=m.Reason(m.CHECK_INCOMPLETE)),
+        ])
+        for mark in hr._VERDICT_MARK.values():
+            self.assertIn(mark, text)
+
+    def test_document_is_wellformed_enough_to_parse(self):
+        text = hr.render([_device()])
+        self.assertTrue(text.startswith("<!DOCTYPE html>"))
+        self.assertIn("</html>", text)
+
+
+class SelfContainmentTests(unittest.TestCase):
+    def test_no_external_resource_references(self):
+        # FR-030: must render offline, after being emailed, behind a restrictive proxy.
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        for pattern in (r'<link[^>]+href=', r'<script[^>]+src=',
+                        r'@import', r'url\(\s*https?:'):
+            self.assertIsNone(re.search(pattern, text, re.IGNORECASE),
+                              f"external reference matched {pattern!r}")
+
+    def test_css_is_inlined(self):
+        self.assertIn("<style>", hr.render([_device()]))
+
+
+class EscapingTests(unittest.TestCase):
+    """FR-033: Cisco-supplied content is text and cannot alter the document."""
+
+    def test_script_in_advisory_title_is_inert(self):
+        hostile = dict(fx.advisory())
+        hostile["advisoryTitle"] = "<script>alert(1)</script>"
+        hostile["advisoryId"] = "<script>alert(2)</script>"
+        text = hr.render([_device(advisories=[hostile])])
+        self.assertNotIn("<script>alert(1)</script>", text)
+        self.assertNotIn("<script>alert(2)</script>", text)
+        self.assertIn("&lt;script&gt;", text)
+
+    def test_anchor_in_cisco_content_is_not_a_live_link(self):
+        hostile = dict(fx.advisory())
+        hostile["advisoryId"] = '<a href="https://evil.invalid">click</a>'
+        text = hr.render([_device(advisories=[hostile])])
+        self.assertNotIn('<a href="https://evil.invalid"', text)
+
+    def test_raw_html_summary_never_reaches_the_document_as_markup(self):
+        # The real shape: every spike advisory had <p>/<strong>/<a> in its summary.
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        self.assertNotIn("<p>A vulnerability", text)
+        self.assertNotIn('href="https://example.invalid/x"', text)
+
+    def test_hostile_inventory_values_are_escaped(self):
+        device = _device(name='<img src=x onerror=alert(1)>')
+        device["raw"]["FirewallName"] = '<img src=x onerror=alert(1)>'
+        text = hr.render([device])
+        self.assertNotIn("<img src=x", text)
+        self.assertIn("&lt;img", text)
+
+    def test_esc_handles_none_and_quotes(self):
+        self.assertEqual(hr.esc(None), "")
+        self.assertIn("&quot;", hr.esc('a "quoted" value'))
+
+
+class AdvisoryDetailTests(unittest.TestCase):
+    """US3: the report is a worklist, not just a list of problems."""
+
+    def test_advisory_id_links_to_ciscos_published_page(self):
+        adv = fx.advisory(advisory_id="cisco-sa-example-AbC123")
+        text = hr.render([_device(advisories=[adv])])
+        self.assertIn('href="https://sec.cloudapps.cisco.com/security/center/content/'
+                      'CiscoSecurityAdvisory/cisco-sa-example-AbC123"', text)
+        self.assertIn("cisco-sa-example-AbC123</a>", text)
+
+    def test_severity_and_title_are_shown(self):
+        text = hr.render([_device(advisories=[fx.advisory(sir="Critical")])])
+        self.assertIn("Critical", text)
+        self.assertIn("Command Injection Vulnerability", text)
+
+    def test_fixed_release_is_shown(self):
+        text = hr.render([_device(advisories=[fx.advisory(first_fix="7.4.3")])])
+        self.assertIn("fixed in 7.4.3", text)
+
+    def test_missing_fixed_release_is_stated_not_inferred(self):
+        text = hr.render([_device(advisories=[fx.advisory(first_fix=None)])])
+        self.assertIn("no fixed release published", text)
+        self.assertNotIn("fixed in ", text)
+
+    def test_first_fix_of_reads_the_nested_shape(self):
+        self.assertEqual(hr.first_fix_of(fx.advisory(first_fix="9.16.4.85")), "9.16.4.85")
+        self.assertEqual(hr.first_fix_of({"platforms": []}), "")
+        self.assertEqual(hr.first_fix_of({}), "")
+
+    def test_cve_identifiers_are_shown(self):
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        self.assertIn("CVE-2026-20012", text)
+
+    def test_advisories_are_ordered_most_severe_first(self):
+        advisories = [
+            fx.advisory(advisory_id="cisco-sa-low", sir="Low"),
+            fx.advisory(advisory_id="cisco-sa-crit", sir="Critical"),
+            fx.advisory(advisory_id="cisco-sa-med", sir="Medium"),
+        ]
+        text = hr.render([_device(advisories=advisories)])
+        self.assertLess(text.index("cisco-sa-crit"), text.index("cisco-sa-med"))
+        self.assertLess(text.index("cisco-sa-med"), text.index("cisco-sa-low"))
+
+    def test_long_advisory_list_is_collapsed_not_truncated(self):
+        # The spike saw one device with 82 advisories (FR-025).
+        advisories = [fx.advisory(advisory_id=f"cisco-sa-{i:03d}") for i in range(82)]
+        text = hr.render([_device(advisories=advisories)])
+        self.assertIn("<details", text)
+        self.assertIn("82 advisories", text)
+        for i in range(82):
+            self.assertIn(f"cisco-sa-{i:03d}", text, "advisory list was truncated")
+
+    def test_single_advisory_is_not_pluralised(self):
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        self.assertIn("1 advisory<", text)
+
+
+class InteractivityTests(unittest.TestCase):
+    def test_filter_controls_exist_for_each_verdict(self):
+        devices = [
+            _device(name="a", verdict=m.IMPACTED, advisories=[fx.advisory()]),
+            _device(name="b", verdict=m.NOT_IMPACTED),
+            _device(name="c", verdict=m.NEEDS_REVIEW, reason=m.Reason(m.CHECK_INCOMPLETE)),
+        ]
+        text = hr.render(devices)
+        for verdict in (m.IMPACTED, m.NOT_IMPACTED, m.NEEDS_REVIEW):
+            self.assertIn(f'data-filter="{verdict}"', text)
+        self.assertIn('data-filter="all"', text)
+
+    def test_rows_carry_their_verdict_for_filtering(self):
+        text = hr.render([_device(verdict=m.IMPACTED, advisories=[fx.advisory()])])
+        self.assertIn(f'data-verdict="{m.IMPACTED}"', text)
+
+    def test_columns_are_sortable_including_priority(self):
+        text = hr.render([_device()])
+        self.assertIn('class="sortable"', text)
+        # The priority column header must itself be sortable.
+        idx = text.index("Priority")
+        self.assertIn("sortable", text[max(0, idx - 60):idx])
+
+    def test_expand_all_control_exists(self):
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        self.assertIn('id="expand-all"', text)
+
+    def test_javascript_is_inlined_and_builds_no_markup_from_cisco_strings(self):
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        self.assertIn("<script>", text)
+        script = text.split("<script>")[1].split("</script>")[0]
+        for sink in ("innerHTML", "outerHTML", "document.write", "insertAdjacentHTML"):
+            self.assertNotIn(sink, script, f"{sink} would allow markup injection")
+
+    def test_still_no_external_references_after_adding_script(self):
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        self.assertIsNone(re.search(r'<script[^>]+src=', text, re.IGNORECASE))
+
+
+class SummaryAndCoverageTests(unittest.TestCase):
+    """US5: a second-hand reader can calibrate before acting."""
+
+    def _summary(self, **over):
+        import datetime as dt
+        base = dict(generated_at=dt.datetime(2026, 7, 25, 14, 30, 5),
+                    inventory_file="inventory.xlsx", device_count=3,
+                    counts={}, partial_cause=None)
+        base.update(over)
+        return base
+
+    def _devices(self):
+        return [
+            _device(name="a", verdict=m.IMPACTED, advisories=[fx.advisory()]),
+            _device(name="b", verdict=m.NOT_IMPACTED),
+            _device(name="c", verdict=m.NEEDS_REVIEW,
+                    reason=m.Reason(m.CHECK_INCOMPLETE)),
+        ]
+
+    def test_run_provenance_is_shown(self):
+        text = hr.render(self._devices(), self._summary())
+        self.assertIn("2026-07-25 14:30:05", text)
+        self.assertIn("inventory.xlsx", text)
+        self.assertIn("Firewalls assessed", text)
+
+    def test_counts_per_verdict_match_the_table(self):
+        devices = self._devices()
+        text = hr.render(devices, self._summary())
+        summary_block = text.split('class="summary"')[1].split("</section>")[0]
+        for verdict in (m.IMPACTED, m.NOT_IMPACTED, m.NEEDS_REVIEW):
+            self.assertIn(verdict, summary_block)
+            expected = sum(1 for d in devices if d["verdict"] == verdict)
+            actual = text.count(f'<tr data-verdict="{verdict}"')
+            self.assertEqual(actual, expected)
+
+    def test_needs_review_count_is_visible_in_the_summary(self):
+        devices = [_device(name=f"n{i}", verdict=m.NEEDS_REVIEW,
+                           reason=m.Reason(m.CHECK_INCOMPLETE)) for i in range(4)]
+        text = hr.render(devices, self._summary(device_count=4))
+        block = text.split('class="facts"')[1].split("</dl>")[0]
+        self.assertIn(m.NEEDS_REVIEW, block)
+        self.assertIn(">4</dd>", block)
+
+    def test_both_coverage_statements_are_present(self):
+        text = hr.render(self._devices(), self._summary())
+        self.assertIn("January 2022", text)
+        self.assertIn("does not account for", text)
+        self.assertIn("listed as affected", text)
+
+    def test_coverage_notes_appear_in_every_report_even_without_a_summary(self):
+        text = hr.render([_device()])
+        for note in hr.COVERAGE_NOTES:
+            self.assertIn(hr.esc(note), text)
+
+    def test_needs_review_is_explicitly_not_a_safety_claim(self):
+        text = hr.render(self._devices(), self._summary())
+        self.assertIn("not a statement of safety", text)
+
+    def test_partial_run_is_disclosed(self):
+        text = hr.render(self._devices(),
+                         self._summary(partial_cause="Cisco became unreachable."))
+        self.assertIn("This run was partial", text)
+        self.assertIn("Cisco became unreachable.", text)
+        self.assertIn("not known to be unaffected", text)
+
+    def test_complete_run_carries_no_partial_notice(self):
+        text = hr.render(self._devices(), self._summary())
+        self.assertNotIn("This run was partial", text)
+
+    def test_missing_summary_does_not_crash(self):
+        text = hr.render([_device()], None)
+        self.assertIn("Firewalls assessed", text)
+
+
+class CredentialHygieneTests(unittest.TestCase):
+    def test_no_credential_value_can_appear_in_the_report(self):
+        # The writer is given devices only; there is no path for a credential to reach it.
+        text = hr.render([_device(advisories=[fx.advisory()])])
+        for forbidden in ("client_secret", "CISCO_CLIENT_SECRET", "Bearer "):
+            self.assertNotIn(forbidden, text)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_matching.py b/tests/test_matching.py
new file mode 100644
index 0000000..8b27036
--- /dev/null
+++ b/tests/test_matching.py
@@ -0,0 +1,315 @@
+"""Tests for the pure matching / verdict logic (spec 006).
+
+The decisive assertion in this file is that no path other than outcome-table row 8 can
+produce NOT_IMPACTED. Everything else is detail.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from cisco_advisory_impact_agent import matching as m
+from tests.fixtures import psirt_responses as fx
+
+
+def _catalogues():
+    cat = m.Catalogues()
+    for ost in ("asa", "ftd"):
+        cat.add_platforms(ost, fx.PLATFORMS[ost])
+    for ost in ("asa", "ftd", "fmc"):
+        cat.add_releases(ost, fx.OS_DATA[ost])
+    return cat
+
+
+def _device(name="fw", model="ISA-3000", family="FTD", version="7.4.2.3"):
+    return {"name": name, "model": model, "family": family, "version": version}
+
+
+class NormalizeReleaseTests(unittest.TestCase):
+    def test_transforms_from_research_decision_6(self):
+        cases = {
+            "9.16(4)67": "9.16.4.67",
+            "9.12(4)67": "9.12.4.67",
+            "9.20(3)7": "9.20.3.7",
+            "9.20(4)": "9.20.4",
+            "9.20(4)7/ASDM 7.22.1": "9.20.4.7",
+            "7.4.2.1-30": "7.4.2.1",
+        }
+        for raw, expected in cases.items():
+            with self.subTest(raw=raw):
+                self.assertEqual(m.normalize_release(raw), expected)
+
+    def test_already_canonical_is_unchanged(self):
+        for value in ("9.19.1.24", "7.4.2.3", "7.0.1", "9.20.4"):
+            self.assertEqual(m.normalize_release(value), value)
+
+    def test_is_idempotent(self):
+        for raw in ("9.16(4)67", "9.20(4)7/ASDM 7.22.1", "7.4.2.1-30"):
+            once = m.normalize_release(raw)
+            self.assertEqual(m.normalize_release(once), once)
+
+    def test_blank_and_none(self):
+        for raw in ("", "   ", None):
+            self.assertEqual(m.normalize_release(raw), "")
+
+    def test_surrounding_whitespace_is_trimmed(self):
+        self.assertEqual(m.normalize_release("  9.16(4)67  "), "9.16.4.67")
+
+
+class PlatformAliasTests(unittest.TestCase):
+    def test_every_real_inventory_model_maps(self):
+        # The 22 distinct models in the team's real inventory (research Decision 7).
+        cases = [
+            ("ISA-3000", "FTD", "ISA3000"),
+            ("ASA 5506", "ASA", "ASA5500X"),
+            ("ASA 5515", "ASA", "ASA5500X"),
+            ("ASA 5525", "ASA", "ASA5500X"),
+            ("ASA 5555", "ASA", "ASA5500X"),
+            ("Firepower 1010", "ASA", "FPR1000"),
+            ("Firepower 1150", "ASA", "FPR1000"),
+            ("Cisco Firepower 1010 Threat Defense", "FTD", "FPR1000"),
+            ("Cisco Firepower 1120 Threat Defense", "FTD", "FPR1000"),
+            ("Firepower 2110", "ASA", "FPR2100"),
+            ("Firepower 2130", "ASA", "FPR2100"),
+            ("Cisco Firepower 2110 Threat Defense", "FTD", "FPR2100"),
+            ("Cisco Firepower 2120 Threat Defense", "FTD", "FPR2100"),
+            ("Firepower 3120", "ASA", "FWL3100"),
+            ("Cisco Firepower 3130 Threat Defense", "FTD", "FWL3100"),
+            ("Cisco Secure Firewall 3120 Threat Defense", "FTD", "FWL3100"),
+            ("Cisco Secure Firewall 3140 Threat Defense", "FTD", "FWL3100"),
+            ("Firepower 4110", "ASA", "FPR4100"),
+            ("Cisco Firepower 4112 Threat Defense", "FTD", "FPR4100"),
+            ("Cisco Firepower Threat Defense for VMware", "FTD", "FPRNGFW"),
+        ]
+        for model, family, expected in cases:
+            with self.subTest(model=model, family=family):
+                self.assertEqual(m.platform_alias_for(model, family), expected)
+
+    def test_asa_ftd_asymmetry_for_5500x_hardware(self):
+        # Cisco's own catalogues name the same hardware differently per family.
+        self.assertEqual(m.platform_alias_for("ASA 5515", "ASA"), "ASA5500X")
+        self.assertEqual(m.platform_alias_for("ASA 5515", "FTD"), "ASA5500")
+
+    def test_unmappable_model_returns_none(self):
+        for model in ("Unknown Appliance 9", "Catalyst 9300 Switch Stack", "", None):
+            self.assertIsNone(m.platform_alias_for(model, "ASA"))
+
+    def test_newer_series_without_an_alias_is_unmapped(self):
+        # Secure Firewall 200/1200/4200/6100 exist in the release catalogue but Cisco
+        # publishes no alias for them yet (research Decision 9).
+        for model in ("Cisco Secure Firewall 4225 Threat Defense",
+                      "Cisco Secure Firewall 1210 Threat Defense"):
+            self.assertIsNone(m.platform_alias_for(model, "FTD"))
+
+    def test_family_platform_support(self):
+        for family in ("asa", "ftd", "fxos", "nxos", "ASA", "FTD"):
+            self.assertTrue(m.family_takes_platform(family))
+        for family in ("fmc", "FMC", "ios", "iosxe", "aci", "", None):
+            self.assertFalse(m.family_takes_platform(family))
+
+    def test_family_supported(self):
+        self.assertTrue(m.family_supported("FMC"))
+        self.assertFalse(m.family_supported("SWITCH"))
+        self.assertFalse(m.family_supported(""))
+
+
+class CatalogueTests(unittest.TestCase):
+    def setUp(self):
+        self.cat = _catalogues()
+
+    def test_platform_index(self):
+        self.assertEqual(self.cat.platforms["asa"]["ASA5500X"],
+                         "Cisco ASA 5500-X Series Firewalls")
+        self.assertTrue(self.cat.known_alias("asa", "ASA5500X"))
+        self.assertFalse(self.cat.known_alias("asa", "ASA5500"))   # FTD-only alias
+        self.assertTrue(self.cat.known_alias("ftd", "ASA5500"))
+
+    def test_release_index_groups_platforms(self):
+        plats = self.cat.release_platforms("asa", "9.16.4.67")
+        self.assertIn("Cisco ASA 5500-X Series Firewalls", plats)
+        self.assertIn("Cisco Firepower 1000 Series", plats)
+
+    def test_fmc_rows_without_platform_name_do_not_crash(self):
+        # FMC catalogue rows carry no platform_name key at all (research Decision 8).
+        self.assertTrue(self.cat.release_known("fmc", "7.4.2.3"))
+        self.assertEqual(self.cat.release_platforms("fmc", "7.4.2.3"), set())
+
+    def test_purged_release_is_not_known(self):
+        # ASA 9.14 is end-of-support; Cisco holds no rows for it.
+        self.assertFalse(self.cat.release_known("asa", "9.14.4.24"))
+
+    def test_platform_confirmed_true_when_listed(self):
+        self.assertTrue(self.cat.platform_confirmed("asa", "9.16.4.67", "ASA5500X"))
+
+    def test_platform_confirmed_false_when_not_listed(self):
+        # ASA 9.18 dropped the 5500-X series.
+        self.assertFalse(self.cat.platform_confirmed("asa", "9.18.4.22", "ASA5500X"))
+
+    def test_platform_confirmed_reconciles_the_fprngfw_name_mismatch(self):
+        # /platforms says "Cisco Firepower NGFW Virtual"; OS_data says "Cisco Secure
+        # Firewall Threat Defense Virtual". Same platform (research Decision 5).
+        self.assertTrue(self.cat.platform_confirmed("ftd", "7.4.2.3", "FPRNGFW"))
+
+    def test_platform_confirmed_fails_closed_for_unknown_alias(self):
+        self.assertFalse(self.cat.platform_confirmed("asa", "9.16.4.67", "NOSUCHALIAS"))
+
+
+class OutcomeTableTests(unittest.TestCase):
+    """One case per row of data-model.md § Check outcome -> Verdict state map."""
+
+    def setUp(self):
+        self.cat = _catalogues()
+
+    def test_row1_missing_release(self):
+        verdict, reason = m.classify(_device(version=""), self.cat)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.FIELD_MISSING)
+        self.assertEqual(reason.detail["field"], "software release")
+
+    def test_row1_missing_model(self):
+        verdict, reason = m.classify(_device(model=""), self.cat)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.FIELD_MISSING)
+        self.assertEqual(reason.detail["field"], "model")
+
+    def test_row2_unsupported_family(self):
+        verdict, reason = m.classify(_device(family="SWITCH", model="Catalyst 9300"),
+                                     self.cat)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.FAMILY_UNSUPPORTED)
+        self.assertEqual(reason.detail["family"], "SWITCH")
+
+    def test_row3_unmapped_model(self):
+        verdict, reason = m.classify(_device(model="Unknown Appliance 9", family="ASA",
+                                             version="9.16.4.67"), self.cat)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.MODEL_UNMAPPED)
+        self.assertEqual(reason.detail["model"], "Unknown Appliance 9")
+
+    def test_row3_alias_cisco_does_not_list(self):
+        # ASA5500 is an FTD-only alias; asking ASA about it must be treated as unmapped.
+        cat = m.Catalogues()
+        cat.add_platforms("asa", [])          # Cisco lists no aliases for asa
+        cat.add_releases("asa", fx.OS_DATA["asa"])
+        verdict, reason = m.classify(_device(model="ASA 5515", family="ASA",
+                                             version="9.16.4.67"), cat)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.MODEL_UNMAPPED)
+
+    def test_row4_impacted(self):
+        verdict, reason = m.classify(_device(), self.cat, m.HAS_ADVISORIES,
+                                     advisories=[fx.advisory()])
+        self.assertEqual(verdict, m.IMPACTED)
+        self.assertIsNone(reason)
+
+    def test_row5_invalid_version(self):
+        verdict, reason = m.classify(_device(family="ASA", model="ASA 5525",
+                                             version="9.14(4)24"),
+                                     self.cat, m.INVALID_VERSION)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.RELEASE_UNKNOWN)
+        self.assertEqual(reason.detail["release"], "9.14.4.24")
+
+    def test_release_unknown_carries_both_raw_and_normalised(self):
+        # The difference between the two is usually what tells a reader what to fix.
+        _verdict, reason = m.classify(_device(family="ASA", model="ASA 5525",
+                                              version="9.14(4)24"),
+                                      self.cat, m.INVALID_VERSION)
+        self.assertEqual(reason.detail["raw_release"], "9.14(4)24")
+        self.assertEqual(reason.detail["release"], "9.14.4.24")
+
+    def test_row6_no_data_but_release_absent_from_catalogue(self):
+        verdict, reason = m.classify(_device(family="ASA", model="ASA 5525",
+                                             version="9.14(4)24"),
+                                     self.cat, m.NO_DATA)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.RELEASE_UNKNOWN)
+
+    def test_row7_release_not_listed_for_platform(self):
+        verdict, reason = m.classify(_device(family="ASA", model="ASA 5515",
+                                             version="9.18(4)22"),
+                                     self.cat, m.NO_DATA)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.RELEASE_NOT_ON_PLATFORM)
+        self.assertEqual(reason.detail["release"], "9.18.4.22")
+        self.assertTrue(reason.detail["platforms"], "must name the platforms Cisco lists")
+        self.assertNotIn("Cisco ASA 5500-X Series Firewalls", reason.detail["platforms"])
+
+    def test_row8_not_impacted_is_the_only_clean_path(self):
+        verdict, reason = m.classify(_device(version="7.9.9"), self.cat, m.NO_DATA)
+        self.assertEqual(verdict, m.NOT_IMPACTED)
+        self.assertIsNone(reason)
+
+    def test_row8_for_a_platformless_family(self):
+        # FMC takes no alias, so a known release with no advisories is clean.
+        verdict, reason = m.classify(_device(model="Secure FMC 1600", family="FMC",
+                                             version="7.4.2.4"),
+                                     self.cat, m.NO_DATA)
+        self.assertEqual(verdict, m.NOT_IMPACTED)
+        self.assertIsNone(reason)
+
+    def test_row9_incomplete_check(self):
+        verdict, reason = m.classify(_device(), self.cat, m.INCOMPLETE)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.CHECK_INCOMPLETE)
+
+    def test_row10_unrecognised_outcome(self):
+        verdict, reason = m.classify(_device(), self.cat, "something-cisco-changed")
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.CHECK_INCOMPLETE)
+
+    def test_no_outcome_yet_is_incomplete_not_clean(self):
+        # A device never reached during a partial run must not read as safe.
+        verdict, reason = m.classify(_device(), self.cat, outcome=None)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.CHECK_INCOMPLETE)
+
+    def test_has_advisories_outcome_with_empty_list_is_not_impacted_claim(self):
+        # Defensive: HAS_ADVISORIES with nothing attached must not assert Impacted.
+        verdict, _ = m.classify(_device(), self.cat, m.HAS_ADVISORIES, advisories=[])
+        self.assertNotEqual(verdict, m.IMPACTED)
+
+
+class SafetyPropertyTests(unittest.TestCase):
+    """Constitution IV: NOT_IMPACTED requires positive confirmation of release AND platform."""
+
+    def setUp(self):
+        self.cat = _catalogues()
+
+    def test_unreconcilable_platform_name_never_yields_not_impacted(self):
+        # A release Cisco knows, on a platform whose display name cannot be reconciled to
+        # any name in the release catalogue: must be NEEDS_REVIEW, never NOT_IMPACTED.
+        cat = m.Catalogues()
+        cat.add_platforms("ftd", [{"platformAlias": "ISA3000", "name": "Totally Renamed"}])
+        cat.add_releases("ftd", [{"nos_version": "7.4.2.3", "nos_type": "FTD",
+                                  "platform_name": "Cisco 3000 Series Industrial "
+                                                   "Security Appliances (ISA)"}])
+        verdict, reason = m.classify(_device(version="7.4.2.3"), cat, m.NO_DATA)
+        self.assertEqual(verdict, m.NEEDS_REVIEW)
+        self.assertEqual(reason.kind, m.RELEASE_NOT_ON_PLATFORM)
+
+    def test_no_outcome_or_failure_ever_yields_not_impacted(self):
+        for outcome in (None, m.INCOMPLETE, m.INVALID_VERSION, "garbage", ""):
+            with self.subTest(outcome=outcome):
+                verdict, _ = m.classify(_device(), self.cat, outcome)
+                self.assertNotEqual(verdict, m.NOT_IMPACTED)
+
+    def test_every_needs_review_carries_a_reason(self):
+        devices = [
+            _device(version=""),
+            _device(model=""),
+            _device(family="SWITCH", model="Catalyst 9300"),
+            _device(model="Unknown Appliance 9", family="ASA", version="9.16.4.67"),
+            _device(family="ASA", model="ASA 5525", version="9.14(4)24"),
+            _device(family="ASA", model="ASA 5515", version="9.18(4)22"),
+        ]
+        for dev in devices:
+            for outcome in (None, m.NO_DATA, m.INVALID_VERSION, m.INCOMPLETE):
+                verdict, reason = m.classify(dev, self.cat, outcome)
+                if verdict == m.NEEDS_REVIEW:
+                    self.assertIsNotNone(reason, f"{dev} / {outcome}")
+                    self.assertTrue(reason.kind)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_psirt.py b/tests/test_psirt.py
new file mode 100644
index 0000000..9bacf3a
--- /dev/null
+++ b/tests/test_psirt.py
@@ -0,0 +1,297 @@
+"""Tests for the Cisco PSIRT API client (spec 006). No network access.
+
+`urlopen` is replaced with a scripted fake, so pacing, token handling and status
+classification are all asserted without waiting or reaching Cisco.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import unittest
+import urllib.error
+
+from cisco_advisory_impact_agent import matching as m
+from cisco_advisory_impact_agent import psirt
+from tests.fixtures import psirt_responses as fx
+
+
+class _Response(io.BytesIO):
+    """Minimal stand-in for the object urlopen returns."""
+
+    def __init__(self, payload, status=200):
+        super().__init__(json.dumps(payload).encode("utf-8"))
+        self.status = status
+
+    def getcode(self):
+        return self.status
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+        return False
+
+
+def _http_error(status, payload):
+    return urllib.error.HTTPError(
+        "https://apix.cisco.com/x", status, "err", {},
+        io.BytesIO(json.dumps(payload).encode("utf-8")))
+
+
+class _Opener:
+    """Scripted opener. `script` is a list of responses/exceptions to hand back in turn."""
+
+    def __init__(self, script):
+        self.script = list(script)
+        self.calls = []
+
+    def __call__(self, request, timeout=None):
+        self.calls.append(request)
+        item = self.script.pop(0) if self.script else _Response({})
+        if isinstance(item, Exception):
+            raise item
+        return item
+
+
+class _Clock:
+    """Monotonic clock that only advances when sleep() is called."""
+
+    def __init__(self):
+        self.t = 0.0
+        self.slept = []
+
+    def sleep(self, seconds):
+        self.slept.append(seconds)
+        self.t += seconds
+
+    def now(self):
+        return self.t
+
+
+def _client(script, clock=None):
+    clk = clock or _Clock()
+    opener = _Opener(script)
+    client = psirt.Client("id-value", "secret-value", opener=opener,
+                          sleep=clk.sleep, clock=clk.now)
+    return client, opener, clk
+
+
+class FetchTokenTests(unittest.TestCase):
+    def test_returns_access_token(self):
+        opener = _Opener([_Response(fx.TOKEN)])
+        token = psirt.fetch_token("id", "secret", opener=opener)
+        self.assertEqual(token, "fixture-token-value")
+
+    def test_posts_form_encoded_client_credentials(self):
+        opener = _Opener([_Response(fx.TOKEN)])
+        psirt.fetch_token("the-id", "the-secret", opener=opener)
+        body = opener.calls[0].data.decode()
+        self.assertIn("grant_type=client_credentials", body)
+        self.assertIn("client_id=the-id", body)
+
+    def test_rejection_raises_auth_error_with_ciscos_reason(self):
+        err = _http_error(401, {"error_description": "invalid_client"})
+        with self.assertRaises(psirt.PsirtAuthError) as ctx:
+            psirt.fetch_token("id", "secret", opener=_Opener([err]))
+        self.assertIn("invalid_client", str(ctx.exception))
+
+    def test_unreachable_raises_distinct_error(self):
+        with self.assertRaises(psirt.PsirtUnreachableError) as ctx:
+            psirt.fetch_token("id", "secret",
+                              opener=_Opener([urllib.error.URLError("proxy refused")]))
+        # The message must say connectivity, not credentials (FR-043).
+        self.assertIn("connectivity", str(ctx.exception).lower())
+
+    def test_auth_and_unreachable_are_distinguishable(self):
+        self.assertTrue(issubclass(psirt.PsirtAuthError, psirt.PsirtError))
+        self.assertTrue(issubclass(psirt.PsirtUnreachableError, psirt.PsirtError))
+        self.assertFalse(issubclass(psirt.PsirtUnreachableError, psirt.PsirtAuthError))
+
+    def test_missing_token_in_response_is_an_auth_error(self):
+        with self.assertRaises(psirt.PsirtAuthError):
+            psirt.fetch_token("id", "secret", opener=_Opener([_Response({"scope": "x"})]))
+
+    def test_no_credential_value_appears_in_any_error(self):
+        secret = "s3cr3t-do-not-leak"
+        cases = [
+            _http_error(401, {"error_description": "invalid_client",
+                              # Cisco echoing the submitted value back at us:
+                              "client_secret": secret}),
+            urllib.error.URLError("boom"),
+        ]
+        for item in cases:
+            with self.subTest(item=type(item).__name__):
+                try:
+                    psirt.fetch_token("the-id", secret, opener=_Opener([item]))
+                except psirt.PsirtError as exc:
+                    self.assertNotIn(secret, str(exc))
+                    self.assertNotIn("the-id", str(exc))
+
+
+class ClassifyResponseTests(unittest.TestCase):
+    def test_200_with_advisories(self):
+        outcome, advisories = psirt.classify_response(200, fx.advisories_response(2))
+        self.assertEqual(outcome, m.HAS_ADVISORIES)
+        self.assertEqual(len(advisories), 2)
+
+    def test_200_with_empty_advisory_list_is_no_data(self):
+        outcome, advisories = psirt.classify_response(200, {"advisories": []})
+        self.assertEqual(outcome, m.NO_DATA)
+        self.assertEqual(advisories, [])
+
+    def test_404_no_data_found(self):
+        outcome, _ = psirt.classify_response(404, fx.NO_DATA_FOUND)
+        self.assertEqual(outcome, m.NO_DATA)
+
+    def test_404_other_error_code_is_incomplete(self):
+        outcome, _ = psirt.classify_response(404, {"errorCode": "VERSION_ID_IS_MANDATORY"})
+        self.assertEqual(outcome, m.INCOMPLETE)
+
+    def test_406_invalid_version(self):
+        for payload in (fx.INVALID_ASA_VERSION, fx.INVALID_FTD_VERSION):
+            outcome, _ = psirt.classify_response(406, payload)
+            self.assertEqual(outcome, m.INVALID_VERSION)
+
+    def test_429_is_incomplete_never_a_verdict(self):
+        outcome, _ = psirt.classify_response(429, fx.TOO_MANY_REQUESTS)
+        self.assertEqual(outcome, m.INCOMPLETE)
+
+    def test_5xx_and_unparseable_are_incomplete(self):
+        self.assertEqual(psirt.classify_response(500, {})[0], m.INCOMPLETE)
+        self.assertEqual(psirt.classify_response(200, None)[0], m.INCOMPLETE)
+
+    def test_documented_conflated_200_shape_is_honoured(self):
+        # The published reference describes this shape; the live API uses status codes.
+        # Either must classify as "release unknown", never as clean.
+        payload = {"errorCode": "NO_IOS_AFFECTING_ADVISORIES_FOUND; INVALID_IOS_VERSION",
+                   "errorMessage": "IOS version not found"}
+        outcome, _ = psirt.classify_response(200, payload)
+        self.assertEqual(outcome, m.INVALID_VERSION)
+
+    def test_classification_ignores_message_text(self):
+        # Same status and errorCode, reworded message -> same outcome.
+        a = psirt.classify_response(404, {"errorCode": "NO_DATA_FOUND",
+                                          "errorMessage": "No advisories found"})
+        b = psirt.classify_response(404, {"errorCode": "NO_DATA_FOUND",
+                                          "errorMessage": "Completely different wording"})
+        self.assertEqual(a[0], b[0])
+
+
+class ClientTests(unittest.TestCase):
+    def test_get_platforms_accepts_a_bare_list(self):
+        client, _, _ = _client([_Response(fx.TOKEN), _Response(fx.PLATFORMS["asa"])])
+        rows = client.get_platforms("asa")
+        self.assertEqual(len(rows), 9)
+
+    def test_get_platforms_accepts_a_wrapped_object(self):
+        client, _, _ = _client([_Response(fx.TOKEN),
+                                _Response({"platforms": fx.PLATFORMS["ftd"]})])
+        self.assertEqual(len(client.get_platforms("ftd")), 8)
+
+    def test_get_platforms_skips_the_request_for_platformless_families(self):
+        client, opener, _ = _client([])
+        self.assertEqual(client.get_platforms("fmc"), [])
+        self.assertEqual(opener.calls, [])
+
+    def test_get_os_data_returns_rows(self):
+        client, _, _ = _client([_Response(fx.TOKEN), _Response(fx.OS_DATA["fmc"])])
+        rows = client.get_os_data("fmc")
+        self.assertEqual(len(rows), 2)
+        self.assertNotIn("platform_name", rows[0])
+
+    def test_advisories_query_includes_the_platform_alias(self):
+        client, opener, _ = _client([_Response(fx.TOKEN),
+                                     _Response(fx.advisories_response(1))])
+        outcome, advisories = client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        self.assertEqual(outcome, m.HAS_ADVISORIES)
+        self.assertEqual(len(advisories), 1)
+        url = opener.calls[-1].full_url
+        self.assertIn("platformAlias=ISA3000", url)
+        self.assertIn("version=7.4.2.3", url)
+        self.assertIn("/OSType/ftd", url)
+
+    def test_advisories_query_omits_alias_for_fmc(self):
+        client, opener, _ = _client([_Response(fx.TOKEN), _Response(fx.NO_DATA_FOUND)])
+        client.get_advisories("fmc", "7.4.2.3", "SHOULD-BE-IGNORED")
+        self.assertNotIn("platformAlias", opener.calls[-1].full_url)
+
+    def test_no_inventory_identifier_is_ever_sent(self):
+        # Constitution Networking clause: only family, platform and release go over the wire.
+        client, opener, _ = _client([_Response(fx.TOKEN), _Response(fx.NO_DATA_FOUND)])
+        client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        url = opener.calls[-1].full_url
+        for param in urllib_query_keys(url):
+            self.assertIn(param, {"version", "platformAlias"})
+
+    def test_token_is_fetched_once_for_many_requests(self):
+        script = [_Response(fx.TOKEN)] + [_Response(fx.NO_DATA_FOUND) for _ in range(3)]
+        client, opener, _ = _client(script)
+        for _ in range(3):
+            client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        token_calls = [c for c in opener.calls if c.full_url == psirt.TOKEN_URL]
+        self.assertEqual(len(token_calls), 1)
+
+    def test_token_is_refetched_once_on_a_rejected_token(self):
+        script = [
+            _Response(fx.TOKEN),                       # initial token
+            _http_error(401, {"errorMessage": "expired"}),  # first attempt rejected
+            _Response(fx.TOKEN),                       # re-auth
+            _Response(fx.advisories_response(1)),      # retry succeeds
+        ]
+        client, opener, _ = _client(script)
+        outcome, _adv = client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        self.assertEqual(outcome, m.HAS_ADVISORIES)
+        token_calls = [c for c in opener.calls if c.full_url == psirt.TOKEN_URL]
+        self.assertEqual(len(token_calls), 2)
+
+    def test_a_second_rejection_is_not_retried_again(self):
+        script = [
+            _Response(fx.TOKEN),
+            _http_error(401, {}), _Response(fx.TOKEN), _http_error(401, {}),
+            _http_error(401, {}),
+        ]
+        client, _, _ = _client(script)
+        outcome, _adv = client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        self.assertEqual(outcome, m.INCOMPLETE)   # never a verdict
+
+    def test_requests_are_paced_within_quota(self):
+        script = [_Response(fx.TOKEN)] + [_Response(fx.NO_DATA_FOUND) for _ in range(3)]
+        clock = _Clock()
+        client, _, _ = _client(script, clock=clock)
+        for _ in range(3):
+            client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        # First request is immediate; each later one waits out the interval.
+        self.assertTrue(clock.slept, "expected pacing sleeps")
+        for waited in clock.slept:
+            self.assertAlmostEqual(waited, psirt.MIN_INTERVAL, places=5)
+
+    def test_transport_failure_raises_unreachable(self):
+        client, _, _ = _client([_Response(fx.TOKEN),
+                                urllib.error.URLError("connection reset")])
+        with self.assertRaises(psirt.PsirtUnreachableError):
+            client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+
+    def test_catalogue_failure_raises_rather_than_returning_empty(self):
+        # A silently-empty catalogue would turn every device into Needs review with a
+        # misleading reason, so this must fail loudly.
+        client, _, _ = _client([_Response(fx.TOKEN), _http_error(500, {})])
+        with self.assertRaises(psirt.PsirtError):
+            client.get_os_data("asa")
+
+    def test_request_count_is_tracked(self):
+        script = [_Response(fx.TOKEN)] + [_Response(fx.NO_DATA_FOUND) for _ in range(2)]
+        client, _, _ = _client(script)
+        client.get_advisories("ftd", "7.4.2.3", "ISA3000")
+        client.get_advisories("ftd", "7.4.2.1", "FPR1000")
+        self.assertEqual(client.request_count, 2)
+
+
+def urllib_query_keys(url):
+    import urllib.parse as up
+    return set(up.parse_qs(up.urlparse(url).query).keys())
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/install-test.sh b/tools/install-test.sh
index 0bc92c8..cfa74e3 100755
--- a/tools/install-test.sh
+++ b/tools/install-test.sh
@@ -3,38 +3,52 @@
 # Clean-room test of the uv install + run flow in a fresh Docker container.
 #
 # Spins up a throwaway container with no prior copy of the tool, installs uv, runs the
-# documented `uv tool install` command, and smoke-tests the result (--version, --help, the
-# API-key gate, and a dry-run that writes a report). Your local .venv, config, and API key
-# never enter the container.
+# documented `uv tool install` command, drops in a sample inventory, and either runs
+# automated smoke checks or hands you an interactive shell. Your local .venv, config, and
+# credentials never enter the container unless you explicitly mount them.
 #
 # Usage:
-#   tools/install-test.sh                 # test the current working tree (local mode, default)
-#   tools/install-test.sh --git           # test `--from git+<repo>@<current-branch>`
-#   tools/install-test.sh --git main      # test a specific branch/tag/commit from GitHub
-#   tools/install-test.sh --shell         # install the tool, then drop into an interactive
-#                                         #   shell in the container for manual poking
-#                                         #   (combine with --git / --image as usual)
-#   tools/install-test.sh --image python:3.12-slim   # use a different base image (default 3.9)
+#   tools/install-test.sh                  # automated checks against the current working tree
+#   tools/install-test.sh --shell          # install, then drop into a shell for manual testing
+#   tools/install-test.sh --live           # install the latest PUBLISHED RELEASE from GitHub
+#   tools/install-test.sh --git            # install from git+<repo>@<current-branch>
+#   tools/install-test.sh --git main       # install from a specific branch/tag/commit
+#   tools/install-test.sh --inventory FILE # use your own .xlsx instead of the generated sample
+#   tools/install-test.sh --image python:3.12-slim   # different base image (default 3.9)
+#
+# Modes are about WHAT gets installed:
+#   (default)  the working tree you have right now  -- use this to test unreleased work
+#   --live     the latest published GitHub release  -- what a real user gets today
+#   --git REF  a specific branch/tag/commit
+#
+# For live testing of `caia --api` you need Cisco PSIRT credentials. Run `caia --config`
+# inside the container (--shell mode) and paste them; they live only in that container and
+# vanish when it exits, so you re-enter them each run. That is the trade for never having
+# host credentials inside a test container.
 #
 # Requires Docker. Local mode works offline against your tree; the container still needs
-# network to fetch uv and (for --git) clone the repo.
+# network to fetch uv, to install (in --live/--git mode), and to reach Cisco for a real run.
 set -euo pipefail
 
 REPO_URL="https://github.com/xavient/cisco-advisory-impact-agent"
+RELEASES_API="https://api.github.com/repos/xavient/cisco-advisory-impact-agent/releases/latest"
 IMAGE="python:3.9-slim"   # 3.9 is the minimum supported Python — install on the floor
 MODE="local"
 GIT_REF=""
 SHELL_MODE=0
+INVENTORY=""
 
 usage() { awk 'NR==1{next} /^#/{sub(/^# ?/,""); print; next} {exit}' "$0"; }
 
 while [ $# -gt 0 ]; do
   case "$1" in
+    --live) MODE="live" ;;
     --git)
       MODE="git"
       if [ $# -gt 1 ] && [ "${2#--}" = "$2" ]; then GIT_REF="$2"; shift; fi
       ;;
     --shell) SHELL_MODE=1 ;;
+    --inventory) INVENTORY="${2:?--inventory needs a path to an .xlsx}"; shift ;;
     --image) IMAGE="${2:?--image needs a value}"; shift ;;
     -h|--help) usage; exit 0 ;;
     *) echo "error: unknown argument '$1'" >&2; usage >&2; exit 2 ;;
@@ -46,26 +60,56 @@ command -v docker >/dev/null 2>&1 || { echo "error: Docker is required but not f
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 
+if [ -n "$INVENTORY" ] && [ ! -f "$INVENTORY" ]; then
+  echo "error: --inventory file not found: $INVENTORY" >&2; exit 1
+fi
+
 # Resolve what uv will install from, and (local mode) stage a clean copy of the tree.
 STAGE=""
 MOUNT_ARGS=()
-if [ "$MODE" = "git" ]; then
-  [ -n "$GIT_REF" ] || GIT_REF="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo main)"
-  INSTALL_FROM="git+${REPO_URL}@${GIT_REF}"
-  echo ">> Mode: git  (uv tool install ... --from ${INSTALL_FROM})"
+case "$MODE" in
+  live)
+    GIT_REF="$(curl -fsSL "$RELEASES_API" 2>/dev/null \
+      | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' | head -1 || true)"
+    [ -n "$GIT_REF" ] || { echo "error: could not determine the latest release from GitHub." >&2; exit 1; }
+    INSTALL_FROM="git+${REPO_URL}@${GIT_REF}"
+    echo ">> Mode: live  (latest published release: ${GIT_REF})"
+    LOCAL_VERSION="$(cat "$ROOT/VERSION" 2>/dev/null || echo '?')"
+    if [ "$GIT_REF" != "$LOCAL_VERSION" ]; then
+      echo ">> NOTE: your working tree is ${LOCAL_VERSION}, the latest release is ${GIT_REF}."
+      echo ">>       Anything not yet released will be ABSENT in this container."
+      echo ">>       To test unreleased work, run without --live."
+    fi
+    ;;
+  git)
+    [ -n "$GIT_REF" ] || GIT_REF="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo main)"
+    INSTALL_FROM="git+${REPO_URL}@${GIT_REF}"
+    echo ">> Mode: git  (uv tool install ... --from ${INSTALL_FROM})"
+    echo ">>       Note: this fetches from GitHub, so unpushed local commits are not included."
+    ;;
+  *)
+    STAGE="$(mktemp -d)"
+    trap 'rm -rf "$STAGE"' EXIT
+    # Copy the working tree minus local/build junk, so the container sees a clean source.
+    tar -C "$ROOT" \
+      --exclude='./.git' --exclude='./.venv' --exclude='./build' --exclude='./dist' \
+      --exclude='./output' --exclude='./inventory' --exclude='./.update-backup' \
+      --exclude='*.egg-info' --exclude='__pycache__' \
+      -cf - . | tar -C "$STAGE" -xf -
+    INSTALL_FROM="/src"
+    # Read-write: it's a disposable copy, and setuptools writes egg-info into the tree at build.
+    MOUNT_ARGS=(-v "${STAGE}:/src")
+    echo ">> Mode: local  (uv tool install ... --from /src  <- current working tree)"
+    ;;
+esac
+
+# An explicit inventory is mounted read-only, so the container cannot alter your file.
+if [ -n "$INVENTORY" ]; then
+  INVENTORY_ABS="$(cd "$(dirname "$INVENTORY")" && pwd)/$(basename "$INVENTORY")"
+  MOUNT_ARGS+=(-v "${INVENTORY_ABS}:/seed/inventory.xlsx:ro")
+  echo ">> Inventory: ${INVENTORY_ABS} (mounted read-only)"
 else
-  STAGE="$(mktemp -d)"
-  trap 'rm -rf "$STAGE"' EXIT
-  # Copy the working tree minus local/build junk, so the container sees a clean source.
-  tar -C "$ROOT" \
-    --exclude='./.git' --exclude='./.venv' --exclude='./build' --exclude='./dist' \
-    --exclude='./output' --exclude='./inventory' --exclude='./.update-backup' \
-    --exclude='*.egg-info' --exclude='__pycache__' \
-    -cf - . | tar -C "$STAGE" -xf -
-  INSTALL_FROM="/src"
-  # Read-write: it's a disposable copy, and setuptools writes egg-info into the tree at build.
-  MOUNT_ARGS=(-v "${STAGE}:/src")
-  echo ">> Mode: local  (uv tool install ... --from /src  <- current working tree)"
+  echo ">> Inventory: generated sample (covers every verdict path)"
 fi
 
 echo ">> Base image: ${IMAGE}"
@@ -87,16 +131,50 @@ uv --version
 echo "== uv tool install (the documented command) =="
 uv tool install cisco-advisory-impact-agent --from "$INSTALL_FROM"
 
-echo "== prepare a working folder with a valid inventory =="
+echo "== prepare a working folder with an inventory =="
 mkdir -p /work && cd /work
-uv run --with openpyxl python - <<PY
+if [ -f /seed/inventory.xlsx ]; then
+  cp /seed/inventory.xlsx /work/inventory.xlsx
+  echo "using the mounted inventory"
+else
+  # Synthetic sample. Deliberately exercises every path the inventory-driven check can
+  # take, including states a real fleet may not contain (a genuinely clean device, and
+  # each Needs-review reason). No real fleet data, so this is safe to keep in the repo.
+  uv run --with openpyxl python - <<PY
 import openpyxl
 wb = openpyxl.Workbook(); ws = wb.active; ws.title = "FW_List"
-ws.append(["FirewallName", "Model", "FirewallType", "IOS version"])
-ws.append(["fw-1", "ASA5525", "ASA", "9.16(4)67"])
-wb.save("inv.xlsx")
-print("wrote inv.xlsx")
+ws.append(["FirewallName", "Model", "Firewalltype", " IOS version",
+           "Priority* (1-High 3-Low)"])
+rows = [
+    # --- expected Impacted: real release/platform pairs Cisco has advisories for ------
+    ("sample-fw-01", "ISA-3000",                            "FTD",  "7.0.1",     1),
+    ("sample-fw-02", "ISA-3000",                            "FTD",  "7.0.1",     2),  # dedupe
+    ("sample-fw-03", "Cisco Firepower 1010 Threat Defense", "FTD",  "7.4.2.1",   1),
+    ("sample-fw-04", "Firepower 2110",                      "ASA",  "9.20(3)7",  2),  # ( ) form
+    ("sample-fw-05", "ASA 5525",                            "ASA",  "9.16(4)67", 3),
+    ("sample-fw-06", "Cisco Secure Firewall 3130 Threat Defense", "FTD", "7.4.2.3", 1),
+    ("sample-fw-07", "Cisco Firepower Threat Defense for VMware", "FTD", "7.4.2.3", 3),
+    ("sample-fw-08", "Secure FMC 1600",                     "FMC",  "7.4.2.3",   2),  # no platform
+    ("sample-fw-09", "ASAv",                                "ASAv", "9.20(4)",   3),  # ASAv -> ASA
+    ("sample-fw-10", "Firepower 4110",                      "ASA",  "9.20(4)7/ASDM 7.22.1", 2),
+    ("sample-fw-11", "Cisco Firepower 1120 Threat Defense", "FTD",  "7.4.2.1-30", 2),  # build suffix
+    # --- expected Needs review, one per reason ---------------------------------------
+    ("sample-fw-12", "ASA 5515",   "ASA",    "9.12(4)67", 3),  # release purged by Cisco
+    ("sample-fw-13", "ASA 5515",   "ASA",    "9.18(4)22", 3),  # release not on this model
+    ("sample-fw-14", "Widget 9000","ASA",    "9.16(4)67", 2),  # model unmappable
+    ("sample-fw-15", "ISA-3000",   "FTD",    "",          1),  # blank release
+    ("sample-fw-16", "",           "FTD",    "7.4.2.3",   3),  # blank model
+    ("sample-fw-17", "Catalyst 9300","SWITCH","17.9.4",   3),  # family out of scope
+    # --- expected Not impacted: a release Cisco knows with no advisories against it ---
+    # (may become Impacted later if Cisco publishes one; that is correct behaviour)
+    ("sample-fw-18", "Cisco Secure Firewall 3130 Threat Defense", "FTD", "7.6.0", 2),
+]
+for r in rows:
+    ws.append(list(r))
+wb.save("inventory.xlsx")
+print(f"wrote inventory.xlsx ({len(rows)} firewalls)")
 PY
+fi
 '
 
 CHECK_SCRIPT='
@@ -106,44 +184,80 @@ command -v caia
 echo "== --version =="
 caia --version
 
-echo "== --help =="
+echo "== --help lists both modes =="
 caia --help >/dev/null && echo "help OK"
+caia --help | grep -q -- "--api" && echo "--api present" || echo "--api ABSENT (expected on releases before 2.3.0)"
 
 URL="https://sec.cloudapps.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-test-abcd1234"
 
-echo "== API-key gate: a real run with no key must exit non-zero and name --config =="
-if caia --url "$URL" --inventory inv.xlsx --no-update-check; then
+echo "== advisory mode: no FueliX key must exit non-zero and name --config =="
+if caia --url "$URL" --inventory inventory.xlsx --no-update-check; then
   echo "FAIL: expected a non-zero exit when no API key is configured"; exit 1
 fi
 echo "key gate OK (exited non-zero)"
 
-echo "== dry-run writes a report into ./output =="
-caia --dry-run --url "$URL" --inventory inv.xlsx --no-update-check
-ls output/analysis_output_*.xlsx >/dev/null 2>&1 && echo "report written OK" || { echo "FAIL: no report"; exit 1; }
+echo "== advisory mode: dry-run writes a spreadsheet report =="
+caia --dry-run --url "$URL" --inventory inventory.xlsx --no-update-check
+ls output/analysis_output_*.xlsx >/dev/null 2>&1 && echo "spreadsheet report OK" || { echo "FAIL: no report"; exit 1; }
+
+# The remaining checks only apply once --api exists in the installed version.
+if caia --help | grep -q -- "--api"; then
+  echo "== inventory mode: mutually exclusive with --url =="
+  if caia --api --url "$URL" --inventory inventory.xlsx --no-update-check; then
+    echo "FAIL: expected non-zero when --api and --url are combined"; exit 1
+  fi
+  echo "mutual exclusion OK"
+
+  echo "== inventory mode: no Cisco credentials must exit non-zero and name --config =="
+  if caia --api --inventory inventory.xlsx --no-update-check; then
+    echo "FAIL: expected non-zero exit with no Cisco credentials"; exit 1
+  fi
+  echo "credential gate OK (exited non-zero)"
+
+  echo "== inventory mode: --dry-run resolves checks with no credentials and no network =="
+  caia --api --dry-run --inventory inventory.xlsx --no-update-check
+  echo "dry-run OK"
+
+  echo "== inventory mode: dry-run wrote no report =="
+  ls output/impact_report_*.html >/dev/null 2>&1 && { echo "FAIL: dry-run must not write a report"; exit 1; }
+  echo "no-report-on-dry-run OK"
+else
+  echo "== skipping --api checks: not present in this version =="
+fi
 
 echo
 echo "ALL CHECKS PASSED"
 '
 
 # --shell: after setup, hand control to an interactive bash (fresh shell, no set -e) so the
-# key gate and other non-zero exits do not kill your session. You land in /work.
+# credential gates and other non-zero exits do not kill your session. You land in /work.
 SHELL_SCRIPT='
 echo
 echo "======================================================================"
-echo "  Ready: caia is installed, and /work has a sample inv.xlsx."
-echo "  Try:"
-echo "    caia --help"
+echo "  Ready: caia is installed, and /work has an inventory.xlsx."
+echo
+echo "  Offline checks (no credentials needed):"
 echo "    caia --version"
-echo "    caia --config     # set a FueliX key for a real run"
-echo "    caia --dry-run --url <ERP-or-advisory-URL> --inventory inv.xlsx --no-update-check"
+echo "    caia --api --dry-run --inventory inventory.xlsx --no-update-check"
+echo
+echo "  Live inventory check (needs Cisco PSIRT credentials):"
+echo "    caia --config      # skip the FueliX prompts; paste the Cisco ID + secret"
+echo "    caia --api --inventory inventory.xlsx --no-update-check"
+echo "    # then open output/impact_report_*.html  (copy it out, or just read the tally)"
+echo
+echo "  Live advisory check (needs a FueliX key):"
+echo "    caia --config      # set the FueliX key"
+echo "    caia --url <ERP-or-advisory-URL> --inventory inventory.xlsx --no-update-check"
+echo
+echo "  Credentials you enter live only in this container and vanish on exit."
 echo "  Type  exit  to leave (the container is discarded)."
 echo "======================================================================"
 echo
 exec bash
 '
 
-# The ${arr[@]+"${arr[@]}"} guard keeps an empty MOUNT_ARGS (git mode) from tripping `set -u`
-# on bash 3.2 (macOS's default).
+# The ${arr[@]+"${arr[@]}"} guard keeps an empty MOUNT_ARGS (git/live mode without an
+# explicit inventory) from tripping `set -u` on bash 3.2 (macOS's default).
 if [ "$SHELL_MODE" = "1" ]; then
   echo ">> Interactive shell mode (type 'exit' to tear down the container)."
   docker run --rm -it ${MOUNT_ARGS[@]+"${MOUNT_ARGS[@]}"} -e INSTALL_FROM="$INSTALL_FROM" \