3b07d340d5
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>
90 lines
2.6 KiB
Markdown
90 lines
2.6 KiB
Markdown
# 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.
|