test: target data-quality reference in page header

Full acceptance remains mandatory for product and test changes; workflow-only pull requests run checkout and verified-secret scanning without rebuilding every stack.

.dockerignore

@@ -0,0 +1,49 @@
+.git
+.gitea
+.github
+.gitignore
+.agents
+.codex
+.claude
+.dyad
+.idea
+.vscode
+.vs
+.venv
+__pycache__
+.pytest_cache
+.ruff_cache
+.mypy_cache
+node_modules
+frontend/node_modules
+frontend/dist
+dist
+artifacts
+coverage
+playwright-report
+test-results
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+*.p12
+*.pfx
+secrets
+credentials
+.state
+data
+backups
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+*.log
+*.tmp
+*.zip
+*.tar
+*.tar.gz
+.DS_Store
+Thumbs.db

.env.example

@@ -2,24 +2,82 @@ COMPOSE_PROJECT_NAME=mobilityops
 MOBILITYOPS_ENV=development
 MOBILITYOPS_DEMO_MODE=true
 MOBILITYOPS_PUBLIC_URL=http://localhost:1228
-MOBILITYOPS_API_URL=http://localhost:8128
+# Build-time API origin baked into the web bundle. Leave empty: the SPA calls its own
+# origin and nginx proxies /api to the API (required by the CSP connect-src 'self').
+VITE_API_BASE_URL=
 DATABASE_URL=postgresql+psycopg://mobilityops:mobilityops@db:5432/mobilityops
 POSTGRES_DB=mobilityops
 POSTGRES_USER=mobilityops
 POSTGRES_PASSWORD=mobilityops
+# Signs session cookies. With MOBILITYOPS_ENV=production the API refuses to start while
+# this (or MOBILITYOPS_CALLBACK_TOKEN) still holds its placeholder value.
 APP_SECRET=replace-in-production
 TZ=Europe/Brussels
-# Session cookie Secure flag. Keep false for LAN/plain-HTTP deployments (including the
+# Session cookie Secure flag. Development on localhost may use false; production startup
-# current Unraid review environment); set true only once MobilityOps is served over HTTPS,
+# requires both an HTTPS public URL and this value set to true.
-# otherwise browsers will silently drop the cookie and no one can log in.
 SESSION_COOKIE_SECURE=false
 
+# Optional OpenID Connect login. Public demo role buttons remain available when enabled.
+OIDC_ENABLED=false
+OIDC_PROVIDER_NAME=Organisatieaccount
+OIDC_ISSUER_URL=
+OIDC_CLIENT_ID=
+OIDC_CLIENT_SECRET=
+OIDC_REDIRECT_URI=
+OIDC_ALLOWED_EMAIL_DOMAINS=
+OIDC_AUTO_PROVISION=true
+OIDC_DEFAULT_ROLE=rental_employee
+
+# Observability: JSON logs are always enabled. Set a token only if /metrics is exposed
+# outside the private Compose network; Prometheus can send it as a bearer token.
+LOG_LEVEL=INFO
+# Required when the observability profile is enabled. Keep private and high entropy.
+METRICS_BEARER_TOKEN=replace-me-private-metrics-token
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=change-me-before-start
+# Alertmanager sends every firing/resolved alert and the continuous watchdog to this
+# owner-managed receiver. Production must route it to a channel that is actually watched.
+ALERTMANAGER_WEBHOOK_URL=https://n8n.itworx.tech/webhook/mobilityops-alerts
+
+# Verified scheduled PostgreSQL backups (Unraid override).
+BACKUP_INTERVAL_SECONDS=86400
+BACKUP_RETENTION_DAYS=30
+BACKUP_MINIMUM_COPIES=7
+# Restore the newest dump into a disposable database at least weekly. Backup health also
+# requires a successful drill within eight days.
+BACKUP_RESTORE_DRILL_INTERVAL_SECONDS=604800
+# Set both values to copy every verified backup to an independently mounted path.
+BACKUP_SECONDARY_DESTINATION=
+MOBILITYOPS_BACKUP_DIR=./backups/postgres
+MOBILITYOPS_BACKUP_SECONDARY_DIR=./backups/offsite
+# Optional real off-site copy through the official rclone OneDrive adapter. OAuth state
+# lives only in MOBILITYOPS_RCLONE_CONFIG_DIR and must never be committed.
+BACKUP_OFFSITE_INTERVAL_SECONDS=900
+RCLONE_ONEDRIVE_REMOTE=onedrive
+RCLONE_ONEDRIVE_PATH=FleetOps/backups
+MOBILITYOPS_RCLONE_CONFIG_DIR=./.secrets/rclone
+MOBILITYOPS_OFFSITE_VERIFY_DIR=./backups/offsite-verify
+
+# Privacy governance defaults.
+PRIVACY_MINIMUM_BOOKING_RETENTION_DAYS=30
+PRIVACY_AUDIT_RETENTION_DAYS=2555
+PRIVACY_AUDIT_EXPORT_MAX_ROWS=10000
+
 # Demo presentation (fictional org identity, badge/manifest, reset safety valve).
 # DEMO_ALLOW_RESET=false permanently disables POST /api/v1/demo/reset (403), independent
 # of role -- a safety valve for any environment where the dataset must not be rebuildable.
 DEMO_ORGANIZATION_NAME=Northstar Mobility
 DEMO_TIMEZONE=Europe/Brussels
 DEMO_ALLOW_RESET=true
+# Prevent public visitors from repeatedly rebuilding the shared dataset. Concurrent
+# resets are always rejected using both process and PostgreSQL advisory locks.
+DEMO_RESET_COOLDOWN_SECONDS=60
+
+# Operational mode: set MOBILITYOPS_DEMO_MODE=false and provide the first manager.
+# Keep these values in a secret store or an untracked production .env file.
+INITIAL_ADMIN_EMAIL=
+INITIAL_ADMIN_PASSWORD=
+INITIAL_ADMIN_DISPLAY_NAME=Operations Manager
 
 # n8n
 N8N_BASE_URL=http://n8n:5678
@@ -29,17 +87,33 @@ N8N_BASIC_AUTH_ACTIVE=true
 N8N_BASIC_AUTH_USER=admin
 N8N_BASIC_AUTH_PASSWORD=change-me
 MOBILITYOPS_CALLBACK_TOKEN=replace-me-n8n-callback-token
+# Sent as the X-Fleet-Ops-Trigger-Token header when Fleet Ops calls the n8n return-
+# processing webhook, so the webhook trigger can require Header Auth instead of being
+# publicly callable by anyone who discovers the URL. Must match the value stored in
+# n8n's "Fleet Ops Webhook Trigger Token" Header Auth credential.
+MOBILITYOPS_WEBHOOK_TRIGGER_TOKEN=replace-me-n8n-webhook-trigger-token
 
 # RAGcore integration
 KNOWLEDGE_PROVIDER=demo
 RAGCORE_BASE_URL=http://ragcore-api:8000
+# Optional existing Docker network used by hosted deployments to reach RAGcore through
+# its private service alias instead of exposing RAGcore on the LAN.
+RAGCORE_DOCKER_NETWORK=
 RAGCORE_TENANT=northstar-mobility-demo
 RAGCORE_WORKSPACE=mobilityops
 RAGCORE_COLLECTION=internal-procedures
 RAGCORE_API_TOKEN=
+# UUID of the RAGcore knowledge space procedures were synced into (see workflow 3).
+RAGCORE_SPACE_ID=
+# Skip the slower generation endpoint temporarily after a timeout/non-2xx response and
+# use the still-grounded extractive search fallback immediately.
+RAGCORE_ANSWERS_CIRCUIT_BREAKER_SECONDS=60
 
-# ITWorx MCP Hub integration
+# ITWorx MCP Hub integration. Registration itself is catalog-driven on the Hub's own
+# side (it reconciles its catalog into the gateway; Fleet Ops never pushes a
+# registration call) -- MCP_HUB_BASE_URL is only used here for an honest reachability
+# health check surfaced on the integration status page.
 MCP_HUB_REGISTRATION_ENABLED=false
 MCP_HUB_BASE_URL=http://itworx-mcp-hub:8000
 MCP_HUB_SERVICE_TOKEN=replace-me-mcp-hub-token
-MCP_PROVIDER_ID=mobilityops
+MCP_PROVIDER_ID=fleet-ops

.gitattributes

@@ -1,4 +1,14 @@
 * text=auto eol=lf
 *.sh text eol=lf
+*.ps1 text eol=crlf
 *.png binary
 *.jpg binary
+*.jpeg binary
+*.webp binary
+*.zip binary
+
+# Generated operational evidence is not part of a source release archive.
+/artifacts export-ignore
+/PROJECT_STATE.md export-ignore
+/MASTER_BUILD_PROMPT.md export-ignore
+/FILE_INDEX.md export-ignore

.gitea/workflows/browser-canary.yml

@@ -0,0 +1,44 @@
+name: MobilityOps browser canary
+
+on:
+  schedule:
+    - cron: "37 4 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: mobilityops-browser-canary
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  chromium:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install locked Chromium runtime
+        working-directory: frontend
+        run: |
+          npm ci --no-audit --no-fund
+          npx playwright install --with-deps chromium
+      - name: Run non-destructive production canary
+        working-directory: frontend
+        env:
+          MOBILITYOPS_PUBLIC_URL: https://fleetops.itworx.tech
+        run: npx playwright test --config=playwright.live.config.ts --project=chromium
+      - name: Upload failure evidence
+        if: failure()
+        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3; Gitea-compatible artifact protocol
+        with:
+          name: browser-canary-failure
+          path: |
+            frontend/playwright-live-report
+            frontend/test-results
+          if-no-files-found: ignore

.gitea/workflows/ci.yml

@@ -0,0 +1,114 @@
+name: MobilityOps acceptance
+
+on:
+  pull_request:
+
+concurrency:
+  group: mobilityops-ci-${{ gitea.repository }}-${{ gitea.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  acceptance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+      - name: Determine validation scope
+        id: scope
+        shell: bash
+        run: |
+          base_sha="${{ gitea.event.pull_request.base.sha }}"
+          if git diff --quiet "$base_sha...HEAD" -- . ':(exclude).gitea/workflows/**'; then
+            echo "full=false" >> "$GITEA_OUTPUT"
+            echo "Workflow-only change: the protected lightweight gate is sufficient."
+          else
+            echo "full=true" >> "$GITEA_OUTPUT"
+            echo "Product or test change: running the complete acceptance gate."
+          fi
+      - name: Secret scan
+        uses: trufflesecurity/trufflehog@b9dd330365132cd2d01dd5dc8a857a056a2544e1 # v3.79.0
+        with:
+          path: ./
+          extra_args: --only-verified
+      - name: Backend tests in isolated PostgreSQL stack
+        if: steps.scope.outputs.full == 'true'
+        run: sh scripts/run-isolated-tests.sh
+      - name: Backend static and contract checks
+        if: steps.scope.outputs.full == 'true'
+        run: |
+          docker compose -p mobilityops-ci -f compose.yaml -f compose.test.yaml run --build --rm api ruff check app tests
+          docker compose -p mobilityops-ci -f compose.yaml -f compose.test.yaml run --rm api mypy app
+          docker compose -p mobilityops-ci -f compose.yaml -f compose.test.yaml run --rm \
+            -v "$PWD:/repo:ro" api python /repo/scripts/check-contracts.py
+          python scripts/check-source-budgets.py
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        if: steps.scope.outputs.full == 'true'
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install frontend dependencies once
+        if: steps.scope.outputs.full == 'true'
+        working-directory: frontend
+        run: npm ci --no-audit --no-fund
+      - name: Frontend lint, build, budget and dependency audit
+        if: steps.scope.outputs.full == 'true'
+        working-directory: frontend
+        run: |
+          npm run lint
+          npm run build
+          npm run budget
+          npm audit --audit-level=high
+      - name: Start the demo stack
+        if: steps.scope.outputs.full == 'true'
+        run: |
+          cp .env.example .env
+          # Acceptance tests intentionally reset their isolated demo dataset per scenario.
+          printf '\nDEMO_RESET_COOLDOWN_SECONDS=0\n' >> .env
+          docker compose -p mobilityops-e2e up --build -d db api web
+          docker network connect mobilityops-e2e_mobilityops "$HOSTNAME"
+          for _attempt in $(seq 1 60); do
+            if curl -fsS http://web/health/ready >/dev/null 2>&1; then break; fi
+            sleep 2
+          done
+          curl -fsS http://web/health/ready
+          docker compose -p mobilityops-e2e exec -T api python -m app.cli seed --reset
+      - name: Install acceptance browsers
+        if: steps.scope.outputs.full == 'true'
+        working-directory: frontend
+        run: npx playwright install --with-deps chromium
+      - name: Run browser acceptance and live smoke suites
+        if: steps.scope.outputs.full == 'true'
+        working-directory: frontend
+        env:
+          MOBILITYOPS_PUBLIC_URL: http://web
+        run: |
+          # Pixel baselines are workstation/rendering specific; keep the PR gate functional.
+          npx playwright test --grep-invert "visual hierarchy"
+          npx playwright test --config=playwright.live.config.ts --project=chromium
+      - name: Run concurrent persisted-read smoke
+        if: steps.scope.outputs.full == 'true'
+        run: python scripts/run-readonly-load-smoke.py --base-url http://web
+      - name: Upload Playwright report
+        if: failure() && steps.scope.outputs.full == 'true'
+        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3; Gitea-compatible artifact protocol
+        with:
+          name: playwright-report
+          path: |
+            frontend/playwright-report
+            frontend/playwright-live-report
+          if-no-files-found: ignore
+      - name: Stack logs on failure
+        if: failure() && steps.scope.outputs.full == 'true'
+        run: docker compose -p mobilityops-e2e logs --tail=200 api web
+      - name: Remove CI stacks
+        if: always() && steps.scope.outputs.full == 'true'
+        run: |
+          docker network disconnect mobilityops-e2e_mobilityops "$HOSTNAME" 2>/dev/null || true
+          docker compose -p mobilityops-e2e down -v --remove-orphans
+          docker compose -p mobilityops-ci -f compose.yaml -f compose.test.yaml down -v --remove-orphans

.gitea/workflows/live-canary.yml

@@ -0,0 +1,31 @@
+name: MobilityOps live probe
+
+on:
+  schedule:
+    - cron: "7 * * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: mobilityops-live-probe
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  public-probe:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    steps:
+      - name: Verify HTTPS readiness and certificate horizon
+        run: |
+          curl --fail --silent --show-error --retry 3 https://fleetops.itworx.tech/health/ready
+          openssl s_client -servername fleetops.itworx.tech -connect fleetops.itworx.tech:443 </dev/null 2>/dev/null \
+            | openssl x509 -checkend 1209600 -noout
+      - name: Report successful external heartbeat
+        env:
+          HEARTBEAT_URL: ${{ secrets.LIVE_CANARY_HEARTBEAT_URL }}
+        run: |
+          if [ -n "$HEARTBEAT_URL" ]; then
+            curl --fail --silent --show-error --retry 3 "$HEARTBEAT_URL"
+          fi

.gitea/workflows/managed-validation.yml

@@ -0,0 +1,117 @@
+name: Managed validation
+
+on:
+  workflow_dispatch:
+    inputs:
+      profile:
+        description: Allowlisted validation profile
+        required: true
+        default: full
+        type: choice
+        options: [test, lint, typecheck, build, security, full]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: managed-validation-${{ gitea.repository }}-${{ gitea.ref }}
+  cancel-in-progress: true
+
+jobs:
+  full:
+    name: full
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Validate repository with a bounded profile
+        shell: bash
+        env:
+          REQUESTED_PROFILE: ${{ inputs.profile }}
+        run: |
+          set -euo pipefail
+          profile="${REQUESTED_PROFILE:-full}"
+          case "${profile}" in
+            test|lint|typecheck|build|security|full) ;;
+            *) echo "Profile is not allowlisted" >&2; exit 2 ;;
+          esac
+
+          git diff --check
+          if git grep -nE '^(<<<<<<< |=======$|>>>>>>> )' -- . ':!*.lock' ':!*.patch'; then
+            echo "Unresolved merge markers detected" >&2
+            exit 1
+          fi
+
+          if [[ -f pyproject.toml || -f requirements.txt ]]; then
+            # Compile only tracked Python sources. Running compileall after a
+            # Node install would otherwise traverse node_modules and turn a
+            # lightweight baseline into a large runner workload.
+            git ls-files -z '*.py' | xargs -0 -r python -m py_compile
+            if [[ -f uv.lock ]]; then
+              python -m venv "${RUNNER_TEMP}/managed-uv"
+              uv_python="${RUNNER_TEMP}/managed-uv/bin/python"
+              "${uv_python}" -m pip install --disable-pip-version-check uv==0.10.0
+              managed_uv="${RUNNER_TEMP}/managed-uv/bin/uv"
+              export UV_PROJECT_ENVIRONMENT="${RUNNER_TEMP}/managed-project-venv"
+              "${managed_uv}" sync --locked
+              export PATH="${UV_PROJECT_ENVIRONMENT}/bin:${PATH}"
+              if [[ "${profile}" == test || "${profile}" == full ]]; then
+                if "${managed_uv}" run python -c 'import pytest' 2>/dev/null; then
+                  "${managed_uv}" run python -m pytest
+                fi
+              fi
+              if [[ "${profile}" == lint || "${profile}" == full ]]; then
+                if "${managed_uv}" run python -c 'import ruff' 2>/dev/null; then
+                  "${managed_uv}" run python -m ruff check .
+                fi
+              fi
+            elif [[ -f requirements.txt ]]; then
+              python -m venv "${RUNNER_TEMP}/managed-python"
+              managed_python="${RUNNER_TEMP}/managed-python/bin/python"
+              "${managed_python}" -m pip install --disable-pip-version-check -r requirements.txt
+              export PATH="${RUNNER_TEMP}/managed-python/bin:${PATH}"
+              if [[ "${profile}" == test || "${profile}" == full ]]; then
+                if "${managed_python}" -c 'import pytest' 2>/dev/null; then
+                  "${managed_python}" -m pytest
+                fi
+              fi
+            fi
+          fi
+
+          # Prepare Python before invoking Node scripts. Polyglot repositories
+          # commonly delegate their test script to Python and need the managed
+          # virtual environment to be active first.
+          if [[ -f package.json ]]; then
+            corepack enable
+            if [[ -f pnpm-lock.yaml ]]; then
+              pnpm install --frozen-lockfile
+              [[ "${profile}" == test || "${profile}" == full ]] && pnpm --if-present test
+              [[ "${profile}" == lint || "${profile}" == full ]] && pnpm --if-present lint
+              [[ "${profile}" == typecheck || "${profile}" == full ]] && pnpm --if-present typecheck
+              [[ "${profile}" == build || "${profile}" == full ]] && pnpm --if-present build
+            elif [[ -f package-lock.json ]]; then
+              npm ci
+              [[ "${profile}" == test || "${profile}" == full ]] && npm run --if-present test
+              [[ "${profile}" == lint || "${profile}" == full ]] && npm run --if-present lint
+              if [[ "${profile}" == typecheck || "${profile}" == full ]]; then
+                npm run --if-present typecheck
+              fi
+              [[ "${profile}" == build || "${profile}" == full ]] && npm run --if-present build
+            fi
+          fi
+
+          if [[ -f go.mod ]]; then
+            if [[ "${profile}" == test || "${profile}" == build || "${profile}" == full ]]; then
+              go test ./...
+            fi
+          fi
+          if [[ -f Cargo.toml ]]; then
+            if [[ "${profile}" == test || "${profile}" == build || "${profile}" == full ]]; then
+              cargo test --locked
+            fi
+          fi
+          if compgen -G '*.sln' >/dev/null; then
+            if [[ "${profile}" == test || "${profile}" == build || "${profile}" == full ]]; then
+              dotnet test --configuration Release
+            fi
+          fi

.gitea/workflows/release.yml

@@ -0,0 +1,50 @@
+name: MobilityOps release evidence
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release-evidence:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - name: Build commit-labelled release images
+        run: |
+          docker build --target runtime --build-arg VCS_REF="$GITHUB_SHA" --tag mobilityops-api-release --file backend/Dockerfile .
+          docker build --build-arg VCS_REF="$GITHUB_SHA" --tag mobilityops-web-release frontend
+          docker build --build-arg VCS_REF="$GITHUB_SHA" --tag mobilityops-backup-tools-release --file deploy/unraid/Dockerfile.backup-tools .
+      - name: Scan all release images
+        run: |
+          for image in mobilityops-api-release mobilityops-web-release mobilityops-backup-tools-release; do
+            docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+              -v mobilityops-release-trivy:/root/.cache/ \
+              aquasec/trivy:0.74.0@sha256:62b1e65e8869bc4b4c6aa4fa2b21595256c7c2f6018a9d9ad61caf87187c1969 \
+              image --scanners vuln --severity HIGH,CRITICAL \
+              --ignore-unfixed --exit-code 1 "$image"
+          done
+      - name: Generate CycloneDX SBOMs with the pinned scanner image
+        run: |
+          for component in api web backup-tools; do
+            docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+              -v "$PWD:/work" -w /work \
+              aquasec/trivy:0.74.0@sha256:62b1e65e8869bc4b4c6aa4fa2b21595256c7c2f6018a9d9ad61caf87187c1969 \
+              image --format cyclonedx --output "mobilityops-${component}-sbom.cdx.json" \
+              "mobilityops-${component}-release"
+          done
+      - name: Record immutable image metadata
+        run: |
+          docker image inspect mobilityops-api-release > mobilityops-api-image.json
+          docker image inspect mobilityops-web-release > mobilityops-web-image.json
+          docker image inspect mobilityops-backup-tools-release > mobilityops-backup-tools-image.json
+          python scripts/generate-release-provenance.py
+          sha256sum mobilityops-*-sbom.cdx.json mobilityops-*-image.json release-provenance.json > SHA256SUMS
+      - name: Upload release evidence
+        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3; Gitea-compatible artifact protocol
+        with:
+          name: mobilityops-${{ github.ref_name }}-evidence
+          path: |
+            mobilityops-*-sbom.cdx.json
+            mobilityops-*-image.json
+            release-provenance.json
+            SHA256SUMS

.gitea/workflows/security.yml

@@ -0,0 +1,42 @@
+name: MobilityOps security
+
+on:
+  schedule:
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: mobilityops-security
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  images:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+      - name: Build production images once
+        run: |
+          docker build --target runtime --build-arg VCS_REF="$GITHUB_SHA" \
+            --tag mobilityops-api-ci --file backend/Dockerfile .
+          docker build --build-arg VCS_REF="$GITHUB_SHA" \
+            --tag mobilityops-web-ci frontend
+      - name: Scan production images for fixed HIGH and CRITICAL vulnerabilities
+        run: |
+          for image in mobilityops-api-ci mobilityops-web-ci; do
+            docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+              docker.io/aquasec/trivy@sha256:be1190afcb28352bfddc4ddeb71470835d16462af68d310f9f4bca710961a41e \
+              image --severity HIGH,CRITICAL --exit-code 1 --ignore-unfixed --no-progress "$image"
+          done
+      - name: Scan repository secrets and misconfiguration
+        uses: docker://docker.io/aquasec/trivy@sha256:be1190afcb28352bfddc4ddeb71470835d16462af68d310f9f4bca710961a41e
+        with:
+          args: fs --scanners misconfig,secret --exit-code 1 --no-progress .
+      - name: Remove temporary image tags
+        if: always()
+        run: docker image rm mobilityops-api-ci mobilityops-web-ci || true

.gitea/workflows/unraid-deploy.yml

@@ -0,0 +1,31 @@
+name: Unraid autoredeploy
+
+on:
+  push:
+    branches: [master]
+    paths-ignore:
+      - ".gitea/**"
+      - "docs/**"
+      - "**/*.md"
+  workflow_dispatch:
+
+concurrency:
+  group: unraid-production-mobilityops
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy mobilityops
+    runs-on: unraid-deploy
+    timeout-minutes: 180
+    steps:
+      - name: Deploy exact Gitea revision
+        run: |
+          set -euo pipefail
+          docker exec gitea-deploy-control \
+            /opt/gitea-deploy/deploy.py deploy \
+            "$GITHUB_REPOSITORY" "$GITHUB_SHA"
+

.gitignore

@@ -1,16 +1,66 @@
+# Secrets and local configuration
 .env
-.venv/
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+credentials/
+
+# Python
 __pycache__/
+*.py[cod]
 .pytest_cache/
-.mypy_cache/
 .ruff_cache/
+.mypy_cache/
+.venv/
+.coverage
+htmlcov/
+*.egg-info/
+
+# Frontend and test output
 node_modules/
-dist/
+frontend/node_modules/
+frontend/dist/
 coverage/
 playwright-report/
 test-results/
-*.pyc
+*.tsbuildinfo
-.DS_Store
+
+# Runtime data and local infrastructure state
+.state/
+data/
+backups/local/
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+*.log
+*.tmp
+
+# Generated release/design evidence. Maintained documentation belongs in docs/.
+artifacts/**/final-summary.md
+artifacts/deployment/
+artifacts/design-validation/current/
+artifacts/**/screenshots/generated/
+
+# Local AI/editor state
+.codex/
+.claude/
+.agents/
+.dyad/
 .idea/
 .vscode/
-*.tsbuildinfo
+.vs/
+.DS_Store
+Thumbs.db
+
+# Archives and local release bundles
+*.zip
+*.tar
+*.tar.gz
+*.tgz

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes are documented here. The project follows semantic release tags for
+the deployable PoC; detailed validation evidence remains in `PROJECT_STATE.md`.
+
+## [Unreleased]
+
+- Added contract-drift, accessibility, Firefox smoke and frontend asset-budget gates.
+- Added immutable commit-labelled deployment with automatic application rollback.
+- Added real PostgreSQL restore drills and routed Alertmanager notifications.
+- Added RAGcore generation circuit breaking and retrieval telemetry.
+- Added scheduled dependency maintenance, dual-image vulnerability scans and release SBOMs.
+
+## [1.0.0-poc] - 2026-08-21
+
+- Completed the locked Fleet Ops proof of concept: operational core, transactional returns,
+  data quality, n8n orchestration, grounded RAGcore knowledge, read-only MCP integration,
+  privacy governance, observability, backup/recovery and full browser acceptance.

CLAUDE.md

@@ -1,61 +0,0 @@
-# Binding instructions for Claude
-
-## Operating mode
-
-Work autonomously. Do not ask the user product, architecture, naming, UI, scope or implementation questions already answered in this repository. Record a reasonable assumption in an ADR only when a genuine gap blocks implementation.
-
-Use normal or medium reasoning for routine work. Reserve high reasoning for an actual cross-service design conflict or a persistent failure after evidence-driven debugging.
-
-Continue from milestone to milestone until every acceptance criterion is satisfied. Do not stop merely because one milestone is complete.
-
-## Token and tool efficiency
-
-1. Read `START_HERE.md`, this file, `PROJECT_STATE.md` and `docs/15-build-plan.md` first.
-2. Read only the milestone-specific documents named in the build plan.
-3. Do not repeatedly reread all documentation.
-4. Keep explanations terse; spend effort on implementation and validation.
-5. Update `PROJECT_STATE.md` after each milestone with decisions, commands, evidence and the exact next action.
-6. Prefer focused file inspection and targeted tests over broad repository scans.
-7. Do not generate large speculative documents after implementation starts.
-
-## Scope discipline
-
-- Build the locked PoC only.
-- Do not add accounting, payments, public reservations, a generic CRM, inventory, HR, a second RAG stack, a separate MCP server or autonomous write actions.
-- Do not modify the RAGcore or ITWorx MCP Hub repositories. Integrate only through documented contracts and configurable adapters.
-- Keep critical business rules in MobilityOps code, not in n8n or prompts.
-- No direct MCP Hub or RAGcore access to the MobilityOps database.
-
-## Product quality
-
-- No dead buttons, empty routes, unexplained placeholders or hardcoded dashboard metrics.
-- Every visible number must derive from persisted data.
-- All important state changes must be audited.
-- AI must never invent an answer when RAGcore is unavailable or returns insufficient evidence.
-- Vehicle returns must commit locally even when n8n is unavailable; orchestration becomes pending and retryable.
-- External dependencies require timeouts, bounded retries, health state and graceful degradation.
-- Demo data must be clearly labelled synthetic.
-
-## Engineering rules
-
-- Backend: Python, FastAPI, SQLAlchemy 2, Alembic, PostgreSQL.
-- Frontend: React, TypeScript, Vite, accessible responsive UI.
-- Validation: Pydantic at API boundaries and database constraints for invariants.
-- Use UUID primary keys internally and stable human-readable public references.
-- Store UTC timestamps; render Europe/Brussels in the UI.
-- API paths start with `/api/v1`.
-- Use an outbox record for reliable post-commit n8n delivery.
-- Tests must cover domain rules, API contracts and the five-minute Playwright demo.
-- Generate and commit dependency lockfiles.
-
-## Git workflow
-
-Create one coherent commit per milestone after its validation passes. Suggested message format:
-
-`M1: implement operational core`
-
-Never rewrite already accepted milestone history unless necessary to fix a regression.
-
-## Definition of done
-
-The project is done only when `docs/14-testing-and-acceptance.md` passes from a clean checkout and `PROJECT_STATE.md` contains the final evidence summary.

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+MobilityOps contributions must preserve fleet-data privacy, deterministic demo behaviour and the fail-closed integration boundaries documented in `SECURITY.md`.
+
+- use synthetic vehicles, customers, bookings, returns, telematics events and identity claims in tests and screenshots;
+- never commit production databases, exports, operator inventories, private service URLs, tokens, backups or generated browser evidence;
+- keep external integrations configurable through environment variables or explicit deployment configuration;
+- document new personal-data fields, retention, authorization, audit and deletion/export behaviour;
+- add negative tests for authentication, authorization, duplicate handling, webhook validation, path containment and stale/unavailable providers;
+- review dependencies, images and browser assets for provenance and redistribution rights.
+
+Run the relevant backend, frontend, migration, integration, Compose and managed-validation gates before review. Security-sensitive findings belong through the private process in `SECURITY.md`.

FILE_INDEX.md

@@ -1,72 +0,0 @@
-# File index
-
-- `.env.example`
-- `.gitignore`
-- `CLAUDE.md`
-- `MASTER_BUILD_PROMPT.md`
-- `Makefile`
-- `PROJECT_STATE.md`
-- `README.md`
-- `START_HERE.md`
-- `backend/Dockerfile`
-- `backend/app/__init__.py`
-- `backend/app/core/__init__.py`
-- `backend/app/core/config.py`
-- `backend/app/main.py`
-- `backend/pyproject.toml`
-- `backend/tests/test_health.py`
-- `compose.yaml`
-- `contracts/events.schema.json`
-- `contracts/mcp-tools.json`
-- `contracts/openapi.yaml`
-- `contracts/ragcore-contract-assumptions.md`
-- `docs/00-product-brief.md`
-- `docs/01-scope-and-non-goals.md`
-- `docs/02-user-stories.md`
-- `docs/03-architecture.md`
-- `docs/04-domain-model.md`
-- `docs/05-api-contract.md`
-- `docs/06-ui-ux.md`
-- `docs/07-data-quality.md`
-- `docs/08-return-workflow.md`
-- `docs/09-ragcore-integration.md`
-- `docs/10-mcp-hub-integration.md`
-- `docs/11-n8n-integration.md`
-- `docs/12-security-and-audit.md`
-- `docs/13-seed-and-demo-scenarios.md`
-- `docs/14-testing-and-acceptance.md`
-- `docs/15-build-plan.md`
-- `docs/16-portfolio-case-study.md`
-- `docs/17-runbook.md`
-- `docs/deferred.md`
-- `frontend/Dockerfile`
-- `frontend/index.html`
-- `frontend/nginx.conf`
-- `frontend/package.json`
-- `frontend/src/App.tsx`
-- `frontend/src/main.tsx`
-- `frontend/src/styles.css`
-- `frontend/tsconfig.json`
-- `frontend/vite.config.ts`
-- `knowledge/manifest.json`
-- `knowledge/procedures/01-vehicle-checkout.md`
-- `knowledge/procedures/02-vehicle-return.md`
-- `knowledge/procedures/03-damage-handling.md`
-- `knowledge/procedures/04-odometer-anomalies.md`
-- `knowledge/procedures/05-cleaning-checklist.md`
-- `knowledge/procedures/06-maintenance-escalation.md`
-- `knowledge/procedures/07-customer-documents.md`
-- `knowledge/procedures/08-privacy.md`
-- `knowledge/procedures/09-booking-conflicts.md`
-- `knowledge/procedures/10-roles-and-escalation.md`
-- `n8n/README.md`
-- `n8n/mobilityops-return-processing.json`
-- `seed/README.md`
-- `seed/bookings.csv`
-- `seed/customers.csv`
-- `seed/data_quality_issues.csv`
-- `seed/generate_seed.py`
-- `seed/inspections.csv`
-- `seed/maintenance.csv`
-- `seed/vehicles.csv`
-- `seed/workflow_runs.csv`

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jens Caers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MASTER_BUILD_PROMPT.md

@@ -1,21 +0,0 @@
-# Paste this once into Claude Code
-
-Build MobilityOps autonomously from this repository.
-
-First read `START_HERE.md`, `CLAUDE.md`, `PROJECT_STATE.md` and `docs/15-build-plan.md`. Treat the repository specifications and contracts as binding. Do not ask me questions that the files already answer, do not broaden the PoC, and do not stop after a milestone.
-
-Implement the milestones in order. For each milestone:
-
-1. read only the documents listed for that milestone;
-2. implement the smallest complete solution;
-3. run the specified validation plus relevant regression tests;
-4. fix failures using evidence rather than guesses;
-5. update `PROJECT_STATE.md` with concise evidence and the exact next step;
-6. commit the completed milestone;
-7. continue immediately.
-
-MobilityOps owns operational data and business rules. RAGcore owns retrieval and grounded answers. ITWorx MCP Hub owns MCP publication and policy. n8n only orchestrates post-commit workflows. Use configurable adapters and working degraded modes so the core demo remains usable when any external service is absent.
-
-The finished PoC must be reproducible from a clean checkout, have no dead UI, use deterministic synthetic data, support the documented five-minute demo, and satisfy every criterion in `docs/14-testing-and-acceptance.md`.
-
-Keep chat output brief. Spend the available context on code, tests, validation and final evidence. Begin now and continue until the repository is complete.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: up down logs test lint seed reset n8n-setup n8n-setup-scan demo e2e
+.PHONY: up down logs test lint contracts seed reset n8n-setup n8n-setup-scan demo e2e live-smoke
 
 up:
 	docker compose up --build -d
@@ -10,11 +10,17 @@ logs:
 	docker compose logs -f --tail=200
 
 test:
-	docker compose run --rm api pytest
+	sh scripts/run-isolated-tests.sh
 
 lint:
-	docker compose run --rm api ruff check .
+	docker compose -f compose.yaml -f compose.test.yaml run --build --rm api ruff check app tests
-	docker compose run --rm api mypy app
+	docker compose -f compose.yaml -f compose.test.yaml run --rm api mypy app
+	cd frontend && npm run lint
+
+contracts:
+	docker compose -f compose.yaml -f compose.test.yaml run --build --rm \
+		-v "$(CURDIR):/repo:ro" api python /repo/scripts/check-contracts.py
+	python scripts/check-source-budgets.py
 
 seed:
 	docker compose exec api python -m app.cli seed --reset
@@ -26,16 +32,19 @@ reset:
 # One-time per environment: imports and activates the n8n return-processing workflow.
 # The n8n owner account itself cannot be scripted safely and must be created once at
 # http://localhost:5678/setup (any email/password, no verification required) before
-# this target's activation takes effect. See docs/17-runbook.md.
+# this target's activation takes effect. The workflow also needs the "Fleet Ops Webhook
+# Trigger Token" and "Fleet Ops Service Token" Header Auth credentials created manually in
+# the n8n UI before it will actually process a return -- see docs/17-runbook.md.
 n8n-setup:
-	docker compose exec n8n n8n import:workflow --input=//imports/mobilityops-return-processing.json
+	docker compose exec n8n n8n import:workflow --input=//imports/workflows/fleet-ops-vehicle-return.json
 	docker compose exec n8n n8n publish:workflow --id=mobilityops-return-processing
 	docker compose restart n8n
 
 # One-time per environment: imports and activates the scheduled quality-scan workflow.
-# Same owner-account precondition as n8n-setup above.
+# Same owner-account and credential preconditions as n8n-setup above (this workflow only
+# needs "Fleet Ops Service Token").
 n8n-setup-scan:
-	docker compose exec n8n n8n import:workflow --input=//imports/mobilityops-scheduled-quality-scan.json
+	docker compose exec n8n n8n import:workflow --input=//imports/workflows/fleet-ops-data-quality-scan.json
 	docker compose exec n8n n8n publish:workflow --id=mobilityops-scheduled-quality-scan
 	docker compose restart n8n
 
@@ -45,3 +54,6 @@ demo: up
 
 e2e:
 	cd frontend && npx playwright test
+
+live-smoke:
+	cd frontend && npx playwright test --config=playwright.live.config.ts

PROJECT_STATE.md

@@ -1,820 +0,0 @@
-# Project state
-
-## Publication and Unraid deployment (2026-08-02)
-
-- Unraid deployment is live at `http://192.168.10.150:1236` from
-  `/mnt/user/appdata/mobilityops`, Compose project `mobilityops`.
-- Deployment config commits: `07ab7a3`, `847cd05`, `e1a1c67`, `1e13943`. The accepted
-  baseline `4bf9afbeff44088864e0844769d4dd0e4089d85b` remains intact.
-- MobilityOps PostgreSQL, API and web services are healthy. Only web port 1236 is exposed
-  by the MobilityOps Compose project; API and PostgreSQL remain internal. Automation uses
-  the server's existing shared n8n at `http://192.168.10.150:5678`; no second MobilityOps
-  n8n container is running.
-- Migrations are at `e7b08389f47f (head)` and deterministic seed counts match final
-  acceptance. A Chrome smoke test covered every requested page and a real return; its n8n
-  event succeeded on attempt 1. Browser console and recent service log scans were clean.
-- RAGcore is disabled in favor of the honest local demo provider. MCP Hub registration is
-  disabled. The MobilityOps workflow is published in the existing n8n and live-verified.
-- Local post-change gates: 66 backend tests, Ruff, mypy (44 files), and frontend production
-  build all pass. Evidence is in `artifacts/deployment/unraid-summary.md`.
-- Published to the private Gitea repository
-  `https://gitea.itworx.tech/Jens/MobilityOps`. `master` is the default branch; the full
-  commit history and baseline commit are present; zero tags exist; remote hygiene is
-  clean. `origin` uses the SSH clone URL supplied by Gitea.
-- Exact next action: none — repository publication and Unraid deployment are complete.
-
-## Current milestone
-
-M7 — complete. All milestones (M0–M7) done, plus a full post-M7 final-acceptance audit (see below). See `artifacts/final-acceptance/summary.md` for the definitive acceptance evidence (supersedes `artifacts/evidence/final-summary.md`, which is kept as historical M7 evidence).
-
-## Locked decisions
-
-- Product name: MobilityOps.
-- Fictitious tenant: Northstar Mobility Demo.
-- PoC only; all operational and knowledge data are synthetic.
-- Core stack and boundaries are defined in `CLAUDE.md` and `docs/03-architecture.md`.
-- RAGcore and ITWorx MCP Hub are external central services.
-- n8n receives post-commit events through an outbox dispatcher.
-- SQLAlchemy 2 declarative models cover the full domain model (`backend/app/models/`); enums are plain `String` columns validated at the Pydantic/service layer, not native PG enums (simpler migrations).
-- `backend/requirements.lock` is compiled inside a `python:3.12-slim` container (matches the Dockerfile base image) via `pip-compile --extra dev`; regenerate the same way if `pyproject.toml` changes.
-- Frontend dependencies pinned (no more `"latest"`); `package-lock.json` committed; Docker build uses `npm ci`.
-- Demo auth is a lightweight HMAC-signed cookie (`app/core/security.py`), not a real password/JWT flow — matches "Demo role buttons create an authenticated session; they do not bypass authorization middleware." Two fixed demo users (`USR-OPS` operations_manager, `USR-EMP` rental_employee) are created by the seed loader, not from a CSV (no `users.csv` in `seed/`).
-- Seed loader (`backend/app/seed_loader.py`) only supports `seed --reset` (always rebuilds); there is no incremental/idempotent-without-reset mode, since the acceptance criteria only require deterministic reset, not partial import.
-- `DataQualityIssue.entity_ref`/`related_ref` from the CSVs are resolved to `entity_type`/`entity_id` (UUID) at load time per the domain model; the original human-readable refs are kept in `evidence_json` (`entity_ref`, `related_refs`) since the API and UI need them and re-resolving UUID→public_ref on every read would be wasteful.
-- `backend/app/core/config.py` added `app_secret`, `session_cookie_name`, `session_ttl_seconds`, `seed_dir` (`/app/seed` in-container), `cors_allow_origins` (comma-separated string, not a list — simpler with pydantic-settings env parsing), `demo_today` (drives the dashboard's "Today" section against the deterministic anchor date, default `2026-08-01`).
-- `compose.yaml` api build context changed from `./backend` to repo root with `dockerfile: backend/Dockerfile`, so the image can `COPY seed ./seed` (seed CSVs are outside `backend/`).
-- Frontend: added `react-router-dom@7.18.2` (bumped from 6.x to clear two real advisories — open redirect + arbitrary constructor injection in v6). One residual `npm audit` finding (RSC-mode CSRF, GHSA-qwww-vcr4-c8h2) does not apply — this SPA never uses React Router's RSC/SSR mode.
-- Nav/pages built so far: Dashboard, Vehicles (list+detail with tabs), Bookings (list+detail), Audit. Data Quality, Knowledge and Automation nav items are intentionally omitted until M3/M5/M4 build the pages behind them — CLAUDE.md forbids dead routes/placeholders.
-- Return workflow (`app/services/returns.py`): the spec's "validate submitted reading against booking start reading" step was dropped as a hard rejection. For the seeded S1 scenario, a booking's `start_odometer_km` can already equal the vehicle's canonical odometer, so any regression-testing value would also be below the booking start, making a hard floor there indistinguishable from — and in conflict with — the documented soft-regression path. Only one odometer check exists now: submitted vs. the vehicle's *canonical* odometer (`vehicle.odometer_km`), matching the domain-model invariant verbatim ("a return with a lower submitted reading is recorded as an inspection and issue, while canonical odometer remains unchanged").
-- Idempotency: new `idempotency_records` table (migration `e7b08389f47f`), unique on `idempotency_key`, keyed to `booking_id`. Same key + same booking replays the stored response; same key + different booking → 409 `IDEMPOTENCY_KEY_REUSED`; different key on an already-returned booking → 409 `INVALID_BOOKING_STATE`. Concurrency is enforced by `SELECT ... FOR UPDATE` on the booking row (re-checked for the idempotency record immediately after acquiring the lock, as a safety net for two simultaneous identical-key requests racing the pre-lock check).
-- `seed_loader.clear_all()` must delete `idempotency_records` before `bookings` (FK) — easy to forget when adding new booking-referencing tables; the ordering list at the top of `seed_loader.py` is the single place to update.
-- Inspection `public_ref` is assigned as `INSP-{count+1:04d}` from a live count query (not gap-safe, fine for a PoC single-writer demo, would need a sequence for real concurrency-safe numbering).
-- Found and fixed during browser verification (not caught by pytest, since it's a UI-only defect): `ReturnForm` originally held its own `result` state and was conditionally rendered only when `booking.status === "active"`; once the return succeeded the booking flipped to `returned` and React unmounted the form before the user ever saw the result panel. Fixed by lifting the result into `BookingDetail` (`ReturnResultPanel` is now a sibling, not nested in `ReturnForm`). Also found: `OutboxEvent.event_id`'s Python-side `default=uuid.uuid4` on the mapped_column only applies at flush/commit time, so reading `event.event_id` before `db.commit()` returned `None` (rendered as the literal string "None" in the result panel); fixed by assigning `event_id=uuid.uuid4()` explicitly at construction. Lesson: SQLAlchemy column `default=` callables are not available on the in-memory Python object until flush — never rely on the generated value for a same-transaction response body without an explicit `db.flush()` or an explicit Python-side assignment.
-- Operational note for this environment: `docker compose run --rm api ...` (used for tests/lint) only starts a throwaway one-off container — it does **not** update the long-running `api`/`web` service containers. After any code change meant to be verified live (browser, curl), `docker compose up -d --build <service>` is required, not just `docker compose build`.
-
-## Completed evidence
-
-### M0 — Reproducible foundation
-- Added `backend/app/core/db.py` (engine/session), `backend/app/models/*` (User, Customer, Vehicle, Booking, Inspection, MaintenanceRecord, DataQualityIssue, OutboxEvent, AuditEvent), Alembic config (`backend/alembic.ini`, `backend/alembic/env.py`) and initial migration `backend/alembic/versions/c9498525abb5_initial_schema.py`.
-- Commands run and verified from this checkout:
-  - `docker compose build api` — OK
-  - `docker compose run --rm api alembic upgrade head` — applied cleanly to empty DB, created 9 tables + `alembic_version`.
-  - `docker compose run --rm api pytest -q` — 1 passed.
-  - `docker compose run --rm api ruff check .` — All checks passed (added `extend-exclude = ["alembic/versions"]` to `backend/pyproject.toml` for autogenerated migration line length).
-  - `docker compose up -d --build` — all 4 services healthy: `curl http://localhost:8128/health` → `{"status":"ok",...}`; `curl -o /dev/null -w "%{http_code}" http://localhost:1228/` → 200; `curl http://localhost:5678/healthz` → 200.
-- Fixed a real scaffold bug: `frontend/src/App.tsx` used `import.meta.env` without a `vite/client` types reference, which broke `npm run build` in Docker (works fine under plain `vite dev` because Vite injects the global at dev-time but `tsc -b` still type-checks it). Added `frontend/src/vite-env.d.ts`.
-- `make` is not installed in this Windows/git-bash shell — validated the underlying `docker compose ...` commands directly instead (Makefile targets are thin wrappers around them and are correct as written for a Linux/CI shell or WSL).
-- Known accepted gap: `npm audit` reports 1 moderate/1 high transitive `esbuild` advisory (dev-server-only, fixed only by a Vite 8 major bump); left as-is for the PoC, noted here rather than silently upgrading a major version.
-
-### M1 — Operational core
-- Backend additions: `app/core/security.py` (HMAC-signed session cookies), `app/api/deps.py` (`get_current_user`, `require_operations_manager`), `app/core/errors.py` (`AppError` + the documented `{"error": {...}}` shape wired as a FastAPI exception handler for both `AppError` and `HTTPException`), `app/seed_loader.py`, `app/cli.py` (`python -m app.cli seed --reset`), `app/services/audit.py`, `app/schemas.py`, routers under `app/api/routers/` (`demo`, `dashboard`, `vehicles`, `bookings`, `audit`).
-- Frontend additions: React Router-based app shell (`src/App.tsx`, `src/components/Layout.tsx`, `src/components/RequireAuth.tsx`), `AuthContext`, typed `api` client (`src/api/client.ts`, `src/api/types.ts`), pages `Login`, `Dashboard`, `Vehicles`/`VehicleDetail`, `Bookings`/`BookingDetail`, `Audit`. Full responsive stylesheet (`src/styles.css`) covering nav collapse and table→card layout under 700px, visible focus states, no hover-only actions.
-- Commands run and verified from this checkout (container rebuilt each time to pick up code changes):
-  - `docker compose run --rm api pytest -q` — **19 passed** (new: `test_seed.py`, `test_auth.py`, `test_dashboard.py`, `test_vehicles.py`, `test_bookings.py`, `test_audit.py`; tests seed the real Postgres via `reset_and_seed` in a session fixture, then exercise the FastAPI app through `TestClient`, not mocks).
-  - `docker compose run --rm api ruff check .` — All checks passed (added `ignore = ["B008"]` — FastAPI's `Depends()`-as-default is idiomatic, not a real bug).
-  - `npm run build` (local, Node 24) — clean `tsc -b && vite build`.
-  - `docker compose up -d --build` then `docker compose exec api python -m app.cli seed --reset` — counts: `users:2 customers:180 vehicles:50 bookings:246 inspections:75 maintenance:40 data_quality_issues:15 workflow_runs:20`.
-  - `curl` end-to-end: `POST /api/v1/demo/login` sets cookie and returns the user; unauthenticated `GET /api/v1/dashboard` → 401 with the documented error shape; authenticated dashboard/vehicle-detail return real seeded data (verified metrics `available:21 rented:11 cleaning:6 maintenance:5 blocked:7`, matching the 50 seeded vehicles).
-  - Browser smoke test (Chrome via MCP) at desktop width: login page → Operations Manager login → Dashboard (metrics + attention items + today + recent automation all populated) → Vehicle detail `MO-016` (tabs render, "Needs attention" badge correct — it's `DQ-DEMO-OVERLAP`/`DQ-DEMO-STATUS`) → Booking detail `BK-DEMO-RETURN` (matches S1 scenario: vehicle `MO-024`, status `active`, start odometer `53610`). Responsive CSS (`@media max-width:700px`) was written and code-reviewed but the automated resize during this session didn't visibly reflect in the captured screenshot (likely a screenshot-timing quirk of the browser tool, not necessarily a real bug) — **treat the ≤360px layout as visually unverified** and re-check with a real device/DevTools emulation before final acceptance (M7).
-- Known accepted gap carried over from M0: `npm audit` residual `esbuild`/Vite-8 dev-server-only advisory.
-
-### M2 — Vehicle return vertical slice
-- Backend additions: `app/models/idempotency.py` (`IdempotencyRecord`), migration `e7b08389f47f_idempotency_records`, `app/services/returns.py` (`register_vehicle_return` — full transaction: row locks, idempotency replay, inspection, canonical-odometer update or regression issue, vehicle status derivation, two audit events, `vehicle.returned.v1` outbox event matching `contracts/events.schema.json`, next-booking-risk lookup), `POST /api/v1/bookings/{public_ref}/return` wired in `app/api/routers/bookings.py` with required `Idempotency-Key` header.
-- Frontend additions: `components/ReturnForm.tsx` (form + `ReturnResultPanel`), wired into `pages/BookingDetail.tsx` (shown only when `booking.status === "active"`; result persists via lifted state after the booking flips to `returned`).
-- Commands run and verified from this checkout:
-  - `docker compose run --rm api pytest -q` — **26 passed**, including `tests/test_return.py` (success/canonical-update, S1 regression scenario by name, damage→blocked, idempotent replay, reject-already-returned, missing-header validation, and a real multi-threaded concurrent-submission test against Postgres asserting exactly 1×201 + 2×409).
-  - `docker compose run --rm api ruff check .` — All checks passed.
-  - `npm run build` — clean.
-  - `docker compose up -d --build` (all services) then `docker compose exec api python -m app.cli seed --reset`, then a full browser run of the S1 demo scenario against `BK-DEMO-RETURN`/`MO-024`: submitted 53000 km (below canonical 54820) → result panel showed `INSP-0076`, `resulting_vehicle_status: maintenance` (correctly derived, since canonical 54820 ≥ `next_service_km` 40000), `DQ-RET-0076` created, automation event queued with a real UUID, "no upcoming booking" risk; vehicle detail page confirmed odometer unchanged at 54,820 km and a "Needs attention" badge.
-  - Both real defects listed above (form disappearing before showing its result; `event_id` reading as `None`) were **found via the browser run, not by pytest** — the test suite asserted on API response shape/values, not on what the UI actually rendered after a status transition. Worth remembering for M3+: UI state-after-mutation bugs need a browser check, not just API tests.
-
-### M3 — Data Quality Workbench
-- `app/services/data_quality.py`: `run_scan()` implements all five rules and is called automatically at the end of `seed_loader.reset_and_seed()` (after `db.commit()` of the base seed), plus exposed as `POST /api/v1/data-quality/scan` (Operations Manager only). Idempotency is simplified from the doc's literal `(rule_type, entity_type, entity_id, evidence fingerprint)` to just `(rule_type, entity_type, entity_id)` while an issue is open — see rationale below.
-- Router `app/api/routers/data_quality.py`: `GET /issues` (filters status/rule_type/severity), `GET /issues/{ref}` (adds `entity_snapshot`/`related_snapshots` for the UI), `POST /issues/{ref}/defer`, `/reject`, `/merge-customers` (Operations Manager only — enforced via `require_operations_manager`), `POST /scan`.
-- **Real bug found and fixed during this milestone, before any browser check**: the first cut of DQ-03 (odometer regression) compared every historical *returned* booking's `end_odometer_km` against the vehicle's *current* `odometer_km`. Since the seed generator assigns `vehicle.odometer_km` independently of booking history (see `seed/generate_seed.py`), this is true for nearly every historical booking by construction (odometer is monotonically increasing over time, so all-but-the-latest reading is "below current") — it produced 51 false-positive issues out of 50 vehicles on first run. Fixed twice: first attempt (compare only the single most-recent booking against canonical) still produced the same problem because canonical itself is disconnected from booking history in this dataset; the working fix compares each vehicle's *own returned-booking sequence* against itself (each booking's end reading vs. the immediately preceding one, chronologically) — a self-consistency check that doesn't depend on the unrelated `vehicle.odometer_km` field at all. Final deterministic seed+scan totals: 15 CSV-seeded + 11 scan-discovered = **26** open/resolved `data_quality_issues` (breakdown: 14 vehicle_status_conflict, 5 missing_required_field, 3 possible_duplicate_customer, 3 odometer_regression, 1 booking_overlap). `tests/test_seed.py`'s exact-count assertion was updated from 15 to 26 accordingly — if the scan logic changes again, update that count.
-- Idempotency simplification rationale: the doc's fingerprint-based key would make the scan blind to issues it structurally can't compute a matching fingerprint for against the CSV-seeded rows (which don't carry a fingerprint field), producing duplicate issues for the same real-world problem (e.g. a second `MO-016` overlap issue next to the seeded `DQ-DEMO-OVERLAP`). Using `(rule_type, entity_type, entity_id)` alone while open is a stricter, safe simplification: it can never falsely suppress an issue for a *different* entity, and per-entity there's realistically only one meaningful open issue of a given rule type at a time for this PoC's scope.
-- Merge UI intentionally does **not** use `window.confirm()` — a native dialog blocks further automation/testing and isn't screen-reader-distinguishable from page content the same way a rendered `role="alertdialog"` panel is. Built an inline two-step confirm instead (`ReturnForm`-style pattern reused).
-- `AttentionItem` gained an `issue_ref` field (dashboard now links attention items straight to `/data-quality/{issue_ref}` instead of only to vehicles); dashboard attention list capped at 8 items (was unbounded, would have shown up to 26 with the richer scan).
-- Commands run and verified from this checkout:
-  - `docker compose run --rm api pytest -q` — **35 passed** (new `tests/test_data_quality.py`: all five rule types present, scan idempotent on rerun, scan requires Operations Manager, S2/S4 issue-detail snapshots correct, defer→reject-on-closed 409, merge requires Operations Manager, merge rejects an unrelated survivor ref, full S2 merge scenario asserting rewiring + audit + replay-is-409).
-  - `docker compose run --rm api ruff check .` — All checks passed.
-  - `npm run build` — clean (had to fix two `possibly 'null'` TS errors from a closure-narrowing limitation — TS doesn't narrow `const` captured-by-closure across nested function boundaries when the value comes from an index/property expression; fixed by re-binding to explicitly-typed local consts right after the guard).
-  - Full browser run: Data Quality list (26 open issues, filterable) → `DQ-DEMO-DUPLICATE` two-column compare (CUS-0012 vs CUS-0178, per-field diff highlighting only where they differ) → merge with inline confirm → issue flips to `resolved` → confirmed `customer_merged` audit event with correct actor/entity/correlation → `DQ-DEMO-OVERLAP` (non-duplicate type) renders evidence JSON + defer/reject, no dead compare UI shown for a rule type it doesn't apply to.
-
-### M4 — n8n automation
-- `app/services/dispatcher.py`: background daemon thread (started/stopped via FastAPI `lifespan`, not an `on_event` hook) polling every `N8N_DISPATCH_INTERVAL_SECONDS` (default 3s). Claim step (`_claim_due_events`) is a short transaction using `SELECT ... FOR UPDATE SKIP LOCKED` that only flips `pending`→`delivering` and commits immediately; the HTTP call to n8n happens with **no open transaction**; the outcome is recorded in a separate short transaction. Exponential backoff `min(2**attempts, 60)` seconds, `N8N_MAX_ATTEMPTS=5` before a permanent `failed`.
-- Dispatcher reconstructs the wire event from `contracts/events.schema.json`'s exact fields (`event_id`, `event_type`, `occurred_at`, `correlation_id`, `aggregate`, `data`) rather than forwarding `OutboxEvent.payload_json` wholesale — that column also carries an internal `aggregate_ref` convenience key (used by dashboard/workflows list rendering) that the schema's `additionalProperties: false` would reject.
-- `POST /api/v1/integrations/n8n/return-callback` (`app/api/routers/integrations.py`): shared-secret auth via `X-Service-Token` header (`N8N_CALLBACK_TOKEN`, propagated to both `api` and `n8n` containers as `MOBILITYOPS_CALLBACK_TOKEN`); idempotent by `Idempotency-Key` (the event UUID) — checked by querying for an existing `AuditEvent` with that event ID in its metadata, **not** by `OutboxEvent.external_run_id`, because the dispatcher only sets that field *after* it gets n8n's final response, which happens *after* n8n has already called this callback mid-workflow — using `external_run_id` as the idempotency guard would have missed the exact redelivery case it's meant to catch.
-- `GET /api/v1/workflows` + `POST /api/v1/workflows/{event_id}/retry` (`app/api/routers/workflows.py`), both Operations Manager only. Retry only allowed from `failed`; sets `pending` + clears `next_attempt_at` so the live dispatcher picks it up on its next cycle (does not reset `attempts`, so the counter reflects true delivery history).
-- Automation nav + page (`pages/Automation.tsx`): table of all runs with status/attempts/last error, Retry button for `failed` rows, visible only to Operations Manager (matches backend authorization rather than just hiding a link).
-- **Two real bugs found and fixed, the second only by testing the actual live n8n round-trip, not by pytest**:
-  1. Seed-loaded `workflow_runs.csv` rows only ever got `payload_json = {"aggregate_ref": ...}` (no `correlation_id`/`aggregate`/`data`) — fine for M1–M3 since nothing read those keys yet, but once the dispatcher tried to *redeliver* a seeded row (i.e. the S5 manual-retry demo scenario) it crashed with `KeyError: 'correlation_id'`, leaving that event stuck in `delivering` forever (the crash happened before the outcome-recording transaction). Fixed in two places: `seed_loader.py` now builds the full schema-compliant envelope for every `workflow_runs.csv` row (matching what the live M2 return flow produces), and `dispatcher._deliver_one` now catches malformed-payload `KeyError`s defensively and resolves the row to `pending`/`failed` instead of leaving it orphaned — added `test_deliver_one_handles_malformed_payload_without_getting_stuck` as a regression test for the latter.
-  2. This n8n image (2.32.7) has dropped `N8N_BASIC_AUTH_ACTIVE` as a UI/API gate — it requires an actual owner account via the `/setup` flow before anything (including webhook registration reliability) works correctly. Also: `n8n import:workflow` requires the workflow JSON to have a top-level `"id"` field (added `"id": "mobilityops-return-processing"`) and **always deactivates** the imported workflow regardless of its `"active"` field — activation requires `n8n publish:workflow --id=<id>` followed by a full n8n restart (documented in n8n 2.x CLI, not obvious from the docs pack). Did this manually this session via the CLI + browser setup wizard; **this is a one-time operational step that is not automated** — a truly clean checkout still needs someone to run `docker compose exec n8n n8n import:workflow --input=//imports/mobilityops-return-processing.json`, `docker compose exec n8n n8n publish:workflow --id=mobilityops-return-processing`, `docker compose restart n8n`, and complete the one-time owner setup at `http://localhost:5678/setup` (any email/password, no verification required) before the automation demo will work. `docs/17-runbook.md` should get this exact sequence in M7.
-- Commands run and verified from this checkout:
-  - `docker compose run --rm api pytest -q` — **49 passed** (new `tests/test_dispatcher.py` — claim/deliver success/failure/backoff/exhaustion-to-failed/malformed-payload, all via `monkeypatch.setattr(dispatcher.httpx, "post", ...)`, no real network calls in tests; `tests/test_integrations.py` — callback auth, unknown-event 404, idempotent-by-event-ID with a real duplicate-call assertion; `tests/test_workflows.py` — role gating, retry-only-from-failed, S5 retry-and-audit).
-  - `docker compose run --rm api ruff check .` — All checks passed.
-  - `npm run build` — clean.
-  - Full live round trip (not mocked): registered a real return on `BK-DEMO-RETURN` → outbox event queued → background dispatcher delivered it to the now-activated n8n workflow within its 3s poll interval → n8n called back into `/api/v1/integrations/n8n/return-callback` (200 OK, confirmed in `docker compose logs api`) → dispatcher's original POST received n8n's success response → event flipped to `succeeded` on attempt 1, visible on `/automation`.
-  - S5 scenario end-to-end in the browser: seeded `BK-H-0020` (`failed`, 3 attempts, "Synthetic connection timeout to n8n") → clicked Retry → `pending` → within ~3s, live dispatcher delivered it through the real n8n instance → `succeeded`, 4 attempts. This is the full documented S5 scenario working for real, not simulated.
-
-### M5 — RAGcore knowledge integration
-- `app/services/knowledge/__init__.py`: `KnowledgeProvider` Protocol (sync, not async — the rest of the backend is sync SQLAlchemy/FastAPI, so an async provider interface would have meant bridging paradigms for no benefit) with `health()`/`ask()`, plus `GroundedAnswer`/`SourceCard`/`KnowledgeHealth` Pydantic models matching `contracts/openapi.yaml`'s `GroundedAnswer` schema exactly. `get_knowledge_provider()` factory switches on `settings.knowledge_provider` ("demo" default, "ragcore" opt-in).
-- `app/services/knowledge/demo.py` — `DemoKnowledgeProvider`: parses the 10 `knowledge/procedures/*.md` files' YAML frontmatter (hand-rolled flat parser, not PyYAML — avoided adding a dependency for a 6-key flat block) and `## `-delimited sections at startup, then does **TF-IDF-weighted keyword retrieval** (not naive keyword counting) with light suffix-stripping stemming (`returns`→`return`, `damaged`→`damage`). This is extractive, not generative: it returns real excerpts and a templated answer sentence, never invented text.
-  - **Real bug found and fixed by testing the actual S6 question, not by inspection**: naive flat keyword-overlap scoring (first cut) let the word "vehicle" — present in nearly every document's title — crowd out the actually-relevant `damage-procedure` document from the top-3 results for "What must I do when a vehicle returns with damage?", because generic words scored the same as distinctive ones. Fixed by computing corpus-wide IDF per token (`log((N+1)/(df+1)) + 1`) and weighting matches by it, so common terms contribute little and rare/distinctive terms (like "damage") dominate the ranking. Verified: the S6 question now returns `damage-procedure` and `vehicle-return-procedure` in the top 3, matching the documented expectation exactly.
-- `app/services/knowledge/ragcore.py` — `RAGcoreKnowledgeProvider`: real `httpx` adapter guessing a plausible REST contract (`GET /health`, `POST /api/v1/ask`) per `contracts/ragcore-contract-assumptions.md` (RAGcore is built separately; no live instance was reachable this session to verify against). Any connection error, timeout, or malformed response degrades to `evidence_state: "unavailable"` rather than raising — this is the adapter that actually exercises the architecture's "RAGcore failure disables knowledge answers only" reliability boundary. Not wired as the active provider by default; `KNOWLEDGE_PROVIDER=ragcore` would need a real, verified base URL to turn on.
-- `POST /api/v1/knowledge/questions` + `GET /api/v1/knowledge/status` (`app/api/routers/knowledge.py`). Audit event `knowledge_question_asked` logs `evidence_state`, `provider`, `source_ids`, and `question_length` only — **not** the question text itself, per `docs/12-security-and-audit.md` ("log question metadata and source IDs, not unnecessary full prompts").
-- Knowledge nav + page (`pages/Knowledge.tsx`): chat-style question box, source cards (title/version/section/excerpt) prioritized over the answer text per `docs/06-ui-ux.md`, explicit `grounded`/`insufficient`/`unavailable` states with distinct visual treatment — never a fabricated-looking answer for the latter two.
-- Dockerfile now also `COPY knowledge ./knowledge`; added `KNOWLEDGE_DIR` setting (`/app/knowledge/procedures` in-container, same pattern as `SEED_DIR`) rather than deriving the path from `__file__` — simpler and doesn't break if the module moves.
-- Commands run and verified from this checkout:
-  - `docker compose run --rm api pytest -q` — **57 passed** (new `tests/test_knowledge.py`: S6 grounded-with-expected-sources, unrelated question is honestly insufficient with no fabrication, demo provider health/document count, endpoint auth required, audit doesn't leak question text, RAGcore adapter degrades to unavailable on a simulated connection error).
-  - `docker compose run --rm api ruff check .` — All checks passed.
-  - `npm run build` — clean.
-  - Full browser run of S6 end-to-end: asked "What must I do when a vehicle returns with damage?" on `/knowledge` → grounded answer citing "Vehicle return procedure" (2 sections) and "Damage handling procedure" with real excerpts. Also asked an unrelated question ("What is the weather forecast for tomorrow?") → correctly returned "Insufficient evidence" / "No matching procedure was found" with zero sources, confirming no fabrication.
-
-### M6 — ITWorx MCP Hub publication
-- `app/api/routers/mcp_integrations.py`: four read-only endpoints under `/api/v1/integrations/mcp/` — `GET operations-summary`, `GET attention-vehicles` (query params `minimum_severity`/`date`/`limit` matching `contracts/mcp-tools.json`'s `inputSchema` exactly), `GET vehicles/{vehicle_ref}`, `POST search-knowledge` (the "narrow façade" the doc calls for — wraps M5's `get_knowledge_provider()` rather than re-implementing retrieval; the contract's tool has no MobilityOps `endpoint` field, only `routing.preferred: ragcore`, so this façade path is MobilityOps's own addition for when the Hub needs a single provider boundary, not literally specified by the contract).
-- Auth: new `require_mcp_service_token` dependency in `app/api/deps.py`, same shared-secret-header shape as the M4 n8n callback (`X-Service-Token` against `MCP_HUB_SERVICE_TOKEN`) plus an optional `X-Client-Id` header (defaults to `"unknown-mcp-client"`) used as the audit actor label — the Hub's actual client-identity header name is unknown (no live Hub to confirm against), so this is a reasonable guess documented here rather than assumed silently.
-- `McpVehicleDetailOut` deliberately omits `registration_number` and all customer data — narrower than the browser-facing `VehicleOut`/`VehicleDetailOut`, matching "no customer or vehicle database access" and the read-only/summary intent of an AI-facing tool. Test `test_vehicle_details_known_ref` asserts the field's absence explicitly so a future change can't silently widen the exposed surface.
-- Extracted `app/services/operations.py` (`compute_metrics`, `list_attention_vehicles`) out of `app/api/routers/dashboard.py` so the MCP operations-summary/attention-vehicles endpoints and the human dashboard share one query implementation instead of two copies that could drift — the same "do not duplicate retrieval logic" principle the doc states for the knowledge tool, applied here to the operational-summary tools too.
-- Every provider call writes an `AuditEvent` (`actor_type="service"`, `actor_label=X-Client-Id`, `action="mcp_tool_request"`, `metadata={tool, status}`) — MobilityOps's own record that its provider APIs were reached, independent of whatever central tool-call audit the Hub itself keeps (per `docs/10-mcp-hub-integration.md`'s audit section, the Hub owns the central log; this is the local corroborating one).
-- No write/mutation endpoints exist under the `/api/v1/integrations/mcp/` namespace at all (verified by `test_no_write_endpoints_exist_under_mcp_namespace` — POST/PUT/DELETE against the vehicle-details path all 404/405) — return registration, customer merge, and any booking/vehicle mutation are correctly absent, per the doc's explicit restriction list.
-- Commands run and verified from this checkout:
-  - `docker compose run --rm api pytest -q` — **66 passed** (new `tests/test_mcp_integrations.py`: token-required, wrong-token 401, all four tools' happy paths, severity/limit filtering, 404 for unknown vehicle, `max_sources` respected, audit actor/action verified, write-method rejection).
-  - `docker compose run --rm api ruff check .` — All checks passed.
-  - Live `curl` verification against the running stack (no browser needed — these are service-to-service endpoints, not UI): missing header → 422; wrong token → 401; correct token → all four endpoints return correct data (`operations-summary` metrics match the dashboard; `attention-vehicles?minimum_severity=high` returned `MO-016`×2 and `MO-031`, all severity `high`; `vehicles/MO-016` returned the narrow read-only shape; `search-knowledge` with `max_sources=2` returned exactly 2 grounded sources for the S6 question). Confirmed via `GET /api/v1/audit?action=mcp_tool_request` that all four calls were recorded with correct `actor_type=service`, tool name, and status.
-
-### M7 — Portfolio polish and final acceptance
-- **Automated clean-checkout migrations**: `backend/entrypoint.sh` now runs `alembic upgrade head` before starting uvicorn (Dockerfile `CMD` changed from `uvicorn ...` to `./entrypoint.sh`). Verified with a true `docker compose down -v` (all volumes wiped) → `docker compose up --build -d` → all 11 tables present, `/health` and web both green, all 66 backend tests pass, with zero manual migration step.
-- **n8n one-time setup scripted where it can be**: `make n8n-setup` runs the import/publish/restart sequence (previously three manual commands discovered ad hoc in M4). The owner-account creation itself cannot be scripted safely (it's an interactive one-time step in n8n 2.x's own onboarding, not a MobilityOps concern) — documented precisely in the rewritten `docs/17-runbook.md`, including the exact URL and that no email verification is required. Re-ran this full sequence from the wiped-volumes state this session and confirmed the S1 return → outbox → live n8n → callback → `succeeded` round trip works on a genuinely clean checkout, not just the already-provisioned stack from M0–M6.
-- **Playwright E2E** (`frontend/e2e/demo.spec.ts`, `frontend/playwright.config.ts`): one test automating the full 9-step documented demo script end-to-end against the live stack — login, dashboard metrics, open `BK-DEMO-RETURN`, register an odometer-regression return (S1), verify the quality issue + queued automation event, merge the duplicate-customer scenario (S2), ask the damage question and verify both expected source citations (S6), inspect audit entries, and verify responsive nav + no horizontal overflow at 360px width. **Passing.** This also resolves the "≤360px layout visually unverified" gap flagged back in M1 — verified both by this test's overflow assertion and by the `9-mobile-dashboard.png` screenshot (nav wraps into rows, metric tiles collapse to a 2-column grid, no horizontal scroll).
-- Added `frontend/e2e/_capture-screenshots.spec.ts` as evidence-generation tooling (underscore-prefixed, excluded from the default `playwright test` / `make e2e` run via `testIgnore` in the config — it calls `demo/reset`, which a real regression test shouldn't do as a side effect). Captured all 9 screenshots into `artifacts/evidence/screenshots/`.
-- Wrote `artifacts/evidence/architecture.md` (mermaid, as-built — distinguishes verified-live components from implemented-but-never-reached-a-real-instance ones, i.e. RAGcore and the MCP Hub) and `artifacts/evidence/final-summary.md` (commit, exact commands, test counts, screenshot index, RAGcore success/unavailable evidence — including a live-demonstrated unavailable case against an unreachable host, not just the unit test — n8n success/retry evidence, MCP sample calls, known limitations, truthful portfolio wording per `docs/16-portfolio-case-study.md`'s template).
-- Updated `README.md` (dropped stale "minimal bootable scaffold, not the finished application" wording and the old two-line quickstart in favor of `make demo` + a pointer to the runbook) and `docs/17-runbook.md` (full rewrite: exact bootstrap, n8n one-time setup, verification commands, required operational checks, recovery expectations).
-- Final placeholder/dead-UI sweep: `grep`'d the full `frontend/src` and `backend/app` trees for scaffold/TODO/FIXME/"must be replaced" markers — none found. `FILE_INDEX.md` was left as-is; it's the original build-pack's archive-completeness manifest (a historical snapshot), not a living index that needs to track every file added since — updating it would misrepresent what it's for.
-- Commands run and verified from this checkout (this milestone, cumulative across the whole build):
-  - `docker compose run --rm api pytest -q` — **66 passed**, ruff clean.
-  - `cd frontend && npm run build` — clean.
-  - `cd frontend && npx playwright test` — **1 passed** (full demo script, live stack).
-  - Full clean-checkout drill: `docker compose down -v` → `docker compose up --build -d` → `docker compose exec api python -m app.cli seed --reset` → `docker compose run --rm api pytest -q` (66 passed) → n8n owner setup + `make n8n-setup` → live S1 return round-tripped through the real n8n instance to `succeeded`.
-
-### Final acceptance audit (post-M7)
-
-A dedicated release-readiness audit was run after M7 claimed completion, specifically to
-catch anything the milestone-by-milestone build might have missed by only ever validating
-each piece in isolation.
-
-- **Real gap found: `mypy` had never been run.** `mypy` is a declared dev dependency
-  (`backend/pyproject.toml`) but was never wired into any milestone's validation loop —
-  only `ruff` was. Running it cold surfaced **43 real type errors across 10 files**, all
-  pre-existing (not introduced by this audit). Triaged and fixed all of them rather than
-  suppressing:
-  - `services/returns.py`: the vehicle lookup after acquiring `FOR UPDATE` could type as
-    `Vehicle | None` with no runtime guard — added an explicit `if vehicle is None: raise
-    AppError(..., 404)`. This was a genuine defensive-programming gap (a dangling FK would
-    have crashed with an unhandled `AttributeError`/500 instead of a clean 404), not just
-    a type annotation issue.
-  - `api/routers/bookings.py`: same pattern for `db.get(Customer, ...)` /
-    `db.get(Vehicle, ...)` in `get_booking` — added a guard raising 500 with a clear
-    message instead of crashing on `None.public_ref`.
-  - `api/deps.py` + `api/routers/demo.py`: `CurrentUser.role` is a `Literal[...]`, but
-    `SessionPayload.role` (decoded from an HMAC-signed cookie) and `User.role` (a DB
-    column) are both plain `str`. Pydantic validates this at runtime already (so it was
-    never exploitable), but `get_current_user` now explicitly checks membership before
-    constructing `CurrentUser`, turning a would-be unhandled `ValidationError` (500) into
-    a clean 401 for a corrupted/tampered cookie — another real defensive improvement, not
-    just a type-checker appeasement.
-  - `api/routers/dashboard.py`, `api/routers/data_quality.py`: two instances of reusing
-    one variable name for both a `Vehicle` and a `Customer` across an if/else branch,
-    which is genuinely confusing to read regardless of what mypy thinks — renamed to
-    distinct variables (`entity`/typed union in dashboard, `customer`/`vehicle` in the
-    data-quality snapshot helper).
-  - `services/data_quality.py`, `seed_loader.py`: `Booking.__table__.update()` /
-    `Customer.__table__.update()` don't typecheck against SQLAlchemy 2.0's stubs (the
-    `.__table__` accessor is typed as the more general `FromClause`, which doesn't
-    declare `.update()`) — switched to the idiomatic `sqlalchemy.update(Model)` construct,
-    which is both correctly typed and the more modern SQLAlchemy 2.0 style anyway.
-  - Remaining handful (schemas.py's deprecated `conint()` → `Annotated[int, Field(...)]`,
-    a `Sequence` vs `list` `.sort()` call, an `assert`-guarded None-narrowing after a
-    `WHERE ... IS NOT NULL` filter mypy can't see through, `Result.rowcount` typing gaps)
-    were either latent pydantic-v1-style API usage or genuine SQLAlchemy stub limitations
-    — fixed with the idiomatic modern equivalent or a narrowly-scoped, commented
-    `# type: ignore[...]` at the exact line, never a blanket suppression.
-  - `make lint` now runs both `ruff check .` and `mypy app`; `mypy app` reports
-    **zero errors across 44 source files**.
-- **No other defects found.** Re-ran the full journey matrix end-to-end against a
-  genuinely wiped-volumes (`docker compose down -v`) clean checkout: all 66 backend
-  tests, ruff, ✅; ran the demo login → dashboard → vehicle/booking detail → return
-  workflow → invalid-mileage rejection (422, both a negative value and a non-numeric
-  string) → data-quality issue review → duplicate-customer merge → audit trail →
-  Knowledge Assistant → live n8n round trip → MCP Hub endpoint journeys directly via
-  `curl` against the running stack, all correct.
-- **Degraded-mode behavior explicitly re-verified live** (not just unit-tested):
-  stopped n8n with `docker compose stop n8n`, registered a return — it committed
-  (`201`, booking flipped to `returned`) exactly as required; the outbox event stayed
-  `pending` with real `ConnectError`s logged and exponential backoff (2 attempts over
-  ~8s); restarted n8n and the dispatcher **self-healed** without any manual
-  intervention, delivering the event to `succeeded` on attempt 5. RAGcore unavailable
-  mode re-verified live against an unreachable host (`ConnectError` → `evidence_state:
-  "unavailable"`, empty answer, no fabrication). MCP Hub unavailability is
-  architecturally moot for MobilityOps — the Hub only ever calls *into* MobilityOps, so
-  there is nothing on the MobilityOps side that can degrade if the Hub is down (only the
-  reverse, "does an unavailable Hub break MobilityOps," which is trivially no since
-  nothing here calls out to it).
-- **New test coverage added, no existing tests weakened**: `frontend/e2e/interactive-elements.spec.ts`
-  (11 Playwright tests — all seven nav items, every filter on every list page, vehicle
-  detail tabs, defer/reject, automation retry, knowledge form, role-switching, and
-  role-based page restriction) plus the existing `demo.spec.ts` — **12/12 e2e tests
-  passing** against the live stack.
-- Verified `.env` is `.gitignore`d and was never committed (`git ls-files` /
-  `git log --all -p -- '*.env'` both empty); scanned full git history for AWS keys,
-  private-key headers, and `sk-...`-style tokens — none found. Every `Settings` field in
-  `backend/app/core/config.py` has a corresponding entry either directly in
-  `.env.example` or is derived/wired through `compose.yaml` (a few purely-internal
-  container-path constants like `SEED_DIR`/`KNOWLEDGE_DIR` are intentionally not
-  operator-configurable and correctly absent from `.env.example`).
-- Grepped the full `frontend/src` and `backend/app` trees for TODO/FIXME/placeholder/
-  fake/stub/mock/"not implemented" markers — zero real hits (the two `placeholder=`
-  matches are legitimate HTML input placeholder attributes). Confirmed dashboard metrics
-  and all list-page data are 100% DB-backed (`compute_metrics` in
-  `services/operations.py`, never a literal in frontend JSX). Confirmed every frontend
-  route in `App.tsx` maps to an implemented page and every nav item maps to a real route
-  — no dead routes.
-- Commands run and verified from this audit:
-  - `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` — **Success: no issues found in 44 source files** (0 errors, down from 43).
-  - `cd frontend && npm run build` — clean (`tsc -b && vite build`).
-  - `cd frontend && npx playwright test` — **12 passed** (`demo.spec.ts` + `interactive-elements.spec.ts`).
-  - Full clean-checkout drill repeated from a fresh `docker compose down -v`: automatic migrations, seed, 66/66 tests, n8n owner setup + `make n8n-setup`, live return round-tripped through n8n to `succeeded`.
-  - See `artifacts/final-acceptance/summary.md` for the complete evidence write-up (commands, exact outputs, demo access, deployment instructions, five-minute demo flow).
-
-## Definition of done
-
-All eight milestones (M0–M7) are complete, and a dedicated post-M7 final-acceptance audit
-found and fixed one real category of gap (`mypy` never having been run) with zero
-regressions. `docs/14-testing-and-acceptance.md`'s clean-checkout acceptance list has been
-walked item by item against a genuinely wiped-volumes checkout, twice (once in M7, once in
-this audit), and `artifacts/final-acceptance/summary.md` is the authoritative final
-evidence document. The two items not fully closed — a live RAGcore instance and a live
-ITWorx MCP Hub instance — were never reachable in this environment; both integrations are
-implemented, unit/contract-tested, directly verified against MobilityOps's own API, and
-their unavailable-degradation paths are live-verified, but an actual round trip against
-real RAGcore/Hub instances remains unconfirmed and is documented as such rather than
-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; 240.24 kB JS,
-    36.63 kB CSS before gzip).
-  - `cd frontend && playwright test --reporter=line` — **19 passed** including the full
-    five-minute demo, every interactive route, return review semantics and four viewport
-    overflow checks.
-- Review deployment updated at `http://192.168.10.150:1236` with persistent PostgreSQL
-  data preserved. Deployed smoke: all ten authenticated routes plus login at
-  desktop and mobile sizes rendered without alert state or horizontal overflow; browser console had zero
-  warnings/errors; seven authenticated API paths returned 200; PostgreSQL/API were
-  healthy and the shared n8n `/healthz` returned `{"status":"ok"}`.
-- Corrected the review topology after confirming the host already runs n8n on port 5678:
-  the temporary `mobilityops-n8n-1` container was removed without deleting its retained
-  volume; the bundled service is now opt-in through the `bundled-n8n` profile; the API
-  points to the shared n8n; and the return workflow is imported and published there.
-- The existing n8n's previously empty `N8N_HOST` and `N8N_EDITOR_BASE_URL` values were
-  persistently set in its Unraid template. A synthetic return then completed the full
-  MobilityOps → shared n8n → callback round trip as `succeeded` on attempt 1, after which
-  deterministic demo state was restored (`BK-DEMO-RETURN` is `active`).
-- Global search is now live for Control Rail sections and `MO-*`, `BK-*`, `DQ-*` public
-  references, including Ctrl/Cmd+K focus and a tested not-found announcement. Final local
-  Playwright result is **19 passed**.
-- Exact next action: hand off `design/mobilityops-premium-ui` for review. The final code,
-  shared-n8n topology and evidence are committed, pushed and deployed; do not merge master
-  automatically.
-
-## Functional completion pass (branch `feat/mobilityops-functional-completion`)
-
-Branched from `design/mobilityops-premium-ui` @ `54dc952`. Full audit at
-`docs/functional-completion/current-functional-audit.md`; server baseline captured before
-any change at `docs/functional-completion/server-baseline.md`.
-
-### Batch 1 — complete (commits `938a739`..`bdc58f3`)
-
-- Fixed the two confirmed list-rendering defects: Vehicles and Bookings both computed a
-  filtered/paginated result but rendered the raw unfiltered array in the table body.
-- Added server-backed session lifecycle: `GET /api/v1/demo/session` (Cache-Control:
-  no-store — a cached 200 was making logout intermittently fail to redirect in e2e
-  testing), `POST /api/v1/demo/logout`. `AuthContext` now verifies against the server on
-  every mount instead of trusting `sessionStorage`, and a central 401 listener on the API
-  client clears auth state from any endpoint.
-- Enforced the brief's role matrix: data-quality (list/detail/defer/reject) and the audit
-  trail were reachable by Rental Employee with no gate beyond authentication (confirmed
-  live via curl before the fix). Both are now `require_operations_manager`-gated
-  server-side, with matching nav-hiding and a restricted-message fallback for direct URL
-  access, and the dashboard no longer links into those areas for that role.
-- Discovered and fixed a latent e2e-suite bug while testing against the real server: all
-  three spec files hardcoded `http://localhost:8128` for their demo-reset helpers, so
-  pointing the suite at Unraid via `MOBILITYOPS_PUBLIC_URL` silently kept resetting the
-  *local* dev database instead. Switched to relative paths so the configured `baseURL` is
-  honoured.
-- Local evidence: `pytest` 75 passed, `ruff check .` clean, `mypy app` 0 issues/44 files,
-  `npx tsc -b` clean, `npm run build` clean, `npx playwright test` **25 passed** (up from
-  19 — 6 new tests this batch), stable across three repeated full-suite runs.
-- Deployed to Unraid (`.deploy/source-revision` = `bdc58f396e99caaf6ef657bb110b479981cc7793`,
-  matches `git rev-parse HEAD` on the feature branch), migrations unchanged at
-  `e7b08389f47f (head)` (no schema change this batch), demo reset run. Re-verified live:
-  role-gate curl checks (403/200/401 as expected) and the full 25-test Playwright suite
-  run with `MOBILITYOPS_PUBLIC_URL=http://192.168.10.150:1236` — **25 passed** against the
-  actual deployment, not just localhost.
-- Exact next action: Batch 2 — authoritative return-preview endpoint shared with commit,
-  and expose `before`/`after` on the audit API + UI.
-
-### Batch 2 — complete (commits `f521295`, `7e34f55`)
-
-- Added `evaluate_return()` (pure, no writes) in `returns.py`, extracted from what
-  `register_vehicle_return` already computed inline; `register_vehicle_return` now calls
-  it instead of duplicating the logic. New non-mutating `POST
-  /api/v1/bookings/{ref}/return-preview` uses the same function, so preview and commit
-  cannot drift.
-- Fixed a real defect this surfaced: `ReturnForm.tsx`'s review step guessed the outcome
-  client-side and got the domain rule wrong — it said damage/technical-warning routes to
-  `maintenance` (actual rule: `blocked`) and the no-contradiction case becomes
-  `available` (actual rule: always `cleaning` first, `maintenance` only past the service
-  threshold). The review step now calls `/return-preview` and renders the server's
-  `resulting_vehicle_status` + `status_reason` verbatim.
-- Result screen now distinguishes local commit success from n8n delivery ("queued... not
-  yet confirmed" instead of implying both succeeded) and links to any created
-  data-quality issue for Operations Manager.
-- Exposed `before`/`after` on `AuditEventOut` (the DB columns already existed but were
-  never serialized) plus a resolved `entity_ref`/`entity_link` for vehicle/booking/
-  data-quality-issue entities. `Audit.tsx` now shows a human-readable change summary per
-  row with raw JSON behind a `<details>` disclosure instead of always-visible JSON.
-- New regression coverage: backend — preview performs no writes (asserted via audit/
-  outbox row counts before vs. after), detects odometer regression, detects service-due,
-  detects next-booking risk, requires an active booking, and matches the commit result;
-  audit — before/after and entity link exposed for both `return_registered` and
-  `vehicle_status_changed`. Frontend — preview correctly reports `blocked` (not
-  `maintenance`) for damage, commit request only fires after confirm (updated to also
-  assert exactly one preview call), audit page shows before/after and a safe link.
-- Local evidence: `pytest` 81 passed, `ruff check .` clean, `mypy app` 0 issues/44 files,
-  `npx tsc -b` clean, `npm run build` clean, `npx playwright test` **27 passed**, stable
-  across two repeated full-suite runs.
-- Deployed to Unraid and re-verified; demo data reset afterward.
-- Exact next action: Batch 3 — data-quality workbench (typed snapshots, bounded
-  resolution flows for all 5 rule types, manual scan UI).
-
-### Batch 3 — complete (commits `6e227a2`, `477b5e7`)
-
-- Typed related-entity snapshots by the reference's own prefix (CUS-/MO-/BK-/INSP-)
-  instead of inferring from `rule_type`. Fixed a real gap this exposed: a
-  `booking_overlap` issue's related refs are bookings, but `get_issue` always resolved
-  them as vehicles, so `_snapshot()` silently returned nothing for them.
-- Added one bounded resolution endpoint per remaining rule type: `provide-fields`
-  (missing_required_field; re-runs the check, resolves only once nothing required is
-  missing), `resolve-odometer-regression` (retain canonical or correct the reading —
-  correction is rejected if it would still be below canonical), `resolve-overlap`
-  (blocks one of the two bookings, re-verifies no overlap remains — found and fixed an
-  autoflush=False bug where the re-verification query didn't see the just-blocked
-  booking's in-memory status change), `apply-recommended-status` (one authoritative
-  recommendation function mirroring the scan's own conflict conditions, re-validated
-  after applying). `possible_duplicate_customer` already had merge; all five rule types
-  now have a real bounded resolution path, not just generic defer/reject.
-- Reintroduced evidence after a non-open decision links the new issue back to the prior
-  one (`evidence.reopened_from` / `previous_decision`) per the documented lifecycle
-  ("reintroduced evidence creates a new issue linked to the prior issue").
-- `DataQualityIssueDetail.tsx` rewritten: a typed panel per rule type instead of a raw
-  `JSON.stringify` dump for four of five types; raw evidence moved behind a `<details>`
-  disclosure. Added a "Run quality scan" action to the workbench (confirmation,
-  progress, per-rule result counts, auto-refresh) — the scan endpoint already existed
-  with no UI trigger.
-- New regression coverage: backend — one resolution test per rule type plus the
-  role-gate/validation-rejection paths and the recurrence-linking behavior (reject an
-  issue, rescan, assert the new issue links back). Frontend — one Playwright test per
-  resolution flow plus the manual scan trigger.
-- Local evidence: `pytest` 96 passed, `ruff check .` clean, `mypy app` 0 issues/44 files,
-  `npx tsc -b` clean, `npm run build` clean, `npx playwright test` **32 passed**, stable
-  across two repeated full-suite runs.
-- Deployed to Unraid and re-verified against the live server; demo data reset afterward.
-- Exact next action: Batch 4 — global search backend + UI, demo reset UI trigger,
-  truthful aggregate integration status (n8n/RAGcore/MCP).
-
-### Batch 4 — complete (commits `4437b87`, `1867828`)
-
-- Added `GET /api/v1/search` — bounded typed results (vehicle/booking/data-quality-issue/
-  section), role-filtered server-side (data-quality and manager-only sections excluded
-  for Rental Employee), customers never returned (no customer detail route exists).
-  Replaced `Layout.tsx`'s blind client-side regex/term guesser with a debounced
-  (250 ms) call to this endpoint, a real `role="listbox"` results panel, arrow-key
-  navigation, Enter/Escape, outside-click close, and a no-results state.
-- Added `GET /api/v1/integrations/status`, aggregating outbox delivery counts into one
-  truthful n8n state (`disabled`/`unavailable`/`degraded`/`operational`/`no_evidence`)
-  instead of the dashboard/automation cards showing whichever status the single most
-  recent event happened to be in. Wired into both `Automation.tsx` and `Dashboard.tsx`.
-  MCP Hub card now reflects the real `registration_enabled` setting.
-- Found and fixed a real config gap this surfaced: `MCP_HUB_REGISTRATION_ENABLED` was
-  documented in `.env.example` but had no `Settings` field, so it was silently dropped
-  by `extra="ignore"` and never read anywhere in the codebase.
-- Added a "Reset demo data" action to the sidebar (Operations Manager only, confirm,
-  progress, error handling) — the endpoint already existed and was already gated, just
-  had no UI trigger. Reset invalidates the acting session server-side, so the flow signs
-  the user out and returns to login.
-- New regression coverage: backend — search role-filtering/customer-exclusion/no-match,
-  integration-status role-gate and state-derivation (including a test that resolves all
-  seeded failures and asserts the state flips to `operational`). Frontend — vehicle/
-  booking/data-quality-issue search navigation, keyboard nav, no-results + Escape, demo
-  reset happy path, rental employee cannot see the reset button, automation page shows
-  aggregate counts.
-- Local evidence: `pytest` 109 passed, `ruff check .` clean, `mypy app` 0 issues/46 files,
-  `npx tsc -b` clean, `npm run build` clean, `npx playwright test` **37 passed**, stable
-  across two repeated full-suite runs.
-- Deployed to Unraid and re-verified against the live server; demo data reset afterward.
-- Exact next action: Batch 5 — bounded outbox delivery-lease recovery for stale
-  `delivering` events, a second (scheduled quality-scan) n8n workflow, final
-  documentation/contract updates and acceptance evidence.
-
-### Batch 5 — complete (commits `ec8f809`, `e115031`, `c981aad`, `824048b`)
-
-- Fixed a real gap: `_claim_due_events` flipped rows to `delivering` and committed
-  before the HTTP call, with no reclaim path if the process died before the outcome was
-  recorded. Each claim now gets a lease deadline (`n8n_delivery_lease_seconds`, default
-  120s, reusing the `next_attempt_at` column) and `run_dispatch_cycle()` sweeps expired
-  leases back to `pending` before claiming new work; `attempts` is preserved, and a
-  still-alive worker's unexpired lease is never touched.
-- Added the second n8n workflow: `POST /api/v1/integrations/n8n/scheduled-scan`
-  (service-token protected, same pattern as the return callback) running the same
-  `run_scan()` the manual UI action uses, audited with `actor_type=service`.
-  `n8n/mobilityops-scheduled-quality-scan.json` (hourly + manual-test trigger) ships
-  `"active": false`. Live-verified twice: executed end-to-end via the Manual test
-  trigger against the **local** n8n instance (full green execution, confirmed via the
-  resulting `data_quality_scan_run` audit event), and published + directly
-  curl-round-tripped against the **shared Unraid n8n** and its live API
-  (`deploy/unraid/setup-scheduled-scan.sh`). The shared instance's own UI could not be
-  browser-tested directly — it runs `N8N_SECURE_COOKIE=true` and refuses login over the
-  plain-HTTP LAN URL, which is correct/expected shared-infrastructure behaviour, not
-  something this task should change.
-- Updated `contracts/openapi.yaml` and `docs/05-api-contract.md` with every endpoint
-  added across all five batches; `docs/07-data-quality.md`, `docs/08-return-workflow.md`
-  and `docs/12-security-and-audit.md` now describe the actual resolution flows, the
-  preview/commit relationship, the role matrix and the audit before/after exposure.
-  Corrected `docs/07-data-quality.md`'s lifecycle description to match the
-  already-implemented `(rule_type, entity_type, entity_id)` idempotency key (no evidence
-  fingerprint) and documented the `reopened_from`/`previous_decision` recurrence link.
-  `README.md`'s scope/integration-status/quality-gate sections updated to match.
-- Local evidence: `pytest` **117 passed**, `ruff check .` clean, `mypy app` 0 issues/46
-  files, `npx tsc -b` clean, `npm run build` clean, `npx playwright test` **37 passed**.
-- **Clean-checkout drill** (section 14): fresh `git clone` of this branch into an
-  isolated scratch directory, `.env` from `.env.example`, isolated Compose project name
-  and remapped host ports (no shared state with the working stack), `up --build -d`
-  from empty volumes → migrations ran automatically → seed → full backend gate (117
-  passed, ruff clean, mypy clean) → `npm ci` (clean; the pre-existing esbuild-moderate/
-  react-router-RSC-high advisories are unchanged, not new) → `tsc -b`/`vite build` clean
-  → full Playwright suite **37 passed** against the isolated stack. Torn down afterward
-  (`down -v` on the isolated project only; the working dev stack was never touched).
-- Deployed to Unraid; migrations unchanged at `e7b08389f47f (head)`. Full 37-test
-  Playwright suite re-run against `http://192.168.10.150:1236` — **37 passed**. Demo
-  data reset afterward.
-- Exact next action: none — all five batches are implemented, tested locally (including
-  a genuine clean-checkout drill), committed, pushed, deployed to Unraid and
-  re-verified against the live server after every batch. See
-  `artifacts/functional-completion/final-summary.md` for the definitive acceptance
-  evidence.
-
-## Demo productization (in progress, same branch `feat/mobilityops-functional-completion`)
-
-Follows the functional-completion work above; turns the now feature-complete PoC into a
-guided, honestly-labelled demo (fictional org "Northstar Mobility", guided tour, 5 named
-scenarios, demo manifest, About page). Gap audit: `docs/demo-release/current-demo-gap-audit.md`.
-
-### Batch 1 — seed date anchoring (complete)
-
-- **Real bug fixed**: `seed/bookings.csv` etc. store absolute ISO timestamps authored
-  around a fixed anchor (`2026-08-01`). Nothing previously re-anchored them at seed/reset
-  time, so scenario bookings (e.g. `BK-DEMO-RETURN`) silently drifted into the past every
-  day the environment wasn't reset. `dashboard.py::_today()` compounded this by filtering
-  "today's movements" against the same frozen `demo_today` setting instead of real time.
-- Fix: `seed_loader.py` now computes `shift = today - SEED_AUTHORED_ANCHOR` once per
-  `load_seed()` call and applies it to every seeded booking/inspection/maintenance/outbox
-  datetime column, so scenarios stay "today"/"near-future" relative to the actual reset
-  moment. `SeedResult` now also carries `anchor_date`/`seeded_at`; `POST /api/v1/demo/reset`
-  returns them; a `demo_data_seeded` audit event records the anchor for traceability.
-  `dashboard.py::_today()` switched from the frozen `demo_today` setting to real wall-clock
-  UTC date. The now-dead `demo_today` setting/env var was removed from `config.py`,
-  `compose.yaml`, `.env`, `.env.example` (nothing else referenced it).
-- Added seed-validation tests (`backend/tests/test_seed.py`) proving S1 (`BK-DEMO-RETURN`/
-  `MO-024`), S2 (`CUS-0012`/`CUS-0178`/`DQ-DEMO-DUPLICATE`), S4 (`MO-016`/
-  `BK-DEMO-OVERLAP-A`/`-B`/`DQ-DEMO-OVERLAP`) and S5 (seeded failed outbox event
-  `00000000-0000-4000-8000-000000000020`, confirmed genuinely `failed` immediately after a
-  fresh reset, not silently auto-healed by the background dispatcher since it only claims
-  `pending` rows) are fully present after every reset, plus a dedicated anchoring test
-  asserting the shift and the audit marker.
-- Live-verified locally: reseeded and confirmed via `psql` that `BK-DEMO-RETURN` now ends
-  today and `BK-DEMO-NEXT`/overlap bookings sit in the near future (today = 2026-08-03).
-- Evidence: `pytest` **122 passed** (117 + 5 new/expanded seed tests), `ruff check .`
-  clean, `mypy app` clean (46 files, canonical `make` scope).
-- Deployed to Unraid (commit `8989ffb`): pushed to Gitea, `git archive` tarball extracted
-  over `/mnt/user/appdata/mobilityops` preserving `.env`/volumes, `api` rebuilt (`db`/`web`
-  untouched — no frontend changes this batch), migrations confirmed at `e7b08389f47f
-  (head)`, reseeded, live-verified via `psql` that `BK-DEMO-RETURN`/`BK-DEMO-NEXT`/overlap
-  bookings sit at the same real-time-relative positions as local. `curl` to
-  `http://192.168.10.150:1236/` returns 200.
-- Exact next action: `GET /api/v1/demo/manifest` + Dutch demo entry screen + permanent
-  demo badge (task #30), then the Demo Guide + scenario overview (task #31).
-
-### Batch 2 — demo manifest, Dutch demo entry, permanent demo badge, About page (complete)
-
-- `GET /api/v1/demo/manifest` (unauthenticated): single source of truth for demo org
-  identity, synthetic-data flag, reset allowance/timestamp/anchor date, guide
-  availability, and the 5 named scenarios with **live** readiness (queries the actual
-  `BK-DEMO-RETURN`/`DQ-DEMO-DUPLICATE`/`DQ-DEMO-OVERLAP`/seeded-failed-event/knowledge-
-  provider records — not hardcoded), plus plain-language integration summaries. Backed by
-  new `backend/app/services/demo_manifest.py`. Refactored the n8n status derivation out of
-  `integration_status.py` into a shared `services/integration_status.py` so the manifest
-  and the existing authenticated `/integrations/status` endpoint reuse one implementation.
-- New settings (`backend/app/core/config.py`, wired through `compose.yaml`/`.env.example`):
-  `DEMO_ORGANIZATION_NAME` (default "Northstar Mobility" — surfaces the project's already-
-  locked fictitious tenant, previously only used internally as the `ragcore_tenant` slug),
-  `DEMO_TIMEZONE`, `DEMO_ALLOW_RESET` (a safety valve — `false` makes `POST
-  /api/v1/demo/reset` return 403 regardless of role; the now-dead `demo_today` setting
-  removed in Batch 1 stays removed).
-- Rewrote `Login.tsx` in Dutch: names the fictional org, one-sentence explanation sourced
-  from the manifest, no password shown/copyable anywhere, "Start begeleide demo" primary
-  CTA (logs in as Operations Manager, navigates to `/dashboard?guide=start` for task #31 to
-  consume) plus "Verken als Operations Manager"/"Verken als Rental Employee" secondary
-  actions. Added a permanent demo badge (topbar pill + popover: synthetic notice,
-  "workflows are real" reassurance, last-reset timestamp, link to `/about`) replacing the
-  old full-width static `.demo-banner` bar — subtle by design per the brief, not a warning
-  bar. New `/about`
-  page (`AboutDemo.tsx`) covering the fictional problem, what's really implemented, what's
-  synthetic, honest per-integration labels (via the manifest), and a reset pointer —
-  reachable from the badge popover, not added to primary nav (preserves the existing Control
-  Rail nav per the "not a redesign" constraint). Frontend nav/design otherwise untouched.
-- Evidence: `pytest` **127 passed**, `ruff check .` clean, `mypy app` clean (48 files);
-  frontend `tsc -b` clean, `npm run build` clean; full Playwright suite **41 passed**
-  (37 existing + 4 new `demo-entry.spec.ts` covering entry copy/no-password, guided-demo
-  login redirect, badge popover content + About link, and Escape/outside-click close).
-  Updated stale English login-button aria-labels and login-copy assertions across the
-  existing specs to match the new Dutch copy.
-- Deployed to Unraid (commit `ac427f4`): pushed to Gitea, `git archive` tarball extracted
-  preserving `.env`/volumes, both `api` and `web` rebuilt (frontend changed this batch),
-  both healthy, migrations unchanged, reseeded. Live-verified: `GET
-  /api/v1/demo/manifest` returns `organization_name: "Northstar Mobility"`,
-  `allow_reset: true`, and all 5 scenarios `ready: true` right after reset. Ran
-  `demo-entry.spec.ts` (4 tests) and the five-minute demo script directly against
-  `http://192.168.10.150:1236` — **5/5 passed**. Reseeded again afterward to leave the
-  server demo-ready.
-- Exact next action: Demo Guide (collapsible panel, 8 steps) + scenario overview (5 cards
-  on the dashboard, consuming `/api/v1/demo/manifest`'s `scenarios` array) — task #31.
-
-### Batch 3 — Demo Guide + scenario overview (complete)
-
-- New `/scenarios` page (`Scenarios.tsx`): all 5 named scenarios as cards (title,
-  operational problem, duration, required role(s), "toont aan", ready/blocked status
-  from the manifest, "Start scenario" linking to the live `start_path`). Dashboard gets
-  one compact "Probeer een demonstratiescenario" panel (not 5 more cards — keeps the
-  existing dashboard uncluttered per the brief) showing readiness count and, for
-  Operations Managers, a guide resume/start control.
-- New Demo Guide: `DemoGuideContext` (sessionStorage-persisted `currentIndex`/`completed`
-  set — browser-only, never touches auth or business logic), 8 static steps
-  (`data/demoGuideSteps.ts`) each with what-you'll-see/why/start-action/expected-outcome,
-  resolving live routes from the manifest for the two scenario-backed steps (return,
-  duplicate-merge) so they can't drift from actual records. `DemoGuide.tsx` renders a
-  fixed side panel (desktop) that becomes a bottom sheet at ≤700px via CSS only (no
-  layout duplication); `DemoGuideTrigger` (topbar, Operations-Manager-only — the 8 steps
-  require OM throughout) shows a live `completed/8` pill. "Demo opnieuw voorbereiden"
-  calls the real reset endpoint, resets guide progress, and returns to `/login` (mirrors
-  the existing sidebar reset flow). Login's "Start begeleide demo" logs in as OM and
-  passes a one-shot `?guide=start` marker the dashboard consumes once then strips.
-- Fixed a real regression caught by the responsive-overflow tests: the new topbar guide
-  trigger pushed `.topbar-meta` past the viewport at ≤420px; fixed by hiding the guide
-  trigger (icon+pill) at that breakpoint — the Dashboard's own "Start demo-gids" control
-  remains reachable there. Also fixed a genuine mobile overflow in the new
-  `.demo-start-panel` (flex items without `min-width:0`/wrap on narrow screens).
-- Fixed one fragile new test (asserted on the transient `?guide=start` URL param, which
-  the app intentionally strips immediately — changed to assert the guide's actual open
-  state instead) and two Playwright strict-mode ambiguous-match errors; confirmed the
-  full 41+6=47-test suite passes twice in a row after these fixes (ruling out flakiness).
-- Evidence: frontend `tsc -b` clean, `npm run build` clean; full Playwright suite
-  **47 passed** (41 existing + 6 new `demo-guide.spec.ts`: scenario overview shows 5
-  ready cards after reset, starting a scenario navigates to its fixed record, guide
-  step navigation/jump/close, progress persists across page navigation, guide hidden
-  from Rental Employee, restart-from-guide resets data and returns to login). Backend
-  untouched this batch (no re-run needed; last backend gate was 127 passed/ruff/mypy
-  clean in Batch 2).
-- Deployed to Unraid (commits `9fff84d`, then `14c2ad3` for a test-only fix): pushed to
-  Gitea, tarball extracted, `web` rebuilt (frontend-only batch), healthy. Live-verified:
-  ran `demo-guide.spec.ts` (6), `demo-entry.spec.ts` (4) and the five-minute demo script
-  directly against `http://192.168.10.150:1236` — **11/11 passed**. Caught and fixed one
-  real environment-sensitive test bug in the process: two tests navigated straight to
-  `/scenarios` right after a login click without waiting for the `/dashboard` redirect,
-  which raced harmlessly on localhost but flaked against Unraid's higher latency — fixed
-  by asserting the redirect first, no app-code change needed. Reseeded afterward to leave
-  the server demo-ready.
-- Exact next action: layer plain-language Dutch explanation onto the return flow, the 5
-  data-quality panels, and fix the knowledge assistant's RAGcore-naming bug — task #33.
-
-### Batch 4 — return/data-quality/knowledge demo legibility (complete)
-
-- **Fixed a real honesty bug**: `Knowledge.tsx` named "RAGcore" in the body copy and the
-  retrieval-flow diagram even though the active provider is the demo TF-IDF one (the
-  small badge below was already honest, contradicting the prose one line above). Now
-  derives a `providerLabel` ("Demo knowledge base" vs "RAGcore") from the real health
-  check and uses it everywhere; added an explicit disclosure note when not RAGcore.
-  Added 4 suggested-question chips. **Discovered and fixed a second real bug in the
-  process**: the brief's suggested Dutch questions (and my own Demo Guide step 6 wording)
-  would have returned "insufficient evidence" against the demo provider, because the
-  indexed procedures are English-only — verified empirically (Dutch question →
-  `insufficient`, its English equivalent → `grounded`). Fixed by keeping suggested
-  questions in English (matching the indexed content) and rewording the Guide step to
-  explain the knowledge base is English, rather than mistranslating the demo's
-  centerpiece feature into silently returning wrong answers.
-- Return flow: `BookingDetail.tsx` now detects the one named return-anomaly scenario
-  booking (via the manifest, not a hardcoded ref) and fetches that vehicle's real
-  canonical odometer to pre-fill `ReturnForm`'s "End odometer" field with a suspicious
-  value below it, plus a callout explaining why — the brief explicitly requires the demo
-  not ask a visitor to invent a suspicious number themselves. Scoped narrowly to that one
-  scenario booking; ordinary returns are unaffected. `ReturnResultPanel` now links to
-  Automation and Audit trail (previously only the vehicle), and shows a "Ga verder met de
-  demo" button when the Demo Guide is open (advances the guide and navigates to the next
-  step). **Fixed a real regression caught by the existing return-review e2e test**: the
-  async pre-fill could silently overwrite odometer text a visitor had already started
-  typing, if the vehicle-detail fetch resolved after they began typing — fixed with an
-  `odometerEditedByUser` ref guard.
-- Data quality: added a shared `RuleExplainer` (what's wrong / why it matters, in plain
-  language) for all 5 rule types on `DataQualityIssueDetail.tsx`; added a generic
-  post-resolution confirmation (audit-trail link, vehicle link, "Ga verder met de demo")
-  for the 4 rule types that previously just silently flipped their status badge with no
-  explicit confirmation, and extended `VehicleStatusConflictPanel`'s existing confirmation
-  with the same links rather than duplicating it. Added a "Demo scenario's only" checkbox
-  filter on `DataQuality.tsx` (client-side `public_ref.startsWith("DQ-DEMO-")`, no new
-  business logic) so the curated issues are easy to find among the full queue.
-- Evidence: frontend `tsc -b` clean, `npm run build` clean; full Playwright suite
-  **51 passed** (47 existing + 4 new `demo-legibility.spec.ts`: return pre-fill + why-
-  suspicious explanation + result links, rule explainer visible, demo-scenario filter
-  narrows correctly, knowledge suggested question returns grounded evidence with the
-  correct provider label). Backend untouched this batch.
-- Deployed to Unraid (commit `ddc3a98`): pushed to Gitea, tarball extracted, `web`
-  rebuilt (frontend-only), healthy. Live-verified: ran `demo-legibility.spec.ts` (4) and
-  the five-minute demo script directly against `http://192.168.10.150:1236` —
-  **5/5 passed**. Reseeded afterward to leave the server demo-ready.
-- Exact next action: plain-language integration-status labels, richer audit narration,
-  the full "Over deze demo" page content (currently a first pass from Batch 2), and
-  wiring reset into the guide/About/OM menu narrative — task #34.
-
-### Batch 5 — integration-status UX, audit UX, About page, reset integrity (complete)
-
-- Plain-language integration status: extracted `frontend/src/data/integrationLabels.ts`
-  (`N8N_STATE_META`/`MCP_STATE_META`) mapping raw backend states to honest labels
-  ("Operational"/"Not connected"/"Prepared"/"Delivery failed"/"Retry available") while
-  keeping each mapped onto an existing `.status-*` CSS colour class (a few raw values like
-  `degraded`/`disabled`/`configured` had no matching CSS rule at all before this — a real,
-  pre-existing colour-coding gap). `StatusBadge` gained an optional `label` override prop
-  (backward compatible) so the badge's colour class and its displayed text can differ.
-  Wired into both `Automation.tsx` and `Dashboard.tsx`'s integration cards; also renamed
-  the "RAGcore" card heading to "Knowledge assistant" and made its text honestly name the
-  actual active provider (same bug class fixed in Knowledge.tsx in Batch 4).
-- Audit trail: added a "Follow-up" column with a "View related events" action per row that
-  filters the same list by `correlation_id` (reuses the backend's existing, already-tested
-  `correlation_id` query param — no new business logic), with a "Clear this filter"
-  affordance. This is how a visitor sees "what else happened as a result of this action"
-  (e.g. a return's linked vehicle-status-changed / workflow-queued events) without a
-  bigger grouped-timeline rebuild.
-- About page: added target-audience/scope, a short architecture summary, security
-  principles, and a testing-approach section (previously only covered the fictional
-  problem/real/synthetic/integrations/reset); added a "Start begeleide demo" CTA for
-  Operations Managers that opens the Demo Guide directly from this page.
-- Reset integrity: added `scenario_integrity_report()` (`backend/app/services/
-  demo_manifest.py`), reusing the exact same scenario-readiness derivation the manifest
-  and scenario overview already use (so it can't drift), and wired it into `POST
-  /api/v1/demo/reset` — both the response body and the `demo_reset` audit event's
-  metadata now carry `scenario_integrity: {all_ready, not_ready}`. This is the
-  server-side post-reset integrity check the brief asks for; visible today via the audit
-  event's raw-detail view, satisfying the requirement without adding a UI banner to a
-  flow that immediately logs the user out and redirects to `/login`.
-- **Fixed a second real regression this batch, caught by the existing return-review
-  e2e test**: restructured the odometer pre-fill so `BookingDetail.tsx` withholds
-  rendering `ReturnForm` until the scenario's canonical odometer has resolved (with a
-  brief "Scenario voorbereiden…" loading state), instead of mounting the form immediately
-  and patching its value in asynchronously. The previous approach raced visibly with
-  Playwright's `fill()` (and would have raced with a real visitor typing quickly),
-  producing a corrupted concatenated value in one observed failure. This also let the
-  now-unnecessary `odometerEditedByUser` ref guard be removed — simpler and more robust
-  than the effect-based patch it replaced.
-- Evidence: `pytest` **127 passed**, `ruff check .` clean, `mypy app` clean (48 files);
-  frontend `tsc -b` clean, `npm run build` clean; full Playwright suite **51 passed**,
-  confirmed stable across three consecutive full runs (given how many timing races this
-  batch and the previous one surfaced, stability was verified deliberately rather than
-  assumed from a single green run).
-- Deployed to Unraid (commit `5fa4fe0`): pushed to Gitea, tarball extracted, both `api`
-  and `web` rebuilt, healthy, migrations unchanged at `e7b08389f47f (head)`, reseeded.
-  Live-verified: ran `demo-legibility.spec.ts` (4), the five-minute demo script, and the
-  full `interactive-elements.spec.ts` suite (26) directly against
-  `http://192.168.10.150:1236` — **31/31 passed**. Reseeded afterward to leave the
-  server demo-ready.
-- Exact next action: full guided-demo Playwright test + remaining targeted demo tests per
-  section 19 (mobile guide, keyboard nav, all scenario flows, About page, accessibility/
-  reduced-motion/console/network checks) — task #35.
-
-### Batch 6 — full guided-demo test + targeted demo tests (complete)
-
-- **Found and fixed a real, fairly serious desktop layout bug** while writing the full
-  guided-demo test: the Demo Guide's fixed right-side panel (400px wide) overlapped the
-  main content area at normal desktop widths with no reflow, so its own step-list buttons
-  intercepted pointer events meant for the page underneath (concretely: the return form's
-  "Review return" button was unclickable while the guide was open, at exactly the
-  viewport size Playwright's default test browser uses — this would have hit real
-  visitors on ordinary laptop screens too). Fixed by adding a `guide-open` class to
-  `.app-workspace` that reserves `padding-right: min(400px, 92vw)` while the guide is open
-  (≥701px only; the ≤700px bottom-sheet layout is unaffected), so content reflows aside
-  instead of sitting underneath the panel.
-- Added `frontend/e2e/guided-demo-full.spec.ts`: one comprehensive test walking a fresh
-  Operations Manager session through all 8 Demo Guide steps in order, performing the
-  **real** action at each step (not just verifying copy) — processes the actual
-  odometer-anomaly return, resolves the resulting data-quality issue, merges the
-  duplicate customer, asks a suggested knowledge question, checks automation + audit,
-  reviews the About page — using the guide's own progression controls
-  ("Volgende"/"Ga naar deze stap"/"Ga verder met de demo") throughout, then resets the
-  demo data again at the end to restore the environment per the brief's requirement.
-- Added `frontend/e2e/demo-accessibility.spec.ts` (4 tests): the guide renders as a
-  correctly-anchored bottom sheet on a 390px mobile viewport with no horizontal overflow;
-  the guide never covers the return form's action buttons on desktop (regression test for
-  the bug above); the demo badge and guide trigger are keyboard-focusable and operable
-  (Enter to open, explicit close controls); key demo pages (dashboard, scenarios, about,
-  guide open) load with no unexpected console errors (the one expected benign 401 from
-  the app's own session-probe on first load is explicitly allow-listed, not silenced
-  blindly).
-- Evidence: full Playwright suite **56 passed** (51 existing + 1 guided-demo-full + 4
-  demo-accessibility), confirmed stable across two consecutive full runs. Backend
-  untouched this batch (last gate: 127 passed/ruff/mypy clean, Batch 5).
-- Deployed to Unraid (commit `07d5605`): pushed to Gitea, tarball extracted, `web`
-  rebuilt (frontend-only), healthy, reseeded. Live-verified: ran
-  `guided-demo-full.spec.ts` and `demo-accessibility.spec.ts` directly against
-  `http://192.168.10.150:1236` — **5/5 passed**, confirming the desktop-overlay layout
-  fix holds on the real deployment too. Reseeded afterward to leave the server
-  demo-ready.
-- Exact next action: clean-checkout demo drill, final documentation set (demo-concept/
-  demo-scenarios/demo-data/demo-guide/demo-runbook, README, .env.example), final Unraid
-  deploy + live evidence with screenshots, `artifacts/demo-release/final-summary.md` —
-  task #36 (final).
-
-### Batch 7 (final) — clean-checkout drill, docs, final Unraid evidence (complete)
-
-- **Clean-checkout drill**: fresh `git clone` into an isolated scratch directory,
-  isolated Compose project (`mobilityops-cleandrill`) + remapped ports via
-  `compose.override.yaml`, `up --build -d` from empty volumes. Migrations ran
-  automatically to `e7b08389f47f (head)`; seeded; full backend gate **127 passed**,
-  ruff/mypy clean; `npm ci` clean (same pre-existing advisories as before, unchanged);
-  `tsc -b`/`vite build` clean; full Playwright suite **56 passed** against the isolated
-  stack; reseeded and confirmed all 5 scenarios `ready: true` via the manifest; torn down
-  (`down -v` on the isolated project only — the working dev stack was untouched
-  throughout).
-- Added the full demo-release documentation set: `docs/demo-release/demo-concept.md`,
-  `demo-scenarios.md`, `demo-data.md`, `demo-guide.md`, `demo-runbook.md`; updated
-  `README.md` (current test counts, links to the new docs, a "Demo" section) and
-  `docs/17-runbook.md` (cross-reference to the demo-specific runbook).
-- Added `frontend/e2e/_capture-demo-screenshots.spec.ts` (tooling, excluded from the
-  regular suite) and captured 17 evidence screenshots live against
-  `http://192.168.10.150:1236` into `artifacts/demo-release/screenshots/`.
-- Final live acceptance: full Playwright suite re-run against the live server —
-  **56 passed**; `docker compose ps` on the server shows `api`/`db`/`web` all healthy;
-  `docker logs` for `api`/`web` show no errors; reseeded to leave the server
-  demo-ready after evidence capture.
-- Wrote `artifacts/demo-release/final-summary.md` with the full required evidence
-  (branches/commits, org/roles/guide/scenarios, seed/date-anchor/reset strategy, real vs.
-  synthetic vs. not-connected, all test results, clean-checkout result, deployment/
-  health/console/log results, responsive/accessibility results including the two real
-  layout bugs found and fixed this work (mobile topbar overflow in Batch 3, desktop
-  guide-panel overlap in Batch 6), known limitations, 5-/10-minute demo flows, redeploy/
-  rollback commands, and the screenshot list).
-- Demo-productization work on this branch is complete. Every task (#29–#36) is done;
-  every batch was tested locally, deployed to Unraid, and re-verified live before moving
-  to the next. See `artifacts/demo-release/final-summary.md` for the definitive
-  acceptance evidence.

README.md

@@ -1,122 +1,95 @@
-# MobilityOps
+# Fleet Ops
 
-**Connected operations for vehicle rental and service teams.**
+**A recruiter-ready operations platform for vehicle rental and service teams.**
 
-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.
+**Try it in two commands** (`cp .env.example .env && make demo`, then open `http://localhost:1228`) · no password required · choose **Highlights in 90 seconds** for the shortest tour. The reference deployment runs on a private LAN (see [deploy/unraid/README.md](deploy/unraid/README.md)); ask for a link if you want the hosted version.
 
-The web application uses the premium responsive **Control Rail** interface: a compact
+Fleet Ops turns fragmented vehicle, booking and procedure data into one controlled operational workspace. It is a complete synthetic-data product demo: the company and records are fictional, while the workflows, persistence, validation, authorization, audit trail and integration boundaries are implemented.
-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.
+![Fleet Ops engineering overview](frontend/public/og-fleet-ops.svg)
 
-## Demo
+## The 90-second tour
 
-The demo presents itself as **Northstar Mobility**, a fictitious Belgian camper/van
+1. Open **Highlights** from the login screen.
-rental company — the login screen, a permanent "Synthetische demo" indicator, an in-app
+2. Follow a vehicle return from review to atomic commit, quality issue, outbox and correlated audit trace.
-guided tour (Demo Guide), a curated `/scenarios` overview, and an "Over deze demo" page
+3. Compare and merge a duplicate customer with explicit human confirmation.
-all make the fictional context, synthetic-data status, and real-vs-simulated boundaries
+4. Ask the Knowledge Hub a damage question and inspect its cited procedure evidence.
-explicit without any verbal explanation. See `docs/demo-release/` for the full demo
+5. Open **Engineering** for the architecture, reliability guarantees, test evidence and honest scope boundary.
-concept, the five named scenarios, the seed/date-anchoring strategy, the guided-tour
-design, and the operational runbook (5-minute and 10-minute demo flows, reset, redeploy,
-rollback).
 
-## Scope
+## What makes it more than a mock-up
 
-The PoC implements:
+- **Transactional operations:** a return writes the inspection, vehicle/booking state, audit events and outbox record atomically. n8n downtime never rolls back the local business transaction.
+- **Explainable data quality:** five persisted rule types, SLA deadlines, assignment, bulk queue controls and bounded resolution flows—not decorative warning cards.
+- **Grounded knowledge:** the live deployment uses RAGcore; insufficient or unavailable evidence produces no invented answer. Citations and provider provenance remain inspectable.
+- **Safe AI exposure:** four tenant-bound, service-authenticated, read-only Fleet Ops tools are published through ITWorx MCP Hub and audited with correlation IDs.
+- **Operational reliability:** bounded retries, delivery leases, health/readiness, Prometheus metrics, Grafana, scheduled verified backups and graceful external-dependency degradation.
+- **Real product ergonomics:** nl-BE, en-GB and fr-BE; responsive from 360 px; keyboard-accessible navigation; role-aware global search; route-level lazy loading; server-enforced permissions.
 
-- operations dashboard with a truthful aggregate n8n/MCP integration-status card;
+## Architecture
-- vehicle and booking views with working search, filters and pagination;
-- server-backed session lifecycle (refresh-safe, central 401 handling);
-- a role matrix enforced server-side and mirrored in the UI (see
-  `docs/12-security-and-audit.md`);
-- vehicle return capture → authoritative server-evaluated review → commit → result;
-- five deterministic data-quality checks, each with a bounded resolution flow, plus a
-  manual scan action;
-- human review and customer merge;
-- audit trail with human-readable before/after evidence and safe entity links;
-- role-aware global search across vehicles, bookings and (Operations Manager) issues;
-- safe, confirmed demo reset;
-- RAGcore-backed knowledge assistant with citations;
-- two n8n workflows: return processing, and a scheduled data-quality scan with
-  crash-recoverable outbox delivery leases;
-- four read-only MCP tools through ITWorx MCP Hub;
-- deterministic demo reset and five-minute showcase.
 
-It is not an ERP, CRM, accounting package, public booking site, payment system or autonomous agent.
+```mermaid
+flowchart LR
+    UI["React + TypeScript\nresponsive operations UI"] -->|session cookie| API["FastAPI\nbusiness rules + RBAC"]
+    API --> DB[(PostgreSQL)]
+    API -->|grounded retrieval| RAG[RAGcore]
+    DB --> OUT["Transactional outbox"]
+    OUT -->|bounded retry| N8N["Existing central n8n"]
+    N8N -->|authenticated callback| API
+    HUB["ITWorx MCP Hub"] -->|4 read-only tools| API
+```
 
-## Integration status
+Fleet Ops owns operational truth. RAGcore owns retrieval, n8n performs post-commit orchestration, and MCP Hub owns tool transport/publication. Neither RAGcore nor MCP Hub accesses the Fleet Ops database directly. See [the as-built architecture](artifacts/evidence/architecture.md).
 
-- **n8n**: fully implemented and verified against a real n8n instance, including
+## Demonstrable scope
-  degraded mode (n8n stopped mid-flow → return still commits, event stays `pending`
-  with backoff, self-heals once n8n returns), the failed-delivery manual-retry path,
-  stale-delivery-lease recovery after a simulated crash, and a second (scheduled
-  quality-scan) workflow live-verified end to end against a real n8n instance.
-  `GET /api/v1/integrations/status` reports a truthful aggregate state from outbox
-  delivery counts, not just the most recent event.
-- **RAGcore**: the demo `KnowledgeProvider` (deterministic TF-IDF extractive retrieval
-  over the local procedure documents) is what satisfies the knowledge-assistant
-  acceptance criteria and is fully verified. A `RAGcoreKnowledgeProvider` HTTP adapter is
-  implemented and unit-tested, including its unavailable-degradation path, but was never
-  exercised against a live RAGcore instance in this environment.
-- **ITWorx MCP Hub**: the four read-only provider endpoints are implemented, tested, and
-  directly `curl`-verified with correct auth enforcement and audit logging.
-  `MCP_HUB_REGISTRATION_ENABLED` is now actually wired into `Settings` (it was previously
-  declared in `.env.example` but silently dropped) and reported honestly by the
-  integration-status endpoint. No live Hub instance was reachable in this environment to
-  verify an actual Hub round trip.
 
-See `artifacts/functional-completion/final-summary.md` for the functional-completion
+- dashboard, vehicle fleet, booking lifecycle and controlled returns;
-audit evidence (supersedes the design-validation summary below for integration status),
+- data-quality queue, assignment, review, merge and resolution;
-and `artifacts/final-acceptance/summary.md` for the original M0–M7 acceptance evidence.
+- correlated human-readable audit history;
+- cited Knowledge Hub with honest provider state;
+- n8n delivery monitoring and manual retry;
+- user administration, privacy export/anonymisation and retention guards;
+- deterministic reset with 2 users, 180 customers, 50 vehicles, 254 bookings, 75 inspections, 40 maintenance records, 33 quality issues and 20 workflow runs.
 
-## Repository map
+This is deliberately not accounting, payments, a public reservation site, generic CRM, inventory, HR or an autonomous write agent.
 
-- `CLAUDE.md` — binding implementation rules.
+## Stack
-- `MASTER_BUILD_PROMPT.md` — prompt to start an autonomous Claude run.
-- `PROJECT_STATE.md` — short persistent project memory.
-- `docs/` — product, architecture, UX and acceptance specification.
-- `contracts/` — OpenAPI, event and MCP contracts.
-- `knowledge/` — fictitious source documents for the MobilityOps RAGcore workspace.
-- `seed/` — deterministic synthetic dataset and generator.
-- `n8n/` — importable workflow definitions.
-- `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.
-- `docs/functional-completion/` — the functional-completion audit and pre-work server baseline.
-- `artifacts/functional-completion/` — functional-completion acceptance evidence.
-- `docs/demo-release/` — demo concept, scenarios, seed/date-anchoring strategy, guided
-  tour, and runbook.
-- `artifacts/demo-release/` — demo-productization acceptance evidence.
 
-## Quickstart
+React, TypeScript, Vite, FastAPI, SQLAlchemy 2, PostgreSQL, Alembic, n8n, RAGcore, ITWorx MCP Hub, Docker Compose, Prometheus, Grafana and Playwright.
+
+## Run locally
 
 ```bash
 cp .env.example .env
 make demo
 ```
 
-This builds and starts the full stack (migrations run automatically) and loads the
-deterministic demo dataset. See `docs/17-runbook.md` for the one-time n8n workflow setup
-required for the automation demo, and the full operational runbook.
-
-Endpoints:
-
 - Web: `http://localhost:1228`
-- API health: `http://localhost:8128/health`
+- API readiness: `http://localhost:8128/health/ready`
-- n8n: `http://localhost:5678`
+- Existing n8n server: point `N8N_WEBHOOK_URL` at its return-processing webhook (see `.env.example`). The bundled `n8n` service in `compose.yaml` is a local fallback only; production reuses the server's central n8n (`compose.unraid.yaml` disables the bundled one).
 
-All defaults are configurable via `.env` (see `.env.example`).
+The deterministic local knowledge provider supports clean-checkout acceptance without pretending to be the live RAGcore integration. Configuration is documented in `.env.example`; operations and recovery are in [docs/17-runbook.md](docs/17-runbook.md).
 
 ## Quality gates
 
 ```bash
-make test    # backend: pytest (127 tests)
+make test    # isolated PostgreSQL backend suite
-make lint    # backend: ruff + mypy (strict, zero errors)
+make lint    # Ruff + strict mypy
-make e2e     # frontend: Playwright end-to-end (56 tests, live stack required)
+make e2e     # complete Playwright browser acceptance
+cd frontend && npm run build
+python scripts/run-readonly-load-smoke.py  # while the demo stack is running
 ```
 
-Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`).
+Release-scoped results and production evidence are recorded in [artifacts/final-acceptance/summary.md](artifacts/final-acceptance/summary.md); older milestone evidence remains explicitly historical. [PROJECT_STATE.md](PROJECT_STATE.md) records the commands and exact deployment revision.
+
+## Repository map
+
+- `backend/` — FastAPI domain, API, migrations and tests
+- `frontend/` — React app and Playwright acceptance suite
+- `contracts/` — OpenAPI, event and MCP contracts
+- `knowledge/` — versioned fictional procedures
+- `n8n/` — importable workflow definitions for the existing server
+- `seed/` — deterministic synthetic dataset
+- `docs/` — architecture, security, UX, testing and runbooks
+- `artifacts/` — dated, release-scoped acceptance evidence and screenshots
+
+“MobilityOps” remains the repository/deployment identifier; **Fleet Ops** is the product name shown to users.

SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Security support |
+|---|---|
+| Latest tagged PoC release and current `master` | Supported |
+| Older commits, branches and untagged deployments | Not supported |
+
+MobilityOps is a synthetic-data proof of concept, not a production identity,
+payments or public reservation platform. Security fixes target the current
+release line only.
+
+## Reporting a vulnerability
+
+Do not disclose suspected vulnerabilities through a public issue.
+
+Report them privately to `jens@itworx.tech` with:
+
+- the affected revision, endpoint or component;
+- reproduction steps and prerequisites;
+- the observed and expected behaviour;
+- the security impact;
+- a minimal proof of concept, without unnecessary personal or secret data.
+
+Receipt should be acknowledged within three business days. An initial
+assessment or request for additional evidence should follow within ten
+business days. Remediation timing depends on severity and reproducibility.
+
+## Scope
+
+In scope:
+
+- MobilityOps backend, frontend, container and deployment code;
+- authentication, authorization, tenant boundaries and audit integrity;
+- database, outbox, backup and restore behaviour;
+- MobilityOps-owned n8n workflow definitions;
+- RAGcore and MCP Hub integration boundaries implemented in this repository.
+
+Out of scope:
+
+- denial-of-service or destructive testing against the hosted demo;
+- social engineering, credential stuffing or physical attacks;
+- synthetic demo-data exposure without a security-boundary failure;
+- vulnerabilities solely inside RAGcore, ITWorx MCP Hub, n8n or another
+  third-party service. Report those to their respective owners.
+
+Do not access data beyond what is required to demonstrate the issue, modify
+shared infrastructure, interrupt other services or retain obtained secrets.
+
+## Coordinated disclosure
+
+Good-faith research that respects this policy and applicable law will be
+handled constructively. Allow a reasonable remediation period before public
+disclosure. Submitted reports and evidence are used only for investigation,
+remediation and verification.

START_HERE.md

@@ -1,39 +0,0 @@
-# MobilityOps — Claude build pack
-
-MobilityOps is a deliberately scoped, working proof of concept for a fictitious Belgian mobility-rental company. It demonstrates how operational data, workflow automation, data-quality review, a central RAG service and a central MCP hub can work together without pretending to be a full ERP.
-
-## Use this pack efficiently
-
-1. Extract this archive into a new repository.
-2. Open the repository in Claude Code.
-3. Paste the contents of `MASTER_BUILD_PROMPT.md` once.
-4. Let Claude continue autonomously through the milestones in `docs/15-build-plan.md`.
-5. Only intervene if the environment itself is unavailable or credentials for an external service are required.
-
-Claude must use `PROJECT_STATE.md` as its compact memory between sessions. Do not restate the full project in later prompts.
-
-## What is included
-
-- locked product scope and non-goals;
-- architecture and domain decisions;
-- API and event contracts;
-- realistic deterministic synthetic seed data;
-- ten fictitious procedures for RAGcore;
-- an initial n8n workflow export;
-- MCP tool definitions for ITWorx MCP Hub;
-- a minimal bootable frontend/API scaffold;
-- acceptance criteria and a five-minute demo script;
-- a master prompt optimized for one autonomous build run.
-
-## Core responsibilities
-
-| Component | Responsibility |
-|---|---|
-| MobilityOps | Operational data, business rules, UI, audit and data-quality review |
-| RAGcore | Document ingestion, retrieval and source-grounded answers |
-| ITWorx MCP Hub | Controlled AI access to MobilityOps tools and MobilityOps knowledge |
-| n8n | Cross-system orchestration after committed domain events |
-
-## Build principle
-
-Finish a small vertical slice completely. No placeholder pages, fake buttons, invented production claims or scope expansion.

artifacts/.gitignore

@@ -0,0 +1,14 @@
+# Generated live deployment and demo evidence must stay outside source control.
+demo-release/
+deployment/
+screenshots/
+*.log
+*.db
+*.db-wal
+*.db-shm
+*.zip
+*.tar
+*.tar.gz
+
+# Keep this policy file.
+!.gitignore

artifacts/demo-release/final-summary.md

@@ -1,195 +0,0 @@
-# Demo-productization final summary
-
-## Branches and commits
-
-- **Gitea repository**: `ssh://git@192.168.10.150:222/Jens/MobilityOps.git` (browsable at
-  `http://192.168.10.150:3000/Jens/MobilityOps`)
-- **Branch**: `feat/mobilityops-functional-completion` (no new branch created; no merge
-  to `main`; no rebase/reset/squash/force-push; full git history preserved, as required)
-- **Start commit** (functional-completion baseline, already accepted):
-  `e0c7ed60112510687627d20a957af91c8b9db7f8`
-- **Final commit**: `4a268c73515dc4f1d56c1aa2f231714654bffbb8` — verified via
-  `git rev-parse HEAD` on `feat/mobilityops-functional-completion` and confirmed to match
-  `/mnt/user/appdata/mobilityops/.deploy/source-revision` on the Unraid server exactly.
-  (This corrects a self-reference gap in the immediately preceding pair of commits, which
-  necessarily could not know their own hash at the time they were written; this is now
-  the single, unambiguous, verified reference. The repository's primary branch is
-  `master`, not `main` — no branch named `main` exists in this repository.)
-- **Live URL**: `http://192.168.10.150:1236`
-
-## Demo organisation and context
-
-**Northstar Mobility** — a fictitious Belgian camper/van rental company (~50 vehicles,
-one main location, rental team, an Operations Manager, a small workshop). This name was
-already a locked internal decision (`ragcore_tenant: northstar-mobility-demo`,
-`PROJECT_STATE.md`'s "Locked decisions") before this work — this pass surfaces it in the
-UI rather than inventing it. Full concept: `docs/demo-release/demo-concept.md`.
-
-## Roles
-
-- **Operations Manager** — full access: data-quality resolution, workflow retries, audit
-  trail, demo reset, the Demo Guide.
-- **Rental Employee** — scoped access: bookings, returns, fleet, knowledge assistant.
-
-Both are reachable from the login screen with no password.
-
-## Demo Guide
-
-An 8-step, sessionStorage-persisted guided tour (Operations-Manager-only, since every
-step requires that role). Full design: `docs/demo-release/demo-guide.md`. Steps: (1)
-understand operational state, (2) open the booking needing attention, (3) process the
-odometer-anomaly return, (4) handle the created data-quality issue, (5) merge the
-duplicate customer, (6) ask the knowledge assistant, (7) check automation + audit, (8)
-review real vs. synthetic vs. not-connected.
-
-## Scenarios (all 5, full detail in `docs/demo-release/demo-scenarios.md`)
-
-| # | Scenario | Fixed records | Role |
-|---|---|---|---|
-| 1 | Odometer regression on return | `BK-DEMO-RETURN` / `MO-024` | Either |
-| 2 | Possible duplicate customer | `CUS-0012` / `CUS-0178` / `DQ-DEMO-DUPLICATE` | OM |
-| 3 | Overlapping bookings | `MO-016` / `BK-DEMO-OVERLAP-A/B` / `DQ-DEMO-OVERLAP` | OM |
-| 4 | Failed automation, retried | outbox event `...020` / `BK-H-0020` | OM |
-| 5 | Grounded procedure question | (no fixed record; suggested questions) | Either |
-
-`GET /api/v1/demo/manifest`'s `scenarios` array derives `ready`/`blocked_reason` from the
-live underlying records, never hardcoded — confirmed via `backend/tests/
-test_demo_manifest.py` (`test_demo_manifest_scenarios_ready_after_fresh_reset`) and
-live-checked after every reset throughout this work.
-
-## Seed strategy and date-anchoring
-
-`seed/generate_seed.py --anchor 2026-08-01 --seed 20260801` produces deterministic CSVs
-with absolute timestamps authored against a fixed anchor. `backend/app/seed_loader.py`
-shifts every seeded datetime by `(real today − authored anchor)` on every seed/reset, so
-"today"/"near-future"/"currently overlapping" scenarios stay true to the actual reset
-moment instead of decaying. This fixed a real, confirmed bug (`BK-DEMO-RETURN` was found
-sitting 2 days in the past before this fix). Full detail: `docs/demo-release/demo-data.md`.
-
-## Reset strategy
-
-`POST /api/v1/demo/reset` (Operations Manager only, gated by `DEMO_ALLOW_RESET`) clears
-MobilityOps's own tables, reseeds with a fresh date anchor, re-runs the data-quality scan,
-and runs a server-side scenario-integrity check (`scenario_integrity_report()`) recorded
-in both the response and the `demo_reset` audit event. Reachable from the sidebar, the
-Demo Guide, and the About page. Never touches shared n8n/RAGcore/MCP data, other
-containers, or volumes.
-
-## Real vs. synthetic vs. not-connected
-
-See `docs/demo-release/demo-concept.md` for the full breakdown. In short: auth/roles,
-vehicle/booking management, return preview/commit, the 5 data-quality rules and their
-resolutions, the audit trail, n8n orchestration, Docker deployment, and the automated
-test suite are all really implemented. The organisation, all people, vehicles, bookings,
-procedures, and the 5 named scenarios are synthetic. RAGcore and the ITWorx MCP Hub are
-not live-connected (honestly labelled "Demomodus"/"Niet gekoppeld" everywhere, never a
-fabricated success).
-
-## Test results
-
-### Backend (clean checkout, isolated stack)
-- `pytest`: **127 passed**
-- `ruff check .`: clean
-- `mypy app`: clean (48 source files)
-
-### Frontend (clean checkout, isolated stack)
-- `npm ci`: clean (pre-existing esbuild-moderate/react-router-RSC-high advisories,
-  unchanged from before this work — not introduced by it)
-- `tsc -b`: clean
-- `npm run build`: clean
-- Full Playwright suite: **56 passed** (against the isolated clean-checkout stack)
-
-### Guided-demo test
-`frontend/e2e/guided-demo-full.spec.ts` — one comprehensive test walking a fresh
-Operations Manager session through all 8 Demo Guide steps performing the real action at
-each step (processes the actual odometer-anomaly return, resolves the resulting
-data-quality issue, merges the duplicate customer, asks a suggested knowledge question,
-checks automation + audit, reviews the About page), then resets the demo data again to
-restore the environment. **Passed**, confirmed stable across repeated runs both locally
-and against the live Unraid deployment.
-
-### Clean-checkout drill
-Fresh `git clone` of this branch/commit into an isolated scratch directory, `.env` from
-`.env.example`, isolated Compose project name (`mobilityops-cleandrill`) and remapped
-host ports (`compose.override.yaml` with `!override` merge tags — no shared state with
-any other stack), `docker compose up --build -d` from empty volumes → migrations ran
-automatically (`e7b08389f47f (head)`) → seeded → full backend gate (127 passed, ruff/
-mypy clean) → `npm ci`/`tsc -b`/`vite build` clean → full Playwright suite (56 passed)
-→ reseeded and confirmed all 5 scenarios `ready: true` via the manifest → torn down
-(`docker compose down -v` on the isolated project only; the working dev stack was never
-touched).
-
-### Server deployment
-Deployed incrementally after every batch (10 deploy cycles across this work); final
-state: both `api` and `web` rebuilt and healthy at the final commit, `db` untouched
-across all of them (no destructive migrations on this branch). Migrations at
-`e7b08389f47f (head)` throughout. `.deploy/source-revision` on the server matches the
-final commit exactly.
-
-### Container health
-`docker compose ps` on the server: `api`, `db`, `web` all `healthy`, no restart loops.
-
-### Browser console / network
-No unexpected console errors on login, dashboard, scenarios, About, or with the Demo
-Guide open (verified via `demo-accessibility.spec.ts`; the one benign 401 from the app's
-own session-probe on first load is expected and explicitly accounted for, not silenced
-blindly). No unresolved server errors in `docker logs` for `api`/`web` at the time of
-this evidence capture.
-
-### Responsive / accessibility
-- Demo Guide renders as a correctly-anchored bottom sheet at 390px with no horizontal
-  overflow (`demo-accessibility.spec.ts`).
-- **Real bug found and fixed**: the Demo Guide's fixed desktop side panel overlapped
-  main content with no reflow, making the return form's "Review return" button
-  unclickable while the guide was open at ordinary desktop widths — this surfaced while
-  writing the full guided-demo test. Fixed via a `guide-open` layout class that reserves
-  space for the panel; regression-tested.
-- Demo badge and Demo Guide triggers are keyboard-focusable and operable (Enter to open,
-  explicit close controls).
-- Existing responsive-overflow checks (390/768/1280/1440px) remain green throughout.
-
-## Known limitations
-
-- RAGcore and the ITWorx MCP Hub are not live-connected in this environment (by design
-  — see scope). The knowledge assistant uses a local, English-only demo knowledge base;
-  a Dutch question against it returns "insufficient evidence" (verified empirically), so
-  suggested questions and the Demo Guide's step 6 instructions deliberately stay in
-  English rather than silently breaking the demo's centerpiece grounded-answer feature.
-- Existing operational screens (Dashboard, Vehicles, Bookings, Data Quality workbench,
-  Audit, Automation internals) remain in English; only new demo-productization surfaces
-  (login, Demo Guide, scenario overview, About page, demo badge, plain-language
-  integration labels) are in Dutch — a deliberate, documented scope decision, not an
-  oversight (`docs/demo-release/current-demo-gap-audit.md`, gap #11).
-- Scenario S3 ("missing inspection before next booking", `MO-031`) is seeded and visible
-  in the attention queue but isn't one of the 5 scenarios surfaced on `/scenarios`,
-  matching the brief's request for exactly 5.
-
-## 5-minute and 10-minute demo flows
-
-See `docs/demo-release/demo-runbook.md` for the exact click-through scripts.
-
-## Redeploy commands and rollback procedure
-
-See `docs/demo-release/demo-runbook.md` — `git archive` → `scp` → extract → rebuild
-`api`/`web` → confirm migrations → reseed. Rollback: extract an earlier
-`.deploy/source-<short-sha>.tar.gz` and update `.deploy/source-revision` to match.
-
-## Evidence screenshots
-
-All captured live against `http://192.168.10.150:1236` (`artifacts/demo-release/screenshots/`):
-
-1. `01-demo-entry-desktop.png` / `02-demo-entry-mobile.png` — demo entry, both sizes
-2. `03-dashboard-with-scenarios.png` — dashboard with the scenario teaser panel
-3. `04-demo-guide.png` — the Demo Guide panel open
-4. `05-return-preview.png` / `06-return-result.png` — the return flow
-5. `07-data-quality-resolution.png` — a data-quality issue with its plain-language explainer
-6. `08-duplicate-customer-merge.png` — the duplicate-customer comparison/merge UI
-7. `09-knowledge-assistant.png` — a grounded answer with cited sources
-8. `10-integration-status.png` — plain-language integration status on Automation
-9. `11-automation-retry-before.png` / `11-automation-retry-after.png` — a workflow retry
-10. `12-audit-trail.png` / `13-audit-related-events.png` — audit trail + correlation drill-down
-11. `14-about-demo.png` — the About page
-12. `15-demo-badge-popover.png` — the permanent synthetic-demo badge popover
-13. `16-reset-confirm.png` — the reset confirmation flow
-
-No secrets appear in any screenshot or in this document.

artifacts/deployment/unraid-summary.md

@@ -1,145 +0,0 @@
-# MobilityOps Unraid deployment evidence
-
-## Outcome
-
-- Deployment: **PASS**
-- Gitea publication: **PASS**
-- Gitea URL: `https://gitea.itworx.tech/Jens/MobilityOps`
-- Visibility: private (verified in the Gitea web UI)
-- Branch: `master`
-- Verified baseline commit: `4bf9afbeff44088864e0844769d4dd0e4089d85b`
-- Deployment implementation commit: `1e13943cffb2da8a328b5b1ea5e9b1fe73fdd774`
-- Server: `192.168.10.150`
-- Server directory: `/mnt/user/appdata/mobilityops`
-- Compose project: `mobilityops`
-- Application URL: `http://192.168.10.150:1236`
-- Port mapping: LAN `0.0.0.0:1236` / `[::]:1236` to `web:80`
-
-## Services and health
-
-| Service | Runtime state | Health | Host exposure |
-|---|---|---|---|
-| `db` | running, 0 restarts | healthy | none (`5432/tcp` internal) |
-| `api` | running, 0 restarts | healthy | none (`8000/tcp` internal) |
-| `web` | running, 0 restarts | healthy | `1236:80` on LAN |
-| shared host `n8n` | running | healthy | `5678:5678` on LAN; outside MobilityOps Compose |
-
-The final review topology reuses the n8n container that was already running on the host.
-Its empty public-host/editor URL settings were corrected in the persistent Unraid template
-so workflow execution URLs are valid. The temporary Compose-owned n8n container was
-removed without deleting its retained volume. Port `1236` was confirmed unused before the
-original deployment; the application directory was created specifically for MobilityOps.
-
-## Deployment commands
-
-The existing SSH aliases resolve to the requested hosts and keys (`gitea.itworx.tech`
-for Gitea SSH and `unraid` for root access). No key was created, copied, or replaced.
-The committed source was transferred from the workstation; Unraid has no Gitea key.
-
-Repository publication used the SSH clone URL supplied by Gitea:
-
-```bash
-git remote add origin ssh://git@192.168.10.150:222/Jens/MobilityOps.git
-git push -u origin master
-git push origin --tags
-```
-
-Git and the Gitea web UI both verified `master` as the default branch, the full commit
-history, baseline commit `4bf9afbeff44088864e0844769d4dd0e4089d85b`, and zero tags.
-The remote tree contains no `.env`, local database, `node_modules`, virtual environment,
-test cache, build cache, Playwright output, or browser binaries.
-
-```bash
-git archive --format=tar.gz --output=<temporary-archive> <commit>
-scp <temporary-archive> unraid:/mnt/user/appdata/mobilityops/.deploy/source.tar.gz
-ssh unraid
-cd /mnt/user/appdata/mobilityops
-tar -xzf .deploy/source.tar.gz
-./deploy/unraid/configure-env.sh http://192.168.10.150:1236
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml up --build -d db api web
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec -T api \
-  python -m app.cli seed --reset
-./deploy/unraid/setup-existing-n8n.sh \
-  n8n \
-  http://192.168.10.150:1236/api/v1/integrations/n8n/return-callback
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml up -d db api web
-```
-
-The server `.env` was created from `.env.example`, is mode `0600`, and contains generated
-runtime secrets. Secret values and n8n owner credentials remain server-only and are not
-included here or in Git.
-
-## Validation evidence
-
-- Migration: `e7b08389f47f (head)`.
-- Deterministic seed: users 2, customers 180, vehicles 50, bookings 246, inspections 75,
-  maintenance 40, data-quality issues 26, workflow runs 20.
-- HTTP: `GET /` returned 200; `GET /health` returned
-  `{"status":"ok","service":"mobilityops-api"}` through the web proxy.
-- Backend gates in an isolated local Compose project: 66 tests passed, Ruff clean, mypy
-  clean across 44 files.
-- Frontend: `npm ci && npm run build` completed (`tsc -b && vite build`).
-- Logs: no traceback, fatal, uncaught, or unresolved startup error in the deployment log
-  scan. Browser console had no warnings or errors during the smoke test.
-- Browser smoke test in Chrome: Operations Manager demo login, Dashboard, Vehicles,
-  Bookings, Data Quality, Knowledge, Automation, and Audit all loaded from the LAN URL.
-- Dashboard showed persisted seed metrics (21 available, 11 rented, 6 cleaning,
-  5 maintenance, 7 blocked, 22 open issues, 1 pending/failed workflow).
-- Return workflow: `BK-DEMO-RETURN` accepted 54,700 km, created `INSP-0076` and
-  `DQ-RET-0076`, preserved the 54,820 km canonical odometer, and changed the booking to
-  returned.
-- Shared-n8n round trip: final post-deploy event `98eb06dc-0bcc-4e3d-96ec-c23b2d266293`
-  reached `succeeded` on attempt 1 with no last error; the deterministic reset afterwards
-  restored `BK-DEMO-RETURN` to `active`.
-- Data quality: `DQ-RET-0076` displayed the persisted regression evidence and related
-  booking/inspection references.
-- Knowledge: UI truthfully showed `Provider: demo · available · 10 procedures indexed`;
-  the damage question returned grounded excerpts and citations from the local procedures.
-
-## Integration status
-
-- RAGcore: disabled for this deployment; `KNOWLEDGE_PROVIDER=demo`. No claim of a live
-  RAGcore connection is shown. Operational functionality is unaffected.
-- ITWorx MCP Hub: registration disabled with `MCP_HUB_REGISTRATION_ENABLED=false`; the
-  independently authenticated provider endpoints remain available internally to the web
-  proxy/API boundary, but no live Hub connection is claimed.
-- n8n: the existing server instance at `http://192.168.10.150:5678` is healthy; the
-  MobilityOps workflow is imported/published there and a real return delivery succeeded.
-  The bundled MobilityOps service is disabled by default in the Unraid overlay.
-
-## Known limitations
-
-- RAGcore and ITWorx MCP Hub are intentionally not connected yet.
-- Demo authentication remains the accepted HMAC-cookie PoC mechanism.
-- The dependency advisories already documented in final acceptance remain unchanged.
-
-## Redeploy
-
-From the workstation, create an archive of the desired committed revision and transfer it
-to `.deploy/source.tar.gz`. On Unraid, preserve `.env` and the named volumes, then run:
-
-```bash
-cd /mnt/user/appdata/mobilityops
-tar -xzf .deploy/source.tar.gz
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml up --build -d db api web
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec -T api alembic current
-curl -fsS http://127.0.0.1:1236/health
-```
-
-## Logs
-
-```bash
-cd /mnt/user/appdata/mobilityops
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml ps
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml logs --tail=200
-docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml logs -f api web
-docker logs -f n8n
-```
-
-## Safe rollback
-
-Choose a known-good commit on the workstation, archive and transfer it as above, then on
-Unraid extract it over the identifiable MobilityOps source directory and run the same
-`up --build -d` command. Preserve `.env` and both named volumes; do not use `down -v`,
-remove volumes, prune Docker, or modify unrelated containers. Check the target commit's
-Alembic compatibility before rolling application code behind the current database schema.

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

@@ -1,89 +0,0 @@
-# MobilityOps premium UI evidence summary
-
-Date: 2026-08-02
-Branch: `design/mobilityops-premium-ui`
-Baseline revision: `dfabb41582e302f45a3de826f85f531bf23dfc8b`
-Final design implementation commit: `1f292e14bb6a2e8ded5dc675b1b3360307d8a9ae`
-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; 240.24 kB JS and 36.63 kB CSS before gzip |
-| Browser journeys | 19 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 |
-| Deployed browser smoke | passed on all 10 authenticated routes plus login at desktop and mobile sizes |
-| Console/network | 0 browser warnings/errors; 7 authenticated API paths returned HTTP 200 |
-| Deployed global search | Ctrl+K plus `MO-024` navigation passed against the review URL |
-
-All displayed operational counts remain derived from the existing persisted API data.
-Synthetic-data labelling is persistent on login and authenticated surfaces.
-
-Deployed evidence is stored in `artifacts/design-validation/implementation/deployed/`.
-The review stack reports healthy PostgreSQL/API state, HTTP 200 from the web application,
-and healthy state from the server's existing n8n at port 5678. A synthetic return reached
-`succeeded` on attempt 1 through that shared n8n and its MobilityOps callback; the demo was
-then reset to its deterministic state.
-
-## 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 resolves Control Rail sections and `MO-*`, `BK-*`, `DQ-*` public
-  references. It intentionally does not offer customer lookup because the locked PoC has
-  no customer detail route or cross-entity search API.
-- The repository retains a bundled n8n service for standalone local clean-checkout demos.
-  The Unraid overlay keeps it behind the opt-in `bundled-n8n` profile; the live review
-  deployment uses the server's existing shared n8n instead.
-- 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.

artifacts/evidence/architecture.md

@@ -1,63 +1,68 @@
-# MobilityOps — as-built architecture
+# Fleet Ops — as-built architecture
 
 ```mermaid
 flowchart TB
-    subgraph Browser
+    UI["Fleet Ops Web\nReact + TypeScript + Vite"]
-        UI["MobilityOps Web<br/>React + TypeScript"]
-    end
 
-    subgraph MobilityOps["MobilityOps (this repo)"]
+    subgraph CORE["Fleet Ops — this repository"]
-        API["FastAPI backend<br/>/api/v1/*"]
+        API["FastAPI /api/v1\nRBAC + domain rules"]
-        DISPATCH["Outbox dispatcher<br/>background thread"]
+        OUT["Outbox dispatcher\nleases + bounded retry"]
         DB[(PostgreSQL)]
+        OBS["Prometheus metrics\nGrafana dashboards"]
         API --> DB
-        DISPATCH --> DB
+        OUT --> DB
+        API --> OBS
     end
 
-    subgraph External["External central services"]
+    subgraph EXT["Existing external platforms"]
-        N8N["n8n<br/>return-processing workflow"]
+        N8N["Central n8n\nsecondary orchestration"]
-        RAGDEMO["Demo KnowledgeProvider<br/>TF-IDF extractive, local files"]
+        RAG["RAGcore\ngrounded procedure retrieval"]
-        RAGCORE["RAGcore<br/>(adapter built, no live instance)"]
+        HUB["ITWorx MCP Hub\ntool transport + publication"]
-        HUB["ITWorx MCP Hub<br/>(endpoints built, no live instance)"]
     end
 
-    UI -->|session cookie| API
+    UI -->|secure session cookie| API
-    API -->|GroundedAnswer| RAGDEMO
+    API -->|tenant/workspace adapter| RAG
-    API -.->|configurable, unavailable-safe| RAGCORE
+    OUT -->|vehicle.returned.v1| N8N
-    DISPATCH -->|POST vehicle.returned.v1| N8N
+    N8N -->|service-authenticated callback| API
-    N8N -->|callback, X-Service-Token| API
+    HUB -->|service-authenticated read-only tools| API
-    HUB -.->|X-Service-Token, read-only| API
-
-    classDef unverified stroke-dasharray: 5 5;
-    class RAGCORE,HUB unverified;
 ```
 
-Dashed boxes/arrows are implemented and unit/contract-tested but were never exercised
+## Ownership and trust boundaries
-against a live instance in this environment (no reachable RAGcore or ITWorx MCP Hub).
-Solid boxes were verified end-to-end, including a real n8n instance.
 
-## Component responsibility (unchanged from `docs/03-architecture.md`)
+| Component | Owns | Explicitly does not own |
+|---|---|---|
+| Fleet Ops | vehicles, customers, bookings, inspections, quality issues, audit, permissions, outbox state | external workflow execution or procedure retrieval |
+| RAGcore | indexing/retrieval and grounded procedure evidence | Fleet Ops database or business state |
+| ITWorx MCP Hub | MCP transport, connector publication and central tool-call audit | Fleet Ops database or write actions |
+| n8n | post-commit workflow orchestration | critical business rules or the source-of-truth transaction |
 
-| Component | Owns |
+## End-to-end return trace
-|---|---|
-| MobilityOps | vehicles, customers, bookings, inspections, data-quality issues, audit, outbox/delivery state |
-| RAGcore | procedure retrieval and grounded answers (demo provider substitutes locally) |
-| ITWorx MCP Hub | MCP transport, tool publication, central tool-call audit |
-| n8n | post-commit secondary orchestration only — never the source of truth for vehicle state |
 
-## Reliability boundaries verified in this build
+```mermaid
+sequenceDiagram
+    actor Operator
+    participant Web
+    participant API
+    participant DB
+    participant n8n
+    Operator->>Web: Review and confirm return
+    Web->>API: POST return with idempotency key
+    API->>DB: Lock booking and validate invariants
+    API->>DB: Commit inspection, state, audit and outbox atomically
+    API-->>Web: Result + correlation ID
+    Web-->>Operator: Human result and full processing trace
+    API->>n8n: Deliver persisted outbox event
+    n8n->>API: Authenticated status callback
+    API->>DB: Persist delivery/audit evidence
+```
 
-1. **Return commits atomically with its outbox event** — `app/services/returns.py`, one
+## Verified reliability properties
-   transaction; verified by `test_concurrent_returns_only_one_succeeds` (real Postgres row
+
-   locking, not mocked).
+1. Concurrent returns serialize through PostgreSQL row locking; only one can commit.
-2. **Outbox delivery is at-least-once, idempotent by event ID** — verified live: the n8n
+2. Local return success is independent of n8n availability. Pending delivery remains persisted and retryable.
-   callback checks for an existing `AuditEvent` by event ID before recording a second time.
+3. Outbox delivery is at-least-once and idempotent by event ID, with crash-recoverable leases and bounded backoff.
-3. **RAGcore failure disables knowledge answers only** — `RAGcoreKnowledgeProvider` degrades
+4. RAGcore failure affects knowledge answers only. The UI reports unavailable/insufficient evidence and does not invent an answer.
-   to `unavailable`; the rest of the app is unaffected because the knowledge router is the
+5. MCP endpoints are a separate tenant-bound, client-identity-validated, read-only surface; every call is audited with a correlation ID.
-   only consumer.
+6. Browser authorization is enforced again on the API. Hiding a navigation item is never the security boundary.
-4. **MCP Hub failure does not affect the web application** — the four MCP provider
+
-   endpoints are a separate authenticated surface (`X-Service-Token`), invisible to the
+The live deployment has exercised all three external boundaries. Local clean-checkout acceptance can use the deterministic extractive knowledge provider while reporting that mode honestly.
-   browser-facing API/UI.
-5. **n8n failure leaves events pending with bounded retries** — verified live: a seeded
-   `failed` event, retried through the UI, was picked up by the background dispatcher and
-   delivered through the real n8n instance within one poll cycle.

artifacts/evidence/final-summary.md

@@ -1,177 +0,0 @@
-# MobilityOps — final acceptance evidence
-
-## Commit
-
-Built on top of commit `c5b7e21f81694f0339ad31e3bf044db952d0fbe0` (M6, "implement ITWorx
-MCP Hub publication"). This evidence file and the rest of M7's polish are committed as
-`M7: portfolio polish and final acceptance` — run `git log --oneline` for the exact hash.
-
-## Exact commands (clean checkout)
-
-```bash
-git clone <repo> && cd MobilityOps
-cp .env.example .env
-make demo          # docker compose up --build -d ; migrations run automatically ; seed --reset
-```
-
-One-time n8n setup (see `docs/17-runbook.md` for full detail — this cannot be scripted
-end-to-end because it requires a one-time owner account created through n8n's web UI):
-
-```bash
-# open http://localhost:5678/setup in a browser, create any owner account
-make n8n-setup
-```
-
-Verification:
-
-```bash
-docker compose run --rm api pytest -q       # 66 passed
-docker compose run --rm api ruff check .    # All checks passed
-cd frontend && npm run build                # clean tsc + vite build
-cd frontend && npx playwright test          # 1 passed (full 5-minute demo script)
-```
-
-## Test counts
-
-- **Backend**: 66 tests passing (`pytest`), 0 skipped, 0 failed. Ruff clean. Coverage by
-  area: seed determinism (2), auth/roles (4), dashboard (3), vehicles (4), bookings (3),
-  return workflow incl. real concurrent-submission test (9), data quality incl. S2/S4
-  scenarios (10), audit (2), n8n dispatcher incl. malformed-payload regression (6),
-  n8n callback idempotency (3), workflows/retry (4), knowledge incl. S6 scenario (7),
-  MCP provider endpoints (8), health (1).
-- **Frontend**: `npm run build` — clean TypeScript + Vite build, zero errors.
-- **End-to-end**: 1 Playwright test (`frontend/e2e/demo.spec.ts`) automating the full
-  documented 5-minute demo script (login → dashboard → S1 return → S2 merge → S6 knowledge
-  question → audit → 360px responsive check) — **passing** against the live stack.
-
-## Screenshots of the seven main pages
-
-Captured live against the deterministic seed (`artifacts/evidence/screenshots/`,
-via `frontend/e2e/_capture-screenshots.spec.ts`):
-
-| # | Page | File |
-|---|---|---|
-| 1 | Login | `1-login.png` |
-| 2 | Dashboard | `2-dashboard.png` |
-| 3 | Vehicles | `3-vehicles.png` |
-| 4 | Bookings | `4-bookings.png` |
-| 5 | Data Quality | `5-data-quality.png` |
-| 6 | Knowledge (grounded S6 answer) | `6-knowledge.png` |
-| 7 | Automation | `7-automation.png` |
-| — | Audit (bonus, 8th nav item) | `8-audit.png` |
-| — | Dashboard at 360px (responsive proof) | `9-mobile-dashboard.png` |
-
-## RAGcore evidence
-
-**Success (demo provider, the one actually satisfying acceptance in this environment)** —
-S6 question against the real `/api/v1/knowledge/questions` endpoint:
-
-```json
-{
-  "answer": "Per \"Vehicle return procedure\" (v2.0), section \"1. Register the return\": Open the active booking and record the ending odometer, fuel level, cleanliness, visible damage, technical warnings and relevant notes.",
-  "evidence_state": "grounded",
-  "sources": [
-    {"document_id": "vehicle-return-procedure", "title": "Vehicle return procedure", "version": "2.0", "section": "1. Register the return", "excerpt": "..."},
-    {"document_id": "vehicle-return-procedure", "title": "Vehicle return procedure", "version": "2.0", "section": "3. Determine next state", "excerpt": "..."},
-    {"document_id": "damage-procedure", "title": "Damage handling procedure", "version": "1.3", "section": "1. Immediate actions", "excerpt": "..."}
-  ],
-  "provider": "demo",
-  "correlation_id": "b50094b7-1c84-4e39-9055-1dc03e8fd1f8"
-}
-```
-
-**Unavailable (RAGcore adapter, live-demonstrated against an unreachable host)** —
-`KNOWLEDGE_PROVIDER=ragcore`, `RAGCORE_BASE_URL=http://ragcore-not-reachable:9999`:
-
-```
-health: {'provider': 'ragcore', 'available': False, 'detail': 'RAGcore unavailable: ConnectError: ...', 'document_count': 0}
-ask:    {'answer': '', 'evidence_state': 'unavailable', 'sources': [], 'provider': 'ragcore', 'correlation_id': 'demo-correlation'}
-```
-
-No live RAGcore instance was reachable in this environment, so the adapter's actual
-request/response contract against a real RAGcore is unverified beyond this
-degrade-safely behavior — see `contracts/ragcore-contract-assumptions.md` and
-`PROJECT_STATE.md`'s M5 notes.
-
-## n8n evidence
-
-**Success** — a real return registered on `BK-DEMO-RETURN`, delivered through the actual
-n8n instance (not mocked), confirmed via `GET /api/v1/workflows`:
-
-```json
-{"event_id": "aa5dfeee-90ca-452a-bdd1-0a0b6d3dd63f", "event_type": "vehicle.returned.v1", "aggregate_ref": "BK-DEMO-RETURN", "status": "succeeded", "attempts": 2, "last_error": null}
-```
-
-(`attempts: 2` because the first delivery attempt landed while n8n was mid-restart from
-the one-time workflow-activation step — the dispatcher's backoff-and-retry handled it
-without any manual intervention, which is itself evidence of the retry behavior working.)
-
-**Retry (S5 scenario)** — seeded `BK-H-0020` (event `00000000-...-0020`), initially
-`failed` after 3 attempts with `"Synthetic connection timeout to n8n"`:
-
-1. Before: `{"status": "failed", "attempts": 3, "last_error": "Synthetic connection timeout to n8n"}`
-2. Operations Manager clicks Retry on `/automation`.
-3. Within one ~3s dispatcher poll cycle, delivered through the live n8n instance.
-4. After: `{"status": "succeeded", "attempts": 4, "last_error": null}`
-
-## MCP tool sample calls
-
-All four provider endpoints, authenticated with `X-Service-Token`:
-
-```
-$ curl -H "X-Service-Token: <token>" http://localhost:8128/api/v1/integrations/mcp/operations-summary
-{"tenant":"northstar-mobility-demo","metrics":{"available":21,"rented":11,"cleaning":6,"maintenance":5,"blocked":7,"open_quality_issues":22,"pending_or_failed_workflows":1}}
-
-$ curl -H "X-Service-Token: <token>" "http://localhost:8128/api/v1/integrations/mcp/attention-vehicles?minimum_severity=high&limit=3"
-[{"vehicle_ref":"MO-016","severity":"high","rule_type":"booking_overlap",...},
- {"vehicle_ref":"MO-016","severity":"high","rule_type":"vehicle_status_conflict",...},
- {"vehicle_ref":"MO-031","severity":"high","rule_type":"missing_required_field",...}]
-
-$ curl -H "X-Service-Token: <token>" http://localhost:8128/api/v1/integrations/mcp/vehicles/MO-016
-{"public_ref":"MO-016","make":"Hymer","model":"Exsis","model_year":2021,"location":"Geel","operational_status":"available","odometer_km":30497,"next_service_km":40000,"open_quality_issue_count":2,"current_booking_ref":null}
-
-$ curl -H "X-Service-Token: <token>" -X POST -d '{"question":"What must I do when a vehicle returns with damage?","max_sources":2}' http://localhost:8128/api/v1/integrations/mcp/search-knowledge
-{"answer":"Per \"Vehicle return procedure\" ...","evidence_state":"grounded","sources":[...2 items...],"provider":"demo",...}
-```
-
-Auth verified: missing header → `422`; wrong token → `401`. All four calls confirmed
-recorded in `GET /api/v1/audit?action=mcp_tool_request` with `actor_type: "service"`.
-
-No live ITWorx MCP Hub instance was reachable in this environment — these are direct
-calls to MobilityOps's own provider endpoints, not a Hub round trip.
-
-## Known PoC limitations
-
-- **RAGcore and ITWorx MCP Hub were never reachable in this build environment.** Both
-  integrations are implemented against best-effort/documented contracts and are
-  unit/contract-tested (including their failure-degradation paths), but neither was
-  verified against a real counterpart service. The demo `KnowledgeProvider` is what
-  actually satisfies the knowledge-assistant acceptance criteria here.
-- **n8n requires a one-time manual owner-account setup** per fresh environment
-  (`docker compose down -v` wipes it) — this is a property of the n8n 2.x image itself
-  (`N8N_BASIC_AUTH_ACTIVE` no longer gates the UI), not something MobilityOps can bypass.
-  Documented precisely in `docs/17-runbook.md`; the workflow import/activation itself
-  *is* scripted (`make n8n-setup`).
-- **Inspection public refs are a simple `count+1` sequence**, not gap-safe under true
-  concurrent writers — acceptable for this single-tenant demo, would need a DB sequence
-  for a multi-writer production system.
-- **The five data-quality rules use simplified idempotency** — `(rule_type, entity_type,
-  entity_id)` while open, rather than the doc's literal evidence-fingerprint scheme — see
-  `PROJECT_STATE.md`'s M3 notes for the reasoning (the fingerprint scheme would have let
-  the scan double-report issues already present in the seeded CSV).
-- **No production authentication** — demo login is an HMAC-signed session cookie tied to
-  two fixed seeded users, appropriate for a PoC, not a real identity provider.
-
-## Portfolio wording (truthful)
-
-MobilityOps is a working proof of concept, not a production system and not deployed for
-any real company. All customers, vehicles, bookings, and documents are synthetic
-(deterministically generated). The application logic it demonstrates is real: a
-transactional vehicle-return workflow with idempotency and concurrency control tested
-against real concurrent database transactions; five explainable, deterministic
-data-quality rules with a working customer-merge UI; a background outbox dispatcher
-verified end-to-end against a real n8n instance including failure/retry; a
-TF-IDF-weighted extractive knowledge assistant that never fabricates answers; and four
-read-only, audited, service-authenticated integration endpoints. RAGcore and the ITWorx
-MCP Hub integrations are implemented and tested in isolation but were not verified
-against live instances of those systems in this environment.

artifacts/final-acceptance/summary.md

@@ -1,265 +1,77 @@
-# MobilityOps — final acceptance audit summary
+# Fleet Ops release acceptance
 
-This audit was run after M0–M7 had already been implemented and committed, specifically
+This file is release-scoped evidence, not a timeless claim. Older evidence under
-to independently re-verify the finished system end to end rather than trust the
+`artifacts/evidence/` is historical. Exact commands and production revisions are recorded
-milestone-by-milestone build log. It found and fixed one real category of defect
+in `PROJECT_STATE.md`.
-(`mypy` had never been run across the whole build) and confirmed everything else — every
-user journey, every button/filter/form, both external-dependency degraded modes, secret
-hygiene, and the clean-checkout path — works as documented.
 
-## Final commit
+## 2026-08-21 release candidate
 
-This audit's fixes are committed as the commit immediately following
+- Backend: **271/271** tests passed against an isolated clean PostgreSQL database.
-`108b5d04fc6f7c5ff9c47009032d6469df29cf3c` ("M7: portfolio polish and final acceptance").
+- Browser acceptance: **155/155** Chromium tests passed in 6.0 minutes.
-Run `git log -1 --format="%H %s"` for the exact hash.
+- Live-safe browser canary: **4/4** passed across Chromium and Firefox against the local
+  deployed stack; unlike the acceptance suite, it never resets or mutates demo records.
+- Accessibility: the principal login, dashboard, data-quality, knowledge, automation and
+  audit routes have no automated critical/serious WCAG 2 A/AA/2.1 AA violations.
+- Frontend: TypeScript, ESLint, production build, dependency audit and per-asset JS/CSS
+  budgets passed; committed visual baselines cover the public entry and engineering story.
+- Contracts: committed OpenAPI, event schema, MCP tools and all five n8n definitions match
+  their code/manifest sources.
+- Recovery: a custom-format PostgreSQL dump was restored into a disposable database; the
+  Alembic revision and non-zero canonical table counts matched the source database.
+- Operations: Prometheus/Alertmanager configuration validation passed, including the
+  watchdog and authenticated n8n receiver route.
 
-## Exact commands executed
+## 2026-08-21 production verification
 
-Clean-checkout drill (run twice during this audit, most recently against fully wiped
+- Immutable application revision `95c91797fa2c599443d69d9c96d83a85ee0711f7` was promoted
-Docker volumes):
+  from a checksum-verified source archive after a fresh production backup.
+- Source revision and both OCI revision labels matched. Public readiness was green,
+  Alembic was at head, all health-gated services were healthy and persisted demo data was
+  retained without a deployment reset.
+- Trivy found zero fixed HIGH/CRITICAL vulnerabilities in each exact production image.
+- Prometheus successfully scraped the bearer-protected API target, Alertmanager carried
+  the active delivery watchdog, and the authenticated n8n alert receiver remained active.
+- The final non-destructive HTTPS canary passed **4/4** across Chromium and Firefox,
+  including the core operator routes and a grounded answer from the real knowledge stack.
 
-```bash
+## 2026-08-21 resilience upgrade verification
-git status                              # working tree clean before starting
-docker compose down -v                  # wipe all volumes — genuinely clean state
-cp .env.example .env
-docker compose up --build -d            # migrations run automatically (backend/entrypoint.sh)
-docker compose exec api python -m app.cli seed --reset
-docker compose run --rm api pytest -q
-docker compose run --rm api ruff check .
-docker compose run --rm api mypy app
-cd frontend && npm run build
-cd frontend && npx playwright test
-```
 
-n8n one-time setup (owner account via browser at `http://localhost:5678/setup`, then):
+- Immutable revision `00191e9b54ee6b961648a6e02abbb3a57957dba0` was promoted from a
+  checksum-verified archive after a verified production dump. A stable gateway now routes
+  to two revision-specific API and two web replicas; stateful services are no longer
+  restarted by routine application releases.
+- Moving host port 1236 from the legacy web container to the gateway was a one-time
+  migration hand-off and produced 14 failures across 1,200 rapid probes. Future releases
+  do not move that port; their acceptance gate is the zero-error versioned gateway reload.
+- The subsequent M50 release exercised that steady-state path: the gateway remained online,
+  atomically switched revision-specific API/web aliases and sustained **700/700** external
+  readiness probes without interruption. Post-promotion Chromium/Firefox acceptance passed
+  **4/4** and 360 concurrent authenticated reads had zero errors at p95 **116.4 ms**.
+- The versioned gateway switch sustained **300/300** local rollout probes without an error.
+  Production's non-destructive Chromium/Firefox canary passed **4/4**, and 360 authenticated
+  concurrent reads returned zero errors at p95 **137.2 ms**.
+- PostgreSQL, backup, Prometheus, Alertmanager, Grafana and the gateway all reported healthy;
+  Alembic was at head, the protected Prometheus target was present, and backup plus real
+  restore-drill evidence remained current.
+- Trivy 0.74 found zero fixed HIGH/CRITICAL vulnerabilities in the exact production API,
+  web and gateway images. The separately built rclone/PostgreSQL backup-tools image is also
+  clean after rebuilding rclone 1.75.0 with Go 1.26.6.
+- The OneDrive worker is deployed as an opt-in profile but is not represented as active:
+  it requires the owner's one-time interactive Microsoft OAuth authorization. Until that
+  happens, verified local backups remain the active recovery source.
 
-```bash
+## Evidence boundary
-docker compose exec n8n n8n import:workflow --input=//imports/mobilityops-return-processing.json
-docker compose exec n8n n8n publish:workflow --id=mobilityops-return-processing
-docker compose restart n8n
-```
 
-Degraded-mode drills:
+The complete local suite uses the deterministic provider and an isolated database so it is
+repeatable and safely destructive. Production verification is deliberately smaller and
+non-destructive; it verifies the real RAGcore/MCP/n8n health surfaces without resetting the
+shared demo. A successful local result is never presented as proof that an external service
+was live. The production subsection is added only after the exact committed release is
+deployed and observed.
 
-```bash
+## Remaining product boundary
-docker compose stop n8n     # then register a return via the API — commits, event stays pending
-docker compose start n8n    # dispatcher self-heals, no manual intervention
-docker compose run --rm -e KNOWLEDGE_PROVIDER=ragcore -e RAGCORE_BASE_URL=http://ragcore-not-reachable:9999 \
-  api python -c "from app.services.knowledge import get_knowledge_provider; ..."
-```
 
-## Test and validation results
+Fleet Ops remains a synthetic single-tenant PoC. It is not a production identity provider,
-
+payment system, accounting package or public reservation platform. External RAGcore, MCP
-| Check | Command | Result |
+Hub and n8n services remain independently operated dependencies and are accessed only
-|---|---|---|
+through their documented adapters.
-| Backend unit/integration tests | `docker compose run --rm api pytest -q` | **66 passed**, 0 failed, 0 skipped |
-| Backend lint | `docker compose run --rm api ruff check .` | **All checks passed** |
-| Backend type check | `docker compose run --rm api mypy app` | **Success: no issues found in 44 source files** (found and fixed 43 pre-existing errors this audit — see below) |
-| Frontend build + typecheck | `cd frontend && npm run build` | Clean (`tsc -b && vite build`, zero errors) |
-| End-to-end (Playwright) | `cd frontend && npx playwright test` | **12 passed** (`demo.spec.ts` — full 9-step demo script; `interactive-elements.spec.ts` — 11 tests covering every nav item, filter, tab, and role boundary) |
-| Clean-checkout migrations | `docker compose down -v && docker compose up --build -d` | 11 tables created automatically, `alembic current` → `e7b08389f47f (head)`, zero manual step |
-| Deterministic seed | `docker compose exec api python -m app.cli seed --reset` | `users:2 customers:180 vehicles:50 bookings:246 inspections:75 maintenance:40 data_quality_issues:26 workflow_runs:20` — identical across every reseed this session |
-| Secret scan | `git ls-files \| grep -x .env`; `git log --all -p -- '*.env'`; history grep for AWS/private-key/`sk-` patterns | No `.env` ever committed; no secrets found in history |
-
-### mypy defects found and fixed (the one real gap this audit uncovered)
-
-`mypy` is a declared dev dependency (`backend/pyproject.toml`) but was never added to any
-milestone's validation loop — only `ruff` was run throughout M0–M7. Running it cold
-surfaced 43 errors across 10 files. All were triaged and fixed (not suppressed):
-
-- **Two genuine defensive-programming gaps**, not just type-annotation issues:
-  - `app/services/returns.py`: the vehicle lookup after acquiring the row lock had no
-    `None` guard; a dangling FK would have crashed with an unhandled 500 instead of a
-    clean `404 VEHICLE_NOT_FOUND`. Fixed.
-  - `app/api/routers/bookings.py`: same pattern in `get_booking` for the customer/vehicle
-    lookups — now returns a clean `500` with a message instead of an `AttributeError`.
-- `app/api/deps.py` / `app/api/routers/demo.py`: `CurrentUser.role` is validated by
-  Pydantic at runtime already, but `get_current_user` now explicitly checks role
-  membership before construction, turning a would-be unhandled `ValidationError` into a
-  clean `401` for a corrupted/tampered session cookie.
-- Two instances of reusing one variable name for both a `Vehicle` and a `Customer` across
-  branches (`dashboard.py`, `data_quality.py`) — renamed for clarity, not just to satisfy
-  mypy.
-- `Booking.__table__.update()` / `Customer.__table__.update()` switched to the idiomatic
-  `sqlalchemy.update(Model)` construct (also fixes the type error).
-- Remainder: deprecated `conint()` → `Annotated[int, Field(...)]`, a `Sequence` vs `list`
-  `.sort()` call, an `assert`-guarded None-narrow after a `WHERE ... IS NOT NULL` filter
-  mypy can't see through, and a couple of narrowly-scoped `# type: ignore[...]` comments
-  for known SQLAlchemy stub gaps (`Result.rowcount`).
-
-`make lint` now runs `ruff check .` **and** `mypy app`.
-
-## Application URLs and ports
-
-| Service | URL | Notes |
-|---|---|---|
-| Web (React SPA) | `http://localhost:1228` | nginx-served static build |
-| API | `http://localhost:8128` | FastAPI, `/health` for liveness |
-| API docs | `http://localhost:8128/docs` | auto-generated OpenAPI/Swagger UI |
-| n8n | `http://localhost:5678` | requires one-time owner setup, see below |
-| PostgreSQL | `localhost:5432` (container-internal only, no host port published) | |
-
-## Demo users and access method
-
-No passwords. Two demo-role buttons on `http://localhost:1228/login`:
-
-- **Open as Operations Manager** → `USR-OPS`, "Amelie De Ridder". Full access: dashboard,
-  data-quality resolution/merge, automation retry, demo reset, MCP/service-token routes
-  are separate (not user-facing).
-- **Open as Rental Employee** → `USR-EMP`, "Karim Boujaddaine". Can register returns and
-  browse vehicles/bookings/knowledge; Automation page is visible but shows a
-  role-restricted message instead of the delivery table (enforced both in the UI and by
-  the backend's `require_operations_manager` dependency — verified by
-  `test_retry_requires_operations_manager` and the e2e role-restriction test).
-
-Session is an HMAC-signed, `HttpOnly` cookie (`app/core/security.py`) — a demo mechanism,
-not a real identity provider (documented as a known limitation).
-
-## Implemented functionality
-
-- Operations dashboard with 100% database-backed metrics, attention items linking to the
-  underlying data-quality issue, "today" departures/returns, and recent automation runs.
-- Vehicle and booking list/detail pages with working filters (status, attention-only) and
-  a tabbed vehicle detail view (overview/bookings/inspections/maintenance/quality).
-- Full transactional vehicle-return workflow: row-locked, idempotent by
-  `Idempotency-Key`, canonical-odometer regression handling (never silently lowers the
-  canonical value), vehicle status derivation, two audit events, and a schema-compliant
-  outbox event — verified against real concurrent submissions (1×201 + 2×409).
-- Invalid-mileage rejection: negative values and non-numeric input both correctly
-  rejected with `422` and a precise Pydantic validation message.
-- Data Quality Workbench: five deterministic rules (duplicate customer via TF-IDF-style
-  weighted signal scoring, missing required field, odometer regression, booking overlap,
-  vehicle status conflict), issue list/detail/defer/reject, and a two-column
-  duplicate-customer compare-and-merge UI with an inline (non-native-dialog) confirmation
-  step, transactional booking rewiring, and audit logging.
-- Full audit trail: every significant action (login, return, vehicle status change,
-  data-quality issue lifecycle, customer merge, workflow retry, demo reset, n8n
-  callback, MCP tool request, knowledge question) is recorded with actor, correlation ID,
-  and before/after state; filterable by action.
-- Knowledge Assistant: deterministic TF-IDF-weighted extractive retrieval over the 10
-  procedure documents — never generative, always cites real excerpts, and honestly
-  reports `insufficient`/`unavailable` states rather than fabricating an answer.
-- n8n automation: background outbox dispatcher (`FOR UPDATE SKIP LOCKED` claim,
-  exponential backoff, no DB transaction held during the HTTP call), a live-verified
-  round trip through an actual n8n workflow, manual retry for failed deliveries, and an
-  Automation page (Operations Manager only) showing all runs with filtering.
-- Four read-only, service-token-authenticated MCP Hub provider endpoints, each recording
-  its own service-request audit event, with zero write/mutation endpoints anywhere in
-  that namespace.
-- Responsive UI verified down to 360px width (nav wraps, tables become cards, metric
-  tiles reflow to a 2-column grid, no horizontal overflow) — both by an automated
-  Playwright viewport/overflow assertion and by a captured screenshot.
-
-## RAGcore integration status: implemented, not live-verified
-
-The active `KnowledgeProvider` in this environment is `DemoKnowledgeProvider` — fully
-implemented, fully tested, fully live-verified, and what actually satisfies the
-knowledge-assistant acceptance criteria. A `RAGcoreKnowledgeProvider` HTTP adapter also
-exists (`app/services/knowledge/ragcore.py`), targeting a best-effort contract inferred
-from `contracts/ragcore-contract-assumptions.md` (no live RAGcore API spec was available).
-Its **unavailable-degradation path is live-verified this audit**: pointed at an
-unreachable host, it returns `{"evidence_state": "unavailable", "answer": "", "sources":
-[]}` with no fabrication, exactly as required — but an actual successful round trip
-against a real RAGcore instance has never been performed, because no such instance was
-reachable in this environment.
-
-## MCP Hub integration status: implemented, not live-verified
-
-All four contracted read-only tools (`mobilityops_get_operations_summary`,
-`mobilityops_list_attention_vehicles`, `mobilityops_get_vehicle_details`,
-`mobilityops_search_knowledge`) are implemented as service-token-protected endpoints under
-`/api/v1/integrations/mcp/`, directly `curl`-verified this audit (auth enforcement,
-correct data shape, no write methods, service-request audit logging). No live ITWorx MCP
-Hub instance was reachable in this environment, so an actual Hub-mediated tool call was
-never performed — only direct calls to MobilityOps's own provider API.
-
-## n8n integration status: implemented and fully live-verified
-
-The only external integration with a real, running counterpart service available in this
-environment. Fully verified this audit, including both success and degraded paths:
-
-- **Success**: a real return registered via the API was delivered by the background
-  dispatcher to an actual n8n instance (owner account + imported/activated workflow),
-  which called back into MobilityOps and was recorded `succeeded`.
-- **Degraded mode**: `docker compose stop n8n`, then a return was registered — it
-  **committed successfully** (`201`, booking `status: returned` persisted) exactly as
-  required by the architecture's reliability boundary ("a return command and its outbox
-  event commit in one transaction" and "n8n failure leaves events pending with bounded
-  retries"). The outbox event stayed `pending` with two real `ConnectError`s logged and
-  exponential backoff.
-- **Self-healing**: restarting n8n required no manual intervention — the background
-  dispatcher picked the pending event back up on its next poll cycle and delivered it to
-  `succeeded` (5 total attempts across the outage).
-- **Manual retry (S5 scenario)**: a seeded `failed` delivery, retried from the Automation
-  page, moved to `pending` and was delivered to `succeeded` by the live dispatcher within
-  one poll cycle.
-
-## Known limitations
-
-- RAGcore and the ITWorx MCP Hub were never reachable in this build/audit environment;
-  both integrations are implemented and tested against inferred/documented contracts but
-  not verified against real instances of those systems (see above).
-- n8n requires a one-time, per-fresh-environment manual owner-account setup through its
-  own web UI (`http://localhost:5678/setup`) — a property of the n8n 2.x image itself
-  (`N8N_BASIC_AUTH_ACTIVE` no longer gates the UI), not something MobilityOps can bypass.
-  The workflow import/activation itself *is* scripted (`make n8n-setup`).
-- Demo authentication is an HMAC-signed session cookie tied to two fixed seeded users —
-  appropriate for a PoC, not a production identity provider.
-- Inspection public references are assigned via a simple `count + 1` sequence, not
-  gap-safe under true concurrent writers (acceptable for this single-tenant demo).
-- The five data-quality rules use a simplified idempotency key
-  (`rule_type, entity_type, entity_id` while open) rather than the spec's literal
-  evidence-fingerprint scheme — documented rationale in `PROJECT_STATE.md`'s M3 notes.
-- `npm audit` reports one residual moderate `esbuild`/Vite-8 dev-server-only advisory
-  (fixable only by a Vite major version bump) and one high `react-router` RSC-mode
-  advisory that does not apply to this app (it never uses React Router's RSC/SSR mode).
-
-## Clean deployment instructions
-
-```bash
-git clone <repo> && cd MobilityOps
-cp .env.example .env
-make demo                      # build, start, migrate (automatic), seed
-```
-
-One-time n8n setup (only needed for the automation demo path; everything else works
-without it):
-
-```bash
-# open http://localhost:5678/setup in a browser, create any owner account
-# (8+ chars, 1 number, 1 capital letter — no email verification required)
-make n8n-setup
-```
-
-Verify:
-
-```bash
-curl http://localhost:8128/health              # {"status":"ok",...}
-curl -o /dev/null -w "%{http_code}\n" http://localhost:1228/   # 200
-make test                                      # 66 backend tests
-make lint                                      # ruff + mypy, zero errors
-make e2e                                        # 12 Playwright tests (stack must be running)
-```
-
-Full detail, recovery expectations, and required operational checks: `docs/17-runbook.md`.
-
-## Five-minute demonstration flow
-
-1. Open `http://localhost:1228` → **Open as Operations Manager**.
-2. **Dashboard**: point out the metrics are live counts (available/rented/cleaning/
-   maintenance/blocked vehicles, open quality issues, pending/failed workflows), and the
-   Attention Required list linking straight to the underlying issues.
-3. **Vehicles → MO-024** → open the active booking `BK-DEMO-RETURN`, register a return
-   with an odometer reading below MO-024's canonical value → the result panel shows the
-   inspection, the derived vehicle status, the automatically-created data-quality issue,
-   and the queued automation event — canonical odometer is confirmed unchanged.
-4. **Data Quality → DQ-DEMO-DUPLICATE**: the two-column CUS-0012/CUS-0178 comparison,
-   merge with the inline confirmation step, issue flips to `resolved`.
-5. **Knowledge**: ask "What must I do when a vehicle returns with damage?" → grounded
-   answer citing both the return and damage-handling procedures with real excerpts.
-6. **Automation**: filter to `failed`, retry the seeded delivery, watch it succeed within
-   a few seconds via the live n8n instance.
-7. **Audit**: filter by `return_registered` or `customer_merged` to show every action from
-   this walkthrough is recorded with actor, timestamp, and correlation ID.
-8. Resize the browser to 360px width to show the responsive layout (nav wraps, tables
-   become cards) — or run `make e2e` and point at the passing responsive assertion.

artifacts/functional-completion/final-summary.md

@@ -1,246 +0,0 @@
-# MobilityOps functional-completion — final summary
-
-## Outcome: PASS
-
-All achievable functional-completion requirements were audited, implemented, tested
-locally (including a genuine clean-checkout drill), committed, pushed, deployed to
-Unraid and re-verified against the live server after every batch.
-
-## Revisions
-
-- Starting branch: `design/mobilityops-premium-ui`
-- Starting/observed commit: `54dc952915a4874fcdf14781e1c37feb0e253851`
-- Completion branch: `feat/mobilityops-functional-completion`
-- Final commit: `5b2827eb7e84e40d97c4d025debb2af1246908e0` (this is the parent commit
-  the deploy below targets; the commit that actually records this string is
-  necessarily one commit later — `git log -1` on this branch is the authoritative
-  source of the true HEAD)
-- Gitea branch URL: `https://gitea.itworx.tech/Jens/MobilityOps` (SSH remote
-  `ssh://git@192.168.10.150:222/Jens/MobilityOps.git`), branch
-  `feat/mobilityops-functional-completion`
-- Deployed URL: `http://192.168.10.150:1236`
-- Server deployment directory: `/mnt/user/appdata/mobilityops`
-- Server Compose project: `mobilityops`
-
-## Exact commands executed (representative — run after every batch)
-
-```bash
-# Local backend gate
-docker compose exec -T api python -m app.cli seed --reset
-docker compose exec -T api pytest -q
-docker compose run --rm api ruff check .
-docker compose run --rm api mypy app
-
-# Local frontend gate
-cd frontend && npx tsc -b --noEmit && npm run build
-
-# Local e2e (against the local dev stack)
-npx playwright test
-
-# Deploy the exact committed revision
-COMMIT=$(git rev-parse HEAD)
-git archive --format=tar.gz --output=/tmp/source.tar.gz "$COMMIT"
-scp -P 22 /tmp/source.tar.gz unraid:/mnt/user/appdata/mobilityops/.deploy/source.tar.gz
-ssh unraid "cd /mnt/user/appdata/mobilityops && tar -xzf .deploy/source.tar.gz && echo $COMMIT > .deploy/source-revision"
-ssh unraid "cd /mnt/user/appdata/mobilityops && docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml up --build -d db api web"
-ssh unraid "cd /mnt/user/appdata/mobilityops && docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec -T api alembic current"
-ssh unraid "cd /mnt/user/appdata/mobilityops && docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec -T api python -m app.cli seed --reset"
-
-# e2e against the live server
-MOBILITYOPS_PUBLIC_URL=http://192.168.10.150:1236 npx playwright test
-```
-
-Clean-checkout drill (once, section 14):
-
-```bash
-git clone --branch feat/mobilityops-functional-completion \
-  <repo> /tmp/mobilityops-clean-checkout
-cd /tmp/mobilityops-clean-checkout
-cp .env.example .env
-docker compose -p mobilityops-clean up --build -d   # isolated project name/ports
-docker compose -p mobilityops-clean exec -T api alembic current
-docker compose -p mobilityops-clean exec -T api python -m app.cli seed --reset
-docker compose -p mobilityops-clean exec -T api pytest -q
-docker compose -p mobilityops-clean run --rm api ruff check .
-docker compose -p mobilityops-clean run --rm api mypy app
-cd frontend && npm ci && npx tsc -b --noEmit && npm run build
-MOBILITYOPS_PUBLIC_URL=http://localhost:11228 npx playwright test
-docker compose -p mobilityops-clean down -v   # isolated project only
-```
-
-## Test and validation results
-
-| Gate | Local dev stack | Clean-checkout (isolated) | Live Unraid |
-|---|---|---|---|
-| `pytest` | 117 passed | 117 passed | — (not applicable; no test runner on the review host) |
-| `ruff check .` | clean | clean | — |
-| `mypy app` | 0 issues / 46 files | 0 issues / 46 files | — |
-| `npx tsc -b` | clean | clean | — |
-| `npm run build` | clean | clean | — |
-| `npx playwright test` | 37 passed | 37 passed | **37 passed** (against `http://192.168.10.150:1236`) |
-| `npm audit` | 4 known advisories (unchanged — see Known limitations) | same | — |
-
-Every batch (1 through 5) was deployed and re-verified with the full 37-test Playwright
-suite against the live server before moving to the next batch, not only at the end.
-
-## Application URLs and ports
-
-| Service | URL / port | Notes |
-|---|---|---|
-| Web (Unraid) | `http://192.168.10.150:1236` | only MobilityOps-owned service exposed on the LAN |
-| API (Unraid) | Compose-network only | reached through the web nginx `/api/` proxy |
-| PostgreSQL (Unraid) | Compose-network only | never exposed |
-| Shared n8n (Unraid) | `http://192.168.10.150:5678` | pre-existing host infrastructure, outside the MobilityOps Compose project |
-| Web (local dev) | `http://localhost:1228` | |
-| API (local dev) | `http://localhost:8128` | |
-| n8n (local dev) | `http://localhost:5678` | bundled, `bundled-n8n` profile |
-
-## Demo users and access method
-
-Two fixed seeded identities, selected via the login screen's role buttons (no
-password): **Amelie De Ridder** (`USR-OPS`, Operations Manager) and **Karim
-Boujaddaine** (`USR-EMP`, Rental Employee). `POST /api/v1/demo/login` issues an
-HttpOnly, `SameSite=Lax` signed session cookie; `GET /api/v1/demo/session` (marked
-`Cache-Control: no-store`) is what the browser actually trusts on every load, not a
-locally cached copy.
-
-## Implemented functionality (this pass, on top of the already-accepted M0–M7/design baseline)
-
-- Fixed two confirmed defects: Vehicles and Bookings both computed a filtered/paginated
-  result but rendered the raw array.
-- Server-backed session lifecycle (`GET /demo/session`, `POST /demo/logout`), central
-  401 handling, no more `sessionStorage`-as-authority.
-- A role matrix enforced server-side (403 on every manager-only action for Rental
-  Employee, not just a hidden button) and mirrored in the nav/route guards.
-- Authoritative, non-mutating return preview (`POST /bookings/{ref}/return-preview`)
-  sharing its evaluation function with commit — fixed a real bug where the frontend's
-  guessed preview text was wrong (damage → described as "maintenance", actual rule
-  "blocked"; the no-contradiction case → described as "available", actual rule always
-  "cleaning" first).
-- Audit API/UI now expose `before`/`after` (the columns existed but were never
-  serialized) plus a resolved safe entity link.
-- Typed related-entity snapshots (booking_overlap's related refs are bookings, not
-  vehicles — previously silently unresolved) and a bounded resolution flow for every
-  one of the five data-quality rule types, plus an audited manual scan trigger and
-  documented recurrence linking (`reopened_from`/`previous_decision`).
-- Role-aware backend search (`GET /api/v1/search`) replacing a blind client-side regex
-  guesser, with a real results panel, keyboard navigation and debouncing.
-- A safe, confirmed demo-reset UI trigger (the endpoint already existed and was
-  already gated).
-- Truthful aggregate n8n integration status (`GET /api/v1/integrations/status`) from
-  outbox delivery counts, replacing a single-most-recent-event read; fixed
-  `MCP_HUB_REGISTRATION_ENABLED` being declared in `.env.example` but never wired into
-  `Settings`.
-- Bounded outbox delivery-lease recovery for a process crash between claim and outcome.
-- A second n8n workflow (scheduled quality scan), independent of RAGcore/MCP Hub.
-
-## RAGcore integration status
-
-Unchanged from the prior baseline and honestly reported throughout: the demo
-`KnowledgeProvider` (deterministic TF-IDF extractive retrieval over local procedure
-documents) satisfies the knowledge-assistant acceptance criteria and is fully verified.
-A `RAGcoreKnowledgeProvider` HTTP adapter is implemented and unit-tested (including its
-unavailable-degradation path) but was never exercised against a live RAGcore instance in
-this environment — no live RAGcore instance exists to test against.
-`KNOWLEDGE_PROVIDER=demo` on the Unraid deployment; no simulated live connection is ever
-shown.
-
-## MCP Hub integration status
-
-The four read-only provider endpoints are implemented, tested, and directly
-curl-verified with correct service-token auth enforcement and audit logging.
-`MCP_HUB_REGISTRATION_ENABLED` — previously declared in `.env.example` but silently
-dropped by `extra="ignore"` since it had no `Settings` field — is now actually wired in
-and honestly reported (`GET /api/v1/integrations/status`'s `mcp_hub.state`). It is
-`false` on the Unraid deployment (`state: "not_configured"`). No live Hub instance was
-reachable in this environment to verify an actual Hub round trip.
-
-## n8n integration status
-
-Fully implemented and live-verified. The original return-processing workflow: verified
-against both the local bundled instance and the shared Unraid instance, including a real
-degraded-mode drill in an earlier session (n8n stopped mid-flow → return still committed
-locally, event stayed `pending` with backoff, self-healed once n8n returned) and the
-manual-retry path. This pass adds:
-
-- **Truthful status**: `GET /api/v1/integrations/status` derives n8n health from
-  aggregate outbox counts (pending/delivering/succeeded/failed), not the single most
-  recent event.
-- **Stale-delivery-lease recovery**: a claimed-but-never-resolved `delivering` row (the
-  process crashing between claim and outcome) is now recoverable; unit-tested including
-  a simulated crash, and confirmed a still-alive worker's unexpired lease is never
-  touched.
-- **Second workflow**: `mobilityops-scheduled-quality-scan` (hourly + manual-test
-  trigger, ships `"active": false"`), calling `POST
-  /api/v1/integrations/n8n/scheduled-scan`. Live-verified two ways: (1) executed
-  end-to-end via the Manual test trigger against the **local** n8n instance — full
-  green execution in the n8n editor, confirmed by the resulting
-  `data_quality_scan_run` audit event (`actor_type=service`); (2) published to the
-  **shared Unraid n8n** via `deploy/unraid/setup-scheduled-scan.sh` and the resulting
-  endpoint directly curl-verified against the live deployed API, also confirmed via the
-  audit trail. The shared instance's own UI could not be browser-tested directly — it
-  runs `N8N_SECURE_COOKIE=true` and refuses login over the plain-HTTP LAN URL used for
-  automated testing here, which is correct, pre-existing shared-infrastructure
-  behaviour and out of scope to change.
-
-## Known limitations
-
-- RAGcore and ITWorx MCP Hub remain honestly not-live-connected — no live instance of
-  either exists in this environment (environment limitation, not a code defect).
-- `npm audit`: one moderate esbuild/Vite dev-server-only advisory (fix requires a Vite
-  major upgrade, deliberately deferred), and a
-  react-router RSC-mode advisory that doesn't apply (the app never uses RSC/SSR mode) —
-  both pre-existing, confirmed unchanged by this pass's clean `npm ci`.
-- Demo authentication remains the accepted HMAC-cookie PoC mechanism tied to two fixed
-  seeded identities — not a production identity provider.
-- The scheduled quality-scan workflow's own n8n-engine execution was verified live
-  against the local bundled n8n and, for the HTTP round trip specifically, against the
-  shared Unraid n8n's resulting API call — not against a full n8n-engine execution *on
-  the shared instance itself*, for the browser-access reason above.
-- `n8n_delivery_lease_seconds` (120s default) is a code-level tunable, not exposed in
-  `.env.example`, consistent with the existing `n8n_dispatch_interval_seconds`/
-  `n8n_max_attempts`/`n8n_http_timeout_seconds` tunables already handled that way.
-
-## Clean deployment instructions
-
-See `deploy/unraid/README.md` and `docs/17-runbook.md` for the full runbook. Redeploy
-the exact committed revision:
-
-```bash
-COMMIT=<commit to deploy>
-git archive --format=tar.gz --output=/tmp/source.tar.gz "$COMMIT"
-scp -P 22 /tmp/source.tar.gz unraid:/mnt/user/appdata/mobilityops/.deploy/source.tar.gz
-ssh unraid "cd /mnt/user/appdata/mobilityops \
-  && tar -xzf .deploy/source.tar.gz \
-  && echo $COMMIT > .deploy/source-revision \
-  && docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml up --build -d db api web \
-  && docker compose -p mobilityops -f compose.yaml -f compose.unraid.yaml exec -T api alembic current \
-  && curl -fsS http://127.0.0.1:1236/health"
-```
-
-`.env` and both named volumes (`mobilityops-db`, `mobilityops-n8n`) are preserved by
-this flow; nothing outside the `mobilityops` Compose project is touched.
-
-## Five-minute demonstration flow
-
-1. Open `http://192.168.10.150:1236`, log in as **Operations Manager**.
-2. Dashboard: point out the persisted readiness metrics and the now-truthful n8n
-   integration-status card (aggregate counts, not just the latest event).
-3. Global search (`Ctrl/Cmd+K`): type a vehicle, booking or issue reference; use arrow
-   keys + Enter to navigate; show the no-results state for a nonsense query.
-4. Bookings: filter by status, page through results (max 25/page), confirm page 2
-   differs from page 1.
-5. Open an active booking → capture a return with a below-canonical odometer reading →
-   the review step shows the server's authoritative evaluation (odometer regression
-   flagged, resulting status and reason) → confirm → result screen distinguishes local
-   commit success from queued-not-yet-confirmed n8n delivery, links to the created
-   data-quality issue.
-6. Data quality: run a manual scan; open the newly flagged (or an existing) issue for
-   each rule type and show its dedicated bounded resolution flow (not raw JSON).
-7. Audit trail: filter by the correlation ID from the return above; show the
-   human-readable before/after change summary, expand the raw-JSON `<details>`.
-8. Switch role to **Rental Employee**: show Data Quality/Integrations/Audit are absent
-   from the nav, and that direct URL navigation to any of them shows the restricted
-   message rather than partial data or a crash.
-9. Switch back to Operations Manager, trigger **Reset demo data** with confirmation,
-   land back at login, log in again to confirm deterministic data was restored.

backend/Dockerfile

@@ -1,16 +1,33 @@
-FROM python:3.12-slim
+FROM python:3.12-slim-bookworm@sha256:a116514e19457bcb7af7efe9c3dd0b9b71e85b317694e7882a1c52aa15a78134 AS runtime-base
+ARG VCS_REF=development
+ARG BUILD_DATE=unknown
+LABEL org.opencontainers.image.title="Fleet Ops API" \
+      org.opencontainers.image.revision="$VCS_REF" \
+      org.opencontainers.image.created="$BUILD_DATE" \
+      org.opencontainers.image.source="https://fleetops.itworx.tech"
 ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
 WORKDIR /app
-COPY backend/requirements.lock ./
+COPY backend/requirements-prod.lock ./
-RUN pip install --no-cache-dir -r requirements.lock
+RUN pip install --no-cache-dir -r requirements-prod.lock
 COPY backend/pyproject.toml ./
 COPY backend/app ./app
 COPY backend/alembic ./alembic
 COPY backend/alembic.ini ./
-COPY backend/tests ./tests
 COPY seed ./seed
 COPY knowledge ./knowledge
 COPY backend/entrypoint.sh ./entrypoint.sh
-RUN pip install --no-cache-dir --no-deps -e . && chmod +x ./entrypoint.sh
+RUN pip install --no-cache-dir --no-deps -e . && chmod +x ./entrypoint.sh \
+    && addgroup --system app && adduser --system --ingroup app --home /app app \
+    && chown -R app:app /app
+
+FROM runtime-base AS test
+COPY backend/requirements.lock ./requirements.lock
+RUN pip install --no-cache-dir -r requirements.lock
+COPY backend/tests ./tests
+USER app
+
+FROM runtime-base AS runtime
+# Run migrations and the API as an unprivileged user; nothing here needs root.
+USER app
 EXPOSE 8000
 CMD ["./entrypoint.sh"]

backend/alembic.ini

@@ -1,7 +1,7 @@
 [alembic]
 script_location = alembic
 prepend_sys_path = .
-version_path_separator = os
+path_separator = os
 
 [loggers]
 keys = root,sqlalchemy,alembic

backend/alembic/versions/0a4c1d2e3f5b_idempotency_request_fingerprint.py

@@ -0,0 +1,28 @@
+"""idempotency request fingerprint
+
+Revision ID: 0a4c1d2e3f5b
+Revises: c24f6a9d013e
+Create Date: 2026-08-16 22:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0a4c1d2e3f5b"
+down_revision: Union[str, None] = "c24f6a9d013e"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "idempotency_records",
+        sa.Column("request_fingerprint", sa.String(length=64), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("idempotency_records", "request_fingerprint")

backend/alembic/versions/4f2b9c8d7e61_unique_open_quality_condition.py

@@ -0,0 +1,27 @@
+"""enforce one open issue per detected condition
+
+Revision ID: 4f2b9c8d7e61
+Revises: 0a4c1d2e3f5b
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "4f2b9c8d7e61"
+down_revision = "0a4c1d2e3f5b"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_index(
+        "uq_data_quality_one_open_condition",
+        "data_quality_issues",
+        ["rule_type", "entity_type", "entity_id"],
+        unique=True,
+        postgresql_where=sa.text("status = 'open'"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("uq_data_quality_one_open_condition", table_name="data_quality_issues")

backend/alembic/versions/799d8800e241_outbox_last_error_code.py

@@ -0,0 +1,25 @@
+"""outbox last_error_code
+
+Revision ID: 799d8800e241
+Revises: e7b08389f47f
+Create Date: 2026-08-03 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = '799d8800e241'
+down_revision: Union[str, None] = 'e7b08389f47f'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column('outbox_events', sa.Column('last_error_code', sa.String(length=60), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column('outbox_events', 'last_error_code')

backend/alembic/versions/a81d0ce9f662_oidc_identity.py

@@ -0,0 +1,28 @@
+"""add optional external OIDC identity
+
+Revision ID: a81d0ce9f662
+Revises: f43d829ab610
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "a81d0ce9f662"
+down_revision = "f43d829ab610"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("identity_provider", sa.String(80), nullable=True))
+    op.add_column("users", sa.Column("external_subject", sa.String(255), nullable=True))
+    op.create_unique_constraint(
+        "uq_user_external_identity", "users", ["identity_provider", "external_subject"]
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("uq_user_external_identity", "users", type_="unique")
+    op.drop_column("users", "external_subject")
+    op.drop_column("users", "identity_provider")

backend/alembic/versions/b7c7b536df85_operational_user_credentials.py

@@ -0,0 +1,25 @@
+"""operational user credentials
+
+Revision ID: b7c7b536df85
+Revises: 799d8800e241
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "b7c7b536df85"
+down_revision = "799d8800e241"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("email", sa.String(length=320), nullable=True))
+    op.add_column("users", sa.Column("password_hash", sa.String(length=512), nullable=True))
+    op.create_unique_constraint("uq_users_email", "users", ["email"])
+
+
+def downgrade() -> None:
+    op.drop_constraint("uq_users_email", "users", type_="unique")
+    op.drop_column("users", "password_hash")
+    op.drop_column("users", "email")

backend/alembic/versions/b913a72e8c14_customer_privacy_state.py

@@ -0,0 +1,24 @@
+"""add explicit customer anonymisation state
+
+Revision ID: b913a72e8c14
+Revises: a81d0ce9f662
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "b913a72e8c14"
+down_revision = "a81d0ce9f662"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("customers", sa.Column("anonymized_at", sa.DateTime(timezone=True)))
+    op.create_index("ix_customers_anonymized_at", "customers", ["anonymized_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_customers_anonymized_at", table_name="customers")
+    op.drop_column("customers", "anonymized_at")

backend/alembic/versions/c24f6a9d013e_domain_constraints_indexes.py

@@ -0,0 +1,68 @@
+"""add domain constraints and operational indexes
+
+Revision ID: c24f6a9d013e
+Revises: b913a72e8c14
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "c24f6a9d013e"
+down_revision = "b913a72e8c14"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    checks = (
+        ("bookings", "ck_bookings_status", "status IN ('reserved','active','returned','cancelled','blocked')"),
+        ("bookings", "ck_bookings_time_window", "ends_at > starts_at"),
+        ("bookings", "ck_bookings_start_odometer", "start_odometer_km IS NULL OR start_odometer_km >= 0"),
+        ("bookings", "ck_bookings_end_odometer", "end_odometer_km IS NULL OR end_odometer_km >= 0"),
+        ("vehicles", "ck_vehicles_operational_status", "operational_status IN ('available','rented','cleaning','maintenance','blocked')"),
+        ("vehicles", "ck_vehicles_model_year", "model_year BETWEEN 1900 AND 2100"),
+        ("vehicles", "ck_vehicles_odometer", "odometer_km >= 0"),
+        ("vehicles", "ck_vehicles_next_service", "next_service_km >= 0"),
+        ("vehicles", "ck_vehicles_version", "version >= 1"),
+        ("data_quality_issues", "ck_data_quality_rule_type", "rule_type IN ('possible_duplicate_customer','missing_required_field','odometer_regression','booking_overlap','vehicle_status_conflict')"),
+        ("data_quality_issues", "ck_data_quality_severity", "severity IN ('low','medium','high')"),
+        ("data_quality_issues", "ck_data_quality_status", "status IN ('open','deferred','resolved','rejected')"),
+        ("outbox_events", "ck_outbox_delivery_status", "delivery_status IN ('pending','delivering','succeeded','failed')"),
+        ("outbox_events", "ck_outbox_attempts", "attempts >= 0"),
+        ("audit_events", "ck_audit_actor_type", "actor_type IN ('user','service','system')"),
+    )
+    for table, name, condition in checks:
+        op.create_check_constraint(name, table, condition)
+
+    op.create_index("ix_bookings_vehicle_status_window", "bookings", ["vehicle_id", "status", "starts_at", "ends_at"])
+    op.create_index("ix_data_quality_work_queue", "data_quality_issues", ["status", "due_at", "severity"])
+    op.create_index("ix_outbox_delivery_next_attempt", "outbox_events", ["delivery_status", "next_attempt_at"])
+    op.create_index("ix_audit_action_occurred", "audit_events", ["action", "occurred_at"])
+    op.create_index("ix_audit_entity", "audit_events", ["entity_type", "entity_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_audit_entity", table_name="audit_events")
+    op.drop_index("ix_audit_action_occurred", table_name="audit_events")
+    op.drop_index("ix_outbox_delivery_next_attempt", table_name="outbox_events")
+    op.drop_index("ix_data_quality_work_queue", table_name="data_quality_issues")
+    op.drop_index("ix_bookings_vehicle_status_window", table_name="bookings")
+    for table, name in (
+        ("audit_events", "ck_audit_actor_type"),
+        ("outbox_events", "ck_outbox_attempts"),
+        ("outbox_events", "ck_outbox_delivery_status"),
+        ("data_quality_issues", "ck_data_quality_status"),
+        ("data_quality_issues", "ck_data_quality_severity"),
+        ("data_quality_issues", "ck_data_quality_rule_type"),
+        ("vehicles", "ck_vehicles_version"),
+        ("vehicles", "ck_vehicles_next_service"),
+        ("vehicles", "ck_vehicles_odometer"),
+        ("vehicles", "ck_vehicles_model_year"),
+        ("vehicles", "ck_vehicles_operational_status"),
+        ("bookings", "ck_bookings_end_odometer"),
+        ("bookings", "ck_bookings_start_odometer"),
+        ("bookings", "ck_bookings_time_window"),
+        ("bookings", "ck_bookings_status"),
+    ):
+        op.drop_constraint(name, table, type_="check")

backend/alembic/versions/d1f83bc64170_revoked_sessions.py

@@ -0,0 +1,49 @@
+"""persist revoked sessions
+
+Revision ID: d1f83bc64170
+Revises: b7c7b536df85
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "d1f83bc64170"
+down_revision = "b7c7b536df85"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "revoked_sessions",
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_revoked_sessions_expires_at", "revoked_sessions", ["expires_at"])
+    op.create_index(
+        "ix_revoked_sessions_token_hash",
+        "revoked_sessions",
+        ["token_hash"],
+        unique=True,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_revoked_sessions_token_hash", table_name="revoked_sessions")
+    op.drop_index("ix_revoked_sessions_expires_at", table_name="revoked_sessions")
+    op.drop_table("revoked_sessions")

backend/alembic/versions/f43d829ab610_quality_work_queue.py

@@ -0,0 +1,65 @@
+"""add ownership and SLA deadlines to data quality issues
+
+Revision ID: f43d829ab610
+Revises: d1f83bc64170
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "f43d829ab610"
+down_revision = "d1f83bc64170"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "data_quality_issues",
+        sa.Column("due_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "data_quality_issues",
+        sa.Column("assigned_to_user_id", sa.Uuid(), nullable=True),
+    )
+    op.create_foreign_key(
+        "fk_data_quality_issues_assigned_user",
+        "data_quality_issues",
+        "users",
+        ["assigned_to_user_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+    op.create_index("ix_data_quality_issues_due_at", "data_quality_issues", ["due_at"])
+    op.create_index(
+        "ix_data_quality_issues_assigned_to_user_id",
+        "data_quality_issues",
+        ["assigned_to_user_id"],
+    )
+    op.execute(
+        """
+        UPDATE data_quality_issues
+        SET due_at = detected_at + CASE severity
+          WHEN 'high' THEN interval '4 hours'
+          WHEN 'low' THEN interval '3 days'
+          ELSE interval '1 day'
+        END
+        WHERE status = 'open' AND due_at IS NULL
+        """
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_data_quality_issues_assigned_to_user_id",
+        table_name="data_quality_issues",
+    )
+    op.drop_index("ix_data_quality_issues_due_at", table_name="data_quality_issues")
+    op.drop_constraint(
+        "fk_data_quality_issues_assigned_user",
+        "data_quality_issues",
+        type_="foreignkey",
+    )
+    op.drop_column("data_quality_issues", "assigned_to_user_id")
+    op.drop_column("data_quality_issues", "due_at")

backend/app/api/deps.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+import hmac
+import re
 from collections.abc import Generator
+from dataclasses import dataclass
 
 from fastapi import Depends, Header, HTTPException, Request, status
 from sqlalchemy.orm import Session
@@ -8,7 +11,9 @@ from sqlalchemy.orm import Session
 from app.core.config import get_settings
 from app.core.db import SessionLocal
 from app.core.security import SessionPayload, read_session_token
+from app.models.user import User
 from app.schemas import CurrentUser, Role
+from app.services.sessions import is_session_revoked
 
 settings = get_settings()
 _VALID_ROLES = frozenset(Role.__args__)  # type: ignore[attr-defined]
@@ -22,13 +27,32 @@ def get_db() -> Generator[Session, None, None]:
         db.close()
 
 
-def get_current_user(request: Request) -> CurrentUser:
+def get_current_user(request: Request, db: Session = Depends(get_db)) -> CurrentUser:
     token = request.cookies.get(settings.session_cookie_name)
     payload: SessionPayload | None = read_session_token(token) if token else None
-    if payload is None or payload.role not in _VALID_ROLES:
+    revoked = token is not None and is_session_revoked(db, token)
+    if payload is None or payload.role not in _VALID_ROLES or revoked:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
-    role: Role = payload.role  # type: ignore[assignment]
+    # Demo reset deliberately rebuilds the deterministic users table. Retaining the
-    return CurrentUser(public_ref=payload.public_ref, display_name=payload.display_name, role=role)
+    # signed demo session until the reset endpoint clears its cookie keeps existing demo
+    # workflows stable; operational sessions are always checked against the live record.
+    if settings.mobilityops_demo_mode:
+        demo_role: Role = payload.role  # type: ignore[assignment]
+        return CurrentUser(
+            public_ref=payload.public_ref,
+            display_name=payload.display_name,
+            role=demo_role,
+        )
+    user = db.get(User, payload.user_id)
+    if (
+        user is None
+        or not user.active
+        or user.public_ref != payload.public_ref
+        or user.role not in _VALID_ROLES
+    ):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    role: Role = user.role  # type: ignore[assignment]
+    return CurrentUser(public_ref=user.public_ref, display_name=user.display_name, role=role)
 
 
 def require_operations_manager(
@@ -41,12 +65,30 @@ def require_operations_manager(
     return user
 
 
+@dataclass(frozen=True)
+class McpClientContext:
+    reported_client_id: str
+    tenant: str
+
+
+_MCP_CLIENT_ID = re.compile(
+    r"^itworx-mcp-hub:(?:readiness|mobilityops:[A-Za-z0-9][A-Za-z0-9._:-]{0,127})$"
+)
+
+
 def require_mcp_service_token(
     x_service_token: str = Header(..., alias="X-Service-Token"),
-    x_client_id: str = Header(default="unknown-mcp-client", alias="X-Client-Id"),
+    x_client_id: str = Header(..., alias="X-Client-Id", min_length=1, max_length=180),
-) -> str:
+    x_tenant_id: str | None = Header(default=None, alias="X-Tenant-Id", max_length=120),
-    if x_service_token != settings.mcp_hub_service_token:
+) -> McpClientContext:
+    if not hmac.compare_digest(x_service_token, settings.mcp_hub_service_token):
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid service token"
         )
-    return x_client_id
+    if not _MCP_CLIENT_ID.fullmatch(x_client_id):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Untrusted MCP client identity"
+        )
+    if x_tenant_id is not None and x_tenant_id != settings.ragcore_tenant:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Tenant mismatch")
+    return McpClientContext(reported_client_id=x_client_id, tenant=settings.ragcore_tenant)

backend/app/api/routers/audit.py

@@ -1,22 +1,30 @@
 from __future__ import annotations
 
+import csv
+import io
+import json
 import uuid
 from collections.abc import Sequence
+from datetime import UTC, datetime, timedelta
 from typing import Any
 
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, HTTPException, Query
-from sqlalchemy import select
+from fastapi.responses import Response
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_db, require_operations_manager
+from app.core.config import get_settings
 from app.models.audit import AuditEvent
 from app.models.booking import Booking
 from app.models.customer import Customer
 from app.models.data_quality import DataQualityIssue
 from app.models.vehicle import Vehicle
-from app.schemas import AuditEventOut, CurrentUser
+from app.schemas import AuditEventOut, AuditEventPageOut, CurrentUser
+from app.services.audit import record_audit_event
 
 router = APIRouter(prefix="/api/v1/audit", tags=["audit"])
+settings = get_settings()
 
 # Only entity types with a stable public reference and (optionally) a real frontend route
 # are resolved here. Types like "system", "knowledge" or "mcp_tool" carry no linkable
@@ -36,6 +44,81 @@ _ROUTE_TEMPLATES: dict[str, str] = {
 }
 
 
+def _as_utc(value: datetime | None) -> datetime | None:
+    """Treat naive query datetimes as UTC so they compare safely with aware values."""
+    if value is None:
+        return None
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+
+@router.get("/export.csv")
+def export_audit_csv(
+    occurred_from: datetime | None = Query(default=None),
+    occurred_to: datetime | None = Query(default=None),
+    db: Session = Depends(get_db),
+    actor: CurrentUser = Depends(require_operations_manager),
+) -> Response:
+    end = _as_utc(occurred_to) or datetime.now(UTC)
+    start = _as_utc(occurred_from) or end - timedelta(days=30)
+    if end <= start or end - start > timedelta(days=90):
+        raise HTTPException(status_code=422, detail="Audit export range must be 1 to 90 days")
+    events = db.scalars(
+        select(AuditEvent)
+        .where(AuditEvent.occurred_at >= start, AuditEvent.occurred_at <= end)
+        .order_by(AuditEvent.occurred_at)
+        .limit(settings.privacy_audit_export_max_rows + 1)
+    ).all()
+    if len(events) > settings.privacy_audit_export_max_rows:
+        raise HTTPException(status_code=413, detail="Audit export exceeds configured row limit")
+    output = io.StringIO(newline="")
+    writer = csv.writer(output)
+    writer.writerow(
+        (
+            "id",
+            "occurred_at",
+            "actor_type",
+            "actor_label",
+            "action",
+            "entity_type",
+            "entity_id",
+            "correlation_id",
+            "before",
+            "after",
+            "metadata",
+        )
+    )
+    for event in events:
+        writer.writerow(
+            (
+                event.id,
+                event.occurred_at.isoformat(),
+                event.actor_type,
+                event.actor_label,
+                event.action,
+                event.entity_type,
+                event.entity_id or "",
+                event.correlation_id,
+                json.dumps(event.before_json, separators=(",", ":"), default=str),
+                json.dumps(event.after_json, separators=(",", ":"), default=str),
+                json.dumps(event.metadata_json, separators=(",", ":"), default=str),
+            )
+        )
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=actor.display_name,
+        action="audit_exported",
+        entity_type="audit",
+        metadata={"from": start.isoformat(), "to": end.isoformat(), "rows": len(events)},
+    )
+    db.commit()
+    return Response(
+        output.getvalue(),
+        media_type="text/csv; charset=utf-8",
+        headers={"Content-Disposition": 'attachment; filename="mobilityops-audit.csv"'},
+    )
+
+
 def _resolve_entity_refs(db: Session, events: Sequence[AuditEvent]) -> dict[uuid.UUID, str]:
     ids_by_type: dict[str, set[uuid.UUID]] = {}
     for event in events:
@@ -51,26 +134,51 @@ def _resolve_entity_refs(db: Session, events: Sequence[AuditEvent]) -> dict[uuid
     return refs
 
 
-@router.get("", response_model=list[AuditEventOut])
+@router.get("", response_model=list[AuditEventOut] | AuditEventPageOut)
 def list_audit_events(
     actor_label: str | None = Query(default=None),
     action: str | None = Query(default=None),
     entity_type: str | None = Query(default=None),
-    correlation_id: str | None = Query(default=None),
+    entity_ref: str | None = Query(default=None, min_length=1, max_length=100),
-    limit: int = Query(default=100, le=500),
+    correlation_id: uuid.UUID | None = Query(default=None),
+    occurred_from: datetime | None = Query(default=None),
+    occurred_to: datetime | None = Query(default=None),
+    page: int | None = Query(default=None, ge=1),
+    page_size: int = Query(default=25, ge=1, le=25),
     db: Session = Depends(get_db),
     _user: CurrentUser = Depends(require_operations_manager),
-) -> list[AuditEventOut]:
+) -> list[AuditEventOut] | AuditEventPageOut:
-    stmt = select(AuditEvent).order_by(AuditEvent.occurred_at.desc()).limit(limit)
+    stmt = select(AuditEvent).order_by(AuditEvent.occurred_at.desc())
     if actor_label:
         stmt = stmt.where(AuditEvent.actor_label == actor_label)
     if action:
         stmt = stmt.where(AuditEvent.action == action)
     if entity_type:
         stmt = stmt.where(AuditEvent.entity_type == entity_type)
+    if entity_ref:
+        matched_ids: set[uuid.UUID] = set()
+        for model in _ENTITY_MODELS.values():
+            matched_ids.update(
+                db.scalars(
+                    select(model.id).where(model.public_ref.ilike(f"%{entity_ref.strip()}%"))
+                ).all()
+            )
+        if not matched_ids:
+            if page is None:
+                return []
+            return AuditEventPageOut(items=[], page=1, page_size=page_size, total=0, total_pages=1)
+        stmt = stmt.where(AuditEvent.entity_id.in_(matched_ids))
     if correlation_id:
         stmt = stmt.where(AuditEvent.correlation_id == correlation_id)
-    events = db.scalars(stmt).all()
+    if occurred_from:
+        stmt = stmt.where(AuditEvent.occurred_at >= occurred_from)
+    if occurred_to:
+        stmt = stmt.where(AuditEvent.occurred_at <= occurred_to)
+    total = db.scalar(select(func.count()).select_from(stmt.subquery())) or 0
+    page_number = page or 1
+    events = db.scalars(
+        stmt if page is None else stmt.offset((page_number - 1) * page_size).limit(page_size)
+    ).all()
     entity_refs = _resolve_entity_refs(db, events)
 
     out = []
@@ -94,4 +202,13 @@ def list_audit_events(
                 metadata=e.metadata_json,
             )
         )
+    if page is None:
         return out
+    total_pages = max(1, (total + page_size - 1) // page_size)
+    return AuditEventPageOut(
+        items=out,
+        page=min(page_number, total_pages),
+        page_size=page_size,
+        total=total,
+        total_pages=total_pages,
+    )

backend/app/api/routers/auth.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import time
+import uuid
+
+from authlib.integrations.starlette_client import OAuth, OAuthError  # type: ignore[import-untyped]
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from fastapi.responses import RedirectResponse
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_user, get_db
+from app.core.config import get_settings
+from app.core.ratelimit import FailedAttemptLimiter
+from app.core.security import (
+    SessionPayload,
+    create_session_token,
+    hash_password,
+    read_session_token,
+    verify_password,
+)
+from app.models.user import User
+from app.schemas import CurrentUser, OidcStatusOut, PasswordLoginRequest
+from app.services.audit import record_audit_event
+from app.services.sessions import revoke_session
+
+router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
+settings = get_settings()
+_login_limiter = (
+    FailedAttemptLimiter(
+        max_failures=settings.login_max_failures,
+        window_seconds=settings.login_failure_window_seconds,
+    )
+    if settings.login_max_failures > 0
+    else None
+)
+
+
+def _client_key(request: Request) -> str:
+    # The API sits behind the web container's reverse proxy in every documented
+    # deployment. The proxy appends/overwrites the socket peer as the final hop, so an
+    # attacker-controlled leading value must never select a fresh limiter bucket.
+    forwarded = request.headers.get("x-forwarded-for", "")
+    if forwarded:
+        return forwarded.split(",")[-1].strip()
+    return request.client.host if request.client else "unknown"
+
+
+oauth = OAuth()
+if settings.oidc_enabled and settings.oidc_issuer_url:
+    oauth.register(
+        name="oidc",
+        client_id=settings.oidc_client_id,
+        client_secret=settings.oidc_client_secret,
+        server_metadata_url=f"{settings.oidc_issuer_url.rstrip('/')}/.well-known/openid-configuration",
+        client_kwargs={"scope": "openid email profile"},
+    )
+
+
+def _current_user_out(user: User) -> CurrentUser:
+    return CurrentUser(
+        public_ref=user.public_ref,
+        display_name=user.display_name,
+        role=user.role,  # type: ignore[arg-type]
+    )
+
+
+def _set_session(response: Response, user: User) -> None:
+    token = create_session_token(
+        SessionPayload(
+            user_id=str(user.id),
+            public_ref=user.public_ref,
+            role=user.role,
+            display_name=user.display_name,
+            issued_at=int(time.time()),
+            session_id=str(uuid.uuid4()),
+        )
+    )
+    response.set_cookie(
+        settings.session_cookie_name,
+        token,
+        httponly=True,
+        samesite="lax",
+        secure=settings.session_cookie_secure,
+        max_age=settings.session_ttl_seconds,
+    )
+
+
+def bootstrap_initial_admin(db: Session) -> None:
+    """Create or rotate the explicitly configured first manager in operational mode."""
+    if (
+        settings.mobilityops_demo_mode
+        or not settings.initial_admin_email
+        or not settings.initial_admin_password
+    ):
+        return
+    email = settings.initial_admin_email.strip().lower()
+    user = db.scalar(select(User).where(User.email == email))
+    if user is None:
+        user = User(
+            public_ref="USR-ADMIN",
+            email=email,
+            password_hash=hash_password(settings.initial_admin_password),
+            display_name=settings.initial_admin_display_name,
+            role="operations_manager",
+            active=True,
+        )
+        db.add(user)
+        record_audit_event(
+            db,
+            actor_type="system",
+            actor_label="bootstrap",
+            action="operational_admin_created",
+            entity_type="user",
+            entity_id=user.id,
+        )
+        db.commit()
+
+
+def _oidc_configured() -> bool:
+    return bool(
+        settings.oidc_enabled
+        and settings.oidc_issuer_url
+        and settings.oidc_client_id
+        and settings.oidc_client_secret
+    )
+
+
+def _oidc_redirect_uri() -> str:
+    return settings.oidc_redirect_uri or (
+        f"{settings.mobilityops_public_url.rstrip('/')}/api/v1/auth/oidc/callback"
+    )
+
+
+def _allowed_oidc_email(email: str) -> bool:
+    domains = {
+        value.strip().casefold()
+        for value in settings.oidc_allowed_email_domains.split(",")
+        if value.strip()
+    }
+    return not domains or email.rsplit("@", 1)[-1].casefold() in domains
+
+
+def _resolve_oidc_user(db: Session, claims: dict[str, object]) -> User:
+    subject = str(claims.get("sub") or "").strip()
+    email = str(claims.get("email") or "").strip().lower()
+    if not subject or not email or claims.get("email_verified") is not True:
+        raise HTTPException(status_code=401, detail="Verified OIDC email and subject are required")
+    if not _allowed_oidc_email(email):
+        raise HTTPException(status_code=403, detail="Email domain is not allowed")
+
+    provider = settings.oidc_issuer_url.rstrip("/")
+    user = db.scalar(
+        select(User).where(
+            User.identity_provider == provider,
+            User.external_subject == subject,
+        )
+    )
+    if user is None:
+        user = db.scalar(select(User).where(User.email == email))
+        if user is not None and user.external_subject not in (None, subject):
+            raise HTTPException(status_code=409, detail="Email is linked to another identity")
+        if user is not None and claims.get("email_verified") is not True:
+            # Linking an existing local account (possibly the bootstrap admin) purely on an
+            # email match requires the IdP to explicitly assert the address is verified;
+            # an absent claim is treated as unverified.
+            raise HTTPException(status_code=401, detail="Verified OIDC email is required")
+    created = user is None
+    if created:
+        if not settings.oidc_auto_provision:
+            raise HTTPException(status_code=403, detail="OIDC user is not provisioned")
+        role = settings.oidc_default_role
+        if role not in {"operations_manager", "rental_employee"}:
+            role = "rental_employee"
+        user = User(
+            public_ref=f"USR-{uuid.uuid4().hex[:8].upper()}",
+            email=email,
+            password_hash=None,
+            display_name=str(claims.get("name") or email),
+            role=role,
+            active=True,
+        )
+        db.add(user)
+        db.flush()
+    assert user is not None
+    if not user.active:
+        raise HTTPException(status_code=403, detail="User is inactive")
+    user.identity_provider = provider
+    user.external_subject = subject
+    record_audit_event(
+        db,
+        actor_type="system" if created else "user",
+        actor_id=None if created else user.id,
+        actor_label=settings.oidc_provider_name,
+        action="oidc_user_provisioned" if created else "oidc_identity_linked",
+        entity_type="user",
+        entity_id=user.id,
+        metadata={"provider": provider},
+    )
+    return user
+
+
+@router.get("/oidc/status", response_model=OidcStatusOut)
+def oidc_status() -> OidcStatusOut:
+    return OidcStatusOut(
+        enabled=_oidc_configured(),
+        provider_name=settings.oidc_provider_name if _oidc_configured() else None,
+    )
+
+
+@router.get("/oidc/login")
+async def oidc_login(request: Request) -> Response:
+    if not _oidc_configured():
+        raise HTTPException(status_code=404, detail="OIDC login is not configured")
+    client = oauth.create_client("oidc")
+    if client is None:
+        raise HTTPException(status_code=503, detail="OIDC client is unavailable")
+    return await client.authorize_redirect(request, _oidc_redirect_uri())
+
+
+@router.get("/oidc/callback")
+async def oidc_callback(request: Request, db: Session = Depends(get_db)) -> Response:
+    if not _oidc_configured():
+        raise HTTPException(status_code=404, detail="OIDC login is not configured")
+    client = oauth.create_client("oidc")
+    if client is None:
+        raise HTTPException(status_code=503, detail="OIDC client is unavailable")
+    try:
+        token = await client.authorize_access_token(request)
+    except OAuthError as exc:
+        raise HTTPException(status_code=401, detail="OIDC authentication failed") from exc
+    user = _resolve_oidc_user(db, dict(token.get("userinfo") or {}))
+    response = RedirectResponse(f"{settings.mobilityops_public_url.rstrip('/')}/dashboard")
+    _set_session(response, user)
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_id=user.id,
+        actor_label=user.display_name,
+        action="oidc_login",
+        entity_type="user",
+        entity_id=user.id,
+        metadata={"provider": settings.oidc_issuer_url.rstrip("/")},
+    )
+    db.commit()
+    return response
+
+
+@router.post("/login", response_model=CurrentUser)
+def password_login(
+    body: PasswordLoginRequest,
+    request: Request,
+    response: Response,
+    db: Session = Depends(get_db),
+) -> CurrentUser:
+    if settings.mobilityops_demo_mode:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Password login is unavailable in demo mode",
+        )
+    limiter_key = _client_key(request)
+    retry_after = _login_limiter.retry_after_seconds(limiter_key) if _login_limiter else 0
+    if retry_after:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many failed login attempts. Try again later.",
+            headers={"Retry-After": str(retry_after)},
+        )
+    user = db.scalar(select(User).where(User.email == body.email.strip().lower()))
+    if user is None or not user.active or not verify_password(body.password, user.password_hash):
+        if _login_limiter:
+            _login_limiter.record_failure(limiter_key)
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials")
+    if _login_limiter:
+        _login_limiter.reset(limiter_key)
+    _set_session(response, user)
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_id=user.id,
+        actor_label=user.display_name,
+        action="password_login",
+        entity_type="user",
+        entity_id=user.id,
+    )
+    db.commit()
+    return _current_user_out(user)
+
+
+@router.get("/session", response_model=CurrentUser)
+def get_session(response: Response, user: CurrentUser = Depends(get_current_user)) -> CurrentUser:
+    response.headers["Cache-Control"] = "no-store"
+    return user
+
+
+@router.post("/logout")
+def logout(request: Request, response: Response, db: Session = Depends(get_db)) -> dict:
+    token = request.cookies.get(settings.session_cookie_name)
+    payload = read_session_token(token) if token else None
+    if payload is not None and token is not None:
+        revoke_session(db, token, payload)
+        record_audit_event(
+            db,
+            actor_type="user",
+            actor_id=uuid.UUID(payload.user_id),
+            actor_label=payload.display_name,
+            action="logout",
+            entity_type="user",
+        )
+        db.commit()
+    response.delete_cookie(settings.session_cookie_name)
+    return {"status": "logged_out"}

backend/app/api/routers/bookings.py

@@ -1,20 +1,36 @@
 from __future__ import annotations
 
+import uuid
+from datetime import UTC, datetime
+from typing import Literal
+
 from fastapi import APIRouter, Depends, Header, HTTPException, Query, Response
-from sqlalchemy import select
+from sqlalchemy import case, func, or_, select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_current_user, get_db
 from app.models.booking import Booking
 from app.models.customer import Customer
+from app.models.inspection import Inspection
 from app.models.vehicle import Vehicle
 from app.schemas import (
+    AvailableVehicleOut,
     BookingOut,
+    BookingPageOut,
+    CancelBookingRequest,
+    CheckoutBookingRequest,
+    CheckoutBookingResult,
+    CompleteBookingRequirementsRequest,
+    CreateBookingRequest,
     CurrentUser,
     NextBookingRisk,
     RegisterReturnRequest,
+    RegisterReturnResult,
+    RescheduleBookingRequest,
     ReturnPreviewResult,
 )
+from app.services.audit import record_audit_event
+from app.services.data_quality import open_odometer_regression_issue
 from app.services.returns import preview_vehicle_return, register_vehicle_return
 
 router = APIRouter(prefix="/api/v1/bookings", tags=["bookings"])
@@ -35,25 +51,339 @@ def _to_out(booking: Booking, customer: Customer, vehicle: Vehicle) -> BookingOu
     )
 
 
-@router.get("", response_model=list[BookingOut])
+@router.get("", response_model=list[BookingOut] | BookingPageOut)
 def list_bookings(
     status: str | None = Query(default=None),
     vehicle_ref: str | None = Query(default=None),
+    query: str | None = Query(default=None, min_length=1, max_length=100),
+    starts_from: datetime | None = Query(default=None),
+    starts_to: datetime | None = Query(default=None),
+    location: str | None = Query(default=None, min_length=1, max_length=120),
+    sort: Literal["operational", "starts_asc", "starts_desc"] = Query(default="operational"),
+    page: int | None = Query(default=None, ge=1),
+    page_size: int = Query(default=25, ge=1, le=25),
     db: Session = Depends(get_db),
     _user: CurrentUser = Depends(get_current_user),
-) -> list[BookingOut]:
+) -> list[BookingOut] | BookingPageOut:
-    stmt = select(Booking).order_by(Booking.starts_at.desc())
+    stmt = select(Booking)
     if status:
         stmt = stmt.where(Booking.status == status)
     if vehicle_ref:
         vehicle = db.scalar(select(Vehicle).where(Vehicle.public_ref == vehicle_ref))
         if vehicle is None:
+            if page is None:
                 return []
+            return BookingPageOut(items=[], page=1, page_size=page_size, total=0, total_pages=1)
         stmt = stmt.where(Booking.vehicle_id == vehicle.id)
-    bookings = db.scalars(stmt).all()
+    if starts_from:
-    customers = {c.id: c for c in db.scalars(select(Customer)).all()}
+        stmt = stmt.where(Booking.ends_at >= starts_from)
-    vehicles = {v.id: v for v in db.scalars(select(Vehicle)).all()}
+    if starts_to:
-    return [_to_out(b, customers[b.customer_id], vehicles[b.vehicle_id]) for b in bookings]
+        stmt = stmt.where(Booking.starts_at < starts_to)
+    if query or location:
+        stmt = stmt.join(Customer, Booking.customer_id == Customer.id).join(
+            Vehicle, Booking.vehicle_id == Vehicle.id
+        )
+    if location:
+        stmt = stmt.where(Vehicle.location.ilike(location.strip()))
+    if query:
+        term = f"%{query.strip()}%"
+        stmt = stmt.where(
+            or_(
+                Booking.public_ref.ilike(term),
+                Customer.first_name.ilike(term),
+                Customer.last_name.ilike(term),
+                Vehicle.public_ref.ilike(term),
+            )
+        )
+    if sort == "starts_asc":
+        stmt = stmt.order_by(Booking.starts_at.asc())
+    elif sort == "starts_desc":
+        stmt = stmt.order_by(Booking.starts_at.desc())
+    else:
+        now = datetime.now(UTC)
+        operational_bucket = case(
+            (Booking.status == "active", 0),
+            (Booking.starts_at >= now, 1),
+            else_=2,
+        )
+        stmt = stmt.order_by(
+            operational_bucket,
+            case((Booking.starts_at >= now, Booking.starts_at)).asc().nulls_last(),
+            Booking.starts_at.desc(),
+        )
+    total = db.scalar(select(func.count()).select_from(stmt.subquery())) or 0
+    page_number = page or 1
+    bookings = db.scalars(
+        stmt if page is None else stmt.offset((page_number - 1) * page_size).limit(page_size)
+    ).all()
+    customer_ids = {booking.customer_id for booking in bookings}
+    vehicle_ids = {booking.vehicle_id for booking in bookings}
+    customers = {
+        customer.id: customer
+        for customer in db.scalars(select(Customer).where(Customer.id.in_(customer_ids))).all()
+    }
+    vehicles = {
+        vehicle.id: vehicle
+        for vehicle in db.scalars(select(Vehicle).where(Vehicle.id.in_(vehicle_ids))).all()
+    }
+    items = [_to_out(b, customers[b.customer_id], vehicles[b.vehicle_id]) for b in bookings]
+    if page is None:
+        return items
+    total_pages = max(1, (total + page_size - 1) // page_size)
+    return BookingPageOut(
+        items=items,
+        page=min(page_number, total_pages),
+        page_size=page_size,
+        total=total,
+        total_pages=total_pages,
+    )
+
+
+@router.post("", response_model=BookingOut, status_code=201)
+def create_booking(
+    body: CreateBookingRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(get_current_user),
+) -> BookingOut:
+    if body.ends_at <= body.starts_at:
+        raise HTTPException(status_code=422, detail="Booking end must be after its start")
+    customer = db.scalar(
+        select(Customer).where(Customer.public_ref == body.customer_ref).with_for_update()
+    )
+    if (
+        customer is None
+        or customer.merged_into_customer_id is not None
+        or customer.anonymized_at is not None
+    ):
+        raise HTTPException(status_code=422, detail="Customer is unavailable for booking")
+    # Serialise booking creation per vehicle. The overlap check must run after
+    # acquiring this lock, otherwise two concurrent requests can both pass it.
+    vehicle = db.scalar(
+        select(Vehicle).where(Vehicle.public_ref == body.vehicle_ref).with_for_update()
+    )
+    if (
+        vehicle is None
+        or not vehicle.active
+        or vehicle.operational_status in {"maintenance", "blocked"}
+    ):
+        raise HTTPException(status_code=422, detail="Vehicle is unavailable for booking")
+    overlap = db.scalar(
+        select(Booking.id).where(
+            Booking.vehicle_id == vehicle.id,
+            Booking.status.in_(("reserved", "active")),
+            Booking.starts_at < body.ends_at,
+            Booking.ends_at > body.starts_at,
+        )
+    )
+    if overlap is not None:
+        raise HTTPException(status_code=409, detail="Vehicle already has an overlapping booking")
+    booking = Booking(
+        public_ref=f"BK-{uuid.uuid4().hex[:10].upper()}",
+        customer_id=customer.id,
+        vehicle_id=vehicle.id,
+        starts_at=body.starts_at,
+        ends_at=body.ends_at,
+        status="reserved",
+        start_odometer_km=None,
+        end_odometer_km=None,
+        # Requirements are intentionally confirmed in a separate, audited action.
+        # Never allow booking creation to bypass that operational checkpoint.
+        requirements_complete=False,
+    )
+    db.add(booking)
+    db.flush()
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="booking_created",
+        entity_type="booking",
+        entity_id=booking.id,
+        after={"public_ref": booking.public_ref, "vehicle_ref": vehicle.public_ref},
+    )
+    db.commit()
+    return _to_out(booking, customer, vehicle)
+
+
+@router.post("/{public_ref}/checkout", response_model=CheckoutBookingResult)
+def checkout_booking(
+    public_ref: str,
+    body: CheckoutBookingRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(get_current_user),
+) -> CheckoutBookingResult:
+    booking = db.scalar(select(Booking).where(Booking.public_ref == public_ref).with_for_update())
+    if booking is None:
+        raise HTTPException(status_code=404, detail="Booking not found")
+    if booking.status != "reserved":
+        raise HTTPException(status_code=409, detail="Only a reserved booking can be checked out")
+    if not booking.requirements_complete:
+        raise HTTPException(status_code=409, detail="Booking requirements are incomplete")
+    vehicle = db.scalar(select(Vehicle).where(Vehicle.id == booking.vehicle_id).with_for_update())
+    if vehicle is None:
+        raise HTTPException(status_code=500, detail="Booking references a missing vehicle")
+    if not vehicle.active or vehicle.operational_status in {"maintenance", "blocked", "rented"}:
+        raise HTTPException(status_code=409, detail="Vehicle is not ready for checkout")
+    active_conflict = db.scalar(
+        select(Booking.id).where(
+            Booking.vehicle_id == vehicle.id,
+            Booking.status == "active",
+            Booking.id != booking.id,
+        )
+    )
+    if active_conflict is not None:
+        raise HTTPException(status_code=409, detail="Vehicle already has an active booking")
+
+    correlation_id = uuid.uuid4()
+    before_booking = {
+        "status": booking.status,
+        "start_odometer_km": booking.start_odometer_km,
+    }
+    before_vehicle = {
+        "operational_status": vehicle.operational_status,
+        "odometer_km": vehicle.odometer_km,
+    }
+    attention_reasons: list[str] = []
+    if body.start_odometer_km < vehicle.odometer_km:
+        attention_reasons.append("odometer_regression")
+    if not body.cleanliness_ok:
+        attention_reasons.append("cleanliness")
+    if body.damage_reported:
+        attention_reasons.append("damage")
+    if body.technical_warning:
+        attention_reasons.append("technical_warning")
+
+    inspection = Inspection(
+        public_ref=f"INSP-{uuid.uuid4().hex[:10].upper()}",
+        booking_id=booking.id,
+        vehicle_id=vehicle.id,
+        type="checkout",
+        fuel_level_percent=body.fuel_level_percent,
+        cleanliness_ok=body.cleanliness_ok,
+        damage_reported=body.damage_reported,
+        technical_warning=body.technical_warning,
+        notes=body.notes,
+        odometer_km=body.start_odometer_km,
+        completed_at=datetime.now(UTC),
+        completed_by=user.display_name,
+    )
+    db.add(inspection)
+    if "odometer_regression" in attention_reasons:
+        open_odometer_regression_issue(
+            db,
+            vehicle=vehicle,
+            reading_ref=inspection.public_ref,
+            reading_km=body.start_odometer_km,
+            canonical_km=vehicle.odometer_km,
+            source_type="checkout",
+            related_refs=[booking.public_ref, inspection.public_ref],
+            actor_label=user.display_name,
+            correlation_id=correlation_id,
+        )
+    if attention_reasons:
+        booking.status = "blocked"
+        vehicle.operational_status = (
+            "maintenance" if body.damage_reported or body.technical_warning else "cleaning"
+        )
+    else:
+        booking.status = "active"
+        booking.start_odometer_km = body.start_odometer_km
+        vehicle.odometer_km = max(vehicle.odometer_km, body.start_odometer_km)
+        vehicle.operational_status = "rented"
+    vehicle.version += 1
+    db.flush()
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="booking_checkout_recorded",
+        entity_type="booking",
+        entity_id=booking.id,
+        correlation_id=correlation_id,
+        before=before_booking,
+        after={
+            "inspection_ref": inspection.public_ref,
+            "booking_status": booking.status,
+            "start_odometer_km": booking.start_odometer_km,
+            "vehicle_status": vehicle.operational_status,
+            "attention_reasons": attention_reasons,
+        },
+    )
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="vehicle_status_changed",
+        entity_type="vehicle",
+        entity_id=vehicle.id,
+        correlation_id=correlation_id,
+        before=before_vehicle,
+        after={
+            "operational_status": vehicle.operational_status,
+            "odometer_km": vehicle.odometer_km,
+        },
+        metadata={"booking_ref": booking.public_ref, "inspection_ref": inspection.public_ref},
+    )
+    db.commit()
+    return CheckoutBookingResult(
+        booking_ref=booking.public_ref,
+        vehicle_ref=vehicle.public_ref,
+        inspection_ref=inspection.public_ref,
+        booking_status=booking.status,
+        resulting_vehicle_status=vehicle.operational_status,
+        activated=booking.status == "active",
+        attention_reasons=attention_reasons,
+    )
+
+
+@router.get("/availability", response_model=list[AvailableVehicleOut])
+def list_available_vehicles(
+    starts_at: datetime,
+    ends_at: datetime,
+    query: str | None = Query(default=None, max_length=100),
+    limit: int = Query(default=25, ge=1, le=50),
+    db: Session = Depends(get_db),
+    _user: CurrentUser = Depends(get_current_user),
+) -> list[AvailableVehicleOut]:
+    if ends_at <= starts_at:
+        raise HTTPException(status_code=422, detail="Booking end must be after its start")
+    overlapping_vehicle_ids = select(Booking.vehicle_id).where(
+        Booking.status.in_(("reserved", "active")),
+        Booking.starts_at < ends_at,
+        Booking.ends_at > starts_at,
+    )
+    stmt = (
+        select(Vehicle)
+        .where(
+            Vehicle.active.is_(True),
+            Vehicle.operational_status.not_in(("maintenance", "blocked")),
+            Vehicle.id.not_in(overlapping_vehicle_ids),
+        )
+        .order_by(Vehicle.location, Vehicle.public_ref)
+        .limit(limit)
+    )
+    if query and query.strip():
+        term = f"%{query.strip()}%"
+        stmt = stmt.where(
+            or_(
+                Vehicle.public_ref.ilike(term),
+                Vehicle.make.ilike(term),
+                Vehicle.model.ilike(term),
+                Vehicle.registration_number.ilike(term),
+                Vehicle.location.ilike(term),
+            )
+        )
+    return [
+        AvailableVehicleOut(
+            public_ref=vehicle.public_ref,
+            make=vehicle.make,
+            model=vehicle.model,
+            registration_number=vehicle.registration_number,
+            location=vehicle.location,
+            operational_status=vehicle.operational_status,
+        )
+        for vehicle in db.scalars(stmt).all()
+    ]
 
 
 @router.get("/{public_ref}", response_model=BookingOut)
@@ -72,6 +402,126 @@ def get_booking(
     return _to_out(booking, customer, vehicle)
 
 
+@router.post("/{public_ref}/complete-requirements", response_model=BookingOut)
+def complete_booking_requirements(
+    public_ref: str,
+    body: CompleteBookingRequirementsRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(get_current_user),
+) -> BookingOut:
+    booking = db.scalar(select(Booking).where(Booking.public_ref == public_ref).with_for_update())
+    if booking is None:
+        raise HTTPException(status_code=404, detail="Booking not found")
+    if booking.status != "reserved":
+        raise HTTPException(
+            status_code=409,
+            detail="Requirements can only be confirmed for a reserved booking",
+        )
+    customer = db.get(Customer, booking.customer_id)
+    vehicle = db.get(Vehicle, booking.vehicle_id)
+    if customer is None or vehicle is None:
+        raise HTTPException(status_code=500, detail="Booking references a missing record")
+    if not booking.requirements_complete:
+        booking.requirements_complete = True
+        record_audit_event(
+            db,
+            actor_type="user",
+            actor_label=user.display_name,
+            action="booking_requirements_completed",
+            entity_type="booking",
+            entity_id=booking.id,
+            before={"requirements_complete": False},
+            after={"requirements_complete": True},
+            metadata={"confirmation": body.confirmation.strip()},
+        )
+        db.commit()
+    return _to_out(booking, customer, vehicle)
+
+
+@router.patch("/{public_ref}/schedule", response_model=BookingOut)
+def reschedule_booking(
+    public_ref: str,
+    body: RescheduleBookingRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(get_current_user),
+) -> BookingOut:
+    if body.ends_at <= body.starts_at:
+        raise HTTPException(status_code=422, detail="Booking end must be after its start")
+    booking = db.scalar(select(Booking).where(Booking.public_ref == public_ref).with_for_update())
+    if booking is None:
+        raise HTTPException(status_code=404, detail="Booking not found")
+    if booking.status != "reserved":
+        raise HTTPException(status_code=409, detail="Only a reserved booking can be rescheduled")
+    vehicle = db.scalar(select(Vehicle).where(Vehicle.id == booking.vehicle_id).with_for_update())
+    customer = db.get(Customer, booking.customer_id)
+    if customer is None or vehicle is None:
+        raise HTTPException(status_code=500, detail="Booking references a missing record")
+    overlap = db.scalar(
+        select(Booking.id).where(
+            Booking.vehicle_id == booking.vehicle_id,
+            Booking.id != booking.id,
+            Booking.status.in_(("reserved", "active")),
+            Booking.starts_at < body.ends_at,
+            Booking.ends_at > body.starts_at,
+        )
+    )
+    if overlap is not None:
+        raise HTTPException(status_code=409, detail="Vehicle already has an overlapping booking")
+    before = {"starts_at": booking.starts_at.isoformat(), "ends_at": booking.ends_at.isoformat()}
+    booking.starts_at = body.starts_at
+    booking.ends_at = body.ends_at
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="booking_rescheduled",
+        entity_type="booking",
+        entity_id=booking.id,
+        before=before,
+        after={"starts_at": booking.starts_at.isoformat(), "ends_at": booking.ends_at.isoformat()},
+        metadata={"reason": body.reason.strip()},
+    )
+    db.commit()
+    return _to_out(booking, customer, vehicle)
+
+
+@router.post("/{public_ref}/cancel", response_model=BookingOut)
+def cancel_booking(
+    public_ref: str,
+    body: CancelBookingRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(get_current_user),
+) -> BookingOut:
+    booking = db.scalar(select(Booking).where(Booking.public_ref == public_ref).with_for_update())
+    if booking is None:
+        raise HTTPException(status_code=404, detail="Booking not found")
+    if booking.status not in ("reserved", "blocked"):
+        # A booking blocked at checkout (damage, technical warning, ...) has no other exit:
+        # it never became active, so it can neither be returned nor completed. Cancelling
+        # it (audited, with a reason) is the only way to close the file.
+        raise HTTPException(
+            status_code=409, detail="Only a reserved or blocked booking can be cancelled"
+        )
+    customer = db.get(Customer, booking.customer_id)
+    vehicle = db.get(Vehicle, booking.vehicle_id)
+    if customer is None or vehicle is None:
+        raise HTTPException(status_code=500, detail="Booking references a missing record")
+    before = {"status": booking.status}
+    booking.status = "cancelled"
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="booking_cancelled",
+        entity_type="booking",
+        entity_id=booking.id,
+        before=before,
+        after={"status": booking.status, "reason": body.reason.strip()},
+    )
+    db.commit()
+    return _to_out(booking, customer, vehicle)
+
+
 @router.post("/{public_ref}/return-preview", response_model=ReturnPreviewResult)
 def preview_return(
     public_ref: str,
@@ -89,6 +539,8 @@ def preview_return(
         resulting_odometer_km=evaluation.resulting_odometer_km,
         resulting_vehicle_status=evaluation.resulting_vehicle_status,
         status_reason=evaluation.status_reason,
+        status_reason_code=evaluation.status_reason_code,
+        status_reason_params=evaluation.status_reason_params,
         would_create_quality_issue=evaluation.would_create_quality_issue,
         attention_reasons=evaluation.attention_reasons,
         next_booking_risk=(
@@ -99,7 +551,7 @@ def preview_return(
     )
 
 
-@router.post("/{public_ref}/return")
+@router.post("/{public_ref}/return", response_model=RegisterReturnResult)
 def register_return(
     public_ref: str,
     body: RegisterReturnRequest,
@@ -107,7 +559,7 @@ def register_return(
     idempotency_key: str = Header(..., alias="Idempotency-Key", min_length=8, max_length=128),
     db: Session = Depends(get_db),
     user: CurrentUser = Depends(get_current_user),
-) -> dict:
+) -> RegisterReturnResult:
     status_code, result = register_vehicle_return(db, public_ref, body, idempotency_key, user)
     response.status_code = status_code
-    return result
+    return RegisterReturnResult(**result)

backend/app/api/routers/customers.py

@@ -0,0 +1,42 @@
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import or_, select
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_user, get_db
+from app.models.customer import Customer
+from app.schemas import CurrentUser, CustomerOptionOut
+
+router = APIRouter(prefix="/api/v1/customers", tags=["customers"])
+
+
+@router.get("", response_model=list[CustomerOptionOut])
+def search_customers(
+    query: str = Query(min_length=2, max_length=100),
+    limit: int = Query(default=20, ge=1, le=50),
+    db: Session = Depends(get_db),
+    _user: CurrentUser = Depends(get_current_user),
+) -> list[CustomerOptionOut]:
+    term = f"%{query.strip()}%"
+    customers = db.scalars(
+        select(Customer)
+        .where(
+            Customer.merged_into_customer_id.is_(None),
+            Customer.anonymized_at.is_(None),
+            or_(
+                Customer.public_ref.ilike(term),
+                Customer.first_name.ilike(term),
+                Customer.last_name.ilike(term),
+                Customer.email.ilike(term),
+            ),
+        )
+        .order_by(Customer.last_name, Customer.first_name)
+        .limit(limit)
+    ).all()
+    return [
+        CustomerOptionOut(
+            public_ref=customer.public_ref,
+            display_name=f"{customer.first_name} {customer.last_name}",
+            email=customer.email,
+        )
+        for customer in customers
+    ]

backend/app/api/routers/dashboard.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-from datetime import UTC, date, datetime
+from datetime import date, datetime
 from typing import Literal
+from zoneinfo import ZoneInfo
 
 from fastapi import APIRouter, Depends
 from sqlalchemy import select
@@ -19,6 +20,7 @@ from app.schemas import (
     AutomationRunOut,
     CurrentUser,
     DashboardOut,
+    EvidenceSignalOut,
     TodayItem,
 )
 from app.services.operations import compute_metrics
@@ -29,10 +31,20 @@ settings = get_settings()
 _SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2}
 
 
+def _local_tz() -> ZoneInfo:
+    return ZoneInfo(settings.demo_timezone)
+
+
 def _today() -> date:
     # Seeded dates are shifted to the real reset moment by `seed_loader.py`'s anchor
     # shift, so "today" must be real wall-clock time, not the frozen `demo_today` setting.
-    return datetime.now(UTC).date()
+    # Timestamps are stored in UTC but the operational day is the local (Europe/Brussels)
+    # calendar day, so a 23:30Z departure belongs to tomorrow's schedule in summer.
+    return datetime.now(_local_tz()).date()
+
+
+def _local_date(value: datetime) -> date:
+    return value.astimezone(_local_tz()).date()
 
 
 @router.get("", response_model=DashboardOut)
@@ -61,19 +73,34 @@ def get_dashboard(
             entity = customers_by_id.get(issue.entity_id)
             link_type = "customer"
         link_ref = entity.public_ref if entity else ""
+        # The backend never emits prose for the attention queue -- only stable signal
+        # codes + raw data params, exactly like the issue detail page's evidence list
+        # (see app/services/data_quality.py::_open_issue). The frontend is the one place
+        # that turns these into the operator's selected language; `evidence_json["summary"]`
+        # is a technical fallback only, never rendered here.
+        signals = [
+            EvidenceSignalOut(code=s["code"], params=s.get("params", {}))
+            for s in issue.evidence_json.get("signals", [])
+        ]
         attention_items.append(
             AttentionItem(
                 kind="quality_issue",
                 severity=issue.severity,
                 rule_type=issue.rule_type,
-                detail=issue.evidence_json.get("summary", ""),
+                evidence_signals=signals,
                 link_type=link_type,
                 link_ref=link_ref,
                 issue_ref=issue.public_ref,
             )
         )
-    attention_items.sort(key=lambda item: _SEVERITY_ORDER.get(item.severity, 3))
+    # Curate a credible severity mix instead of letting `high` dominate every slot:
-    attention_items = attention_items[:8]
+    # each item's real severity is unchanged, only the display selection is capped per
+    # tier (a handful of "now", then "today", then "later") so a heavy day of high-severity
+    # issues doesn't crowd out medium/low ones the operator should still see.
+    high_items = [i for i in attention_items if i.severity == "high"]
+    medium_items = [i for i in attention_items if i.severity == "medium"]
+    low_items = [i for i in attention_items if i.severity == "low"]
+    attention_items = (high_items[:3] + medium_items[:3] + low_items[:2])[:8]
 
     today = _today()
     bookings = db.scalars(select(Booking)).all()
@@ -81,25 +108,27 @@ def get_dashboard(
     for b in bookings:
         vehicle = vehicles_by_id.get(b.vehicle_id)
         vehicle_ref = vehicle.public_ref if vehicle else ""
-        if b.starts_at.date() == today and b.status in ("reserved", "active"):
+        if _local_date(b.starts_at) == today and b.status in ("reserved", "active"):
             today_items.append(
                 TodayItem(
-                    kind="departure", booking_ref=b.public_ref, vehicle_ref=vehicle_ref,
+                    kind="departure",
+                    booking_ref=b.public_ref,
+                    vehicle_ref=vehicle_ref,
                     scheduled_at=b.starts_at,
                 )
             )
-        if b.ends_at.date() == today and b.status in ("active", "returned"):
+        if _local_date(b.ends_at) == today and b.status in ("active", "returned"):
             today_items.append(
                 TodayItem(
-                    kind="return", booking_ref=b.public_ref, vehicle_ref=vehicle_ref,
+                    kind="return",
+                    booking_ref=b.public_ref,
+                    vehicle_ref=vehicle_ref,
                     scheduled_at=b.ends_at,
                 )
             )
     today_items.sort(key=lambda item: item.scheduled_at)
 
-    recent = db.scalars(
+    recent = db.scalars(select(OutboxEvent).order_by(OutboxEvent.occurred_at.desc()).limit(5)).all()
-        select(OutboxEvent).order_by(OutboxEvent.occurred_at.desc()).limit(5)
-    ).all()
     recent_automation = [
         AutomationRunOut(
             event_id=str(r.event_id),
@@ -108,6 +137,7 @@ def get_dashboard(
             status=r.delivery_status,
             attempts=r.attempts,
             last_error=r.last_error,
+            last_error_code=r.last_error_code,
             occurred_at=r.occurred_at,
         )
         for r in recent

backend/app/api/routers/data_quality.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+from datetime import UTC, datetime
+
 from fastapi import APIRouter, Depends, HTTPException, Query
-from sqlalchemy import select
+from sqlalchemy import case, func, select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_db, require_operations_manager
@@ -9,23 +11,33 @@ from app.models.booking import Booking
 from app.models.customer import Customer
 from app.models.data_quality import DataQualityIssue
 from app.models.inspection import Inspection
+from app.models.maintenance import MaintenanceRecord
+from app.models.user import User
 from app.models.vehicle import Vehicle
 from app.schemas import (
+    ApplyRecommendedStatusRequest,
     ApplyRecommendedStatusResult,
+    BulkDataQualityWorkRequest,
+    BulkDataQualityWorkResult,
     CurrentUser,
     DataQualityIssueDetailOut,
     DataQualityIssueOut,
+    DataQualityIssuePageOut,
     MergeCustomersRequest,
     MergeCustomersResult,
     ProvideFieldsRequest,
     ResolveOdometerRegressionRequest,
     ResolveOverlapRequest,
     ScanResultOut,
+    StatusRecommendationOut,
+    VehicleStatusFactsOut,
 )
+from app.services.audit import record_audit_event
 from app.services.data_quality import (
     apply_recommended_status,
     defer_issue,
     merge_customers,
+    preview_vehicle_status_recommendation,
     provide_missing_fields,
     reject_issue,
     resolve_booking_overlap,
@@ -37,6 +49,7 @@ router = APIRouter(prefix="/api/v1/data-quality", tags=["data-quality"])
 
 
 def _to_out(issue: DataQualityIssue) -> DataQualityIssueOut:
+    assignee = issue.assigned_to_user
     return DataQualityIssueOut(
         public_ref=issue.public_ref,
         rule_type=issue.rule_type,
@@ -46,27 +59,160 @@ def _to_out(issue: DataQualityIssue) -> DataQualityIssueOut:
         status=issue.status,
         evidence=issue.evidence_json,
         detected_at=issue.detected_at,
+        due_at=issue.due_at,
+        assigned_to_ref=assignee.public_ref if assignee else None,
+        assigned_to_name=assignee.display_name if assignee else None,
+        overdue=(
+            issue.status == "open" and issue.due_at is not None and issue.due_at < datetime.now(UTC)
+        ),
         resolved_at=issue.resolved_at,
     )
 
 
-@router.get("/issues", response_model=list[DataQualityIssueOut])
+@router.get("/issues", response_model=list[DataQualityIssueOut] | DataQualityIssuePageOut)
 def list_issues(
     status: str | None = Query(default=None),
     rule_type: str | None = Query(default=None),
     severity: str | None = Query(default=None),
+    assigned_to_ref: str | None = Query(default=None),
+    overdue: bool | None = Query(default=None),
+    demo_only: bool | None = Query(default=None),
+    page: int | None = Query(default=None, ge=1),
+    page_size: int = Query(default=25, ge=1, le=25),
     db: Session = Depends(get_db),
     _user: CurrentUser = Depends(require_operations_manager),
-) -> list[DataQualityIssueOut]:
+) -> list[DataQualityIssueOut] | DataQualityIssuePageOut:
-    stmt = select(DataQualityIssue).order_by(DataQualityIssue.detected_at.desc())
+    severity_order = case(
+        (DataQualityIssue.severity == "high", 0),
+        (DataQualityIssue.severity == "medium", 1),
+        else_=2,
+    )
+    stmt = select(DataQualityIssue).order_by(
+        DataQualityIssue.due_at.asc().nulls_last(),
+        severity_order,
+        DataQualityIssue.detected_at.desc(),
+    )
     if status:
         stmt = stmt.where(DataQualityIssue.status == status)
     if rule_type:
         stmt = stmt.where(DataQualityIssue.rule_type == rule_type)
     if severity:
         stmt = stmt.where(DataQualityIssue.severity == severity)
-    issues = db.scalars(stmt).all()
+    if assigned_to_ref == "unassigned":
-    return [_to_out(i) for i in issues]
+        stmt = stmt.where(DataQualityIssue.assigned_to_user_id.is_(None))
+    elif assigned_to_ref:
+        stmt = stmt.join(DataQualityIssue.assigned_to_user).where(
+            User.public_ref == assigned_to_ref
+        )
+    if overdue is True:
+        stmt = stmt.where(
+            DataQualityIssue.status == "open",
+            DataQualityIssue.due_at < datetime.now(UTC),
+        )
+    if demo_only is True:
+        # Server-side so the guided demo scenarios are found on any page, not only the
+        # 25 rows currently loaded in the browser.
+        stmt = stmt.where(DataQualityIssue.public_ref.like("DQ-DEMO-%"))
+    total = db.scalar(select(func.count()).select_from(stmt.subquery())) or 0
+    page_number = page or 1
+    issues = db.scalars(
+        stmt if page is None else stmt.offset((page_number - 1) * page_size).limit(page_size)
+    ).all()
+    items = [_to_out(i) for i in issues]
+    if page is None:
+        return items
+    total_pages = max(1, (total + page_size - 1) // page_size)
+    return DataQualityIssuePageOut(
+        items=items,
+        page=min(page_number, total_pages),
+        page_size=page_size,
+        total=total,
+        total_pages=total_pages,
+    )
+
+
+@router.post("/issues/bulk-work", response_model=BulkDataQualityWorkResult)
+def update_issue_work_queue(
+    body: BulkDataQualityWorkRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(require_operations_manager),
+) -> BulkDataQualityWorkResult:
+    refs = list(dict.fromkeys(body.issue_refs))
+    if (
+        body.assigned_to_ref is None
+        and not body.clear_assignment
+        and body.due_at is None
+        and not body.clear_due_at
+    ):
+        raise HTTPException(status_code=422, detail="No work queue change was requested")
+    if body.assigned_to_ref is not None and body.clear_assignment:
+        raise HTTPException(status_code=422, detail="Choose an assignee or clear assignment")
+    if body.due_at is not None and body.clear_due_at:
+        raise HTTPException(status_code=422, detail="Choose a due date or clear the due date")
+    if body.due_at is not None and body.due_at.tzinfo is None:
+        raise HTTPException(status_code=422, detail="Due date must include a timezone")
+
+    assignee = None
+    if body.assigned_to_ref is not None:
+        assignee = db.scalar(
+            select(User).where(
+                User.public_ref == body.assigned_to_ref,
+                User.active.is_(True),
+            )
+        )
+        if assignee is None:
+            raise HTTPException(status_code=422, detail="Active assignee not found")
+
+    issues = list(
+        db.scalars(
+            select(DataQualityIssue).where(DataQualityIssue.public_ref.in_(refs)).with_for_update()
+        ).all()
+    )
+    if len(issues) != len(refs):
+        found = {issue.public_ref for issue in issues}
+        missing = next(ref for ref in refs if ref not in found)
+        raise HTTPException(status_code=404, detail=f"Data quality issue {missing} not found")
+
+    for issue in issues:
+        if issue.status != "open":
+            raise HTTPException(
+                status_code=409,
+                detail=f"Data quality issue {issue.public_ref} is not open",
+            )
+        before = {
+            "assigned_to_ref": issue.assigned_to_user.public_ref
+            if issue.assigned_to_user
+            else None,
+            "due_at": issue.due_at.isoformat() if issue.due_at else None,
+        }
+        if body.assigned_to_ref is not None:
+            issue.assigned_to_user = assignee
+        elif body.clear_assignment:
+            issue.assigned_to_user = None
+        if body.due_at is not None:
+            issue.due_at = body.due_at
+        elif body.clear_due_at:
+            issue.due_at = None
+        after = {
+            "assigned_to_ref": assignee.public_ref
+            if body.assigned_to_ref is not None and assignee
+            else (None if body.clear_assignment else before["assigned_to_ref"]),
+            "due_at": issue.due_at.isoformat() if issue.due_at else None,
+        }
+        record_audit_event(
+            db,
+            actor_type="user",
+            actor_label=user.display_name,
+            action="data_quality_work_updated",
+            entity_type="data_quality_issue",
+            entity_id=issue.id,
+            before=before,
+            after=after,
+        )
+    db.commit()
+    for issue in issues:
+        db.refresh(issue)
+    return BulkDataQualityWorkResult(updated=[_to_out(issue) for issue in issues])
 
 
 # Every public reference in this system carries its entity type in its own prefix
@@ -79,6 +225,8 @@ _PREFIX_TO_TYPE = {
     "MO-": "vehicle",
     "BK-": "booking",
     "INSP-": "inspection",
+    "MAINT-": "maintenance",
+    "MNT-": "maintenance",
 }
 
 
@@ -111,6 +259,7 @@ def _snapshot(entity_type: str, ref: str, db: Session) -> dict | None:
         return {
             "entity_type": "vehicle",
             "public_ref": vehicle.public_ref,
+            "registration_number": vehicle.registration_number,
             "make": vehicle.make,
             "model": vehicle.model,
             "location": vehicle.location,
@@ -146,6 +295,17 @@ def _snapshot(entity_type: str, ref: str, db: Session) -> dict | None:
             "completed_at": inspection.completed_at.isoformat(),
             "booking_ref": booking.public_ref if booking else None,
         }
+    if entity_type == "maintenance":
+        record = db.scalar(select(MaintenanceRecord).where(MaintenanceRecord.public_ref == ref))
+        if record is None:
+            return None
+        return {
+            "entity_type": "maintenance",
+            "public_ref": record.public_ref,
+            "odometer_km": record.odometer_km,
+            "occurred_at": record.occurred_at.isoformat(),
+            "category": record.category,
+        }
     return None
 
 
@@ -217,9 +377,7 @@ def provide_fields(
     return _to_out(issue)
 
 
-@router.post(
+@router.post("/issues/{public_ref}/resolve-odometer-regression", response_model=DataQualityIssueOut)
-    "/issues/{public_ref}/resolve-odometer-regression", response_model=DataQualityIssueOut
-)
 def resolve_odometer(
     public_ref: str,
     body: ResolveOdometerRegressionRequest,
@@ -241,17 +399,41 @@ def resolve_overlap(
     return _to_out(issue)
 
 
+@router.post("/issues/{public_ref}/status-recommendation", response_model=StatusRecommendationOut)
+def status_recommendation(
+    public_ref: str,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(require_operations_manager),
+) -> StatusRecommendationOut:
+    """Non-mutating preview: computes the recommendation without changing anything,
+    resolving no issue and writing no audit event. Safe to call repeatedly."""
+    _issue, _vehicle, recommendation, token = preview_vehicle_status_recommendation(db, public_ref)
+    return StatusRecommendationOut(
+        current_status=recommendation.current_status,
+        recommended_status=recommendation.recommended_status,
+        recommendation_code=recommendation.recommendation_code,
+        safe_to_apply=recommendation.safe_to_apply,
+        manual_review_required=recommendation.manual_review_required,
+        facts=VehicleStatusFactsOut(**recommendation.facts.as_dict()),
+        blocking_reasons=recommendation.blocking_reasons,
+        recommendation_token=token,
+    )
+
+
 @router.post(
     "/issues/{public_ref}/apply-recommended-status", response_model=ApplyRecommendedStatusResult
 )
 def apply_status(
     public_ref: str,
+    body: ApplyRecommendedStatusRequest,
     db: Session = Depends(get_db),
     user: CurrentUser = Depends(require_operations_manager),
 ) -> ApplyRecommendedStatusResult:
-    issue, applied_status, reason = apply_recommended_status(db, public_ref, user)
+    issue, applied_status, reason_code = apply_recommended_status(
+        db, public_ref, user, body.recommendation_token
+    )
     return ApplyRecommendedStatusResult(
-        issue=_to_out(issue), applied_status=applied_status, reason=reason
+        issue=_to_out(issue), applied_status=applied_status, reason_code=reason_code
     )
 
 

backend/app/api/routers/demo.py

@@ -1,27 +1,36 @@
 from __future__ import annotations
 
+import threading
 import time
 import uuid
+from datetime import UTC, datetime
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_current_user, get_db, require_operations_manager
 from app.core.config import get_settings
+from app.core.db import begin_exclusive_demo_reset, end_exclusive_demo_reset, engine
 from app.core.security import SessionPayload, create_session_token, read_session_token
+from app.models.audit import AuditEvent
 from app.models.user import User
 from app.schemas import CurrentUser, DemoLoginRequest, DemoManifestOut
 from app.seed_loader import reset_and_seed
 from app.services.audit import record_audit_event
 from app.services.demo_manifest import build_demo_manifest, scenario_integrity_report
+from app.services.sessions import revoke_session
 
 router = APIRouter(prefix="/api/v1/demo", tags=["demo"])
 settings = get_settings()
+_reset_guard = threading.Lock()
+_RESET_ADVISORY_LOCK_ID = 706_533_149
 
 
 @router.get("/manifest", response_model=DemoManifestOut)
 def demo_manifest(db: Session = Depends(get_db)) -> DemoManifestOut:
+    if not settings.mobilityops_demo_mode:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Demo mode is disabled")
     # Deliberately unauthenticated: the demo-entry screen and the permanent demo badge
     # both need this before any session exists. Nothing here is sensitive — it's the same
     # honest "what is this demo" summary a logged-in user would see.
@@ -32,6 +41,8 @@ def demo_manifest(db: Session = Depends(get_db)) -> DemoManifestOut:
 def demo_login(
     body: DemoLoginRequest, response: Response, db: Session = Depends(get_db)
 ) -> CurrentUser:
+    if not settings.mobilityops_demo_mode:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Demo mode is disabled")
     public_ref = "USR-OPS" if body.role == "operations_manager" else "USR-EMP"
     user = db.scalar(select(User).where(User.public_ref == public_ref))
     if user is None:
@@ -44,6 +55,7 @@ def demo_login(
             role=user.role,
             display_name=user.display_name,
             issued_at=int(time.time()),
+            session_id=str(uuid.uuid4()),
         )
     )
     response.set_cookie(
@@ -68,9 +80,7 @@ def demo_login(
 
 
 @router.get("/session", response_model=CurrentUser)
-def get_session(
+def get_session(response: Response, user: CurrentUser = Depends(get_current_user)) -> CurrentUser:
-    response: Response, user: CurrentUser = Depends(get_current_user)
-) -> CurrentUser:
     # Never let the browser (or an intermediary) cache an authentication check — a stale
     # cached 200 here would keep showing a logged-out browser as authenticated.
     response.headers["Cache-Control"] = "no-store"
@@ -81,7 +91,8 @@ def get_session(
 def demo_logout(request: Request, response: Response, db: Session = Depends(get_db)) -> dict:
     token = request.cookies.get(settings.session_cookie_name)
     payload = read_session_token(token) if token else None
-    if payload is not None:
+    if payload is not None and token is not None:
+        revoke_session(db, token, payload)
         record_audit_event(
             db,
             actor_type="user",
@@ -101,12 +112,46 @@ def demo_reset(
     db: Session = Depends(get_db),
     user: CurrentUser = Depends(require_operations_manager),
 ) -> dict:
+    if not settings.mobilityops_demo_mode:
+        # Outside demo mode the reset endpoint must not exist at all: it wipes
+        # operational data and replaces it with synthetic records.
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Demo mode is disabled")
     if not settings.demo_allow_reset:
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
             detail="Demo reset is disabled on this deployment.",
         )
-    result = reset_and_seed(db)
+    if not _reset_guard.acquire(blocking=False):
+        raise HTTPException(status_code=409, detail="A demo reset is already running.")
+    replica_lock_connection = None
+    try:
+        # A session-level lock on its own connection rejects another replica immediately;
+        # the main DB session can then safely end its auth read transaction and wait on
+        # the normal shared/exclusive data barrier without releasing this replica guard.
+        replica_lock_connection = engine.connect()
+        locked = replica_lock_connection.scalar(
+            select(func.pg_try_advisory_lock(_RESET_ADVISORY_LOCK_ID))
+        )
+        if not locked:
+            raise HTTPException(status_code=409, detail="A demo reset is already running.")
+        begin_exclusive_demo_reset(db)
+        # The audit timestamp is shared by every replica. A process-local monotonic
+        # timestamp cannot protect a multi-replica deployment.
+        last_reset_at = db.scalar(
+            select(AuditEvent.occurred_at)
+            .where(AuditEvent.action == "demo_reset")
+            .order_by(AuditEvent.occurred_at.desc())
+            .limit(1)
+        )
+        elapsed = (datetime.now(UTC) - last_reset_at).total_seconds() if last_reset_at else None
+        if elapsed is not None and elapsed < settings.demo_reset_cooldown_seconds:
+            retry_after = max(1, int(settings.demo_reset_cooldown_seconds - elapsed + 0.999))
+            raise HTTPException(
+                status_code=429,
+                detail=f"Demo reset is cooling down. Retry in {retry_after} seconds.",
+                headers={"Retry-After": str(retry_after)},
+            )
+        result = reset_and_seed(db, preserve_integration_telemetry=True, commit=False)
         integrity = scenario_integrity_report(db)
         record_audit_event(
             db,
@@ -121,6 +166,16 @@ def demo_reset(
             },
         )
         db.commit()
+        end_exclusive_demo_reset(db)
+    finally:
+        if replica_lock_connection is not None:
+            try:
+                replica_lock_connection.scalar(
+                    select(func.pg_advisory_unlock(_RESET_ADVISORY_LOCK_ID))
+                )
+            finally:
+                replica_lock_connection.close()
+        _reset_guard.release()
     response.delete_cookie(settings.session_cookie_name)
     return {
         "status": "reset",

backend/app/api/routers/integration_status.py

@@ -4,16 +4,10 @@ from fastapi import APIRouter, Depends
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_db, require_operations_manager
-from app.core.config import get_settings
+from app.schemas import CurrentUser, IntegrationStatusOut
-from app.schemas import (
+from app.services.integration_status import derive_mcp_hub_status, derive_n8n_status
-    CurrentUser,
-    IntegrationStatusOut,
-    McpHubIntegrationStatus,
-)
-from app.services.integration_status import derive_n8n_status
 
 router = APIRouter(prefix="/api/v1/integrations", tags=["integrations"])
-settings = get_settings()
 
 
 @router.get("/status", response_model=IntegrationStatusOut)
@@ -23,8 +17,5 @@ def integration_status(
 ) -> IntegrationStatusOut:
     return IntegrationStatusOut(
         n8n=derive_n8n_status(db),
-        mcp_hub=McpHubIntegrationStatus(
+        mcp_hub=derive_mcp_hub_status(db),
-            registration_enabled=settings.mcp_hub_registration_enabled,
-            state="configured" if settings.mcp_hub_registration_enabled else "not_configured",
-        ),
     )

backend/app/api/routers/integrations.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
+import hashlib
+import hmac
 import uuid
 from datetime import UTC, datetime
-from typing import Any
+from pathlib import Path
 
 from fastapi import APIRouter, Depends, Header
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_db
@@ -13,23 +15,101 @@ from app.core.config import get_settings
 from app.core.errors import AppError
 from app.models.audit import AuditEvent
 from app.models.outbox import OutboxEvent
-from app.schemas import ScanResultOut
+from app.schemas import (
+    N8nHeartbeatIn,
+    N8nHeartbeatResult,
+    ProcedureDocumentOut,
+    ProcedureListOut,
+    ProcedureSyncResultIn,
+    ProcedureSyncResultResult,
+    ReturnCallbackIn,
+    ScanResultOut,
+    WorkflowErrorReportIn,
+    WorkflowErrorReportResult,
+)
 from app.services.audit import record_audit_event
 from app.services.data_quality import run_scan
+from app.services.knowledge.procedures import iter_procedure_documents
 
 router = APIRouter(prefix="/api/v1/integrations/n8n", tags=["integrations"])
 settings = get_settings()
 
+_CANONICAL_WORKFLOW_NAMES = frozenset(
+    {
+        "Fleet Ops — Vehicle Return Orchestration",
+        "Fleet Ops — Scheduled Data Quality Scan",
+        "Fleet Ops — RAGcore Procedure Sync",
+        "Fleet Ops — Workflow Error Handler",
+    }
+)
+
+
+def _require_service_token(service_token: str) -> None:
+    # Constant-time comparison: a plain ``!=`` leaks how many leading bytes matched.
+    if not hmac.compare_digest(
+        service_token.encode("utf-8"), settings.n8n_callback_token.encode("utf-8")
+    ):
+        raise AppError("UNAUTHORIZED_SERVICE", "Invalid service token.", status_code=401)
+
+
+def _lock_idempotency_key(db: Session, namespace: str, key: str) -> None:
+    """Serialize callback check+insert by a stable, transaction-scoped key."""
+    digest = hashlib.sha256(f"{namespace}:{key}".encode()).digest()
+    lock_id = int.from_bytes(digest[:8], byteorder="big", signed=True)
+    db.scalar(select(func.pg_advisory_xact_lock(lock_id)))
+
+
+@router.post("/heartbeat", response_model=N8nHeartbeatResult)
+def workflow_heartbeat(
+    body: N8nHeartbeatIn,
+    service_token: str = Header(..., alias="X-Service-Token"),
+    db: Session = Depends(get_db),
+) -> N8nHeartbeatResult:
+    """Authenticated, idempotent execution evidence from a canonical n8n workflow."""
+    _require_service_token(service_token)
+    if body.workflow_name not in _CANONICAL_WORKFLOW_NAMES:
+        raise AppError("UNKNOWN_WORKFLOW", "Unknown Fleet Ops workflow.", status_code=422)
+    _lock_idempotency_key(db, "n8n_workflow_heartbeat", f"{body.execution_id}:{body.status}")
+    already_recorded = (
+        db.scalar(
+            select(AuditEvent.id).where(
+                AuditEvent.action == "n8n_workflow_heartbeat",
+                AuditEvent.metadata_json["execution_id"].astext == body.execution_id,
+                AuditEvent.after_json["status"].astext == body.status,
+            )
+        )
+        is not None
+    )
+    if not already_recorded:
+        record_audit_event(
+            db,
+            actor_type="service",
+            actor_label="n8n workflow heartbeat",
+            action="n8n_workflow_heartbeat",
+            entity_type="automation",
+            after={
+                "workflow_id": body.workflow_id,
+                "workflow_name": body.workflow_name,
+                "status": body.status,
+            },
+            metadata={"execution_id": body.execution_id},
+        )
+        db.commit()
+    return N8nHeartbeatResult(
+        status="already_registered" if already_recorded else "registered",
+        execution_id=body.execution_id,
+        occurred_at=datetime.now(UTC),
+    )
+
 
 @router.post("/return-callback")
 def return_callback(
-    body: dict[str, Any],
+    body: ReturnCallbackIn,
     idempotency_key: str = Header(..., alias="Idempotency-Key"),
     service_token: str = Header(..., alias="X-Service-Token"),
     db: Session = Depends(get_db),
 ) -> dict:
-    if service_token != settings.n8n_callback_token:
+    _require_service_token(service_token)
-        raise AppError("UNAUTHORIZED_SERVICE", "Invalid service token.", status_code=401)
 
     try:
         event_id = uuid.UUID(idempotency_key)
@@ -38,9 +118,29 @@ def return_callback(
             "INVALID_IDEMPOTENCY_KEY", "Idempotency-Key must be the event's UUID.", status_code=422
         ) from exc
 
-    event = db.scalar(select(OutboxEvent).where(OutboxEvent.event_id == event_id))
+    event = db.scalar(select(OutboxEvent).where(OutboxEvent.event_id == event_id).with_for_update())
     if event is None:
         raise AppError("EVENT_NOT_FOUND", "No outbox event matches this event ID.", status_code=404)
+    if body.event_id != event_id:
+        raise AppError(
+            "CALLBACK_EVENT_MISMATCH",
+            "Callback event_id does not match Idempotency-Key.",
+            status_code=409,
+        )
+    try:
+        expected_correlation_id = uuid.UUID(str(event.payload_json["correlation_id"]))
+    except (KeyError, TypeError, ValueError) as exc:
+        raise AppError(
+            "INVALID_EVENT_CORRELATION",
+            "The stored outbox event has no valid correlation ID.",
+            status_code=409,
+        ) from exc
+    if body.correlation_id != expected_correlation_id:
+        raise AppError(
+            "CALLBACK_CORRELATION_MISMATCH",
+            "Callback correlation_id does not match the outbox event.",
+            status_code=409,
+        )
 
     # Idempotent by event ID: n8n or our own dispatcher may redeliver the same event
     # (e.g. a lost response after a timeout), so this callback must not double-record.
@@ -60,10 +160,8 @@ def return_callback(
             actor_label="n8n",
             action="n8n_return_followup_recorded",
             entity_type="booking",
-            correlation_id=uuid.UUID(body.get("correlation_id"))
+            correlation_id=expected_correlation_id,
-            if body.get("correlation_id")
+            after={"follow_up": body.follow_up, "summary": body.summary},
-            else None,
-            after={"follow_up": body.get("follow_up"), "summary": body.get("summary")},
             metadata={"event_id": str(event_id)},
         )
         db.commit()
@@ -84,8 +182,121 @@ def scheduled_scan(
     safe to call repeatedly: run_scan() only ever creates an issue for a condition that
     doesn't already have one open, so a duplicate or overlapping trigger does no
     duplicate domain work -- it just reports zero new issues for anything already known."""
-    if service_token != settings.n8n_callback_token:
+    _require_service_token(service_token)
-        raise AppError("UNAUTHORIZED_SERVICE", "Invalid service token.", status_code=401)
 
     result = run_scan(db, actor_label="n8n scheduled scan", actor_type="service")
     return ScanResultOut(created=result.created)
+
+
+@router.post("/workflow-error", response_model=WorkflowErrorReportResult)
+def workflow_error(
+    body: WorkflowErrorReportIn,
+    service_token: str = Header(..., alias="X-Service-Token"),
+    db: Session = Depends(get_db),
+) -> WorkflowErrorReportResult:
+    """Receives a bounded, secret-free failure report from the central n8n "Fleet Ops --
+    Workflow Error Handler" workflow, which is attached as the Error Workflow on every
+    other Fleet Ops n8n workflow. Idempotent on execution_id: n8n may redeliver the same
+    error report (e.g. after a timed-out response), so this must not double-record."""
+    _require_service_token(service_token)
+    _lock_idempotency_key(db, "n8n_workflow_failure", body.execution_id)
+
+    already_recorded = (
+        db.scalar(
+            select(AuditEvent.id).where(
+                AuditEvent.action == "n8n_workflow_failure_registered",
+                AuditEvent.metadata_json["execution_id"].astext == body.execution_id,
+            )
+        )
+        is not None
+    )
+    if not already_recorded:
+        record_audit_event(
+            db,
+            actor_type="service",
+            actor_label="n8n error handler",
+            action="n8n_workflow_failure_registered",
+            entity_type="automation",
+            correlation_id=body.correlation_id,
+            after={
+                "workflow_id": body.workflow_id,
+                "workflow_name": body.workflow_name,
+                "error_category": body.error_category,
+                "error_summary": body.error_summary,
+                "trigger_context": body.trigger_context,
+                "attempt": body.attempt,
+                "retry_action": body.retry_action,
+                "failed_at": body.failed_at.isoformat(),
+            },
+            metadata={"execution_id": body.execution_id},
+        )
+        db.commit()
+
+    return WorkflowErrorReportResult(
+        status="already_registered" if already_recorded else "registered",
+        execution_id=body.execution_id,
+        occurred_at=datetime.now(UTC),
+    )
+
+
+@router.get("/procedures", response_model=ProcedureListOut)
+def list_procedures(service_token: str = Header(..., alias="X-Service-Token")) -> ProcedureListOut:
+    """Read-only source list for the RAGcore Procedure Sync workflow: every procedure
+    Markdown file Fleet Ops ships, across every supported language, with a stable
+    per-document id (source_id) and a content hash so the caller can detect changes
+    without re-fetching content it already has."""
+    _require_service_token(service_token)
+
+    documents = [
+        ProcedureDocumentOut(
+            id=doc.source_id,
+            language=doc.language,
+            document_id=doc.document_id,
+            title=doc.title,
+            version=doc.version,
+            content=doc.content,
+            content_hash=doc.content_hash,
+        )
+        for doc in iter_procedure_documents(Path(settings.knowledge_dir))
+    ]
+    return ProcedureListOut(documents=documents)
+
+
+@router.post("/procedures-sync-result", response_model=ProcedureSyncResultResult)
+def procedures_sync_result(
+    body: ProcedureSyncResultIn,
+    service_token: str = Header(..., alias="X-Service-Token"),
+    db: Session = Depends(get_db),
+) -> ProcedureSyncResultResult:
+    """Receives a summary (counts only, no document content) from the n8n "Fleet Ops --
+    RAGcore Procedure Sync" workflow once it finishes uploading procedures to RAGcore.
+    Idempotent on execution_id, matching the workflow-error and return-callback pattern."""
+    _require_service_token(service_token)
+    _lock_idempotency_key(db, "n8n_procedure_sync", body.execution_id)
+
+    already_recorded = (
+        db.scalar(
+            select(AuditEvent.id).where(
+                AuditEvent.action == "n8n_procedures_synced",
+                AuditEvent.metadata_json["execution_id"].astext == body.execution_id,
+            )
+        )
+        is not None
+    )
+    if not already_recorded:
+        record_audit_event(
+            db,
+            actor_type="service",
+            actor_label="n8n procedure sync",
+            action="n8n_procedures_synced",
+            entity_type="automation",
+            after={"synced": body.synced, "failed": body.failed},
+            metadata={"execution_id": body.execution_id},
+        )
+        db.commit()
+
+    return ProcedureSyncResultResult(
+        status="already_registered" if already_recorded else "registered",
+        execution_id=body.execution_id,
+        occurred_at=datetime.now(UTC),
+    )

backend/app/api/routers/knowledge.py

@@ -1,18 +1,32 @@
 from __future__ import annotations
 
+import hashlib
 import uuid
 from typing import Literal
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, HTTPException, Request, status
 from pydantic import BaseModel, Field
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_current_user, get_db
+from app.core.config import get_settings
+from app.core.ratelimit import SlidingWindowLimiter
+from app.models.audit import AuditEvent
 from app.schemas import CurrentUser
 from app.services.audit import record_audit_event
 from app.services.knowledge import GroundedAnswer, KnowledgeHealth, get_knowledge_provider
 
 router = APIRouter(prefix="/api/v1/knowledge", tags=["knowledge"])
+settings = get_settings()
+_question_limiter = (
+    SlidingWindowLimiter(
+        max_requests=settings.knowledge_max_requests,
+        window_seconds=settings.knowledge_rate_limit_window_seconds,
+    )
+    if settings.knowledge_max_requests > 0
+    else None
+)
 
 SupportedLanguage = Literal["nl-BE", "en-GB", "fr-BE"]
 
@@ -22,12 +36,39 @@ class AskQuestionRequest(BaseModel):
     language: SupportedLanguage = "en-GB"
 
 
+class KnowledgeFeedbackRequest(BaseModel):
+    correlation_id: uuid.UUID
+    helpful: bool
+
+
 @router.post("/questions", response_model=GroundedAnswer)
 def ask_question(
     body: AskQuestionRequest,
+    request: Request,
     db: Session = Depends(get_db),
     user: CurrentUser = Depends(get_current_user),
 ) -> GroundedAnswer:
+    if _question_limiter is not None:
+        forwarded = request.headers.get("x-forwarded-for", "")
+        client_ip = (
+            forwarded.split(",")[-1].strip()
+            if forwarded
+            else request.client.host
+            if request.client
+            else "unknown"
+        )
+        token = request.cookies.get(settings.session_cookie_name, "")
+        session_key = hashlib.sha256(token.encode("utf-8")).hexdigest()
+        retry_after = max(
+            _question_limiter.consume(f"ip:{client_ip}"),
+            _question_limiter.consume(f"session:{session_key}"),
+        )
+        if retry_after:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Too many knowledge questions. Try again later.",
+                headers={"Retry-After": str(retry_after)},
+            )
     correlation_id = str(uuid.uuid4())
     provider = get_knowledge_provider()
     answer = provider.ask(body.question, correlation_id, body.language)
@@ -51,9 +92,78 @@ def ask_question(
     return answer
 
 
+@router.post("/feedback")
+def record_feedback(
+    body: KnowledgeFeedbackRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(get_current_user),
+) -> dict[str, str]:
+    question_event = db.scalar(
+        select(AuditEvent.id).where(
+            AuditEvent.action == "knowledge_question_asked",
+            AuditEvent.correlation_id == body.correlation_id,
+            AuditEvent.actor_label == user.display_name,
+        )
+    )
+    if question_event is None:
+        raise HTTPException(status_code=404, detail="Knowledge exchange not found")
+
+    existing = db.scalar(
+        select(AuditEvent).where(
+            AuditEvent.action == "knowledge_feedback_recorded",
+            AuditEvent.correlation_id == body.correlation_id,
+            AuditEvent.actor_label == user.display_name,
+        )
+    )
+    if existing is not None:
+        existing.metadata_json = {"helpful": body.helpful}
+    else:
+        record_audit_event(
+            db,
+            actor_type="user",
+            actor_label=user.display_name,
+            action="knowledge_feedback_recorded",
+            entity_type="knowledge",
+            correlation_id=body.correlation_id,
+            metadata={"helpful": body.helpful},
+        )
+    db.commit()
+    return {"status": "recorded"}
+
+
 @router.get("/status", response_model=KnowledgeHealth)
 def knowledge_status(
     language: SupportedLanguage = "en-GB",
+    db: Session = Depends(get_db),
     _user: CurrentUser = Depends(get_current_user),
 ) -> KnowledgeHealth:
-    return get_knowledge_provider().health(language)
+    health = get_knowledge_provider().health(language)
+    if health.provider != "ragcore":
+        return health
+
+    latest_sync = db.scalar(
+        select(AuditEvent)
+        .where(AuditEvent.action == "n8n_procedures_synced")
+        .order_by(AuditEvent.occurred_at.desc())
+        .limit(1)
+    )
+    if latest_sync is None:
+        return health
+
+    reported = latest_sync.after_json or {}
+    synced = reported.get("synced")
+    failed = reported.get("failed")
+    return health.model_copy(
+        update={
+            "reported_synced_document_count": synced if isinstance(synced, int) else None,
+            "reported_failed_document_count": failed if isinstance(failed, int) else None,
+            "last_sync_at": latest_sync.occurred_at,
+            # A persisted sync callback is useful additional provenance, but must not
+            # downgrade stronger provider-side verification to merely "reported".
+            "statistics_state": (
+                health.statistics_state
+                if health.statistics_state == "verified"
+                else "sync_reported"
+            ),
+        }
+    )

backend/app/api/routers/mcp_integrations.py

@@ -3,11 +3,11 @@ from __future__ import annotations
 import uuid
 from datetime import date
 
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, Header, Query, Response
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app.api.deps import get_db, require_mcp_service_token
+from app.api.deps import McpClientContext, get_db, require_mcp_service_token
 from app.core.config import get_settings
 from app.core.errors import AppError
 from app.models.booking import Booking
@@ -27,44 +27,94 @@ router = APIRouter(prefix="/api/v1/integrations/mcp", tags=["mcp"])
 settings = get_settings()
 
 
-def _audit_service_request(db: Session, *, client_id: str, tool: str, status_label: str) -> None:
+def get_correlation_id(
+    x_correlation_id: str | None = Header(default=None, alias="X-Correlation-Id"),
+) -> str:
+    """Preserve the Hub's own inbound correlation ID through MCP client -> Hub -> Fleet
+    Ops -> RAGcore -> Fleet Ops Audit; only mint a fresh one when none was supplied or
+    it isn't a valid UUID (per the task's own correlation-propagation contract)."""
+    if x_correlation_id:
+        try:
+            return str(uuid.UUID(x_correlation_id))
+        except ValueError:
+            pass
+    return str(uuid.uuid4())
+
+
+def _audit_service_request(
+    db: Session,
+    *,
+    reported_client_id: str,
+    tool: str,
+    status_label: str,
+    correlation_id: str,
+    metadata: dict[str, object] | None = None,
+) -> None:
     record_audit_event(
         db,
         actor_type="service",
-        actor_label=client_id,
+        # The shared service token authenticates the Hub, not the caller identity that
+        # the Hub reports in a header. Keep attribution authoritative and retain the
+        # reported value only as explicitly non-authenticated diagnostic metadata.
+        actor_label="itworx-mcp-hub",
         action="mcp_tool_request",
         entity_type="mcp_tool",
-        correlation_id=uuid.uuid4(),
+        correlation_id=uuid.UUID(correlation_id),
-        metadata={"tool": tool, "status": status_label},
+        metadata={
+            "tool": tool,
+            "status": status_label,
+            "reported_client_id": reported_client_id,
+            **(metadata or {}),
+        },
     )
     db.commit()
 
 
+def _set_trace_headers(response: Response, correlation_id: str, tenant: str) -> None:
+    response.headers["X-Correlation-Id"] = correlation_id
+    response.headers["X-Tenant-Id"] = tenant
+    response.headers["Cache-Control"] = "no-store"
+
+
 @router.get("/operations-summary", response_model=OperationsSummaryOut)
 def operations_summary(
+    response: Response,
     db: Session = Depends(get_db),
-    client_id: str = Depends(require_mcp_service_token),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
 ) -> OperationsSummaryOut:
     metrics = compute_metrics(db)
+    _set_trace_headers(response, correlation_id, client.tenant)
     _audit_service_request(
-        db, client_id=client_id, tool="mobilityops_get_operations_summary", status_label="ok"
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_get_operations_summary",
+        status_label="ok",
+        correlation_id=correlation_id,
     )
-    return OperationsSummaryOut(tenant=settings.ragcore_tenant, metrics=metrics)
+    return OperationsSummaryOut(tenant=client.tenant, metrics=metrics)
 
 
 @router.get("/attention-vehicles", response_model=list[AttentionVehicleOut])
 def attention_vehicles(
+    response: Response,
     minimum_severity: str = Query(default="medium", pattern="^(low|medium|high)$"),
     date_filter: date | None = Query(default=None, alias="date"),
     limit: int = Query(default=20, ge=1, le=50),
     db: Session = Depends(get_db),
-    client_id: str = Depends(require_mcp_service_token),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
 ) -> list[AttentionVehicleOut]:
     results = list_attention_vehicles(
         db, minimum_severity=minimum_severity, on_or_before=date_filter, limit=limit
     )
+    _set_trace_headers(response, correlation_id, client.tenant)
     _audit_service_request(
-        db, client_id=client_id, tool="mobilityops_list_attention_vehicles", status_label="ok"
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_list_attention_vehicles",
+        status_label="ok",
+        correlation_id=correlation_id,
     )
     return [AttentionVehicleOut(**r) for r in results]
 
@@ -72,16 +122,20 @@ def attention_vehicles(
 @router.get("/vehicles/{vehicle_ref}", response_model=McpVehicleDetailOut)
 def vehicle_details(
     vehicle_ref: str,
+    response: Response,
     db: Session = Depends(get_db),
-    client_id: str = Depends(require_mcp_service_token),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
 ) -> McpVehicleDetailOut:
+    _set_trace_headers(response, correlation_id, client.tenant)
     vehicle = db.scalar(select(Vehicle).where(Vehicle.public_ref == vehicle_ref))
     if vehicle is None:
         _audit_service_request(
             db,
-            client_id=client_id,
+            reported_client_id=client.reported_client_id,
-            tool="mobilityops_get_vehicle_details",
+            tool="fleet_ops_get_vehicle_details",
             status_label="not_found",
+            correlation_id=correlation_id,
         )
         raise AppError("VEHICLE_NOT_FOUND", "Vehicle not found.", status_code=404)
 
@@ -99,7 +153,11 @@ def vehicle_details(
     )
 
     _audit_service_request(
-        db, client_id=client_id, tool="mobilityops_get_vehicle_details", status_label="ok"
+        db,
+        reported_client_id=client.reported_client_id,
+        tool="fleet_ops_get_vehicle_details",
+        status_label="ok",
+        correlation_id=correlation_id,
     )
     return McpVehicleDetailOut(
         public_ref=vehicle.public_ref,
@@ -118,17 +176,29 @@ def vehicle_details(
 @router.post("/search-knowledge", response_model=GroundedAnswer)
 def search_knowledge(
     body: McpKnowledgeSearchRequest,
+    response: Response,
     db: Session = Depends(get_db),
-    client_id: str = Depends(require_mcp_service_token),
+    client: McpClientContext = Depends(require_mcp_service_token),
+    correlation_id: str = Depends(get_correlation_id),
 ) -> GroundedAnswer:
     provider = get_knowledge_provider()
-    correlation_id = str(uuid.uuid4())
+    answer = provider.ask(body.question, correlation_id, language=body.locale)
-    answer = provider.ask(body.question, correlation_id)
+    source_count_available = len(answer.sources)
     answer.sources = answer.sources[: body.max_sources]
+    _set_trace_headers(response, correlation_id, client.tenant)
+    response.headers["X-Sources-Available"] = str(source_count_available)
+    response.headers["X-Sources-Returned"] = str(len(answer.sources))
     _audit_service_request(
         db,
-        client_id=client_id,
+        reported_client_id=client.reported_client_id,
-        tool="mobilityops_search_knowledge",
+        tool="fleet_ops_search_knowledge",
         status_label=answer.evidence_state,
+        correlation_id=correlation_id,
+        metadata={
+            "tenant": client.tenant,
+            "locale": body.locale,
+            "sources_available": source_count_available,
+            "sources_returned": len(answer.sources),
+        },
     )
     return answer

backend/app/api/routers/observability.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import hmac
+
+from fastapi import APIRouter, Header, HTTPException
+from fastapi.responses import Response
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+from sqlalchemy import func, select
+
+from app.core.config import get_settings
+from app.core.db import SessionLocal
+from app.core.observability import OUTBOX_EVENTS
+from app.models.outbox import DELIVERY_STATUSES, DEMO_SCENARIO_ERROR_CODE, OutboxEvent
+
+router = APIRouter(tags=["observability"])
+settings = get_settings()
+
+
+def _refresh_database_metrics() -> None:
+    with SessionLocal() as db:
+        rows = db.execute(
+            select(
+                OutboxEvent.delivery_status,
+                (OutboxEvent.last_error_code == DEMO_SCENARIO_ERROR_CODE).label("demo"),
+                func.count(),
+            ).group_by(OutboxEvent.delivery_status, "demo")
+        ).all()
+    OUTBOX_EVENTS.clear()
+    # Keep every time series present even when a state currently contains no rows.
+    # Stable zero-valued series make dashboards and alerts deterministic after resets,
+    # restores and fresh installations instead of turning "zero" into "no data".
+    for scenario in ("synthetic", "operational"):
+        for status in DELIVERY_STATUSES:
+            OUTBOX_EVENTS.labels(scenario, status).set(0)
+    for status, is_demo, count in rows:
+        OUTBOX_EVENTS.labels("synthetic" if is_demo else "operational", str(status)).set(count)
+
+
+@router.get("/metrics", include_in_schema=False)
+def metrics(authorization: str | None = Header(default=None)) -> Response:
+    if settings.metrics_bearer_token:
+        supplied = authorization.removeprefix("Bearer ") if authorization else ""
+        if not hmac.compare_digest(supplied, settings.metrics_bearer_token):
+            raise HTTPException(status_code=401, detail="Metrics token required")
+    _refresh_database_metrics()
+    return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)

backend/app/api/routers/privacy.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import JSONResponse
+from sqlalchemy import func, or_, select
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_db, require_operations_manager
+from app.core.config import get_settings
+from app.models.booking import Booking
+from app.models.customer import Customer
+from app.schemas import (
+    CurrentUser,
+    CustomerAnonymizeRequest,
+    CustomerAnonymizeResult,
+    PrivacyRetentionOut,
+)
+from app.services.audit import record_audit_event
+
+router = APIRouter(prefix="/api/v1/privacy", tags=["privacy"])
+settings = get_settings()
+
+
+def _retention_cutoff() -> datetime:
+    return datetime.now(UTC) - timedelta(days=settings.privacy_minimum_booking_retention_days)
+
+
+def _customer_is_eligible(db: Session, customer_id) -> bool:
+    blocking = db.scalar(
+        select(func.count())
+        .select_from(Booking)
+        .where(
+            Booking.customer_id == customer_id,
+            or_(
+                Booking.status.in_(("reserved", "active")),
+                Booking.ends_at > _retention_cutoff(),
+            ),
+        )
+    )
+    return not blocking
+
+
+@router.get("/retention", response_model=PrivacyRetentionOut)
+def retention_status(
+    db: Session = Depends(get_db),
+    _user: CurrentUser = Depends(require_operations_manager),
+) -> PrivacyRetentionOut:
+    customers = db.scalars(select(Customer)).all()
+    return PrivacyRetentionOut(
+        minimum_booking_retention_days=settings.privacy_minimum_booking_retention_days,
+        audit_retention_days=settings.privacy_audit_retention_days,
+        customers_total=len(customers),
+        customers_anonymized=sum(customer.anonymized_at is not None for customer in customers),
+        customers_eligible=sum(
+            customer.anonymized_at is None and _customer_is_eligible(db, customer.id)
+            for customer in customers
+        ),
+    )
+
+
+@router.get("/customers/{public_ref}/export")
+def export_customer_data(
+    public_ref: str,
+    db: Session = Depends(get_db),
+    actor: CurrentUser = Depends(require_operations_manager),
+) -> JSONResponse:
+    customer = db.scalar(select(Customer).where(Customer.public_ref == public_ref))
+    if customer is None:
+        raise HTTPException(status_code=404, detail="Customer not found")
+    bookings = db.scalars(
+        select(Booking).where(Booking.customer_id == customer.id).order_by(Booking.starts_at)
+    ).all()
+    payload = {
+        "generated_at": datetime.now(UTC).isoformat(),
+        "customer": {
+            "public_ref": customer.public_ref,
+            "first_name": customer.first_name,
+            "last_name": customer.last_name,
+            "email": customer.email,
+            "phone": customer.phone,
+            "postal_code": customer.postal_code,
+            "city": customer.city,
+            "date_of_birth": customer.date_of_birth.isoformat() if customer.date_of_birth else None,
+            "anonymized_at": customer.anonymized_at.isoformat() if customer.anonymized_at else None,
+        },
+        "bookings": [
+            {
+                "public_ref": booking.public_ref,
+                "starts_at": booking.starts_at.isoformat(),
+                "ends_at": booking.ends_at.isoformat(),
+                "status": booking.status,
+            }
+            for booking in bookings
+        ],
+    }
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=actor.display_name,
+        action="privacy_customer_exported",
+        entity_type="customer",
+        entity_id=customer.id,
+        metadata={"customer_ref": customer.public_ref, "booking_count": len(bookings)},
+    )
+    db.commit()
+    return JSONResponse(
+        payload,
+        headers={"Content-Disposition": f'attachment; filename="{public_ref}-privacy.json"'},
+    )
+
+
+@router.post("/customers/{public_ref}/anonymize", response_model=CustomerAnonymizeResult)
+def anonymize_customer(
+    public_ref: str,
+    body: CustomerAnonymizeRequest,
+    db: Session = Depends(get_db),
+    actor: CurrentUser = Depends(require_operations_manager),
+) -> CustomerAnonymizeResult:
+    customer = db.scalar(
+        select(Customer).where(Customer.public_ref == public_ref).with_for_update()
+    )
+    if customer is None:
+        raise HTTPException(status_code=404, detail="Customer not found")
+    if body.confirmation != public_ref:
+        raise HTTPException(
+            status_code=422, detail="Customer reference confirmation does not match"
+        )
+    if customer.anonymized_at is not None:
+        return CustomerAnonymizeResult(
+            public_ref=public_ref,
+            anonymized_at=customer.anonymized_at,
+            status="already_anonymized",
+        )
+    if not _customer_is_eligible(db, customer.id):
+        raise HTTPException(
+            status_code=409,
+            detail="Customer has an active/recent booking within the minimum retention period",
+        )
+    anonymized_at = datetime.now(UTC)
+    customer.first_name = "Anoniem"
+    customer.last_name = public_ref
+    customer.email = None
+    customer.phone = None
+    customer.postal_code = None
+    customer.city = None
+    customer.date_of_birth = None
+    customer.anonymized_at = anonymized_at
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=actor.display_name,
+        action="privacy_customer_anonymized",
+        entity_type="customer",
+        entity_id=customer.id,
+        before={"anonymized": False},
+        after={"anonymized": True},
+        metadata={"reason": body.reason, "customer_ref": public_ref},
+    )
+    db.commit()
+    return CustomerAnonymizeResult(
+        public_ref=public_ref,
+        anonymized_at=anonymized_at,
+        status="anonymized",
+    )