MobilityOps/docs/demo-release/current-demo-gap-audit.md

Current demo-readiness gap audit

Performed 2026-08-03 against feat/mobilityops-functional-completion @ e0c7ed60112510687627d20a957af91c8b9db7f8 (verified: correct branch, working tree clean, matches the deployed Unraid revision). Method: read CLAUDE.md/AGENTS.md (identical, no demo-specific guidance yet), README.md, PROJECT_STATE.md, the docs list in the brief, artifacts/final-acceptance/summary.md, artifacts/functional-completion/final-summary.md, seed/generate_seed.py, seed/*.csv, backend/app/seed_loader.py, backend/app/core/config.py, backend/app/api/routers/dashboard.py; live-browsed the deployed app at http://192.168.10.150:1236 (login, dashboard, a data-quality issue, a booking detail, knowledge, automation).

What already works well (do not rebuild)

• The premium Control Rail UI, role-based nav, server-backed sessions, return preview/ commit, all five data-quality resolution flows, audit before/after, role-aware search, truthful integration status, demo reset, stale-lease recovery and the two n8n workflows are all implemented, tested and live-verified per artifacts/functional-completion/final-summary.md — this pass does not touch that business logic.
• docs/13-seed-and-demo-scenarios.md already names exactly the scenarios this brief wants surfaced: S1 odometer-regression return (BK-DEMO-RETURN/MO-024), S2 duplicate customer (CUS-0012/CUS-0178, issue DQ-DEMO-DUPLICATE), S4 booking overlap (MO-016, issue DQ-DEMO-OVERLAP, bookings BK-DEMO-OVERLAP-A/B), S5 failed workflow (seeded failed outbox event, retryable from Automation), S6 grounded knowledge question. These map directly to the brief's 5 requested scenarios — no new scenarios need to be invented, only surfaced with guidance. (S3, "missing inspection before next booking" on MO-031, exists too but isn't one of the 5 requested; leave it as-is, it still shows up in the attention queue.)
• seed/generate_seed.py already produces believable Flemish/Dutch data: first/last name pools (Sofie, Lotte, Bram, Peeters, Janssens, Vermeulen, ...), real Kempen-region towns (Geel, Turnhout, Herentals, Mol, Westerlo, Tessenderlo-Ham), .test email addresses, and believable RV/camper makes (Adria, Dethleffs, Hymer, Bürstner, ...). Confirmed live: DQ-DEMO-DUPLICATE shows customer "Bram Peeters" (Geel) with email bram.peeters.12@example.test. The underlying data quality is already demo-grade — the gap is structural/experiential, not data flavour.

Confirmed gaps

1. No fictional organisation identity anywhere

Login/demo-entry screen says "MobilityOps · Control Centre" and generic marketing copy ("Every hand-off. One clear view.") but never names a demonstration organisation. A stranger cannot tell whose fleet this is. Confirmed via full-repo search: "Northstar Mobility" is never rendered in the UI, but it is already the project's locked fictitious tenant name — PROJECT_STATE.md's "Locked decisions" section states verbatim "Fictitious tenant: Northstar Mobility Demo", and ragcore_tenant defaults to "northstar-mobility-demo" in backend/app/core/config.py, compose.yaml, .env.example, knowledge/manifest.json and contracts/mcp-tools.json. So using "Northstar Mobility" as the visible demo brand (as this brief suggests) is not a new invention — it surfaces a decision the project already made and only ever used internally as a RAGcore-tenant slug. No renaming/config changes needed, just make it visible.

2. No guided path — a visitor has no idea where to start

The dashboard shows real attention-queue items (duplicate customer, booking overlap, vehicle status conflict, missing field) and today's movements (BK-DEMO-RETURN 11:00), but nothing tells a first-time visitor which of these is worth clicking, in what order, or why. There is no "start guided demo" affordance, no scenario overview, no step-by-step walkthrough. Everything technically works; nothing narrates.

3. Live date anchoring is broken — confirmed, reproducible

seed/bookings.csv stores absolute fixed ISO timestamps authored around anchor date 2026-08-01 (generate_seed.py --anchor 2026-08-01). backend/app/core/config.py's demo_today setting ("2026-08-01") is used only by dashboard.py::_today() to filter "today's movements" against that frozen date — nothing re-anchors the underlying booking/inspection/maintenance/outbox dates themselves. Live-confirmed right now (today is 2026-08-03): BK-DEMO-RETURN shows status active with ends_at = 01/08/2026 09:00 — already two days in the past, for a booking that's supposed to look "in progress, due for return soon." BK-DEMO-NEXT (meant to read as "near-future") starts 2026-08-02, also already past. Every day this environment isn't reset, this gets worse, and after any seed --reset it snaps right back to the same frozen 2026-08-01-relative positions regardless of the real reset moment. This is exactly the failure mode brief section 7 describes and must be fixed at the source (seed_loader.py), not papered over in the UI.

4. Knowledge assistant names "RAGcore" directly, not honestly "demo mode"

/knowledge page copy: "Answers are shown only when RAGcore returns sufficient cited evidence" and a "RAGcore" label on the sources block — while the actual active provider is KNOWLEDGE_PROVIDER=demo (confirmed: badge below correctly shows demo · Available · 10 procedures indexed, which contradicts the body copy one line below it). This is the exact misleading-integration-status problem brief section 11 warns against — the small badge is honest, the prose isn't. No suggested questions are offered.

5. Integration status labels are technical, not demo-plain-language

Automation page shows raw states like not_configured/degraded/operational (English, developer register) rather than the plain-language labels section 12 asks for (Operationeel / Demomodus / Niet gekoppeld / Voorbereid / Verwerking mislukt / Opnieuw proberen mogelijk).

6. Data-quality resolution panels are functionally complete but not narrated

Confirmed live on DQ-DEMO-DUPLICATE: the compare/merge UI works well, but nothing explains why this matters operationally (duplicate billing/contact risk) or what happens next in plain terms before the user acts. Same pattern across the other 4 rule-type panels (already reviewed in this session's earlier batch). No "demo scenario" filter exists to surface the curated issues first.

7. No "About this demo" page

No page anywhere explains what's real, what's synthetic, what's live vs. demo-mode vs. not-connected, or the architecture/testing approach in plain terms. A visitor exploring alone has no way to self-answer "is this real?"

8. No permanent, explained "synthetic demo" indicator

The existing demo-banner ("Synthetic demo data · no real customer or vehicle information") is a full-width static bar repeated on every page — present, but static text only, no link to more explanation, no reset-timestamp/anchor info, and (per section 4) shouldn't be a dominant warning bar; it should be a subtle, explained badge.

9. Demo reset exists but is not discoverable as a demo feature

POST /api/v1/demo/reset and its sidebar UI trigger (this session's earlier batch) work correctly and are Operations-Manager-gated, but reset isn't connected to any demo narrative (no "prepare demo again" framing, not reachable from an About page or guide, no post-reset scenario-integrity confirmation beyond the raw counts).

10. No demo manifest / no single source of "what's on right now"

Nothing exposes demo mode, scenario list, integration status and guidance availability as one small structured payload the frontend can render consistently (badge tooltip, guide, scenario overview, About page all currently would have to duplicate this knowledge if built independently).

11. Everything is in English; the brief asks for consistent Dutch demo text

All existing UI copy is English. The brief explicitly asks for consistent Dutch product text for the demo-facing additions. Recorded decision (no existing doc answers this, and translating the entire already-shipped, already-tested Control Rail UI is out of proportion to "add guidance," would touch dozens of files and contradicts "this is not a redesign"): new demo-productization surfaces are written in Dutch (demo entry copy, Demo Guide, scenario overview, About-this-demo page, the demo badge/tooltip, plain-language integration-status labels). Existing operational screens (Dashboard, Vehicles, Bookings, Data Quality workbench, Audit, Automation internals) stay in English — they are already shipped, tested, and section 16 explicitly forbids rebuilding working screens without functional reason. This mirrors how a real bilingual guided demo works: narration in one language, software in whatever it already ships in.

Scope reminder (not gaps — explicitly out of scope per the brief)

• No RAGcore or MCP Hub live implementation.
• No new business logic in the 5 resolution flows — only explanatory framing around the existing ones.
• No full redesign, new component library, new color palette, or full retranslation.

Plan (implementation batches, matches task list)

1. Fix date anchoring in seed_loader.py (shift all seeded dates by today − anchor at every reset); switch dashboard.py::_today() to real wall-clock date; add a demo_data_seeded audit marker recording the anchor/reset moment.
2. GET /api/v1/demo/manifest (org name, demo mode, scenarios, integration status, reset timestamp) + Dutch demo entry screen + permanent demo badge with popover.
3. Demo Guide (collapsible panel/bottom sheet, 8 steps) + scenario overview (5 cards) on the dashboard.
4. Layer plain-language Dutch explanation onto the return flow, the 5 DQ panels and the knowledge assistant (fix the RAGcore-naming bug), without touching their logic.
5. Plain-language integration status labels, richer audit narration for guide-linked events, "Over deze demo" page, reset wired into guide/About/OM menu with a post-reset scenario-integrity check.
6. Full guided-demo Playwright test + targeted tests per section 19.
7. Clean-checkout demo drill, docs, Unraid deploy, final evidence with screenshots.