docs: align approval-gate wording with shipped console

README.md

@@ -15,7 +15,7 @@ three-phase safety engine (DIAGNOSE → APPROVE → VERIFY).
 Current production path:
 
 ```text
-Dashboard -> FastAPI Cloud Run (opens approval gate)
+Dashboard -> FastAPI Cloud Run (creates gated read-only run)
  -> Diagnose Agent Engine -> Candidate Agent Engine -> Rationale Agent Engine
  -> deterministic controller validates + emits DIAGNOSED EvidencePack
  -> /packs/{id}/decision hash-bound approval ticket
@@ -25,9 +25,10 @@ Dashboard -> FastAPI Cloud Run (opens approval gate)
 The three Agent Engine resources perform read-only Mongo diagnosis, candidate testing,
 and rationale generation with Python-native tools.
 Deterministic Python remains the safety authority: it recomputes the ESR winner, evidence
-hash, phase transitions, index apply, and verification. `/run` opens the approval gate
-before diagnosis and remains read-only; `/packs/{run_id}/decision` is the only path that
-can issue the one-time approval ticket required for mutation.
+hash, phase transitions, index apply, and verification. `/run` creates a gated read-only
+run. Mutation remains impossible until the operator approves a matching EvidencePack hash;
+`/packs/{run_id}/decision` is the only path that can issue the one-time internal apply
+action required for mutation.
 
 The dashboard reads only `EvidencePack` JSON, including `approval_gate` state and
 `agent_trace` proof that the gate opened before Agent Engine participation. Internally,

contracts/examples/evidence_pack.example.json

@@ -8,7 +8,7 @@
  "resource": null,
  "stage": "gate",
  "status": "ok",
- "summary": "Approval gate opened before diagnosis.",
+ "summary": "/run created a gated read-only run; mutation requires matching evidence hash approval.",
  "tool": "approval_gate"
  },
  {

dashboard/README.md

@@ -88,15 +88,16 @@ lib/
  diagnosis; during a run it is collecting evidence, then it moves to pending
  approval with the required hash.
 - **Ask the agent** calls the same-origin `/api/run` proxy, which forwards to the
- Cloud Run API with the server-side token. The backend opens the approval gate
-first, then asks the Diagnose, Candidate, and Rationale Agent Engine resources
-for read-only diagnosis.
+ Cloud Run API with the server-side token. The backend creates a gated read-only
+run, then asks the Diagnose, Candidate, and Rationale Agent Engine resources for
+ read-only diagnosis.
 - The returned pack is `diagnosed`, shown as **pending approval**. No database
  mutation happens during this step. `agent_trace` starts with `approval_gate/gate`,
  then shows the split Agent Engine role events plus deterministic validation.
-- **Approve fix** posts the displayed `evidence_hash` through the same-origin
- decision proxy. The backend issues a one-time approval ticket and applies/verifies
- the index only after that hash-bound approval. If the API is not configured, the
- UI shows an error and does not fake a saved decision.
+- **Approve this evidence hash** posts the displayed `evidence_hash` through the
+ same-origin decision proxy. The backend verifies the hash, issues a one-time
+ internal apply action, and applies/verifies the index only after that hash-bound
+ approval. If the API is not configured, the UI shows an error and does not fake a
+ saved decision.
 - The trace panel and footer show when the pack came from the live API, where the
  EvidencePack aggregate and internal ledger event collections are persisted.

demo/architecture.md

@@ -40,7 +40,7 @@ flowchart TB
  end
 
  DASH -- "GET /packs/:id" --> API
- DASH -- "POST /run opens gate first" --> API
+ DASH -- "POST /run creates gated read-only run" --> API
  DASH -- "POST /packs/:id/decision" --> API
  API -- "/run asks diagnose role" --> DIAG
  API -- "/run asks candidate role" --> CAND
@@ -66,7 +66,7 @@ flowchart TB
 
 | Stage (UI) | Engine phase | What happens | Who does it |
 |------------|-------------|--------------|-------------|
-| **Gate** | (pre) | Approval gate opens before diagnosis; mutation is blocked | **human gate / controller** |
+| **Gate** | (pre) | `/run` creates a gated read-only run; mutation is blocked | **human gate / controller** |
 | **Detect** | (pre) | Slow query surfaced from the fixture / logs | Diagnose Agent Engine |
 | **Diagnose** | `DIAGNOSE` | Read `explain`, extract stages + counters, identify the blocking-sort root cause | Diagnose Agent Engine, deterministic code validates |
 | **Test** | `DIAGNOSE` | Compare B vs C and propose index **C** (correct ESR) from measured evidence | Candidate Agent Engine, deterministic code recomputes |
@@ -78,8 +78,8 @@ flowchart TB
 Three things make it a real plan-and-execute system (and the reason we run on
 **Agent Engine + ADK**, not the no-code console):
 
-1. **Gate-first control plane** — `/run` opens an approval gate before diagnosis,
-and every emitted pack records that gate plus the required evidence hash.
+1. **Gated read-only run** — `/run` creates a gated run record and keeps mutation
+impossible until the operator approves a matching EvidencePack hash.
 2. **Hash-bound approval ticket** — the controller blocks at `APPROVE` until a
  decision arrives carrying the matching `evidence_hash`. Only the decision
  route can issue the one-time ticket required by `apply_and_verify`; stale

demo/dashboard-walkthrough.md

@@ -42,13 +42,13 @@ done and it's waiting at **Approve**.
 > Annotation: "Five visible stages over a phase-gated engine — the agent can't
 > skip ahead or apply early."
 
-### Predicted vs Observed (`03-plan.png`) — the centerpiece
+### Before / After Explain Diff (`03-plan.png`) — the centerpiece
 Two columns, Before (serving index B) and After (recommended index C):
 - **Stage chain** — each plan stage as a chip. `SORT` renders **red**, `IXSCAN`
  **green**, so the eye lands on the blocking sort immediately.
 - **Metrics** — keys examined, docs examined, returned, millis. The
  *keys examined* figure is the headline: **17,209 (B) vs 64 (C)**.
-- A **blocking sort / no sort** badge per column.
+- A **SORT present / SORT removed** badge per column.
 
 > Annotation: "The color *is* the diagnosis — red SORT on the left, gone on the
 > right. 269× fewer index keys for the same 20 rows."

demo/demo-script.md

@@ -50,11 +50,11 @@ This is the **prediction** — state it before showing the result.
 ## 2:10–2:35 — Approve: the human gate
 
 > "Nothing gets applied automatically. The operator sees the evidence pack — and
-> its hash — inside the gate that was opened before diagnosis — and approves. The
+> its hash — inside the gated read-only run — and approves. The
 > approval route issues the one-time ticket bound to that exact evidence hash; if
 > the evidence changed, the approval is rejected."
 
-Click **Approve fix**. The gate closes as verified after apply + verify completes.
+Click **Approve this evidence hash**. The gate closes as verified after apply + verify completes.
 
 ## 2:35–3:00 — Verify: predicted vs observed
 

deploy/cloudrun.md

@@ -74,11 +74,12 @@ in the repo root and push the image to Artifact Registry automatically.
 >
 > **Agent Engine:** all three split resources are required for deploy:
 > `AGENT_ENGINE_DIAGNOSE_RESOURCE`, `AGENT_ENGINE_CANDIDATE_RESOURCE`, and
-> `AGENT_ENGINE_RATIONALE_RESOURCE`. `/run` opens the approval gate first, then
-> calls the Diagnose, Candidate, and Rationale Agent Engine resources in order.
-> The deterministic controller validates the winner/hash and emits the DIAGNOSED
-> EvidencePack. `MONGO_SECRET_NAME` is also required; production must read MongoDB
-> credentials from Secret Manager.
+> `AGENT_ENGINE_RATIONALE_RESOURCE`. `/run` creates a gated read-only run, then calls
+> the Diagnose, Candidate, and Rationale Agent Engine resources in order. Mutation remains
+> impossible until the operator approves a matching EvidencePack hash. The deterministic
+> controller validates the winner/hash and emits the DIAGNOSED EvidencePack.
+> `MONGO_SECRET_NAME` is also required; production must read MongoDB credentials from
+> Secret Manager.
 
 ### What the script does