reclaim/RUN.md

# Recl∆Im (F∆I) — Run-Guide (Phase 0)

> Stand v0.1.0 — Demo-Modus, ohne externe Daten, ohne Hub-Verbindung.

## Layout

```
fai_reclaim/
├── MACHBARKEITSSTUDIE.md     # die Studie (v0.3, AG-intern)
├── RUN.md                    # diese Datei
├── app/                      # Flutter-Client, Brand-Skin fai_web
│   ├── lib/                  # Dart-Code (Pages, Widgets, Data, Theme)
│   ├── assets/
│   │   ├── fonts/            # SIL-OFL TTFs (setup.sh holt sie)
│   │   └── fixtures/         # Phase-0 Demo-Daten
│   ├── macos/                # Plattform-Scaffolds (auto-generiert)
│   ├── setup.sh              # Fonts + Pakete
│   └── pubspec.yaml
└── flows/
    └── durchstich-gewo-14.yaml   # vertikaler Phase-0-Flow
```

Die acht zugehörigen Module liegen unter `fai_chain_modules/` als
eigene Crate-Verzeichnisse, ABI `chain:platform`, alle Apache 2.0:

- `text-akoma-normalize/` (Pflicht-Eingang, gesetze-im-internet-XML-Adapter)
- `text-deontic-extract/` (Pflicht-Tupel via Regex + LLM-Vorschlag im Flow)
- `graph-citation-extract/` (`cites`, `verweist_iVm`)
- `text-readability-score/` (Flesch-DE + Verweistiefe)
- `stats-cohort-size/` (DESTATIS-/IHK-Kohorten, Phase 0 mit Stub-Tabelle)
- `graph-shapley-attribution/` (Pfad-anteilige Splittung)
- `econ-skm-score/` (Standardkostenmodell P×F×T×h)
- `law-benefit-score/` (7-dim. Nutzen-Aggregation — das einzige genuin
  domänen-spezifische Modul, gehört in `chain-modules-law/`)

## Sofort starten (Demo-UI, kein Hub nötig)

```bash
cd app
./setup.sh                # Fonts + flutter pub get
./build-macos.sh          # Robust-Build (strippt macOS-xattrs vor CodeSign)
open build/macos/Build/Products/Debug/reclaim_app.app
```

Direkter `flutter run -d macos` funktioniert auch, kann aber bei
einem frischen Checkout an `com.apple.provenance`-xattrs scheitern
(macOS-Eigenheit bei via curl/iCloud erstellten Dateien) — dann
einmal `./build-macos.sh` und danach `flutter run -d macos`.

Erwartet: Brand-Landing → Klick auf „App öffnen" →
NavigationRail (Heatmap / Normen / Freigaben / Hub / Methodik / Recht)
mit fünf Pilot-Norm-Punkten. Default ist der **Live-Hub-Modus**
(läuft ein `chain serve` auf 127.0.0.1:50051, werden die fünf Normen
live ausgewertet — `submit` pro Norm, echte skm/benefit-Achsen). Ohne
Hub bzw. mit Demo-Toggle im Hub-Reiter: die fünf Fixtures mit
T4-Demo-Banner.

Test-Suite (smoke):
```bash
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- **und** im Live-Hub-Modus: die SDK wählt per
conditional import den `GrpcWebClientChannel`, sodass der Browser
denselben Hub auf 127.0.0.1:50051 erreicht (verifiziert: „App öffnen"
feuert 5× `Submit` über gRPC-Web). Der Hub muss gRPC-Web anbieten —
`chain serve` tut das auf einer Loopback-Bindung von Haus aus.

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. Der Heatmap-Tab füllt sich automatisch live: `HubRepository.list()`
   führt pro Pilot-Norm den `reclaim-evaluate`-Flow via `submit()` aus
   (json-Inputs für skm/benefit) und mappt `SubmitResponse.outputs`
   (norm/skm/benefit/frust/cohort/duties) in Evaluation-Objekte. Kein
   manuelles `chain run` nötig — die App treibt die Flows selbst. (Der
   Audit-Log speichert keine Outputs, nur Hashes; daher der
   submit-Pfad statt eventLog.) Offene `system.approval`-Aufgaben
   erscheinen separat im „Freigaben"-Reiter zur juristischen Bestätigung.

## Modul-Tests (lokal grün ohne Hub)

```bash
for m in text-akoma-normalize text-deontic-extract \
         graph-citation-extract text-readability-score \
         stats-cohort-size graph-shapley-attribution \
         econ-skm-score law-benefit-score; do
  (cd ../fai_chain_modules/$m && cargo test) || break
done
```

## WASM-Build (für `chain install`)

```bash
cd ../fai_chain_modules/text-akoma-normalize
cargo build --release --target wasm32-wasip2
# Artefakt: target/wasm32-wasip2/release/text_akoma_normalize.wasm
```

Selber Aufruf für die anderen sieben Verzeichnisse.

## Live-Flow (Default, sobald `chain serve` läuft)

```bash
chain serve &
chain install text.akoma_normalize text.deontic_extract \
              graph.citation_extract text.readability_score \
              stats.cohort_size graph.shapley_attribution \
              econ.skm_score law.benefit_score \
              http.request system.approval
chain run flows/durchstich-gewo-14.yaml \
  --input norm_url=https://www.gesetze-im-internet.de/gewo/__14.xml \
  --input cohort_id=berlin-kmu
chain admin events --limit 10
chain admin approvals list   # Juristen-Gate
```

Im Flutter-Client den `MockRepository` durch eine `HubRepository`
(gRPC gegen `localhost:50051`) ersetzen — Interface bleibt gleich,
keine UI-Änderung nötig.

## Was Phase 0 NICHT enthält (bewusst)

- gRPC-Anbindung Flutter ↔ Hub (Woche 1)
- Echte NKR-Datenbank-Anbindung (Woche 2-3)
- DESTATIS GENESIS-API-Adapter (Woche 4)
- Juristen-Approval-Backend-Anbindung (Woche 5)
- Volle Akoma-Ntoso-Konvertierung (v0.2)
- HTML- und FORMEX-Adapter für `text.akoma_normalize` (v0.2/0.3)