MobilityOps/docs/demo-release/demo-guide.md

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 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.