From febbf0b50522b7b49571e9cef89de2a7a98d932c Mon Sep 17 00:00:00 2001
From: flemming-it <sf@flemming.it>
Date: Thu, 18 Jun 2026 14:19:59 +0200
Subject: [PATCH] feat(web): add serve-web.sh + document hub smoke +
 prod-deploy path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

serve-web.sh builds the release web bundle and serves it via
python3's stdlib http.server on http://127.0.0.1:8080, so an
AG reviewer can click a link instead of being asked to install
Flutter to see the demo.

RUN.md grows three new sections:

  - Web-Variante: single-command local serve, scope (mock works
    1:1, hub mode pending gRPC-Web in chain_client_sdk_dart).
  - Production deploy path: Hetzner-CX + Caddy, DNS
    reclaim.flemming.ai — matches the existing F∆I Hetzner
    pattern documented in fai_chain release-host.
  - Hub-Smoke-Test: how to verify the new HubRepository.list()
    wiring against a separately-running 'chain serve'
    (Hub-Reiter → Verbindung testen → flow.completed events
    populate the Heatmap-Tab once chain run has been invoked
    and the approval gate is cleared).

Signed-off-by: flemming-it <sf@flemming.it>
---
 RUN.md           | 31 +++++++++++++++++++++++++++++++
 app/serve-web.sh | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100755 app/serve-web.sh

diff --git a/RUN.md b/RUN.md
index 05501ba..a00cc13 100644
--- a/RUN.md
+++ b/RUN.md
@@ -56,6 +56,37 @@ Test-Suite (smoke):
 flutter test
 ```
 
+## Web-Variante (gleiche Codebase, ein Befehl)
+
+```bash
+cd app
+./serve-web.sh           # baut + serviert auf http://127.0.0.1:8080
+```
+
+Funktioniert im Demo-/Mock-Modus 1:1. Im Live-Hub-Modus
+braucht die Web-Variante zusätzlich einen gRPC-Web-Branch in
+`chain_client_sdk_dart` (Phase 1, dokumentiert in
+docs/architecture/protocol-surfaces.md des Ch∆In-Repos).
+
+Produktion: build/web/ auf einen statischen Host kippen
+(F∆I-Pattern: Hetzner-CX + Caddy mit Auto-HTTPS, analog
+`fai_chain` Release-Host). DNS: `reclaim.flemming.ai`.
+
+## Hub-Smoke-Test (chain serve läuft separat)
+
+Wenn ein `chain serve` lokal auf 127.0.0.1:50051 läuft (vom
+fai_chain-Setup):
+
+1. App starten, „Hub"-Reiter öffnen
+2. Host/Port stehen schon, „Hub beim Start nutzen" anschalten
+3. „Verbindung testen" → erwartet `healthy=true`
+4. Falls capabilities installiert sind: „Installierte
+   Capabilities" listet sie auf
+5. Nach `chain run flows/durchstich-gewo-14.yaml` und einem
+   `system.approval`-Approve wird der Heatmap-Tab live gefüllt
+   (HubRepository.list liest `flow.completed`-Events aus dem
+   Audit-Log und übersetzt sie in Evaluation-Objekte)
+
 ## Modul-Tests (lokal grün ohne Hub)
 
 ```bash
diff --git a/app/serve-web.sh b/app/serve-web.sh
new file mode 100755
index 0000000..1e783cd
--- /dev/null
+++ b/app/serve-web.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Local web preview for Recl∆Im.
+#
+# Builds the release web bundle (~16 s) and serves it on
+# http://127.0.0.1:8080 via python3's stdlib http.server so an
+# AG-member can poke the demo from a browser without the
+# Flutter dev tooling being installed on the reviewer's machine.
+#
+# Production path (NOT done by this script):
+#
+#   1. Copy build/web/ to a static host. Hetzner CX-Server +
+#      Caddy with auto-HTTPS is the existing F∆I pattern (see
+#      fai_chain release-host).
+#   2. Set the CSP, HSTS, and frame-ancestors headers Caddy
+#      already templates per F∆I deployment.
+#   3. Add reclaim.flemming.ai DNS A-record to the F∆I IP.
+#
+# For local dev: this script is enough.
+
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+PORT="${PORT:-8080}"
+HOST="${HOST:-127.0.0.1}"
+
+echo "[1/2] flutter build web --release"
+flutter build web --release
+
+echo "[2/2] serving build/web/ on http://$HOST:$PORT"
+echo "      Ctrl+C to stop."
+echo
+
+cd build/web
+exec python3 -m http.server "$PORT" --bind "$HOST"