flemming-it 3b07d340d5 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

2.6 KiB

Raw Blame History

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

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:

{ "greeting": "Hello, World" }

Real-world example: extract → summarize

The bundled flows/extract-summarize.yaml chains two modules:

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.

2.6 KiB Raw Blame History