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.