MobilityOps/docs/final-product-polish/audit.md

# Final product polish — audit

Performed 2026-08-03 against `feat/mobilityops-functional-completion`.

## Commit state

- **Local/branch HEAD**: `4a268c73515dc4f1d56c1aa2f231714654bffbb8`
- **Deployed on Unraid** (`/mnt/user/appdata/mobilityops/.deploy/source-revision`):
  `4a268c73515dc4f1d56c1aa2f231714654bffbb8` — **matches exactly**, no drift.
- **Repository's primary branch is `master`, not `main`** — no branch named `main` exists
  (`git branch -a` / `git remote show` confirm only `master`, `design/mobilityops-premium-ui`,
  and `feat/mobilityops-functional-completion`). `origin/master` = local `master` =
  `e0c7ed60112510687627d20a957af91c8b9db7f8`, unchanged since the functional-completion
  baseline — this is the baseline to compare against before any future merge.
- **Evidence-file mismatch found and corrected**: `artifacts/demo-release/final-summary.md`
  recorded final commit `294a8176d19...` (one commit behind actual HEAD, because its own
  "record the hash" follow-up commit necessarily couldn't self-reference). Corrected to
  the verified, unambiguous `4a268c73515dc4f1d56c1aa2f231714654bffbb8`, cross-checked
  against both `git rev-parse HEAD` and the server's `source-revision`.
- Containers on Unraid: `api`/`db`/`web` all healthy; migrations at `e7b08389f47f (head)`.

## Remaining "MobilityOps" mentions (user-facing)

- `frontend/index.html:7` — `<title>MobilityOps</title>`; `:6` meta description.
- `frontend/src/components/Layout.tsx:178` — sidebar brand lockup `<strong>MobilityOps</strong>`.
- `frontend/src/components/Layout.tsx:232` — global search `aria-label`/visually-hidden
  label "Search MobilityOps".
- `frontend/src/components/Layout.tsx:299` — footer `<span>MobilityOps PoC</span>` (also
  the "PoC" mention to remove).
- `frontend/src/pages/Login.tsx:27` — the manifest-fallback org description string.
- `frontend/src/pages/AboutDemo.tsx:32,63,71` — page heading and two body paragraphs.
- `frontend/src/pages/Knowledge.tsx:108` — empty-state copy.
- `frontend/src/pages/BookingDetail.tsx:80` — scenario callout copy.
- `frontend/src/data/demoGuideSteps.ts:91` — step 8's expected-outcome text.
- `backend/app/services/demo_manifest.py:24` — `ORGANIZATION_DESCRIPTION` (the string
  `Login.tsx:27` falls back to when the manifest hasn't loaded yet — both need updating
  together to avoid a flash of stale branding).
- `backend/app/main.py:36` — FastAPI `title="MobilityOps API"` (visible in the OpenAPI/
  Swagger UI a reviewer might open; low-risk to rename since it's a display string, not a
  route or contract field).
- **`knowledge/procedures/*.md` — user-facing, appears directly in cited answer text**:
  `02-vehicle-return.md`, `03-damage-handling.md` (also says "PoC"), `05-cleaning-
  checklist.md`, `07-customer-documents.md` (also says "PoC"), `09-booking-conflicts.md`
  all say "MobilityOps" in prose that gets quoted verbatim as a knowledge-assistant
  answer excerpt — these must be rebranded too, not just the app chrome.
- e2e tests asserting on the string "MobilityOps" that must be updated alongside the
  rename (not gaps, just dependencies): `demo-accessibility.spec.ts`, `demo-entry.spec.ts`,
  `guided-demo-full.spec.ts` (About-page heading), `ui-redesign.spec.ts` (4× "Search
  MobilityOps" combobox name).

**Kept as technical identifiers** (per the brief, not renamed): Git repo `Jens/MobilityOps`,
local repo folder name, Compose project `mobilityops`, deployment dir
`/mnt/user/appdata/mobilityops`, Postgres db/user `mobilityops`, `knowledge/manifest.json`'s
`"workspace": "mobilityops"` (a RAGcore-workspace config value), frontend package name
`mobilityops-web`, and the internal API route prefix conventions.

## Language problems (no i18n exists at all)

- `frontend/package.json` has no i18n library (`i18next`/`react-i18next`/etc. absent).
- There is no language switcher anywhere and no persisted language preference.
- The existing UI mixes English (Dashboard, Vehicles, Bookings, Data Quality workbench,
  Audit, Automation internals — all shipped in Task-B's demo-productization pass) and
  Dutch (Login, Demo Guide, Scenarios, About, demo badge — added in the same pass) by a
  documented, deliberate scope decision at the time. That decision must now be superseded:
  the brief requires one true default (nl-BE) with working en-GB/fr-BE switching across
  the **entire** application, so the English-language existing screens are now in scope
  for translation, not just new surfaces.
- The demo knowledge base (`knowledge/procedures/*.md`) is English-only; a Dutch or French
  question against it returns `insufficient` evidence (verified empirically in the prior
  work) — this is a real gap for the trilingual guided demo requirement.

## Remaining technical user-facing language

- `frontend/src/pages/Automation.tsx:183` — `{r.event_type}` rendered raw (e.g.
  `vehicle.returned.v1`) in the primary ledger table, no human label.
- `frontend/src/pages/Automation.tsx:91` — "delivered through the outbox" in primary copy.
- `frontend/src/pages/Audit.tsx:129` — `{e.correlation_id.slice(0, 8)}` shown as the
  visible `<summary>` trigger text for technical detail, not a meaningful reference.
- `frontend/src/pages/DataQualityIssueDetail.tsx:341,366` — "canonical odometer" used
  directly in primary decision copy, not translated to an operational phrase.
- No central technical→human terminology mapping exists anywhere in the frontend.

## Demo Guide panel problems

- `frontend/src/components/DemoGuide.tsx` + the `@media (min-width: 701px)` rule in
  `styles.css` implement exactly **one** behaviour for every desktop/tablet width ≥701px:
  a fixed 400px right-side panel with `.app-workspace.guide-open { padding-right:
  min(400px, 92vw) }` reserving space. There is no distinction between "extra-wide
  desktop, dock + reflow with a guaranteed minimum content width" and "standard desktop/
  tablet, floating non-modal sheet that auto-collapses to a progress chip" as the brief
  now requires — today the panel never collapses to a chip at all; it only fully opens
  or fully closes.
- "Ga naar deze stap" (`DemoGuide.tsx`'s `goToStepRoute()`) only calls `navigate(...)`; it
  does not scroll to or focus the relevant target element, and does not auto-collapse the
  panel afterward.
- No semantic target anchors exist on pages for the guide to scroll/focus toward.
- Reduced-motion is not explicitly handled for the panel's open/close or any future
  collapse/expand transition.

## Data Quality Workbench contrast and hierarchy

- Confirmed by direct inspection of `DataQualityIssueDetail.tsx`: only the odometer-
  regression decision (lines 349,358) uses the higher-contrast `.check-card` treatment
  (`background: var(--surface-subtle); border: 1px solid var(--line); padding: 10px 12px`).
  Every other decision point — `DuplicateCustomerPanel`'s survivor choice (134,143) and
  per-field merge choice (172,187), and `BookingOverlapPanel`'s block-choice (459) — uses
  the bare `.checkbox-label` class: a small inline radio with no card background, no
  border, no selected-state treatment, and no visible risk/consequence copy next to the
  option. This is the inconsistency the brief describes as "kleine losse radioknoppen in
  een zwak omlijnde rij."
- Resolve/defer/reject already have some visual differentiation (`button-primary` for the
  main resolution action inside each panel; a separate "Defer or reject" section below),
  but defer and reject are rendered as two identically-weighted plain `<button>` elements
  with no secondary/tertiary visual distinction from each other.
- No sticky/always-visible action bar exists within longer resolution panels.

## Automation/audit density

- `frontend/src/pages/Automation.tsx`'s delivery ledger renders every one of the ~20
  seeded `succeeded` events as an individual flat table row with only a status-text
  filter (`pending`/`delivering`/`succeeded`/`failed`) — no grouping/summarization of
  repeated successes, and event references are raw 8-character UUID slices with no
  meaningful short display reference scheme.
- `frontend/src/pages/Audit.tsx` shows one row per raw audit event; my prior "View related
  events" filter (added in the demo-productization pass) lets a user filter down to a
  correlation group, but does not present that group as one collapsed operational summary
  by default — a visitor still sees N separate technical rows even after filtering.
- Before/after is already shown as a computed diff string (`describeChanges()`), not raw
  JSON, which partially satisfies 8C already — but the diff is a flat semicolon-joined
  string, not the labelled multi-line "Status: A → B" presentation the brief shows.

## Rows that are not fully clickable

- **Attention Queue** (`Dashboard.tsx:126-146`, `.attention-list li`): only the `<Link>`
  wrapping the item's title text is interactive; the severity badge, detail text, ref,
  and chevron are inert. Confirmed by direct markup inspection.
- **Today's movements** (`Dashboard.tsx:153-161`, `.movement-timeline li`): only the
  `<Link>` wrapping the booking reference is interactive; each row unambiguously points
  to one booking, so this qualifies for the same fully-clickable-row treatment.
- **Recent activity** (`Dashboard.tsx:220-224`, `.recent-list li`): has **no** link at all
  today, and there is no existing single-record detail page for an individual automation
  event to point to — out of scope for "make it clickable" per the brief's own
  "alleen wanneer de volledige rij ondubbelzinnig naar één bestemming verwijst" carve-out;
  left as-is unless a natural destination is introduced elsewhere in this pass.
- Scenario cards (`Scenarios.tsx`) already use a single full-card "Start scenario" link
  per card with no competing interactive elements inside — already compliant, no change
  needed.

## Plan (implementation order)

1. Rebrand to Fleet Ops (frontend strings, backend description strings, knowledge
   procedure prose, index.html, e2e assertions) — batch, tested, committed.
2. i18n architecture: add `i18next`/`react-i18next`, language switcher, persistence,
   `html lang`, `Intl` formatting, namespaces, fail-fast missing-key check.
3. Translate all existing screens + new demo surfaces into nl-BE/en-GB/fr-BE.
4. Backend message-code fields for data-quality reasons/recommended actions/return
   reasons/integration statuses/audit actions/errors; frontend localizes.
5. Multilingual knowledge base (5 procedures × 3 locales) + locale-aware provider lookup.
6. Adaptive Demo Guide: docked-rail / floating-sheet+chip / mobile-bottom-sheet behaviour,
   scroll-to-target + focus + highlight, reduced motion.
7. Data Quality Workbench: choice cards everywhere, sticky action bar, de-emphasized
   defer/reject, contrast fixes.
8. Central terminology mapping layer (nl/en/fr) used in Automation/Audit/Data-Quality.
9. Automation ledger grouping/filtering + retry UX narration.
10. Audit trail human action labels + correlation-grouped summary + labelled diffs.
11. Fully clickable Attention Queue + Today's movements rows, with tests.
12. Responsive pass across the 7 required breakpoints × 3 languages.
13. Full test suite additions (i18n, branding, guide, quality, queue, automation/audit,
    trilingual guided demo).
14. Clean-checkout drill.
15. Deploy feature branch to Unraid for final validation.
16. Safe merge to `master` (the repository's actual main branch) + redeploy + final
    evidence at `artifacts/fleet-ops-release/final-summary.md`.