docs(design): add final validation evidence

PROJECT_STATE.md

@@ -263,3 +263,43 @@ claimed.
 ## Known blockers
 
 None. External service credentials may be absent; use the documented demo/degraded providers. The n8n workflow-activation steps are a one-time manual setup requirement in this environment (owner-account creation via n8n's own `/setup` UI cannot be scripted safely), fully documented in `docs/17-runbook.md` and scripted where possible (`make n8n-setup`). RAGcore and the ITWorx MCP Hub itself were never reachable in this environment — both integrations are implemented and directly tested/curl-verified against MobilityOps's own API, but neither a real RAGcore instance nor a real Hub round trip was available to confirm end-to-end.
+
+## Premium Control Rail UI transformation (2026-08-02)
+
+- Branch: `design/mobilityops-premium-ui`, branched from verified deployed revision
+  `dfabb41582e302f45a3de826f85f531bf23dfc8b`; master history was not rewritten.
+- Audited every route at 1440, 1280, 768 and 390 px. Baseline findings and captures are
+  in `docs/design/current-ux-audit.md` and `artifacts/design-validation/current/`.
+- Authored three twelve-screen product directions and generated representative Stitch
+  anchors in project `17018847755558569017`: Control Rail, Dispatch Ledger and Service
+  Atelier. Control Rail was selected and refined twice for hierarchy, accessibility and
+  responsive implementation. Decision, screen inventory, tokens and exact Stitch IDs
+  are in `docs/design/design-directions.md`, `docs/design/design-system.md` and
+  `docs/design/stitch-manifest.md`.
+- Rebuilt the complete React interface around a responsive Control Rail shell: inline SVG
+  icon/brand system, desktop rail, named landmarks, skip link, top bar, mobile bottom
+  navigation, shared loading/error/empty states and reduced-motion support.
+- Redesigned all shipped pages. The dashboard now prioritizes persisted readiness,
+  Attention and today's movements; booking results paginate at 25 rows; every responsive
+  table retains field labels; integrations distinguish n8n evidence, live RAGcore health
+  and the unconfigured MCP adapter without inventing status.
+- Return registration is now capture → review → result. A regression test proves the
+  return endpoint is not called before confirmation; the existing idempotency and local
+  commit/outbox contract is unchanged.
+- Final browser captures are in `artifacts/design-validation/implementation/`. DOM
+  measurements and Playwright both prove no horizontal overflow at 390, 768, 1280 and
+  1440 px. See `docs/design/implementation-validation.md`.
+- Final validation commands from this branch:
+  - `docker compose run --rm api pytest -q` — **66 passed**.
+  - `docker compose run --rm api ruff check .` — **All checks passed**.
+  - `docker compose run --rm api mypy app` — **0 issues in 44 files**.
+  - `cd frontend && npm run lint` — clean TypeScript check.
+  - `cd frontend && npm run build` — production build succeeded (59 modules; 238.66 kB JS,
+    36.54 kB CSS before gzip).
+  - `cd frontend && playwright test --reporter=line` — **18 passed** including the full
+    five-minute demo, every interactive route, return review semantics and four viewport
+    overflow checks.
+- Exact next action after this record: commit this evidence set, push
+  `design/mobilityops-premium-ui`, and deploy that branch to the
+  existing Unraid review stack without touching master or persistent volumes; verify live
+  health and responsive UI.

README.md

@@ -4,6 +4,12 @@
 
 MobilityOps is a working proof of concept for a fictitious mobility company. It combines vehicle and booking operations, a controlled vehicle-return workflow, data-quality review, RAGcore-backed internal knowledge, n8n orchestration and read-only tools published through ITWorx MCP Hub.
 
+The web application uses the premium responsive **Control Rail** interface: a compact
+operations-first workspace with persisted readiness metrics, evidence-led exceptions,
+review-before-commit return handling and mobile navigation designed down to 390 px. See
+`docs/design/design-directions.md` and `docs/design/implementation-validation.md` for the
+design decision and visual evidence.
+
 All people, companies, vehicles, bookings and documents are synthetic. The workflows, validation, integrations, audit logging and access boundaries are intended to be real.
 
 ## Scope
@@ -53,6 +59,7 @@ commands.
 - `backend/` — FastAPI/SQLAlchemy/Alembic API.
 - `frontend/` — React/TypeScript/Vite web app, including the Playwright end-to-end suite (`frontend/e2e/`).
 - `artifacts/evidence/` — final acceptance evidence (screenshots, architecture, `final-summary.md`).
+- `artifacts/design-validation/` — baseline audit, Stitch direction references and implemented responsive captures.
 
 ## Quickstart
 
@@ -78,7 +85,7 @@ All defaults are configurable via `.env` (see `.env.example`).
 ```bash
 make test    # backend: pytest (66 tests)
 make lint    # backend: ruff + mypy (strict, zero errors)
-make e2e     # frontend: Playwright end-to-end (12 tests, live stack required)
+make e2e     # frontend: Playwright end-to-end (18 tests, live stack required)
 ```
 
 Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`).

artifacts/design-validation/final-design-summary.md

@@ -0,0 +1,77 @@
+# MobilityOps premium UI evidence summary
+
+Date: 2026-08-02
+Branch: `design/mobilityops-premium-ui`
+Baseline revision: `dfabb41582e302f45a3de826f85f531bf23dfc8b`
+Final design revision: `b3946af4e0e14f2a3acecd212e9f0079e3028fca`
+Review URL: `http://192.168.10.150:1236`
+
+## Outcome
+
+The working PoC was transformed into the Control Rail operational interface without
+changing backend contracts or adding scope. All existing journeys remain functional;
+return registration gained an evidence-based review boundary before commit.
+
+## Evidence index
+
+- Baseline audit: `docs/design/current-ux-audit.md`
+- Three directions and decision: `docs/design/design-directions.md`
+- Design tokens and component rules: `docs/design/design-system.md`
+- Stitch resource IDs: `docs/design/stitch-manifest.md`
+- Implemented visual validation: `docs/design/implementation-validation.md`
+- Baseline captures: `artifacts/design-validation/current/`
+- Stitch captures: `artifacts/design-validation/stitch/`
+- Final responsive captures: `artifacts/design-validation/implementation/`
+
+## Major implementation changes
+
+- Responsive Control Rail shell with compact top bar, desktop rail, off-canvas menu and
+  labelled mobile bottom navigation.
+- Live readiness band, filterable Attention queue, movement timeline, honest integration
+  pulse and persisted activity on the operations dashboard.
+- Searchable fleet and booking registries; booking client pagination limits the DOM to 25
+  operational rows; responsive tables retain field labels.
+- Capture → review → result return workflow with calculated consequence preview and no
+  write request before confirmation.
+- Match/conflict duplicate comparison, evidence-first knowledge, system-health cards and
+  expandable audit metadata.
+- Inline SVG product mark, Feather-like line icon set, CSS control-centre illustration,
+  timeline/status motion and reduced-motion fallback; no image or motion dependency.
+
+## Validation
+
+| Gate | Result |
+|---|---|
+| Backend tests | 66 passed |
+| Backend lint | ruff passed |
+| Backend types | mypy: 0 issues in 44 files |
+| Frontend types/build | passed; 59 modules; 238.66 kB JS and 36.54 kB CSS before gzip |
+| Browser journeys | 18 passed locally |
+| Horizontal overflow | none at 390/768/1280/1440 px |
+| Accessibility | named landmarks, skip link, visible focus, text-plus-shape status, labelled mobile rows, reduced-motion support |
+| Console/network | pending final deployed smoke test; local API/browser journeys are clean |
+
+All displayed operational counts remain derived from the existing persisted API data.
+Synthetic-data labelling is persistent on login and authenticated surfaces.
+
+## Performance observations
+
+No runtime font, image or animation dependency was added. The application uses inline SVG
+and CSS visuals, and the production bundle remains appropriate for this internal PoC.
+
+## Known limitations
+
+- Global search is present as a shell affordance but does not execute a cross-entity
+  query because no matching API contract exists; route-level search and filters are live.
+- The MCP Hub state is correctly shown as not configured in the current PoC rather than
+  simulated as healthy.
+- Live RAGcore and MCP Hub round trips remain subject to the existing environment limits
+  documented in `PROJECT_STATE.md`; their degradation behavior is unchanged.
+
+## Rollback
+
+The accepted baseline remains reachable at commit
+`dfabb41582e302f45a3de826f85f531bf23dfc8b`. To roll back the review deployment without
+rewriting git history, archive that revision, extract it over the application source on
+Unraid while preserving `.env` and Docker volumes, and run
+`docker compose -p mobilityops up -d --build`. Verify `/health` and port 1236 afterwards.

docs/design/implementation-validation.md

@@ -0,0 +1,60 @@
+# Premium UI implementation validation
+
+Date: 2026-08-02
+Branch: `design/mobilityops-premium-ui`
+
+## Implemented scope
+
+- New responsive Control Rail shell, icon system, product mark, top bar, desktop rail,
+  off-canvas navigation and labelled mobile bottom navigation.
+- Redesigned login, dashboard, fleet, vehicle, bookings, booking return, data quality,
+  duplicate review, knowledge, integrations and audit surfaces.
+- Return capture now has an explicit review step; no return API request is sent before
+  confirmation. The existing idempotency key and local-commit/outbox behavior remain.
+- Booking rows are limited to 25 per client-side page; mobile tables keep explicit field
+  labels through `data-label` semantics.
+- Loading, empty and error surfaces, focus treatment, reduced-motion handling and honest
+  integration states are shared system behaviors.
+
+## Visual evidence
+
+Desktop:
+
+![Implemented desktop login](../../artifacts/design-validation/implementation/desktop/login-1440.png)
+
+![Implemented desktop dashboard](../../artifacts/design-validation/implementation/desktop/dashboard-1440.png)
+
+![Implemented return capture](../../artifacts/design-validation/implementation/desktop/booking-return-1440.png)
+
+![Implemented return review](../../artifacts/design-validation/implementation/desktop/booking-return-review-1440.png)
+
+Mobile:
+
+![Implemented mobile login](../../artifacts/design-validation/implementation/mobile/login-390.png)
+
+![Implemented mobile dashboard](../../artifacts/design-validation/implementation/mobile/dashboard-390.png)
+
+![Implemented mobile duplicate review](../../artifacts/design-validation/implementation/mobile/duplicate-review-390.png)
+
+The complete capture set is in `artifacts/design-validation/implementation/`.
+
+## Responsive evidence
+
+Browser evaluation measured the document element after authenticated page render:
+
+| Width | Client width | Scroll width | Result |
+|---:|---:|---:|---|
+| 390 | 375 (vertical scrollbar present) | 375 | no horizontal overflow |
+| 768 | 753 (vertical scrollbar present) | 753 | no horizontal overflow |
+| 1280 | 1265 (vertical scrollbar present) | 1265 | no horizontal overflow |
+| 1440 | 1425 (vertical scrollbar present) | 1425 | no horizontal overflow |
+
+The same widths are automated in `frontend/e2e/ui-redesign.spec.ts`.
+
+## Performance choices
+
+- No image runtime dependency and no animation library were added.
+- Branding, navigation and workflow illustrations are inline SVG/CSS.
+- Inter is used only when locally available; there is no blocking font request.
+- The production build remains a single small PoC bundle (approximately 239 kB JS and
+  37 kB CSS uncompressed at implementation time).