feat(studio): Welcome page Phase B — embedded doc reader (v0.38.0)

Second slice of the Welcome surface. Operator-facing documentation now lives inside Studio as bundled assets and renders inline via a modal sheet — no browser, no external link, air-gap-tauglich. - Four operator-readable explainers under `assets/docs/`, each with an EN + DE pair: architecture[_de].md — Hub / Module / Flow + how they fit security[_de].md — sandbox model, declared perms, operator ceiling audit[_de].md — hash-chained log, WORM-1 mechanics, `fai admin verify-events` flows[_de].md — flow YAML, templating reference, extract→summarize example These are short (≈ 300-500 words each), operator-shaped prose. Not copies of the architecture docs in fai_platform/docs/architecture/ — those are contributor-dense. - pubspec.yaml declares `assets/docs/` so the markdown ships inside the Studio binary. Air-gap deployments read them with no network access. - New `_DocReaderSheet` modal: 85 %-of-viewport bottom sheet, drag handle + title bar with the doc icon and close button, scrollable Markdown body styled to match Studio chrome. Loads `assets/docs/<slug>_<locale>.md` first, falls back to the EN file. Locale comes from `Localizations.localeOf(context)`. - `_DocsRow` on the Welcome page sits below the trust-posture deck. Two-column grid on ≥ 640 dp, single column below. Each card is icon + title + one-line blurb + chevron; click opens the reader sheet for that slug. - 12 new ARB keys for the docs section (header, blurb, four card titles + blurbs, close button, error message). - 4 new icons reused: `account_tree_outlined` (architecture), `shield_outlined` (security), `verified_outlined` (audit), `alt_route_outlined` (flows). Implements Phase B of `docs/landing-page-design.md`. Phase C (live getting-started checklist with persistent state) is the last remaining slice. Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>
2026-05-09 00:24:31 +02:00 · 2026-05-09 00:24:31 +02:00 · 3b07d340d5
commit 3b07d340d5
parent 3a7d0e74ad
16 changed files with 1051 additions and 3 deletions
--- a/assets/docs/architecture.md
+++ b/assets/docs/architecture.md
@ -0,0 +1,51 @@
+# Architecture in one paragraph
+
+F∆I has three concepts you'll meet everywhere: **Hub**,
+**Module**, **Flow**.
+
+**The hub** is a single Rust binary called `fai`. It runs as a
+gRPC server, loads modules, executes flows, and writes events
+to a SQLite database. One binary, no Docker, no message broker,
+no cluster. You can run it on a laptop, a Raspberry Pi, or a
+locked-down KRITIS server — same artefact every time.
+
+**A module** is a small WebAssembly component that does one
+thing well. Modules are sandboxed: each one declares the
+network endpoints, files, and environment variables it needs,
+and the hub enforces that list. A module that doesn't ask for
+network access can't reach the network. Modules ship as `.fai`
+bundles with a CycloneDX SBOM and a sigstore signature.
+
+**A flow** is a YAML file with three top-level keys:
+`inputs:`, `steps:`, `outputs:`. Steps run in declared order,
+each step calls one module, and outputs from one step can feed
+inputs of the next. Flows are deterministic — same inputs
+produce the same audit trail.
+
+## How the pieces fit
+
+```
+Studio ──gRPC──▶ Hub ──loads──▶ Module (WASM)
+                  │
+                  ├──executes──▶ Flow (YAML chain of modules)
+                  │
+                  └──writes────▶ Audit log (hash-chained, in
+                                  SQLite; WORM-1 by construction)
+```
+
+## What you don't need
+
+- No container runtime. The hub doesn't shell out to Docker
+  or Podman. Modules are WASM components loaded in-process.
+- No external database. SQLite ships with the hub.
+- No background services. One process; restart with
+  `fai daemon restart` — see Doctor → Daemon control.
+
+## Where to go next in this app
+
+- **Store** to discover modules and federated MCP / n8n
+  capabilities, install them in one click.
+- **Flows** to run the sample flows that ship with the hub
+  (e.g. `extract-summarize`).
+- **Audit** to see every event the hub recorded — the
+  hash-chained log is the platform's source of truth.
--- a/assets/docs/architecture_de.md
+++ b/assets/docs/architecture_de.md
@ -0,0 +1,55 @@
+# Architektur in einem Absatz
+
+F∆I hat drei Konzepte, die dir überall begegnen: **Hub**,
+**Modul**, **Flow**.
+
+**Der Hub** ist ein einzelnes Rust-Binary namens `fai`. Er
+läuft als gRPC-Server, lädt Module, führt Flows aus und
+schreibt Ereignisse in eine SQLite-Datenbank. Ein Binary, kein
+Docker, kein Message-Broker, kein Cluster. Du kannst ihn auf
+einem Laptop, einem Raspberry Pi oder einem abgeriegelten
+KRITIS-Server laufen lassen — immer dasselbe Artefakt.
+
+**Ein Modul** ist eine kleine WebAssembly-Komponente, die eine
+Sache gut macht. Module laufen in einer Sandbox: jedes deklariert
+die Netzwerk-Endpunkte, Dateien und Umgebungsvariablen, die es
+braucht, und der Hub setzt diese Liste durch. Ein Modul, das
+keinen Netzwerkzugriff anfordert, kann das Netzwerk nicht
+erreichen. Module kommen als `.fai`-Bundles mit CycloneDX-SBOM
+und sigstore-Signatur.
+
+**Ein Flow** ist eine YAML-Datei mit drei Top-Level-Schlüsseln:
+`inputs:`, `steps:`, `outputs:`. Schritte laufen in deklarierter
+Reihenfolge, jeder Schritt ruft ein Modul auf, und Ausgaben
+eines Schritts können in die Eingaben des nächsten fließen.
+Flows sind deterministisch — gleiche Eingaben erzeugen dieselbe
+Audit-Spur.
+
+## Wie die Teile zusammenpassen
+
+```
+Studio ──gRPC──▶ Hub ──lädt──▶ Modul (WASM)
+                  │
+                  ├──führt aus──▶ Flow (YAML-Verkettung von Modulen)
+                  │
+                  └──schreibt────▶ Audit-Log (hash-verkettet, in
+                                    SQLite; WORM-1 qua Konstruktion)
+```
+
+## Was du nicht brauchst
+
+- Keine Container-Runtime. Der Hub ruft kein Docker oder Podman.
+  Module sind WASM-Komponenten, in-process geladen.
+- Keine externe Datenbank. SQLite kommt mit dem Hub.
+- Keine Hintergrunddienste. Ein Prozess; Neustart per
+  `fai daemon restart` — siehe Diagnose → Daemon-Steuerung.
+
+## Wo es in dieser App weitergeht
+
+- **Store** zum Entdecken von Modulen und föderierten MCP/n8n-
+  Fähigkeiten, Installation in einem Klick.
+- **Flows** zum Ausführen der Beispiel-Flows, die mit dem Hub
+  kommen (z.B. `extract-summarize`).
+- **Protokoll** für jedes vom Hub aufgezeichnete Ereignis — das
+  hash-verkettete Log ist die Single Source of Truth der
+  Plattform.
--- a/assets/docs/audit.md
+++ b/assets/docs/audit.md
@ -0,0 +1,69 @@
+# Tamper-evident audit log
+
+Every action the hub takes goes into one append-only event
+log. Module installs, flow runs, approval decisions, channel
+switches, daemon restarts — all recorded with the same shape.
+
+## What an event looks like
+
+```
+timestamp:     2026-05-08T14:32:11Z
+event_id:      ev_01H...
+event_type:    flow.completed
+flow_name:     extract-summarize
+flow_execution: fe_01H...
+duration_ms:   1240
+module_name:   text.summarize
+module_version: 0.1.0
+detail:        { engine: "ollama", model_name: "gemma3:4b",
+                  model_digest: "sha256:..." }
+prev_event_sha256: 6f4e...8b5f
+```
+
+The `prev_event_sha256` field is the key. Every new event
+hashes its content together with the previous event's hash. To
+falsify event N, an attacker would need to rewrite every event
+from N+1 onwards — and the chain head would no longer match
+what the operator's last verification recorded.
+
+## What "WORM-1" means
+
+WORM-1 is our first WORM (write-once-read-many) tier:
+
+- **Append-only**: the hub never deletes individual events.
+  The CLI / RPC has a single batch operation,
+  `clear_event_log`, which wipes the channel and seeds a
+  `chain.reset` marker carrying reviewer + reason. Refused on
+  beta / production channels.
+- **Tamper-evident**: the chain reveals any retroactive edit.
+  Verification runs end-to-end on every Doctor-page load and
+  via `fai admin verify-events`.
+- **Self-contained**: SQLite + chain hash is enough; no
+  external WORM sink needed.
+
+WORM-2 (Linux append-only file attribute) and WORM-3 (external
+WORM sink) are roadmap items, not yet shipped.
+
+## What you'll see in this app
+
+- **Doctor → Event log**: live "chain intact" / "tamper
+  detected" indicator with verified-event count. Click "Verify
+  now" for an explicit re-check.
+- **Audit page**: live stream of recent events with filter
+  chips (flow / step / module). Click any row to see the full
+  event JSON.
+- **Doctor → Daemon files → Audit-DB**: reveals the SQLite file
+  in your file manager.
+
+## Reading the chain by hand
+
+If you want to verify outside Studio:
+
+```bash
+fai admin verify-events
+# Prints "Hash chain intact: N events verified" or names the
+# first event whose hash mismatches.
+```
+
+The chain is the source of truth — every other audit-related
+piece of UI in Studio reads from it.
--- a/assets/docs/audit_de.md
+++ b/assets/docs/audit_de.md
@ -0,0 +1,70 @@
+# Manipulationssicheres Audit-Log
+
+Jede Aktion des Hubs landet in einem append-only Event-Log.
+Modul-Installationen, Flow-Läufe, Freigabe-Entscheidungen,
+Kanal-Wechsel, Daemon-Neustarts — alle mit derselben Form
+aufgezeichnet.
+
+## So sieht ein Event aus
+
+```
+timestamp:     2026-05-08T14:32:11Z
+event_id:      ev_01H...
+event_type:    flow.completed
+flow_name:     extract-summarize
+flow_execution: fe_01H...
+duration_ms:   1240
+module_name:   text.summarize
+module_version: 0.1.0
+detail:        { engine: "ollama", model_name: "gemma3:4b",
+                  model_digest: "sha256:..." }
+prev_event_sha256: 6f4e...8b5f
+```
+
+Das `prev_event_sha256`-Feld ist der Kern. Jedes neue Event
+hasht seinen Inhalt zusammen mit dem Hash des vorherigen.
+Wer Event N fälschen will, müsste alle Events ab N+1 neu
+schreiben — und der Ketten-Kopf würde nicht mehr zu dem
+passen, was der Operator zuletzt verifiziert hat.
+
+## Was „WORM-1" bedeutet
+
+WORM-1 ist unsere erste WORM-Stufe (write-once-read-many):
+
+- **Append-only**: Der Hub löscht keine einzelnen Events. Die
+  CLI/RPC hat eine einzige Batch-Operation,
+  `clear_event_log`, die den Kanal komplett leert und einen
+  `chain.reset`-Marker mit Prüfer + Begründung seedet. Auf
+  beta-/production-Kanälen verweigert.
+- **Manipulationssicher**: Die Kette zeigt jede nachträgliche
+  Änderung. Verifikation läuft bei jedem Doctor-Page-Load
+  komplett und über `fai admin verify-events`.
+- **Selbst-tragend**: SQLite + Ketten-Hash genügen; keine
+  externe WORM-Senke nötig.
+
+WORM-2 (Linux append-only Datei-Attribut) und WORM-3 (externe
+WORM-Senke) sind Roadmap-Punkte, noch nicht ausgeliefert.
+
+## Was du in dieser App siehst
+
+- **Diagnose → Audit-Log**: Live-Anzeige „Kette intakt" /
+  „Manipulation erkannt" mit Anzahl verifizierter Events.
+  „Jetzt prüfen" für explizite Neu-Verifikation.
+- **Protokoll-Seite**: Live-Stream der letzten Events mit
+  Filter-Chips (Flow / Step / Modul). Klick auf eine Zeile
+  öffnet das vollständige Event-JSON.
+- **Diagnose → Daemon-Dateien → Audit-DB**: Zeigt die SQLite-
+  Datei im Datei-Manager.
+
+## Die Kette per Hand prüfen
+
+Wer außerhalb von Studio verifizieren will:
+
+```bash
+fai admin verify-events
+# Druckt „Hash-Kette intakt: N Events verifiziert" oder nennt
+# das erste Event, dessen Hash nicht passt.
+```
+
+Die Kette ist die Single Source of Truth — jede andere Audit-
+bezogene UI in Studio liest aus ihr.
--- a/assets/docs/flows.md
+++ b/assets/docs/flows.md
@ -0,0 +1,90 @@
+# Flow composition
+
+A flow is a YAML file with three top-level keys: `inputs:`,
+`steps:`, `outputs:`. Read top to bottom, it tells the hub
+what kind of inputs to accept, which modules to call in what
+order, and what to surface as the final result.
+
+## Smallest possible flow
+
+```yaml
+name: hello
+description: Echo a name back as a greeting.
+
+inputs:
+  name:
+    type: text
+
+steps:
+  - id: greet
+    module: debug.echo
+    inputs:
+      payload: "Hello, {{ inputs.name }}"
+
+outputs:
+  greeting: "{{ steps.greet.outputs.payload }}"
+```
+
+`fai run flows/hello.yaml --input name=World` produces:
+
+```json
+{ "greeting": "Hello, World" }
+```
+
+## Real-world example: extract → summarize
+
+The bundled `flows/extract-summarize.yaml` chains two modules:
+
+```yaml
+steps:
+  - id: extract
+    module: text.extract
+    inputs:
+      document: "{{ inputs.file }}"
+
+  - id: summarize
+    module: text.summarize
+    inputs:
+      text: "{{ steps.extract.outputs.text }}"
+      style: "three bullet points"
+```
+
+The `{{ steps.extract.outputs.text }}` template plumbs the
+output of one step into the next. The flow engine type-coerces
+JSON / FileRef / Text per the destination module's manifest, so
+you don't need explicit conversion steps.
+
+## Templating reference (short)
+
+| Expression                         | Resolves to                |
+|------------------------------------|----------------------------|
+| `{{ inputs.X }}`                   | input named X              |
+| `{{ steps.Y.outputs.Z }}`          | output Z of step Y         |
+| `{{ env.OPENAI_API_KEY }}`         | env var (must be declared) |
+| `{{ now }}`                        | ISO-8601 UTC timestamp     |
+| `{{ flow.execution_id }}`          | per-run id (audit-log key) |
+
+## Audit posture
+
+Every step emits four events:
+
+- `step.started` — module name, version, manifest hash
+- `step.completed` — duration, output size, well-known
+  fields auto-elevated (`model_digest`, `engine`, …)
+- `step.failed` — error name + message
+- `flow.completed` — sum of step durations, total events
+
+All hash-chained into the same audit log. See the **Audit-log**
+explainer for the chain mechanics.
+
+## What you'll see in this app
+
+- **Flows page**: list of saved flows under `~/.fai/data/flows/`.
+  Click `Run`, fill any required inputs, watch the result.
+- **Audit page**: per-step events appear within seconds of a
+  flow finishing. Filter on `flow.` to see only flow-level
+  rows.
+- **Store**: any installed module shows up as available for
+  `module:` in a flow YAML. Synthetic federated entries
+  (`mcp.<server>.<tool>`, `n8n.<endpoint>.<workflow>`) work
+  the same way.
--- a/assets/docs/flows_de.md
+++ b/assets/docs/flows_de.md
@ -0,0 +1,92 @@
+# Flow-Komposition
+
+Ein Flow ist eine YAML-Datei mit drei Top-Level-Schlüsseln:
+`inputs:`, `steps:`, `outputs:`. Von oben nach unten gelesen,
+sagt sie dem Hub, welche Eingaben er akzeptiert, welche Module
+in welcher Reihenfolge aufgerufen werden und was am Ende als
+Ergebnis nach außen geht.
+
+## Kleinster möglicher Flow
+
+```yaml
+name: hello
+description: Gibt einen Namen als Begrüßung zurück.
+
+inputs:
+  name:
+    type: text
+
+steps:
+  - id: greet
+    module: debug.echo
+    inputs:
+      payload: "Hallo, {{ inputs.name }}"
+
+outputs:
+  greeting: "{{ steps.greet.outputs.payload }}"
+```
+
+`fai run flows/hello.yaml --input name=Welt` ergibt:
+
+```json
+{ "greeting": "Hallo, Welt" }
+```
+
+## Realbeispiel: extract → summarize
+
+Der mitgelieferte Flow `flows/extract-summarize.yaml`
+verkettet zwei Module:
+
+```yaml
+steps:
+  - id: extract
+    module: text.extract
+    inputs:
+      document: "{{ inputs.file }}"
+
+  - id: summarize
+    module: text.summarize
+    inputs:
+      text: "{{ steps.extract.outputs.text }}"
+      style: "drei Stichpunkte"
+```
+
+Das Template `{{ steps.extract.outputs.text }}` reicht die
+Ausgabe eines Schritts an den nächsten weiter. Die Flow-Engine
+konvertiert JSON / FileRef / Text passend zum Ziel-Modul-
+Manifest, ohne explizite Wandlungs-Schritte.
+
+## Templating-Referenz (kurz)
+
+| Ausdruck                           | Löst sich auf zu             |
+|------------------------------------|------------------------------|
+| `{{ inputs.X }}`                   | Eingabe namens X             |
+| `{{ steps.Y.outputs.Z }}`          | Ausgabe Z von Schritt Y      |
+| `{{ env.OPENAI_API_KEY }}`         | Env-Var (deklariert nötig)   |
+| `{{ now }}`                        | ISO-8601-UTC-Zeitstempel     |
+| `{{ flow.execution_id }}`          | Lauf-ID (Audit-Log-Schlüssel)|
+
+## Audit-Posture
+
+Jeder Schritt emittiert vier Events:
+
+- `step.started` — Modul-Name, Version, Manifest-Hash
+- `step.completed` — Dauer, Output-Größe, gewhitelistete Felder
+  automatisch elevated (`model_digest`, `engine`, …)
+- `step.failed` — Fehler-Name + Nachricht
+- `flow.completed` — Summe der Schritt-Dauern, Events gesamt
+
+Alle hash-verkettet im gleichen Audit-Log. Siehe Audit-Log-
+Erklärung für die Ketten-Mechanik.
+
+## Was du in dieser App siehst
+
+- **Flows-Seite**: Liste der gespeicherten Flows unter
+  `~/.fai/data/flows/`. `Starten` klicken, geforderte Eingaben
+  ausfüllen, Ergebnis verfolgen.
+- **Protokoll-Seite**: Schritt-Events erscheinen Sekunden
+  nach Flow-Ende. `Flow`-Filter zeigt nur Flow-Level-Zeilen.
+- **Store**: Jedes installierte Modul taucht als verfügbares
+  `module:` in der Flow-YAML auf. Synthetische föderierte
+  Einträge (`mcp.<server>.<tool>`, `n8n.<endpoint>.<workflow>`)
+  funktionieren genauso.
--- a/assets/docs/security.md
+++ b/assets/docs/security.md
@ -0,0 +1,66 @@
+# Sandbox model
+
+Every F∆I module runs inside a WebAssembly sandbox with no
+ambient access to the host. The module can do exactly what it
+declares in its `module.yaml` — and nothing else.
+
+## What a module declares
+
+```yaml
+permissions:
+  - net: api.openai.com         # outbound HTTPS only
+  - net: 127.0.0.1:11434         # local Ollama
+  - fs.read: /var/lib/fai/in     # read-only directory
+  - fs.write: /var/lib/fai/out   # writable directory
+  - env: OPENAI_API_KEY          # one specific env var
+  - hub: invoke                  # call other modules
+```
+
+Anything not on this list is impossible at runtime. A module
+that forgets to ask for `net:` cannot reach the network at all.
+The hub's `WasiCtxBuilder` wires only the declared preopens
+and env vars — there is no escape hatch.
+
+## What the operator controls
+
+Operators add their own ceiling on top in `~/.fai/config.yaml`:
+
+```yaml
+security:
+  module_allowlist:               # only these modules may load
+    - "text.*"
+  module_denylist:                # never load these
+    - "experimental.*"
+  max_permissions:                # cap requests per scope
+    net: ["api.openai.com"]
+    fs.read: ["/var/lib/fai"]
+  require_signatures: true        # reject unsigned bundles
+  require_sbom: true              # reject bundles without CycloneDX
+```
+
+Modules whose declared permissions exceed the operator's
+ceiling fail to load with an explicit error. The operator
+ceiling is the second gate; the module's own declaration is
+the first.
+
+## What you'll see in this app
+
+- The **Store** detail sheet for an installed module shows
+  the declared permissions list with icons (`net:` globe,
+  `fs.read:` folder, `fs.write:` edit, `env:` terminal).
+- The **Doctor** page summary tile shows total module count
+  and capability count.
+- A **flow run** that violates a permission fails with a
+  named error (`PermissionDenied: net:example.com`) in the
+  audit log — visible on the Audit page.
+
+## What we don't have
+
+- No process-level isolation between modules. They all run
+  inside one hub process. A WASM trap escalates to a flow-step
+  failure, not a hub crash, but heap exhaustion in one module
+  can pressure the others. Pooled instance mode is on the
+  roadmap.
+- No live policy backend (OPA-style runtime decisions).
+  Permission lists are static at module-load time. Customer
+  -driven; deferred until a real deployment needs it.
--- a/assets/docs/security_de.md
+++ b/assets/docs/security_de.md
@ -0,0 +1,68 @@
+# Sandbox-Modell
+
+Jedes F∆I-Modul läuft in einer WebAssembly-Sandbox ohne
+ambienten Hostzugriff. Das Modul kann genau das, was es in
+seiner `module.yaml` deklariert — und sonst nichts.
+
+## Was ein Modul deklariert
+
+```yaml
+permissions:
+  - net: api.openai.com         # nur ausgehendes HTTPS
+  - net: 127.0.0.1:11434         # lokales Ollama
+  - fs.read: /var/lib/fai/in     # nur-lese-Verzeichnis
+  - fs.write: /var/lib/fai/out   # schreibbares Verzeichnis
+  - env: OPENAI_API_KEY          # eine bestimmte Umgebungsvariable
+  - hub: invoke                  # andere Module aufrufen
+```
+
+Was nicht auf der Liste steht, ist zur Laufzeit unmöglich. Ein
+Modul, das `net:` vergisst, kann das Netzwerk gar nicht
+erreichen. Der `WasiCtxBuilder` des Hubs verdrahtet nur die
+deklarierten Preopens und Env-Vars — keine Hintertür.
+
+## Was der Operator kontrolliert
+
+Operatoren setzen ihre eigene Obergrenze in
+`~/.fai/config.yaml`:
+
+```yaml
+security:
+  module_allowlist:               # nur diese Module laden
+    - "text.*"
+  module_denylist:                # diese nie laden
+    - "experimental.*"
+  max_permissions:                # Cap je Scope
+    net: ["api.openai.com"]
+    fs.read: ["/var/lib/fai"]
+  require_signatures: true        # unsignierte Bundles ablehnen
+  require_sbom: true              # Bundles ohne CycloneDX ablehnen
+```
+
+Module, deren Berechtigungen die Operator-Obergrenze
+überschreiten, scheitern beim Laden mit explizitem Fehler. Die
+Operator-Obergrenze ist die zweite Schleuse; die Modul-eigene
+Deklaration ist die erste.
+
+## Was du in dieser App siehst
+
+- Das **Store**-Detail-Sheet eines installierten Moduls zeigt
+  die Berechtigungsliste mit Icons (`net:` Globus, `fs.read:`
+  Ordner, `fs.write:` Stift, `env:` Terminal).
+- Die **Diagnose**-Seite zeigt Modul-Anzahl und Capability-
+  Anzahl im Summary.
+- Ein **Flow-Lauf**, der eine Berechtigung verletzt, schlägt
+  mit benanntem Fehler fehl (`PermissionDenied:
+  net:example.com`) — sichtbar im Protokoll.
+
+## Was es nicht gibt
+
+- Keine Prozess-Isolation zwischen Modulen. Alle laufen im
+  einen Hub-Prozess. Ein WASM-Trap eskaliert zum
+  Flow-Schritt-Fehler, nicht zum Hub-Crash, aber
+  Speicher-Überlastung in einem Modul kann die anderen
+  beeinträchtigen. Pooled-Instance-Modus ist auf der Roadmap.
+- Keine Live-Policy-Backend (OPA-artige Laufzeit-
+  Entscheidungen). Berechtigungslisten sind statisch zur
+  Modul-Ladezeit. Kunden-getrieben; aufgeschoben bis ein
+  echter Einsatz es braucht.