Initial MobilityOps build pack (docs, contracts, scaffold)

docs/00-product-brief.md

@@ -0,0 +1,27 @@
+# Product brief
+
+## Problem
+
+A small vehicle-rental and service company works with booking data, vehicle status, inspections, maintenance records and internal procedures spread across systems and spreadsheets. Employees manually reconcile information, miss incomplete returns and spend time locating procedures.
+
+## Solution
+
+MobilityOps provides one operational view, one complete return workflow, targeted data-quality review and a source-grounded knowledge assistant. It demonstrates realistic integration boundaries without claiming to replace the source systems.
+
+## Primary users
+
+### Operations Manager
+
+Monitors attention items, reviews data-quality issues, inspects workflow failures and uses the knowledge assistant.
+
+### Rental Employee
+
+Views bookings, registers a vehicle return, records inspection details and follows grounded procedures.
+
+## Product promise
+
+Within five minutes a visitor can see persisted operational data, complete a return, trigger automation, resolve a duplicate, inspect the audit trail, ask a policy question and query live data through MCP.
+
+## Honesty statement
+
+All entities and documents are synthetic. The application behaviour and integrations are real. Do not claim measured commercial savings or production use.

docs/01-scope-and-non-goals.md

@@ -0,0 +1,36 @@
+# Scope and non-goals
+
+## Required PoC scope
+
+- demo login for Operations Manager and Rental Employee;
+- dashboard derived from persisted data;
+- vehicle list/detail;
+- booking list/detail;
+- complete vehicle-return command;
+- five data-quality rule types;
+- customer duplicate review and merge;
+- audit log;
+- workflow/outbox view;
+- RAGcore-backed knowledge assistant plus demo fallback;
+- two n8n workflow definitions, one required for the live demo;
+- four read-only MCP tools published through ITWorx MCP Hub;
+- deterministic demo reset.
+
+## Non-goals
+
+Do not build:
+
+- accounting, invoices, payments or pricing;
+- public search or customer reservation pages;
+- generic CRM functionality;
+- workshop inventory or parts management;
+- document OCR or broad document-management features;
+- autonomous writes through MCP;
+- a second vector database or RAG pipeline inside MobilityOps;
+- complex notifications, email delivery or mobile apps;
+- multi-tenant administration beyond a fixed demo tenant;
+- ML predictions based on synthetic data.
+
+## Scope-change rule
+
+A feature may be added only when it is necessary to satisfy an existing acceptance criterion. Nice-to-have ideas go to `docs/deferred.md` and are not implemented during the PoC.

docs/02-user-stories.md

@@ -0,0 +1,32 @@
+# User stories
+
+## Dashboard
+
+- As an Operations Manager, I can see available, rented, maintenance and blocked vehicles so I know the current operational state.
+- As an Operations Manager, I can open an attention item and reach the relevant record directly.
+
+## Return workflow
+
+- As a Rental Employee, I can register a return with mileage, fuel, cleanliness, damage and technical notes.
+- The system validates mileage and required fields before deriving the new vehicle state.
+- A problematic return is committed, audited and blocked even when n8n is unavailable.
+
+## Data quality
+
+- As an Operations Manager, I can review possible duplicate customers with explainable match signals.
+- I can merge, reject or defer the duplicate and see an audit event.
+- I can review falling mileage, overlapping bookings, missing required data and status conflicts.
+
+## Knowledge
+
+- As an employee, I can ask a question about one of the supplied procedures.
+- The answer contains sources and document versions, or explicitly states that evidence is insufficient.
+
+## Automation
+
+- As an Operations Manager, I can see pending, successful and failed workflow deliveries.
+- Failed deliveries can be retried safely without duplicating domain actions.
+
+## MCP
+
+- As an authorised external AI client, I can request the operations summary, attention vehicles, vehicle details and procedure search without database or write access.

docs/03-architecture.md

@@ -0,0 +1,55 @@
+# Architecture
+
+## Context
+
+```text
+External AI client
+      |
+      v
+ITWorx MCP Hub ---------> RAGcore
+      |                      ^
+      v                      |
+MobilityOps API <------ MobilityOps UI
+      |
+      +---- PostgreSQL
+      |
+      +---- Outbox dispatcher ----> n8n
+```
+
+## Ownership
+
+### MobilityOps
+
+Owns vehicles, customers, bookings, inspections, maintenance summaries, data-quality issues, audit events and integration delivery state.
+
+### RAGcore
+
+Owns procedure ingestion, chunking, embeddings, retrieval and grounded answer generation. MobilityOps stores only document references and last-known synchronization state where useful.
+
+### ITWorx MCP Hub
+
+Owns MCP transport, tool publication, client policy and central tool audit. The hub calls versioned MobilityOps APIs and RAGcore APIs. It never reads the MobilityOps database.
+
+### n8n
+
+Receives committed events and orchestrates secondary work. It does not decide whether a vehicle return is valid or what the canonical vehicle status is.
+
+## Reliability boundaries
+
+1. A return command and its outbox event commit in one database transaction.
+2. Outbox delivery is at-least-once; the n8n workflow and callback endpoint are idempotent by event ID.
+3. RAGcore failure disables knowledge answers only.
+4. MCP Hub failure does not affect the MobilityOps web application.
+5. n8n failure leaves events pending with bounded retries and visible status.
+
+## Security boundaries
+
+- browser uses application authentication;
+- service-to-service calls use scoped tokens;
+- no arbitrary SQL, shell or generic HTTP tools;
+- read-only MCP tools only for the PoC;
+- user and service actions are distinguishable in audit events.
+
+## Deployment
+
+MobilityOps may run in its own Compose project. RAGcore and MCP Hub are configured by URL and credentials and may be on another internal Docker network or behind TLS endpoints.

docs/04-domain-model.md

@@ -0,0 +1,118 @@
+# Domain model
+
+Use UUID primary keys internally. Human-facing references are immutable unique strings.
+
+## User
+
+- id
+- public_ref (`USR-...`)
+- display_name
+- role: `operations_manager | rental_employee`
+- active
+
+## Customer
+
+- id
+- public_ref (`CUS-0001`)
+- first_name, last_name
+- email, phone
+- postal_code, city
+- date_of_birth (optional)
+- merged_into_customer_id (optional)
+- created_at, updated_at
+
+## Vehicle
+
+- id
+- public_ref (`MO-001`)
+- make, model, model_year
+- registration_number
+- location
+- operational_status: `available | rented | cleaning | maintenance | blocked`
+- odometer_km
+- next_service_km
+- active
+- version for optimistic concurrency
+
+## Booking
+
+- id
+- public_ref (`BK-...`)
+- customer_id, vehicle_id
+- starts_at, ends_at
+- status: `reserved | active | returned | cancelled | blocked`
+- start_odometer_km, end_odometer_km
+- requirements_complete
+
+Database invariant: active/reserved bookings for the same vehicle may not overlap after validation. A deliberate seeded conflict may be imported as an external-data quality issue through a controlled bypass, never created through the normal command API.
+
+## Inspection
+
+- id
+- public_ref
+- booking_id, vehicle_id
+- type: `checkout | return`
+- fuel_level_percent
+- cleanliness_ok
+- damage_reported
+- technical_warning
+- notes
+- odometer_km
+- completed_at, completed_by
+
+## MaintenanceRecord
+
+- id
+- vehicle_id
+- occurred_at
+- odometer_km
+- category
+- summary
+
+## DataQualityIssue
+
+- id
+- public_ref
+- rule_type:
+  - `possible_duplicate_customer`
+  - `missing_required_field`
+  - `odometer_regression`
+  - `booking_overlap`
+  - `vehicle_status_conflict`
+- entity_type, entity_id
+- severity: `low | medium | high`
+- status: `open | deferred | resolved | rejected`
+- evidence_json
+- proposed_action_json
+- detected_at, resolved_at, resolved_by
+
+## OutboxEvent / WorkflowRun
+
+- id / event_id
+- event_type
+- aggregate_type, aggregate_id
+- payload_json
+- occurred_at
+- delivery_status: `pending | delivering | succeeded | failed`
+- attempts, next_attempt_at, last_error
+- external_run_id
+
+## AuditEvent
+
+- id
+- actor_type: `user | service | system`
+- actor_id / actor_label
+- action
+- entity_type, entity_id
+- correlation_id
+- before_json, after_json, metadata_json
+- occurred_at
+
+## Required invariants
+
+- a vehicle return cannot reduce the canonical odometer;
+- a return with a lower submitted reading is recorded as an inspection and issue, while canonical odometer remains unchanged;
+- damage or a critical warning blocks the vehicle;
+- merged customers remain as tombstones linked to the survivor;
+- resolving a quality issue and applying its correction is transactional and audited;
+- public references never change after creation.

docs/05-api-contract.md

@@ -0,0 +1,75 @@
+# API contract summary
+
+The machine-readable baseline is `contracts/openapi.yaml`.
+
+## Authentication
+
+The demo may use signed server-issued sessions or short-lived JWTs. Demo-role buttons create an authenticated session; they do not bypass authorization middleware.
+
+## Required routes
+
+### System and demo
+
+- `GET /health`
+- `GET /api/v1/system/status`
+- `POST /api/v1/demo/login`
+- `POST /api/v1/demo/reset` — Operations Manager only
+
+### Dashboard
+
+- `GET /api/v1/dashboard`
+
+### Vehicles
+
+- `GET /api/v1/vehicles`
+- `GET /api/v1/vehicles/{public_ref}`
+
+### Bookings and return
+
+- `GET /api/v1/bookings`
+- `GET /api/v1/bookings/{public_ref}`
+- `POST /api/v1/bookings/{public_ref}/return`
+
+Return commands require an `Idempotency-Key` header and optimistic version where relevant.
+
+### Data quality
+
+- `GET /api/v1/data-quality/issues`
+- `GET /api/v1/data-quality/issues/{public_ref}`
+- `POST /api/v1/data-quality/issues/{public_ref}/defer`
+- `POST /api/v1/data-quality/issues/{public_ref}/reject`
+- `POST /api/v1/data-quality/issues/{public_ref}/merge-customers`
+
+### Knowledge
+
+- `POST /api/v1/knowledge/questions`
+- `GET /api/v1/knowledge/status`
+
+### Automation and audit
+
+- `GET /api/v1/workflows`
+- `POST /api/v1/workflows/{event_id}/retry`
+- `GET /api/v1/audit`
+
+### MCP-provider endpoints
+
+Service-token protected:
+
+- `GET /api/v1/integrations/mcp/operations-summary`
+- `GET /api/v1/integrations/mcp/attention-vehicles`
+- `GET /api/v1/integrations/mcp/vehicles/{public_ref}`
+
+Knowledge search may be routed by the Hub directly to RAGcore or through a narrowly scoped MobilityOps façade. Use the contract chosen in `docs/10-mcp-hub-integration.md`.
+
+## Error shape
+
+```json
+{
+  "error": {
+    "code": "ODOMETER_REGRESSION",
+    "message": "The submitted reading is below the current canonical odometer.",
+    "correlation_id": "...",
+    "details": {}
+  }
+}
+```

docs/06-ui-ux.md

@@ -0,0 +1,78 @@
+# UI and UX specification
+
+## Design goal
+
+A recruiter or non-technical manager must understand the business value within thirty seconds. Use a restrained professional interface, clear language and direct links from attention items to records.
+
+## Persistent demo disclosure
+
+Show a compact banner on every authenticated page:
+
+> Synthetic demo environment — no real customer or vehicle data.
+
+## Navigation
+
+- Dashboard
+- Vehicles
+- Bookings
+- Data Quality
+- Knowledge
+- Automation
+- Audit
+
+## Demo login
+
+Two primary buttons:
+
+- Open as Operations Manager
+- Open as Rental Employee
+
+Also show one sentence explaining what each role can demonstrate.
+
+## Dashboard
+
+Top metrics:
+
+- available;
+- rented;
+- maintenance;
+- blocked;
+- open quality issues;
+- failed/pending workflows.
+
+Sections:
+
+1. Attention required — sorted by severity and proximity to next booking.
+2. Today — departures, returns and incomplete inspections.
+3. Recent automation — latest five runs.
+
+## Vehicle list/detail
+
+List filters: status, location, attention only. Detail tabs: overview, bookings, inspections, maintenance, quality issues, audit.
+
+## Booking return flow
+
+Use a short single-page form with visible validation. After submission show a result summary explaining:
+
+- persisted inspection;
+- resulting vehicle status;
+- created quality issue if any;
+- queued automation event;
+- next booking risk.
+
+## Data Quality Workbench
+
+Use a two-column comparison for duplicate customers with matching signals and a deliberate field-selection merge step. Other issue types need evidence, proposed resolution and an audit preview.
+
+## Knowledge
+
+Chat-like question box is acceptable, but the answer must prioritize source cards: title, version, section and excerpt. Show explicit unavailable and insufficient-evidence states.
+
+## Accessibility
+
+- keyboard-operable controls;
+- visible focus;
+- semantic headings and form labels;
+- status not encoded by color alone;
+- responsive at 360 px width;
+- no hover-only actions.

docs/07-data-quality.md

@@ -0,0 +1,47 @@
+# Data-quality rules
+
+Run rules after seed/import, after relevant commands and through an explicit scan service. Rules must be deterministic and explainable.
+
+## DQ-01 Possible duplicate customer
+
+Signals and example weights:
+
+- exact normalized email: 60;
+- exact normalized phone: 50;
+- exact postal code: 10;
+- strong normalized full-name similarity: up to 30.
+
+Open an issue at score >= 70. Store individual signals; do not expose a mysterious AI-only confidence.
+
+Resolution:
+
+- merge into selected survivor;
+- reject as not duplicate;
+- defer.
+
+Merge rewires booking references, preserves the loser as a tombstone and audits before/after values.
+
+## DQ-02 Missing required field
+
+Required for active customers: first name, last name and at least one of email or phone. Required for active vehicles: registration number, make, model and location.
+
+## DQ-03 Odometer regression
+
+Flag an inspection or maintenance reading below the canonical odometer. Never lower the canonical value automatically.
+
+## DQ-04 Booking overlap
+
+Flag overlapping `reserved` or `active` bookings for one vehicle. Normal write APIs reject new overlaps; the seed/import path may create one controlled legacy conflict.
+
+## DQ-05 Vehicle status conflict
+
+Examples:
+
+- status `available` while an active booking exists;
+- status `rented` without an active booking;
+- status `available` while critical open quality issue exists;
+- status `maintenance` with an active booking.
+
+## Lifecycle
+
+Detection is idempotent by `(rule_type, entity_type, entity_id, evidence fingerprint)` while open. Resolved issues remain historical. Reintroduced evidence creates a new issue linked to the prior issue where useful.

docs/08-return-workflow.md

@@ -0,0 +1,42 @@
+# Vehicle-return workflow
+
+## Input
+
+- booking public reference;
+- submitted end odometer;
+- fuel level 0–100;
+- cleanliness flag;
+- damage flag;
+- technical warning flag;
+- notes;
+- idempotency key.
+
+## Transaction
+
+1. Authorize Rental Employee or Operations Manager.
+2. Lock booking and vehicle rows.
+3. Reject cancelled/already-returned booking unless idempotency replay matches.
+4. Validate required fields and submitted reading against booking start reading.
+5. Create a return inspection.
+6. Set booking to returned and store submitted end reading.
+7. If submitted reading >= canonical odometer, update canonical odometer.
+8. Otherwise create `odometer_regression`; keep canonical odometer unchanged.
+9. Derive vehicle state:
+   - damage or technical warning -> `blocked`;
+   - service threshold reached -> `maintenance`;
+   - otherwise -> `cleaning`.
+10. Create quality issues for contradictions.
+11. Create audit events.
+12. Insert `vehicle.returned.v1` outbox event.
+13. Commit once.
+
+## Post-commit n8n behaviour
+
+The event contains enough identifiers to retrieve current state, not an uncontrolled full database snapshot. n8n may create a cleaning/maintenance follow-up through a narrow callback API and return its run ID.
+
+## Failure behaviour
+
+- n8n unavailable: return succeeds; event stays pending.
+- duplicate event delivery: n8n and callback are idempotent by event ID.
+- callback fails: workflow appears failed and is retryable.
+- concurrent return submissions: only one succeeds; same idempotency key replays the original response.

docs/09-ragcore-integration.md

@@ -0,0 +1,65 @@
+# RAGcore integration
+
+## Objective
+
+Use the existing central RAGcore project. MobilityOps must not implement embeddings, vector storage, chunking or its own answer-generation pipeline.
+
+## Namespace
+
+- tenant: `northstar-mobility-demo`
+- workspace: `mobilityops`
+- collection: `internal-procedures`
+
+These values are configurable.
+
+## Source documents
+
+The ten Markdown files under `knowledge/procedures/` are authoritative PoC sources. Keep their IDs, versions and effective dates as metadata.
+
+## Required adapter interface
+
+```python
+class KnowledgeProvider(Protocol):
+    async def health(self) -> KnowledgeHealth: ...
+    async def ask(self, question: str, actor: ActorContext) -> GroundedAnswer: ...
+    async def sync_manifest(self, documents: list[KnowledgeDocumentRef]) -> SyncResult: ...
+```
+
+Implement:
+
+- `RAGcoreKnowledgeProvider`;
+- `DemoKnowledgeProvider` using deterministic keyword/BM25-style local source retrieval only.
+
+The demo provider is a resilience/test adapter, not a second RAG platform. It must return extracted source passages and a template summary; it must not pretend to be generative AI.
+
+## Answer contract
+
+```json
+{
+  "answer": "...",
+  "evidence_state": "grounded | insufficient | unavailable",
+  "sources": [
+    {
+      "document_id": "damage-procedure",
+      "title": "Damage handling procedure",
+      "version": "1.3",
+      "section": "2. Immediate actions",
+      "excerpt": "..."
+    }
+  ],
+  "provider": "ragcore",
+  "correlation_id": "..."
+}
+```
+
+## Safety
+
+- send actor scope and tenant/workspace with each request;
+- enforce source allow-list for this PoC;
+- never fall back to general model knowledge silently;
+- no customer PII is indexed in RAGcore;
+- log question metadata and source IDs, not unnecessary full prompts.
+
+## Degraded mode
+
+When RAGcore is unreachable, return `unavailable` and keep all operational functions available. When evidence is weak, return `insufficient` with the best source matches and no fabricated procedure.

docs/10-mcp-hub-integration.md

@@ -0,0 +1,56 @@
+# ITWorx MCP Hub integration
+
+## Objective
+
+Publish four read-only MobilityOps capabilities through the existing central ITWorx MCP Hub. MobilityOps does not host MCP transport itself.
+
+## Provider registration
+
+- provider ID: `mobilityops`
+- API base: configurable internal MobilityOps API URL
+- authentication: scoped service token
+- mode: read-only
+- required scope: `mobilityops.read`
+
+## Tools
+
+The machine-readable definitions are in `contracts/mcp-tools.json`.
+
+1. `mobilityops_get_operations_summary`
+2. `mobilityops_list_attention_vehicles`
+3. `mobilityops_get_vehicle_details`
+4. `mobilityops_search_knowledge`
+
+## Routing
+
+Operational tools:
+
+```text
+AI client -> MCP Hub -> MobilityOps provider API
+```
+
+Knowledge tool:
+
+Preferred:
+
+```text
+AI client -> MCP Hub -> RAGcore workspace mobilityops
+```
+
+If the Hub requires a single provider boundary, route through a narrow MobilityOps knowledge façade that calls RAGcore. Do not duplicate retrieval logic.
+
+## Restrictions
+
+Do not expose:
+
+- generic SQL;
+- arbitrary URL fetching;
+- arbitrary shell commands;
+- return registration;
+- customer merge;
+- booking or vehicle mutation;
+- secrets or raw service configuration.
+
+## Audit
+
+The Hub owns central tool-call audit. MobilityOps also records service requests that reach its provider APIs with tool name, correlation ID, client/service identity and result status.

docs/11-n8n-integration.md

@@ -0,0 +1,41 @@
+# n8n integration
+
+## Role
+
+n8n orchestrates secondary cross-system work after MobilityOps commits canonical state. It is not the domain engine.
+
+## Required live workflow: return processing
+
+Input: `vehicle.returned.v1` webhook event.
+
+Steps:
+
+1. validate event type and schema;
+2. derive a follow-up category from the already-calculated state;
+3. call the narrow MobilityOps callback endpoint with event ID and follow-up summary;
+4. return a stable workflow result;
+5. on errors, fail visibly so the outbox dispatcher can retry.
+
+The starter export is `n8n/mobilityops-return-processing.json`. Claude may correct its credentials and callback route but must preserve idempotency.
+
+## Optional second workflow: knowledge sync
+
+Input: manual trigger or manifest-changed event.
+
+Steps:
+
+1. read the fixed knowledge manifest;
+2. call RAGcore ingestion/sync API;
+3. record per-document results through MobilityOps integration status API.
+
+This workflow is useful but must not delay the core demo if RAGcore's final API is not ready.
+
+## Outbox dispatcher
+
+- polls pending records;
+- claims with `FOR UPDATE SKIP LOCKED` or equivalent;
+- sends event with timeout;
+- exponential backoff with a small maximum attempt count;
+- supports explicit manual retry;
+- preserves last error and response metadata;
+- does not hold a database transaction open during network I/O.

docs/12-security-and-audit.md

@@ -0,0 +1,47 @@
+# Security and audit
+
+## Demo authentication
+
+Role buttons may create a session for a seeded demo identity. All API routes still enforce authorization. Demo reset and customer merge require Operations Manager.
+
+## Service authentication
+
+Use separate scoped credentials for:
+
+- n8n callbacks;
+- MCP Hub provider calls;
+- RAGcore calls.
+
+Never reuse browser session secrets.
+
+## Sensitive data
+
+All data are synthetic, but design as though data were sensitive:
+
+- do not log full tokens;
+- avoid logging complete customer payloads;
+- validate and size-limit free-text inputs;
+- escape rendered content;
+- use CSRF protection for cookie sessions or use a secure token model;
+- restrictive CORS;
+- secrets from environment or mounted secret files.
+
+## Audit events
+
+Required actions:
+
+- demo login;
+- return registration;
+- vehicle status change;
+- data-quality issue creation and resolution;
+- customer merge;
+- workflow retry;
+- demo reset;
+- MCP provider request;
+- knowledge question status and source IDs.
+
+Audit is append-only through the application. Provide filters by actor, action, entity and correlation ID.
+
+## Confirmation
+
+No write-capable MCP actions exist in this PoC. Destructive UI actions such as demo reset and customer merge require explicit confirmation.

docs/13-seed-and-demo-scenarios.md

@@ -0,0 +1,54 @@
+# Seed and demo scenarios
+
+## Dataset
+
+`seed/generate_seed.py` creates a deterministic snapshot for a chosen anchor date and random seed. The committed CSV files are generated with:
+
+```bash
+python seed/generate_seed.py --anchor 2026-08-01 --seed 20260801
+```
+
+Target scale:
+
+- 50 vehicles;
+- 180 customers including three duplicate pairs;
+- 220 historical and 25 current/future bookings;
+- realistic inspections and maintenance records;
+- fixed quality and workflow scenarios.
+
+## Required named scenarios
+
+### S1 — Odometer regression return
+
+Booking `BK-DEMO-RETURN` for vehicle `MO-024` is active. Submit a return reading below the canonical odometer. Expected: inspection saved, canonical odometer unchanged, vehicle blocked or cleaning according to other flags, quality issue created, event queued and audit visible.
+
+### S2 — Duplicate customer merge
+
+Customers `CUS-0012` and `CUS-0178` share normalized contact data and similar names. Expected: issue with explainable signals, merge rewires bookings, loser becomes tombstone, audit preserved.
+
+### S3 — Missing inspection before next booking
+
+Vehicle `MO-031` has a near-future booking and an unresolved operational attention item. Expected: dashboard links to its record.
+
+### S4 — Legacy booking overlap
+
+Vehicle `MO-016` has two imported overlapping reservations. Expected: visible quality issue; normal booking command would reject the same overlap.
+
+### S5 — Failed workflow
+
+One seeded outbox/workflow record is failed with a safe simulated connection error. Expected: dashboard and Automation page show it; Operations Manager can retry.
+
+### S6 — Grounded damage question
+
+Question: “What must I do when a vehicle returns with damage?” Expected: answer cites damage handling and return inspection procedures.
+
+## Demo reset
+
+Reset must:
+
+- require Operations Manager;
+- rebuild the deterministic dataset;
+- re-establish scenario references;
+- clear non-seed audit/workflow state;
+- complete safely and visibly;
+- be covered by a test.

docs/14-testing-and-acceptance.md

@@ -0,0 +1,74 @@
+# Testing and acceptance
+
+## Test layers
+
+### Unit/domain
+
+- vehicle status derivation;
+- return mileage handling;
+- duplicate scoring and merge rules;
+- booking overlap detection;
+- status conflict rules;
+- outbox retry schedule;
+- RAG answer-state mapping.
+
+### Database/integration
+
+- migrations from empty database;
+- constraints and transaction rollback;
+- concurrent return submissions;
+- idempotency replay;
+- customer merge atomicity;
+- outbox claim concurrency;
+- demo reset determinism.
+
+### API contract
+
+Validate OpenAPI and test authentication, role boundaries, filtering, error shape and service-token routes.
+
+### External adapters
+
+Use contract tests with fake HTTP servers for RAGcore, n8n and MCP Hub-facing APIs. Test timeout, unavailable, malformed response and success.
+
+### Playwright
+
+The five-minute demo must be automated:
+
+1. login as Operations Manager;
+2. verify dashboard metrics are loaded;
+3. open active demo booking;
+4. register odometer-regression return;
+5. verify issue and queued workflow;
+6. resolve/merge the duplicate customer scenario;
+7. ask the damage procedure question and inspect citations;
+8. inspect audit entries;
+9. verify responsive navigation at mobile width.
+
+## Clean-checkout acceptance
+
+From a clean checkout:
+
+1. copy `.env.example` to `.env`;
+2. run one documented bootstrap command;
+3. migrations and seed complete automatically or via one explicit command;
+4. web and API health become green;
+5. all automated tests pass;
+6. no secret is required for the demo provider;
+7. RAGcore unavailable state is clear and operational pages still work;
+8. n8n unavailable does not roll back a vehicle return;
+9. MCP provider endpoints are read-only and service-protected;
+10. no visible route contains dead actions or placeholder data.
+
+## Final evidence
+
+Create `artifacts/evidence/final-summary.md` containing:
+
+- commit/tag;
+- exact commands;
+- test counts;
+- screenshots of the seven main pages;
+- RAGcore success and unavailable evidence;
+- n8n success and retry evidence;
+- MCP tool sample calls;
+- known PoC limitations;
+- truthful portfolio wording.

docs/15-build-plan.md

@@ -0,0 +1,113 @@
+# Autonomous build plan
+
+Claude must complete all milestones in one continuous run where possible.
+
+## M0 — Reproducible foundation
+
+Read: `README.md`, `docs/03-architecture.md`, `docs/04-domain-model.md`, `docs/14-testing-and-acceptance.md`.
+
+Deliver:
+
+- stable backend/frontend project structure;
+- dependency lockfiles;
+- Compose health and clean-checkout bootstrap;
+- migrations framework;
+- CI-friendly commands;
+- initial lint/test gates.
+
+Validate: clean build, API/web health, baseline tests.
+
+## M1 — Operational core
+
+Read: `docs/02-user-stories.md`, `docs/05-api-contract.md`, `docs/06-ui-ux.md`, `docs/13-seed-and-demo-scenarios.md`.
+
+Deliver:
+
+- demo authentication and authorization;
+- deterministic seed import/reset;
+- dashboard;
+- vehicle and booking list/detail;
+- audit foundation.
+
+Validate: real persisted metrics, role tests, responsive smoke test.
+
+## M2 — Vehicle return vertical slice
+
+Read: `docs/08-return-workflow.md`, `contracts/events.schema.json`.
+
+Deliver:
+
+- complete transactional return command;
+- idempotency and concurrency handling;
+- status derivation;
+- outbox record;
+- result UI and audit.
+
+Validate: success, odometer regression, replay, concurrent submission and rollback tests.
+
+## M3 — Data Quality Workbench
+
+Read: `docs/07-data-quality.md`.
+
+Deliver:
+
+- five rules;
+- issue scan/lifecycle;
+- duplicate comparison and transactional merge;
+- issue UI and dashboard attention integration.
+
+Validate: seeded scenarios, idempotent scans, merge rewiring and audit.
+
+## M4 — n8n automation
+
+Read: `docs/11-n8n-integration.md`, `n8n/README.md`.
+
+Deliver:
+
+- dispatcher with retry/backoff;
+- working return workflow and callback;
+- Automation UI;
+- failed seeded run and manual retry.
+
+Validate: n8n online success, offline pending behaviour, duplicate delivery idempotency.
+
+## M5 — RAGcore knowledge integration
+
+Read: `docs/09-ragcore-integration.md`, `knowledge/manifest.json`.
+
+Deliver:
+
+- provider interface;
+- deterministic demo provider;
+- RAGcore adapter against the actual available contract;
+- Knowledge UI with source cards and honest states;
+- document sync support when feasible.
+
+Validate: grounded demo question, insufficient evidence, timeout/unavailable and source metadata tests.
+
+## M6 — ITWorx MCP Hub publication
+
+Read: `docs/10-mcp-hub-integration.md`, `contracts/mcp-tools.json`.
+
+Deliver:
+
+- protected provider APIs;
+- registration/configuration documentation or automation compatible with the Hub;
+- four validated read-only tools;
+- service audit events.
+
+Validate: tool schemas, authorization denial, sample Hub calls, no write or generic tool exposure.
+
+## M7 — Portfolio polish and final acceptance
+
+Read: `docs/06-ui-ux.md`, `docs/14-testing-and-acceptance.md`, `docs/16-portfolio-case-study.md`.
+
+Deliver:
+
+- remove rough edges and placeholders;
+- complete Playwright demo;
+- screenshots and architecture diagram;
+- concise deployment/runbook;
+- final evidence, version and case-study text.
+
+Validate: all acceptance criteria from a clean checkout.

docs/16-portfolio-case-study.md

@@ -0,0 +1,43 @@
+# Portfolio case-study template
+
+## Title
+
+MobilityOps — connected operations for vehicle rental and service teams
+
+## One-sentence summary
+
+A working synthetic-data PoC that unifies vehicle and booking operations, automates vehicle returns, surfaces data-quality problems and exposes grounded internal knowledge through reusable RAG and MCP platforms.
+
+## Problem
+
+Operational information was modelled as fragmented across booking, vehicle and procedure sources, causing manual checks, inconsistent states and slow access to instructions.
+
+## Approach
+
+- MobilityOps owns canonical operational data and business rules.
+- A transactional return workflow persists inspections, derives status and queues post-commit orchestration.
+- Explainable rules detect duplicates, mileage regressions, overlaps, missing fields and status conflicts.
+- RAGcore provides source-grounded procedure answers.
+- ITWorx MCP Hub exposes narrowly scoped read-only AI tools.
+- n8n orchestrates secondary processing without becoming the business-rule engine.
+
+## Demonstrable results
+
+Use only facts actually measured in the final build, such as:
+
+- 50 deterministic synthetic vehicles and 245 bookings;
+- five automated data-quality rule types;
+- one end-to-end return workflow;
+- ten versioned source procedures;
+- four read-only MCP tools;
+- tested degraded modes for RAGcore and n8n.
+
+Do not claim real customer adoption, production use or percentage time savings.
+
+## Stack
+
+React, TypeScript, FastAPI, PostgreSQL, n8n, RAGcore, ITWorx MCP Hub, Docker Compose and Playwright.
+
+## Demo disclosure
+
+All data and the represented company are fictitious. The software behaviour, integration contracts, audit trail and validation are implemented as a real proof of concept.

docs/17-runbook.md

@@ -0,0 +1,28 @@
+# PoC runbook
+
+## Bootstrap
+
+```bash
+cp .env.example .env
+docker compose up --build -d
+```
+
+Claude must replace this scaffold runbook with exact migration, seed, test and integration commands after implementation.
+
+## Required operational checks
+
+- API and web health;
+- database migration level;
+- pending/failed outbox count;
+- RAGcore provider state;
+- n8n connectivity;
+- MCP provider endpoint authorization;
+- deterministic demo reset.
+
+## Recovery expectations
+
+- database restart: application reconnects;
+- n8n outage: events remain pending and retryable;
+- RAGcore outage: knowledge shows unavailable, operations continue;
+- MCP Hub outage: web application unaffected;
+- failed demo experiment: Operations Manager reset restores the seed.

docs/deferred.md

@@ -0,0 +1,14 @@
+# Deferred ideas
+
+Not part of the PoC:
+
+- document OCR and intake;
+- pricing recommendations;
+- sales workflows;
+- maintenance work orders and parts;
+- calendar view;
+- notifications and email delivery;
+- write-capable MCP tools with approval;
+- true multi-tenancy;
+- production SSO;
+- advanced analytics.