# SQL Catalog MVP Demo Walkthrough

This walkthrough uses the supplied real Clinic Health Check report. SQL text, digests, symptoms,
metric keys, and evidence come from that report. Historical dates and metric values are deterministic
derivatives whose provenance is stored on each Finding.

## Prepare

The prepare command replaces the current demo database contents. Run it before rehearsal and again
before the presentation:

```bash
python3 scripts/demo_flow.py prepare
```

Keep the backend on port `8765` and Vite on port `5173`, then open:

```text
http://127.0.0.1:5173
```

The prepared baseline intentionally withholds one real Critical slow-log Finding for the source
cluster. This allows the live API call to demonstrate automatic Catalog registration without
inventing a digest.

## Main Story

1. Open Workbench with the source Organization selected. The Catalog review queue refreshes every
   five seconds.
2. Trigger the reserved Clinic Finding through the public Finding API wrapper:

   ```bash
   python3 scripts/demo_flow.py new
   ```

3. The first Workbench row shows Critical current risk, why it needs attention, and Review Evidence
   as the next action. Open it to inspect the Catalog Overview, metric history, and linked Finding.
4. Select Start Review. The unowned item is claimed by the signed-in user and the
   decision is recorded in the Catalog timeline.
5. Select Start Treatment, confirm the linked Finding, objective, success criteria, owner, and
   severity, then create the Treatment.
6. In Treatment Detail, add an Analysis Record. Move the lifecycle from Assessment to Planning.
7. Select Share Recommendation. The form is fixed to a reviewed, customer-visible Plan Record, so
   saving it writes the recommendation milestone to both Treatment and Catalog timelines and moves
   the active Treatment to Alignment to represent waiting for customer action.
8. Return to the Catalog Item. The Timeline shows registration, review, Treatment creation, analysis,
   recommendation delivery, and the current governance state as expandable nodes.

## Existing Digest and Reappearance

The prepare command prints `historical_catalog_url`. That Catalog Item has 27 historical daily
Clinic-derived observations and a completed Treatment. Its SQL Performance History includes general
activity trends and symptom-specific metric groups such as Total Keys and Processed Keys. The
reappearance command adds the next daily observation as the 28th point.

To demonstrate a previously treated digest appearing again:

```bash
python3 scripts/demo_flow.py reappear
```

Open the returned Catalog URL or the prioritized Workbench review queue. The row explains that this
SQL reappeared after governance. The new Finding joins the existing Catalog Item; it does not reopen
the completed Treatment automatically. The Catalog timeline records the recurrence and leaves the
next intervention decision to the owner.

## Rehearsal Notes

- Run `prepare` before each complete rehearsal.
- `new` and `reappear` use unique event suffixes by default. Pass `--event-suffix rehearsal-1` when
  demonstrating idempotency with the same event identifier.
- Use UTC during the presentation so Clinic windows, chart points, Records, and timeline timestamps
  use one consistent time basis.