chain-studio/docs/landing-page-design.md

Welcome / Landing-page design

Status: Design draft. Not built yet.

Why we need it

The Today-Hero in the Store mixed two genres of editorial content:

• Operator-actionable: "DeepWiki is two clicks away", "text.summarize is in the grid", "try the extract→summarize flow". These belong in the Store carousel — they point at store / federation items the operator can act on.
• Architecture education: "every module is sandboxed", "the audit log is hash-chained", "the hub fits in one binary, no Docker". These are what F∆I is — they belong on a Welcome page that introduces the platform on first launch and stays available afterwards as a reference.

The operator feedback that made this distinction explicit:

"interessante store einträge oder auch mcp etc zeigen und nicht einfach etwas übers system. Stattdessen brauchen wir als erstes im system eine art landing page die genau das macht und auch zu doku verlinkt, aber diese auch in das system optisch integriert und nicht einfach nach außen verlinkt."

The architectural-education stories already left the Store carousel in the same release. The Welcome page is where they land.

Page shape

A new top-level Studio surface, accessed from the sidebar above Doctor. First-launch operators land here automatically; returning operators can come back any time.

┌──────────────────────────────────────────────────────────┐
│  AppBar: Welcome                                         │
├──────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────┐ │
│  │  HERO                                               │ │
│  │  F∆I Platform                                       │ │
│  │  Deterministic workflow engine for AI-assisted     │ │
│  │  document processing in regulated environments.    │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌──── Three-pillar row (Hub / Module / Flow) ────┐    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐      │    │
│  │  │   HUB    │  │  MODULE  │  │   FLOW   │      │    │
│  │  │ icon     │  │ icon     │  │ icon     │      │    │
│  │  │ One bin- │  │ Does one │  │ YAML     │      │    │
│  │  │ ary that │  │ thing,   │  │ chains   │      │    │
│  │  │ runs the │  │ sandboxed│  │ modules  │      │    │
│  │  │ flows    │  │ WASM     │  │ together │      │    │
│  │  └──────────┘  └──────────┘  └──────────┘      │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  ┌──── Trust posture ─────────────────────────────┐    │
│  │  🛡  Sandbox by default                          │    │
│  │     Every module declares fs / net / env perms; │    │
│  │     the hub enforces them. Click "Doctor →      │    │
│  │     Modules" to see live permissions per module.│    │
│  │                                                 │    │
│  │  ⛓  Tamper-evident audit log                    │    │
│  │     Every event hash-chained; Doctor verifies   │    │
│  │     end-to-end on every load. WORM-1 promise.   │    │
│  │                                                 │    │
│  │  ✈  Air-gap ready                               │    │
│  │     One binary, SQLite state, no Docker, no     │    │
│  │     external services. Once a module is         │    │
│  │     installed, the flow runs without further    │    │
│  │     network access.                             │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  ┌──── Getting-started checklist ─────────────────┐    │
│  │  ☐ Configure System AI (Settings → System AI)  │    │
│  │  ☐ Add a public MCP source (Store → DeepWiki)  │    │
│  │  ☐ Install your first text module              │    │
│  │  ☐ Run the extract → summarize sample flow     │    │
│  └────────────────────────────────────────────────┘    │
│                                                          │
│  ┌──── Documentation, embedded ───────────────────┐    │
│  │  Architecture map · Module experience ·        │    │
│  │  Flow composition · Compliance posture          │    │
│  │  → click opens an in-app reader, not a browser │    │
│  └────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────┘

Optical integration of docs

The user constraint:

"diese auch in das system optisch integriert und nicht einfach nach außen verlinkt"

So clicking a documentation card does not open a browser. Instead a _DocReaderSheet (modal bottom-sheet, same shape as _StoreDetailSheet) renders the markdown inline using the existing flutter_markdown package — same one the Store uses for module READMEs. The doc source is bundled with Studio as assets/docs/*.md, kept in sync via a build step that copies the relevant files from fai_platform/docs/.

Pros:

• Air-gap-tauglich (no network call to read docs)
• Operator stays in Studio context — Cmd-Tab to a browser breaks flow
• Same look-and-feel as module-doc rendering
• Bilingual: each doc has a _de.md sibling next to .md

Cons / tradeoffs:

• Studio binary grows by the size of bundled docs (a few hundred KB)
• Doc-update lifecycle: a Studio release ships a fixed snapshot. Live-fetched-from-hub is a Phase 1 question.

Getting-started checklist

Stateful — the page tracks which items the operator has completed and persists state to ~/.fai/studio/onboarding.json (same shape as theme/locale persistence in hub.dart). Each checkmark is computed:

• ✓ System AI configured: HubService.systemAiStatus().enabled
• ✓ Public MCP source added: any mcp.<server>.<tool> in store
• ✓ First text module installed: any installed module whose name starts with text.
• ✓ Sample flow run: any flow.completed event in audit log naming extract-summarize.yaml (or any flow that uses both text.extract and text.summarize)

Operator can dismiss the checklist once everything is checked.

Sidebar placement

The Welcome page becomes the new sidebar default — index 0, above Doctor. First-launch experience hits it; afterward operators most often go to Store / Audit, but the home icon stays one click away.

labelOf(context) for the Welcome page returns l.navWelcome ("Welcome" / "Willkommen"). New ARB keys: navWelcome, plus the section-header strings (already mostly covered by existing doctorChain* / doctorPathLog keys that we can reference from the doc-card descriptions).

Implementation phases

Big enough that a single commit doesn't make sense. Three phased PRs:

1. Phase A — sidebar + scaffolding + hero + three-pillar row + trust-posture row. No docs yet, just the static content with hard-coded strings (with i18n). Lands without the embedded-doc reader.
2. Phase B — bundled markdown docs + _DocReaderSheet. Pick 4-5 source docs from fai_platform/docs/architecture/ that map to operator concerns (security, host-services, flow-experience, compliance-gaps). Add a build script that syncs them into assets/docs/.
3. Phase C — getting-started checklist with computed state. Adds the persistence layer + the audit-log inspection helper.

Out of scope

• A "tutorial mode" that walks the operator through the steps interactively. Editorial checklist + concise explanations is enough for v1; tutorial state is a Phase 1+ idea.
• Live-fetched docs from hub.fetch_doc(...). Air-gap posture requires bundled docs.
• Per-deployment branding (custom logo / color). Not a KRITIS need.