# The in-app Demo Guide

## What it is (and isn't)

The Demo Guide is a compact, reusable side panel (a bottom sheet on mobile) that walks an
Operations Manager through eight fixed steps covering the demo's core functionality. It is
**not** a generic tutorial engine and **not** a source of business logic — every action it
prompts is a real action against the real API; the guide only narrates, links, and tracks
progress. It duplicates no business logic: routes for the two scenario-backed steps
(return, duplicate-merge) are resolved from the live `GET /api/v1/demo/manifest` response
rather than hardcoded, so they can never point at a stale or missing record.

## Where it lives

- `frontend/src/data/demoGuideSteps.ts` — the eight step definitions (title, what you'll
  see, why it matters, the exact start action, the expected outcome, and a `route()`
  function).
- `frontend/src/context/DemoGuideContext.tsx` — open/close state and step progress,
  persisted to `sessionStorage` only (browser-local, never touches auth or business
  state; a "Demo opnieuw voorbereiden" restart or a new browser session starts fresh).
- `frontend/src/components/DemoGuide.tsx` — the panel itself and its topbar trigger
  (`DemoGuideTrigger`, Operations-Manager-only, since all eight steps require that role).

## The eight steps

1. **Understand the operational state** — the dashboard's readiness and attention queue.
2. **Open the booking needing attention** — `BK-DEMO-RETURN`, resolved from the manifest.
3. **Process the return with an odometer anomaly** — same booking; the return form is
   pre-filled with the suspicious reading (see [`demo-scenarios.md`](demo-scenarios.md)
   scenario 1).
4. **Handle the created data-quality issue** — the fresh odometer-regression issue that
   step 3 just created.
5. **Review and merge the possible duplicate customer** — `DQ-DEMO-DUPLICATE`.
6. **Ask the procedure assistant a question** — one of the suggested questions.
7. **Check automation and the audit trail**.
8. **Review what's real, simulated, or not yet connected** — the About page.

## How progression works

- **"Ga naar deze stap"** navigates to the step's resolved route without marking it done.
- **"Volgende"** marks the current step complete and advances the index (used for steps
  with no dedicated in-page continuation, like the knowledge-assistant step).
- Several real actions (a successful return, a resolved data-quality issue) show their
  own **"Ga verder met de demo"** button that both completes the current step and
  navigates straight to the next one — this is how the guide chains through steps 3→4→5
  without a detour back through the panel's own controls.
- The step list on the panel lets you jump directly to any step.
- **"Demo opnieuw voorbereiden"** calls the real reset endpoint, resets the guide's own
  progress, and returns to the login screen — mirroring the existing sidebar reset
  control, not a separate implementation.

## A known, deliberate limitation: suggested questions stay in English

The demo knowledge base's five procedure documents (`knowledge/procedures/*.md`) are
written in English. Verified empirically while building step 6: an equivalent Dutch
question returned `insufficient` evidence against the demo provider, while the English
original returned `grounded`. Rather than mistranslate the demo's centerpiece "grounded
answer" feature into something that silently answers incorrectly, the suggested questions
on `/knowledge` and this guide's step 6 instructions stay in English, with the guide
explicitly explaining why in Dutch. Retranslating the procedure documents themselves was
judged out of scope for a demo-productization pass (see the language-split note in
`docs/demo-release/current-demo-gap-audit.md`, gap #11).

## Layout note: the panel reserves space, it doesn't overlap content

On desktop the panel is a fixed 400px-wide right-side overlay. `Layout.tsx` adds a
`guide-open` class to the main workspace while the guide is open, which reserves
`padding-right` so page content reflows aside instead of sitting underneath the panel —
this was a real bug found and fixed while building the full guided-demo Playwright test
(see `PROJECT_STATE.md`, Batch 6): without it, the return form's "Review return" button
was unclickable while the guide was open at ordinary desktop widths.