Publish curated MobilityOps source from 64b0a721955f10dfd1570b6b5933c0a0462ff442

README.md

@@ -1,20 +1,60 @@
-# MobilityOps · public source
+# Fleet Ops
 
-MobilityOps (Fleet Ops) is a synthetic-data operations demo for vehicle rental and service teams. This repository is the reviewed public source snapshot. Development and deployment happen in a private canonical repository; each public update is generated from a committed revision with a fresh content review.
+<p align="center"><strong>One operational workspace for a fictional vehicle rental fleet.</strong></p>
 
-## Run locally
+<p align="center"><a href="#try-the-demo">Try the demo</a> · <a href="#what-you-can-do">Features</a> · <a href="#how-it-works">Architecture</a> · <a href="#deployment-notes">Deployment</a></p>
 
-Copy `.env.example` to `.env`, then run `make demo`. Open <http://localhost:1228>. The demo uses fictional records and a local knowledge provider.
+Fleet Ops is the application in the `MobilityOps` repository. It brings vehicles, bookings, returns, data quality and procedures into one controlled workspace. This public edition uses **synthetic people, vehicles and activity** so you can explore the real workflows without exposing operational data.
 
-## Contents
+![Fleet Ops guided demo entry](frontend/e2e/__screenshots__/highlights-main.png)
 
-- `backend/` — FastAPI domain and API
-- `frontend/` — React interface and browser tests
-- `contracts/` — API and event contracts
-- `knowledge/` and `seed/` — synthetic procedures and records
+*The application supports English, Dutch and French. This demo capture shows the Dutch interface.*
 
-## Security
+## Try the demo
 
-Please report vulnerabilities through the contact in [SECURITY.md](SECURITY.md). No operational deployment state or private Git history is included in this repository.
+Requirements: Docker Engine with Compose and a recent `make` implementation.
 
-Licensed under the terms in [LICENSE](LICENSE).
+```bash
+cp .env.example .env
+make demo
+```
+
+Open <http://localhost:1228>. No demo password is required. Choose **Highlights in 90 seconds** for a short guided tour, or enter as an operations manager or rental employee. API readiness is available at <http://localhost:8128/health/ready>.
+
+The demo includes a deterministic dataset and a local knowledge provider. It does not require a live external AI service or production n8n endpoint.
+
+## What you can do
+
+| Area | Workflow |
+| --- | --- |
+| Fleet and bookings | Inspect vehicle availability, booking state, returns and maintenance context. |
+| Controlled returns | Preview an inspection and commit the vehicle, booking, audit and outbox changes together. |
+| Data quality | Review rule-backed issues, assignments, deadlines and explicit customer merges. |
+| Knowledge | Ask procedural questions and inspect cited evidence; insufficient evidence stays unanswered. |
+| Integrations | See delivery state, bounded retries and correlated audit events. |
+| Administration | Manage roles, privacy exports, anonymisation and retention controls. |
+
+![Fleet Ops interface overview](frontend/public/og-fleet-ops.svg)
+
+## How it works
+
+```mermaid
+flowchart LR
+    Web[React and TypeScript] --> API[FastAPI and role checks]
+    API --> DB[(PostgreSQL)]
+    API --> Knowledge[Grounded knowledge provider]
+    DB --> Outbox[Transactional outbox]
+    Outbox --> Automation[n8n integration]
+```
+
+The API owns operational state. Return processing is transactional; external automation receives an outbox event after the database commit. The demo can use bundled n8n, while a production installation can connect to an existing instance. The frontend is responsive and supports keyboard navigation.
+
+## Deployment notes
+
+The Compose stack includes the web app, API, database and a local automation fallback. Copy `.env.example`, set unique credentials and an appropriate `N8N_WEBHOOK_URL`, then mount persistent PostgreSQL storage. Put the web endpoint behind HTTPS, verify `/health/ready`, and test backup and restore before use. The public source intentionally contains no private deployment configuration.
+
+For development, use `make test`, `make lint`, `make e2e` and `npm run build --prefix frontend`. The main directories are `backend/` (API and migrations), `frontend/` (UI and browser tests), `contracts/` (integration schemas), and `knowledge/` plus `seed/` (fictional demo content).
+
+## About this public copy
+
+This repository is published from a reviewed private source commit. `PUBLIC_SOURCE_MANIFEST.json` records the source revision and file hashes. No private Git history is included. See [SECURITY.md](SECURITY.md) for vulnerability reporting and [LICENSE](LICENSE) for licensing.