Docs and UI accuracy

README.md

@@ -5,6 +5,16 @@
 HydraLoop is a synthetic, sandboxed, co-evolutionary adversarial payment security lab
 for the era of **agentic commerce**.
 
+## Visual demo
+
+Add the assets below in `docs/images/` before merging this branch so judges can see
+the UI immediately when they open the repository.
+
+![Lab live run (streaming)](docs/images/lab-live-run.gif)
+![Arena loop view](docs/images/arena-loop.png)
+![Cases explainability view](docs/images/cases-explainability.png)
+![Audit hash-chain verification](docs/images/audit-chain.png)
+
 ## Why now
 
 Autonomous agents are starting to make payments on people's behalf. That collapses the

docs/DEMO_SCRIPT.md

@@ -19,33 +19,33 @@ snapshot and an "offline" badge; the demo still works.
 
 ## Beat 1 - the premise (30s)
 
-On the **Arena** screen, click **JUDGE DEMO MODE**. Read the first caption aloud: autonomous
+On the **Arena** screen, click **Caption walkthrough**. Read the first caption aloud: autonomous
 agents now initiate payments, so fraud becomes an adaptive, machine-speed adversary. Point at
 the KPI bar: escape rate and attacker ROI are the two numbers that matter, and both should fall.
 
 ## Beat 2 - the loop runs (45s)
 
-Let demo mode advance, or press **RUN CO-EVOLUTION** for a live run. Narrate: the red team
+Let the caption walkthrough advance, or press **Start live loop** for a live run. Narrate: the red team
 escapes through specific modes (call them out from the ticker), the blue team retrains from
 immune memory, and the **regression gauntlet** blocks a model that would have regressed. That
 rollback is the point: we never ship a weaker defence.
 
 ## Beat 3 - the attack, in plain English (30s)
 
-Open **Threat Board**, filter to **Agentic Commerce**. These four scenarios model
+Open **Threats**, filter to **Agentic Commerce**. These four scenarios model
 agent-initiated fraud: mandate drift, checkout takeover, agent-swarm probing, destination
 redirection - all behavioural-metadata-only, no recipes. Open **Lineage**, click a node, and
 read the one-paragraph brief so judges see the attack described in words, not just genes.
 
 ## Beat 4 - the defence is explainable (20s)
 
-Open **Investigation**. Pick a flagged transaction. Show the SHAP reason codes and the
+Open **Cases**. Pick a flagged transaction. Show the SHAP reason codes and the
 counterfactual: "if the payee were not new, risk drops by N points." This is what an analyst
 would act on.
 
 ## Beat 5 - it is honest (25s)
 
-Open **Governance**. The run history is a hash chain. Click **Verify chain**: green. Say that
+Open **Audit**. The run history is a hash chain. Click **Verify chain**: green. Say that
 any edit to history would break the chain on the next verification. Then mention the data
 credibility benchmark (`python -m hydraloop bench`) that reports discriminator AUC and TSTR /
 TRTS against a shifted or real reference, so we measure fidelity instead of asserting it.

docs/ONE_PAGER.md

@@ -33,10 +33,11 @@ security. It has three parts locked in a closed loop.
 
 ## What you can see in three minutes
 
-Arena (the loop running live), Threat Board (28 abstracted scenarios across 7 families),
-Attack Genome Lineage (the mutation trail with plain-English briefs), Investigation (SHAP
-reason codes plus a counterfactual), Scoreboard (escape rate and recall by generation), and
-Governance (verify the hash chain on stage).
+Lab (type any threat description and watch Identify to Detect run step by step),
+Arena (the loop running live), Threats (28 abstracted scenarios across 7 families),
+Lineage (the mutation trail with plain-English briefs), Cases (SHAP reason codes plus a
+counterfactual), Metrics (escape rate and recall by generation), and Audit
+(verify the hash chain on stage).
 
 ## Results to point at
 

docs/RESPONSIBLE_AI.md

@@ -61,7 +61,7 @@ invalid, so the generator cannot emit anything outside the abstraction policy.
 
 Each generation is written to an append-only, hash-chained ledger. Every entry embeds the
 previous entry's digest, so any edit to run history is detectable on the next verification. The
-Governance screen recomputes the chain live and reports a break if one exists. The
+Audit screen recomputes the chain live and reports a break if one exists. The
 `run_manifest.json` records the config hash so results trace back to the exact configuration.
 
 ## Human oversight of the defence

docs/images/README.md

@@ -0,0 +1,15 @@
+# Demo assets
+
+Place judge-facing UI assets here before opening the PR:
+
+- 2 to 3 screenshots (PNG/JPG)
+- 1 short Lab run GIF
+
+Recommended names used by the main README:
+
+- lab-live-run.gif
+- arena-loop.png
+- cases-explainability.png
+- audit-chain.png
+
+You can rename these, but update the image links in ../README.md to match.

ui/components/Lab.tsx

@@ -56,7 +56,12 @@ function unreachableBackendHint(): string {
     typeof window !== "undefined" &&
     ["localhost", "127.0.0.1"].includes(window.location.hostname);
   if (local) {
-    return "The API is not running. In a second terminal: activate .venv, then run python -m hydraloop api";
+    return (
+      "The Lab could not reach the API. Usually this is either (1) the API is not running, or " +
+      "(2) the browser blocked the request because the UI is on a different localhost port. " +
+      "Check the UI URL port in the address bar, then open http://127.0.0.1:8000/api/health in a new tab. " +
+      "If health fails, start the API in a second terminal: activate .venv, then run python -m hydraloop api."
+    );
   }
   return (
     "This deployment has no live backend attached, so the pipeline cannot run here. " +