summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/tui-reference.md175
-rw-r--r--docs/tutorial/TUTORIAL.md245
-rw-r--r--docs/tutorial/assets/00-hero-flamegraph.pngbin0 -> 156731 bytes
-rw-r--r--docs/tutorial/assets/00-logo.pngbin0 -> 332693 bytes
-rw-r--r--docs/tutorial/assets/01-launch.gifbin0 -> 4244461 bytes
-rw-r--r--docs/tutorial/assets/02-overview-tab.gifbin0 -> 263106 bytes
-rw-r--r--docs/tutorial/assets/03-syscalls-tab.gifbin0 -> 1091628 bytes
-rw-r--r--docs/tutorial/assets/04-files-tab.gifbin0 -> 1577094 bytes
-rw-r--r--docs/tutorial/assets/05-processes-tab.gifbin0 -> 1034718 bytes
-rw-r--r--docs/tutorial/assets/06-latency-gaps-tab.gifbin0 -> 300466 bytes
-rw-r--r--docs/tutorial/assets/07-stream-live.gifbin0 -> 7063227 bytes
-rw-r--r--docs/tutorial/assets/08-stream-pause-filter.gifbin0 -> 5796596 bytes
-rw-r--r--docs/tutorial/assets/09-stream-regex-search.gifbin0 -> 5367913 bytes
-rw-r--r--docs/tutorial/assets/10-stream-csv-export.gifbin0 -> 4671995 bytes
-rw-r--r--docs/tutorial/assets/11-pid-tid-probe.gifbin0 -> 3584783 bytes
-rw-r--r--docs/tutorial/assets/12-parquet-recording.gifbin0 -> 2353504 bytes
-rw-r--r--docs/tutorial/assets/13-tui-flamegraph.gifbin0 -> 6333590 bytes
-rw-r--r--docs/tutorial/assets/13a-order-by-process.pngbin0 -> 231292 bytes
-rw-r--r--docs/tutorial/assets/13b-order-by-path.pngbin0 -> 218540 bytes
-rw-r--r--docs/tutorial/assets/13c-order-by-syscall.pngbin0 -> 255276 bytes
-rw-r--r--docs/tutorial/assets/13d-order-by-pid.pngbin0 -> 183662 bytes
-rw-r--r--docs/tutorial/assets/13e-order-by-process-paths.pngbin0 -> 214308 bytes
-rw-r--r--docs/tutorial/assets/14-headless-modes.gifbin0 -> 4791550 bytes
-rw-r--r--docs/tutorial/assets/screenshot-dashboard.pngbin0 -> 173558 bytes
-rw-r--r--docs/tutorial/assets/screenshot-files-grouped.pngbin0 -> 207344 bytes
-rw-r--r--docs/tutorial/assets/screenshot-flamegraph.pngbin0 -> 171887 bytes
-rw-r--r--docs/tutorial/assets/screenshot-latency.pngbin0 -> 105203 bytes
-rw-r--r--docs/tutorial/assets/screenshot-overview.pngbin0 -> 167438 bytes
-rw-r--r--docs/tutorial/assets/screenshot-pidpicker-open.pngbin0 -> 122673 bytes
-rw-r--r--docs/tutorial/assets/screenshot-pidpicker.pngbin0 -> 122249 bytes
-rw-r--r--docs/tutorial/assets/screenshot-probes.pngbin0 -> 157287 bytes
-rw-r--r--docs/tutorial/assets/screenshot-processes.pngbin0 -> 191556 bytes
-rw-r--r--docs/tutorial/assets/screenshot-recording-active.pngbin0 -> 188855 bytes
-rw-r--r--docs/tutorial/assets/screenshot-stream-export.pngbin0 -> 28883 bytes
-rw-r--r--docs/tutorial/assets/screenshot-stream-filtered.pngbin0 -> 198074 bytes
-rw-r--r--docs/tutorial/assets/screenshot-stream-live.pngbin0 -> 29593 bytes
-rw-r--r--docs/tutorial/assets/screenshot-stream-search.pngbin0 -> 169878 bytes
-rw-r--r--docs/tutorial/assets/screenshot-syscalls.pngbin0 -> 226128 bytes
-rw-r--r--docs/tutorial/assets/screenshot-tidpicker.pngbin0 -> 121954 bytes
-rwxr-xr-xdocs/tutorial/scripts/run-tape.sh52
-rwxr-xr-xdocs/tutorial/scripts/sudo-keepalive.sh13
-rwxr-xr-xdocs/tutorial/scripts/workload.sh77
-rw-r--r--docs/tutorial/tapes/01-launch.tape23
-rw-r--r--docs/tutorial/tapes/02-overview-tab.tape23
-rw-r--r--docs/tutorial/tapes/03-syscalls-tab.tape36
-rw-r--r--docs/tutorial/tapes/04-files-tab.tape32
-rw-r--r--docs/tutorial/tapes/05-processes-tab.tape30
-rw-r--r--docs/tutorial/tapes/06-latency-gaps-tab.tape22
-rw-r--r--docs/tutorial/tapes/07-stream-live.tape22
-rw-r--r--docs/tutorial/tapes/08-stream-pause-filter.tape46
-rw-r--r--docs/tutorial/tapes/09-stream-regex-search.tape40
-rw-r--r--docs/tutorial/tapes/10-stream-csv-export.tape28
-rw-r--r--docs/tutorial/tapes/11-pid-tid-probe.tape41
-rw-r--r--docs/tutorial/tapes/12-parquet-recording.tape28
-rw-r--r--docs/tutorial/tapes/13-tui-flamegraph.tape22
-rw-r--r--docs/tutorial/tapes/14-headless-modes.tape38
56 files changed, 818 insertions, 175 deletions
diff --git a/docs/tui-reference.md b/docs/tui-reference.md
deleted file mode 100644
index d6a7266..0000000
--- a/docs/tui-reference.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# TUI Reference
-
-## TUI Flamegraphs
-
-Flamegraphs are available only inside the TUI dashboard.
-Use `-fields` to change the stack order and `-count` to choose the metric.
-The default stack order is `comm,path,tracepoint` (bottom to top).
-
-## Recording Modes
-
-`ior` has four distinct output flows:
-
-| Mode | How to use it | What it writes | Filter behavior |
-| --- | --- | --- | --- |
-| TUI dashboard | default startup | nothing continuously; data stays in memory unless you export | current TUI/global filters drive what you see |
-| TUI CSV snapshot export | press `e` in the dashboard | one `ior-stream-<timestamp>.csv` snapshot of the current filtered stream view | exports only the currently filtered in-memory rows |
-| Headless `.ior.zst` export | start with `-flamegraph -name <name>` | one aggregated native trace artifact written at shutdown | no TUI filter stack; this is the native trace/integration workflow |
-| Parquet recording | press `R` in the TUI, or start with `-parquet <file>` | a streaming Parquet file of traced syscall rows | TUI mode records rows that pass the active TUI filter; headless `-parquet` records all traced rows |
-
-Important distinction:
-
-- `.ior.zst` output is an aggregated native artifact, not a row-by-row event log.
-- CSV export is a point-in-time snapshot of the ring buffer.
-- Parquet recording is a streaming capture from start to stop.
-- The ring buffer is capped, so CSV export is not a replacement for Parquet recording or `.ior.zst` output.
-
-### Headless Native `.ior.zst` Output
-
-Use `-flamegraph` when you want the native `ior` trace artifact instead of a streaming row log:
-
-```shell
-sudo ./ior -flamegraph -name trace-run -duration 60
-```
-
-Native `.ior.zst` behavior:
-
-- writes one `*.ior.zst` file when the run ends
-- stores aggregated counters for repeated syscall/path/process combinations
-- is intended for `ior`'s native flamegraph and integration-style workflows
-- does not preserve one output row per traced syscall
-
-### TUI Parquet Recording
-
-Start a recording from the dashboard with `R`.
-
-- First `R`: open a filename prompt (`ior-recording-<timestamp>.parquet` by default).
-- `Enter`: start recording to that file.
-- Second `R`: stop and finalize the active Parquet file.
-- Recording stops automatically when you quit the TUI or reselect PID/TID/session scope.
-
-Lifecycle details:
-
-- TUI recording uses the active TUI global filter at emission time.
-- If a filter change restarts tracing, the recorder stays alive and continues writing matching rows after the restart.
-- The dashboard footer shows the active recording path or the last recording error.
-
-### Headless Parquet Recording
-
-Use `-parquet` to skip the TUI and stream traced syscall rows directly to a Parquet file:
-
-```shell
-sudo ./ior -parquet trace.parquet -duration 60
-```
-
-Headless Parquet mode behavior:
-
-- skips the TUI completely
-- records all traced rows
-- rejects content filters such as `-comm`, `-path`, `-pid`, and `-tid`
-- cannot be combined with `-plain`, `-flamegraph`, `--testflames`, or `--testliveflames`
-
-Use headless mode when you want a full recording, and TUI mode when you want interactive filtering plus optional start/stop recording from the dashboard.
-
-### Choosing Between `.ior.zst` and Parquet
-
-| Question | Native `.ior.zst` | Parquet |
-| --- | --- | --- |
-| Data shape | aggregated counters | one row per traced syscall |
-| Write pattern | collect in memory, write one compressed artifact at the end | stream rows continuously while recording |
-| Best for | `ior`-native trace artifacts, flamegraph workflows, integration assertions | offline analysis in other tools, long captures, preserving per-event detail |
-| Relative write cost | usually lower because repeated events are folded together before file write | usually higher because each traced row is serialized |
-| Detail retained | loses original row order and per-event granularity | keeps per-event timing and syscall fields |
-
-Rule of thumb:
-
-- choose `.ior.zst` when you want the native `ior` artifact and do not need every traced syscall row preserved
-- choose Parquet when you want a full event stream for downstream analysis outside `ior`
-
-## TUI Navigation
-
-The TUI has an in-screen help panel (toggle with **H**) that lists all available
-keys. Use it to discover shortcuts without consulting this document.
-
-Dashboard tabs:
-
-- **tab** / **shift+tab** — next / previous tab
-- **1** — Overview
-- **2** — Syscalls
-- **3** — Files
-- **4** — Processes
-- **5** — Latency+Gaps
-- **6** — Stream
-
-The TUI has two key scopes:
-
-- Global hotkeys: available from any dashboard screen.
-- Dashboard hotkeys: behavior that depends on the active tab (especially `6:Stream`).
-
-### Global Hotkeys
-
-- `tab` / `shift+tab`: cycle tabs.
-- `1`–`6`: jump to tab by number (`7` is an alias for `6`).
-- `e`: export filtered stream rows to CSV (`ior-stream-<timestamp>.csv`).
-- `R`: start or stop Parquet recording.
-- `p`: re-open process selector (PID selection flow).
-- `t`: open TID selector flow.
-- `o`: open probe selection/toggling dialog.
-- `r`: refresh dashboard snapshot.
-- `H`: toggle bottom help sections on/off.
-- `q` or `ctrl+c`: quit.
-
-### Dashboard / Tab-Specific Hotkeys
-
-- `d` in `3:Files`: toggle directory-grouped files view.
-- `s` in sortable tabs (`2:Syscalls`, `3:Files`, `4:Processes`): sort by selected column.
-- `S` in sortable tabs: reverse-sort by selected column.
-- `j/k` or `up/down` in list tabs: scroll list.
-
-`left/right` and `h/l` do not switch tabs. In `6:Stream` paused mode they move the selected column.
-
-### 6:Stream Hotkeys and Behavior
-
-`6:Stream` has two modes:
-
-- Live mode (`paused=false`): rows update continuously.
-- Pause mode (`paused=true`): selection/cell/filter/search/export workflows are enabled.
-
-Core controls:
-
-- `space`: toggle live/pause.
-- `g`/`G`: jump to top/tail.
-- `c`: clear stream filters.
-- `f`: open advanced filter modal.
-- `j/k` or `up/down`: move selected row (pause) or scroll (live).
-- `left/right` or `h/l`: move selected column in pause mode.
-
-#### Enter-Based Filter Stack (Pause Mode)
-
-In pause mode, `enter` on the selected cell pushes a filter onto a stack and
-immediately re-filters the current ring buffer snapshot. Filters are stackable.
-
-- String columns use case-insensitive substring match:
- - `Comm` → `comm~<value>`
- - `Syscall` → `syscall~<value>`
- - `File` → `file~<value>`
-- Numeric exact match: `PID`, `TID`, `FD`, `Ret`, `Bytes`
-- Numeric threshold (`>=`): `Latency` → `latency>=selected_value`, `Gap` → `gap>=selected_value`
-
-`esc` in pause mode pops the most recent filter (LIFO); repeated `esc` undoes
-all stacked filters.
-
-#### Regex Search (Pause Mode)
-
-- `/`: search forward; `?`: search backward.
-- Search checks all stream columns and wraps around the ring buffer.
-- `n` / `N`: next / previous match.
-
-#### Stream CSV Export (Pause Mode)
-
-- `x`: quick export filtered stream rows to CSV.
-- `X`: export with filename prompt.
-- `E`: open last stream-exported CSV in foreground editor (`EDITOR` → `VISUAL` → `SUDO_EDITOR` → `hx` → `vi`).
-
-`e` (global) exports a fresh filtered snapshot even outside paused mode; `x`/`X`
-export the exact paused view.
diff --git a/docs/tutorial/TUTORIAL.md b/docs/tutorial/TUTORIAL.md
new file mode 100644
index 0000000..e53013a
--- /dev/null
+++ b/docs/tutorial/TUTORIAL.md
@@ -0,0 +1,245 @@
+# I/O Riot NG: a guided tour
+
+This tutorial walks through every major surface of `ior` — the dashboard tabs, the live stream, recording, headless modes, and the in-TUI flamegraph — using short animated GIFs so you can *see* what the keys actually do.
+
+Every GIF in this document is regenerated from a [VHS](https://github.com/charmbracelet/vhs) tape under [`demo/tapes/`](./tapes). To rebuild them all, run `sudo -v && mage demo` (see [Regenerating the demo](#regenerating-the-demo)).
+
+## Contents
+
+1. [Installing ior](#installing-ior)
+2. [First launch: the PID picker](#first-launch-the-pid-picker)
+3. [Touring the dashboard tabs](#touring-the-dashboard-tabs)
+ - [1 · Flamegraph (default landing tab)](#1--flamegraph-default-landing-tab)
+ - [2 · Overview](#2--overview)
+ - [3 · Syscalls](#3--syscalls)
+ - [4 · Files](#4--files)
+ - [5 · Processes](#5--processes)
+ - [6 · Latency + Gaps](#6--latency--gaps)
+ - [7 · Stream](#7--stream)
+4. [Mastering the Stream tab](#mastering-the-stream-tab)
+ - [Pause + stacked filters](#pause--stacked-filters)
+ - [Regex search](#regex-search)
+ - [CSV export](#csv-export)
+5. [Choosing what to trace](#choosing-what-to-trace)
+6. [Recording for offline analysis](#recording-for-offline-analysis)
+ - [TUI Parquet recording](#tui-parquet-recording)
+ - [Headless modes](#headless-modes)
+7. [Regenerating the demo](#regenerating-the-demo)
+
+## Installing ior
+
+See the [main README](../../README.md) for full install steps. The quickest path from any Docker-capable Linux host:
+
+```shell
+git clone https://codeberg.org/snonux/ior ~/git/ior
+cd ~/git/ior
+mage buildDocker # builds inside a Rocky 9 container, ~15 min on first run
+```
+
+For a native build (libbpfgo must be cloned alongside the repo first — see the README):
+
+```shell
+mage all
+```
+
+ior needs `CAP_BPF`, so every invocation below uses `sudo`.
+
+The build dance only has to happen once: the resulting `ior` binary is fully statically linked and uses CO-RE, so the same binary runs on any BTF-enabled Linux kernel without recompilation. See the [Compile once, run everywhere](../../README.md#compile-once-run-everywhere) section for details.
+
+## First launch: the PID picker
+
+`sudo ./ior` starts with the **PID picker**. The cursor is on **All PIDs**, so pressing `Enter` traces the whole system. Type into the filter box to narrow the list by PID, comm, or cmdline; arrow keys move the selection.
+
+![Cold start: PID picker, then the dashboard appears](./assets/01-launch.gif)
+
+The same picker can be re-opened later from the dashboard with `p`.
+
+![PID picker default state](./assets/screenshot-pidpicker.png)
+
+## Touring the dashboard tabs
+
+The dashboard has seven tabs, addressable by number key. The default landing tab is **Flamegraph**. `tab` / `shift+tab` step forward / back.
+
+| Key | Tab | What it shows |
+|-----|-------------------|--------------------------------------------------------------------------|
+| `1` | Flamegraph (`Flm`)| Live FlameGraph of the configured stack (`comm`/`path`/`tracepoint`) |
+| `2` | Overview (`Ovr`) | Sparkline + top syscalls + top paths summary |
+| `3` | Syscalls (`Sys`) | Sortable per-syscall counters, latency, byte volume |
+| `4` | Files (`Fil`) | Per-path counters; `d` toggles directory grouping |
+| `5` | Processes (`Pro`) | Per-process / per-comm counters |
+| `6` | Latency (`Lat`) | Latency + inter-syscall gap histograms |
+| `7` | Stream (`Str`) | Live tail of individual traced events |
+
+### 1 · Flamegraph (default landing tab)
+
+The first thing you see after dismissing the PID picker is the **live flamegraph**. Bars grow as new events come in. `o` cycles the stack ordering (e.g. `comm/path/tracepoint` ↔ `comm/tracepoint/path`); `b` toggles the size metric (event count vs. duration vs. gap).
+
+![Live flamegraph rebuilding from real workload](./assets/13-tui-flamegraph.gif)
+
+### 2 · Overview
+
+Press `2`. The Overview tab is the at-a-glance view: a sparkline of recent event volume, the top syscalls, and the top paths.
+
+![Overview tab populating](./assets/02-overview-tab.gif)
+
+### 3 · Syscalls
+
+Press `3`. A sortable table of every traced syscall (count, average latency, total bytes). `j` / `k` (or arrow keys) scroll the rows; `←` / `→` move the selected column; `s` sorts by the selected column using its default direction; `S` reverses.
+
+![Syscalls table with sort + reverse-sort](./assets/03-syscalls-tab.gif)
+
+### 4 · Files
+
+Press `4`. Per-path counters. The most useful key here is `d`, which toggles **directory grouping** — paths roll up into their parent directory, which is essential when one process touches thousands of files in `/usr/share/...`.
+
+![Files tab toggling directory grouping](./assets/04-files-tab.gif)
+
+### 5 · Processes
+
+Press `5`. Per-process / per-comm view. `S` reverse-sorts; combine with `←` / `→` to pick a column.
+
+![Processes tab](./assets/05-processes-tab.gif)
+
+### 6 · Latency + Gaps
+
+Press `6`. Two histograms: syscall **latency** (how long the syscall ran) and the inter-syscall **gap** (idle time on the same thread between syscalls). The big-write workload running in the background spreads the latency distribution noticeably.
+
+![Latency + gap histograms](./assets/06-latency-gaps-tab.gif)
+
+### 7 · Stream
+
+Press `7`. A live tail of every traced event row — comm, PID, TID, syscall, file, FD, return value, bytes, latency, gap. This is the workhorse view; the next section explores it in depth.
+
+![Stream tab live-tailing rows](./assets/07-stream-live.gif)
+
+## Mastering the Stream tab
+
+Stream has two modes: **Live** (rows scroll past) and **Pause** (`space` toggles). Almost everything interesting happens in pause mode.
+
+### Pause + stacked filters
+
+In pause mode, navigate with `j`/`k` (rows) and `←` / `→` (columns). Pressing `Enter` on the selected cell **pushes a new filter onto a stack** and immediately re-filters the ring buffer. Filters are stackable, so you can drill down — first by `Comm`, then by `Syscall`, then by `File`. `Esc` pops the most recent filter (LIFO); keep hitting `Esc` to undo all the way back.
+
+![Pause, push two filters, undo with Esc](./assets/08-stream-pause-filter.gif)
+
+The filter is reflected in the bottom status line, and matches the same syntax you'd type by hand: `comm~bash`, `syscall~openat`, `latency>=100000`, etc.
+
+### Regex search
+
+`/` opens a forward regex prompt; `?` opens a backward one. `n` jumps to the next match in the same direction; `N` reverses. The search runs against every column on every row in the ring buffer and wraps at the end.
+
+![Regex search with /, n, n, then ?](./assets/09-stream-regex-search.gif)
+
+### CSV export
+
+Three keys, three flavours:
+
+- `e` — quick export of the **current TUI-filter snapshot** to `ior-stream-<timestamp>.csv` in the current working directory. Works from any tab, not just Stream.
+- `x` — quick export of the **paused stream view** specifically (preserves your filter stack).
+- `X` — same as `x`, but prompts for a filename first.
+- `E` — open the most recent stream-exported CSV in your `$EDITOR` (`hx` / `vi` fallback).
+
+![Press 'e', then ls the resulting CSV](./assets/10-stream-csv-export.gif)
+
+If you don't want CSV export at all, start ior with `-tuiExport=false`; the help footer hides the export keys and `e` becomes a no-op.
+
+## Choosing what to trace
+
+Three modal pickers reshape what the rest of the TUI sees:
+
+- `p` — **PID picker** (re-opens the launch picker).
+- `t` — **TID picker** for thread-level focus.
+- `o` — **Probes** dialog: enable / disable individual syscall tracepoints.
+
+![PID, TID, and probe pickers](./assets/11-pid-tid-probe.gif)
+
+Restricting to a single PID is also exposed as a CLI flag (`-pid <n>`), as is comm/path filtering (`-comm`, `-path`). Tracepoint subsetting on the command line uses `-tps <regex>` / `-tpsExclude <regex>`.
+
+## Recording for offline analysis
+
+ior has three persistence flows; each solves a different problem.
+
+| Flow | How | What you get |
+|------------------------|----------------------------------------------|---------------------------------------------------------|
+| TUI Parquet recording | `R` from the dashboard | streaming Parquet of every row that passes your filter |
+| Headless `.ior.zst` | `sudo ./ior -flamegraph -name <name>` | one aggregated native trace artifact (bandwidth-cheap) |
+| Headless Parquet | `sudo ./ior -parquet trace.parquet` | streaming Parquet, full firehose, no TUI |
+| Plain CSV | `sudo ./ior -plain` | one CSV row per event on stdout |
+
+### TUI Parquet recording
+
+Press `R` in the dashboard, accept the default filename (`ior-recording-<timestamp>.parquet`) with `Enter`, and rows start streaming to disk. The footer shows the active recording path (or the last error). Press `R` again to stop.
+
+![Start, run, and stop a parquet recording](./assets/12-parquet-recording.gif)
+
+The recorder follows your *current* TUI global filter — narrow with `p`/`t`/`o` first if you want a focused capture.
+
+### Headless modes
+
+For unattended captures or scripting, skip the TUI entirely. The demo runs all three back-to-back, capped with `-duration` so each terminates on its own.
+
+![Three headless flows in one tape](./assets/14-headless-modes.gif)
+
+`-flamegraph` writes one aggregated `.ior.zst` artifact at shutdown — ideal for `ior`'s native flamegraph and integration workflows. `-parquet` streams every row, so the file grows continuously. `-plain` is the lightest weight: CSV to stdout you can pipe into anything.
+
+## Regenerating the demo
+
+The whole asset pipeline is reproducible:
+
+```shell
+mage installDemoTools # one-time: VHS via go install + ttyd via dnf
+sudo -v # warm the sudo timestamp once
+mage demo # regen all 14 GIFs + screenshots (~10 min)
+```
+
+Or rebuild a single tape after editing it:
+
+```shell
+TAPE=07-stream-live mage demoOne
+```
+
+Tapes live in [`tapes/`](./tapes), the background workload that drives them is [`scripts/workload.sh`](./scripts/workload.sh), and the resulting assets land in [`assets/`](./assets). VHS records headlessly under `ttyd` + Chromium — no real terminal window opens, so `mage demo` is safe to run in the background while you keep working.
+
+## Hotkey Quick Reference
+
+### Global keys
+
+| Key | Action |
+|-----|--------|
+| `tab` / `shift+tab` | next / previous tab |
+| `1`–`6` (`7` = alias for `6`) | jump to tab by number |
+| `H` | toggle bottom help panel |
+| `e` | export filtered stream snapshot to CSV |
+| `R` | start / stop Parquet recording |
+| `p` | re-open PID picker |
+| `t` | open TID picker |
+| `o` | open probe selection dialog |
+| `r` | refresh dashboard snapshot |
+| `q` / `ctrl+c` | quit |
+
+### Tab-specific keys (`2:Syscalls`, `3:Files`, `4:Processes`)
+
+| Key | Action |
+|-----|--------|
+| `s` | sort by selected column (default direction) |
+| `S` | reverse-sort by selected column |
+| `j`/`k` or `↑`/`↓` | scroll list |
+| `d` (Files only) | toggle directory grouping |
+
+### Stream tab (`7:Stream`)
+
+| Key | Action |
+|-----|--------|
+| `space` | toggle live / pause mode |
+| `g` / `G` | jump to top / tail |
+| `j`/`k` or `↑`/`↓` | move row (pause) / scroll (live) |
+| `←`/`→` or `h`/`l` | move selected column (pause only) |
+| `enter` | push cell value as filter (pause) |
+| `esc` | pop most recent filter (LIFO) |
+| `c` | clear all stream filters |
+| `f` | open advanced filter modal |
+| `/` / `?` | regex search forward / backward |
+| `n` / `N` | next / previous search match |
+| `x` | quick CSV export of paused view |
+| `X` | CSV export with filename prompt |
+| `E` | open last CSV export in `$EDITOR` |
diff --git a/docs/tutorial/assets/00-hero-flamegraph.png b/docs/tutorial/assets/00-hero-flamegraph.png
new file mode 100644
index 0000000..d409e79
--- /dev/null
+++ b/docs/tutorial/assets/00-hero-flamegraph.png
Binary files differ
diff --git a/docs/tutorial/assets/00-logo.png b/docs/tutorial/assets/00-logo.png
new file mode 100644
index 0000000..d2da30c
--- /dev/null
+++ b/docs/tutorial/assets/00-logo.png
Binary files differ
diff --git a/docs/tutorial/assets/01-launch.gif b/docs/tutorial/assets/01-launch.gif
new file mode 100644
index 0000000..978b95e
--- /dev/null
+++ b/docs/tutorial/assets/01-launch.gif
Binary files differ
diff --git a/docs/tutorial/assets/02-overview-tab.gif b/docs/tutorial/assets/02-overview-tab.gif
new file mode 100644
index 0000000..56f0e98
--- /dev/null
+++ b/docs/tutorial/assets/02-overview-tab.gif
Binary files differ
diff --git a/docs/tutorial/assets/03-syscalls-tab.gif b/docs/tutorial/assets/03-syscalls-tab.gif
new file mode 100644
index 0000000..47c4029
--- /dev/null
+++ b/docs/tutorial/assets/03-syscalls-tab.gif
Binary files differ
diff --git a/docs/tutorial/assets/04-files-tab.gif b/docs/tutorial/assets/04-files-tab.gif
new file mode 100644
index 0000000..af18828
--- /dev/null
+++ b/docs/tutorial/assets/04-files-tab.gif
Binary files differ
diff --git a/docs/tutorial/assets/05-processes-tab.gif b/docs/tutorial/assets/05-processes-tab.gif
new file mode 100644
index 0000000..a6beed1
--- /dev/null
+++ b/docs/tutorial/assets/05-processes-tab.gif
Binary files differ
diff --git a/docs/tutorial/assets/06-latency-gaps-tab.gif b/docs/tutorial/assets/06-latency-gaps-tab.gif
new file mode 100644
index 0000000..b0d9c81
--- /dev/null
+++ b/docs/tutorial/assets/06-latency-gaps-tab.gif
Binary files differ
diff --git a/docs/tutorial/assets/07-stream-live.gif b/docs/tutorial/assets/07-stream-live.gif
new file mode 100644
index 0000000..af742bd
--- /dev/null
+++ b/docs/tutorial/assets/07-stream-live.gif
Binary files differ
diff --git a/docs/tutorial/assets/08-stream-pause-filter.gif b/docs/tutorial/assets/08-stream-pause-filter.gif
new file mode 100644
index 0000000..7821cf7
--- /dev/null
+++ b/docs/tutorial/assets/08-stream-pause-filter.gif
Binary files differ
diff --git a/docs/tutorial/assets/09-stream-regex-search.gif b/docs/tutorial/assets/09-stream-regex-search.gif
new file mode 100644
index 0000000..73e068b
--- /dev/null
+++ b/docs/tutorial/assets/09-stream-regex-search.gif
Binary files differ
diff --git a/docs/tutorial/assets/10-stream-csv-export.gif b/docs/tutorial/assets/10-stream-csv-export.gif
new file mode 100644
index 0000000..aa5bb3b
--- /dev/null
+++ b/docs/tutorial/assets/10-stream-csv-export.gif
Binary files differ
diff --git a/docs/tutorial/assets/11-pid-tid-probe.gif b/docs/tutorial/assets/11-pid-tid-probe.gif
new file mode 100644
index 0000000..f7f96c7
--- /dev/null
+++ b/docs/tutorial/assets/11-pid-tid-probe.gif
Binary files differ
diff --git a/docs/tutorial/assets/12-parquet-recording.gif b/docs/tutorial/assets/12-parquet-recording.gif
new file mode 100644
index 0000000..b9baab3
--- /dev/null
+++ b/docs/tutorial/assets/12-parquet-recording.gif
Binary files differ
diff --git a/docs/tutorial/assets/13-tui-flamegraph.gif b/docs/tutorial/assets/13-tui-flamegraph.gif
new file mode 100644
index 0000000..71aece3
--- /dev/null
+++ b/docs/tutorial/assets/13-tui-flamegraph.gif
Binary files differ
diff --git a/docs/tutorial/assets/13a-order-by-process.png b/docs/tutorial/assets/13a-order-by-process.png
new file mode 100644
index 0000000..8a469bf
--- /dev/null
+++ b/docs/tutorial/assets/13a-order-by-process.png
Binary files differ
diff --git a/docs/tutorial/assets/13b-order-by-path.png b/docs/tutorial/assets/13b-order-by-path.png
new file mode 100644
index 0000000..3518412
--- /dev/null
+++ b/docs/tutorial/assets/13b-order-by-path.png
Binary files differ
diff --git a/docs/tutorial/assets/13c-order-by-syscall.png b/docs/tutorial/assets/13c-order-by-syscall.png
new file mode 100644
index 0000000..3eb5058
--- /dev/null
+++ b/docs/tutorial/assets/13c-order-by-syscall.png
Binary files differ
diff --git a/docs/tutorial/assets/13d-order-by-pid.png b/docs/tutorial/assets/13d-order-by-pid.png
new file mode 100644
index 0000000..0d56f12
--- /dev/null
+++ b/docs/tutorial/assets/13d-order-by-pid.png
Binary files differ
diff --git a/docs/tutorial/assets/13e-order-by-process-paths.png b/docs/tutorial/assets/13e-order-by-process-paths.png
new file mode 100644
index 0000000..ccd450a
--- /dev/null
+++ b/docs/tutorial/assets/13e-order-by-process-paths.png
Binary files differ
diff --git a/docs/tutorial/assets/14-headless-modes.gif b/docs/tutorial/assets/14-headless-modes.gif
new file mode 100644
index 0000000..cf245f4
--- /dev/null
+++ b/docs/tutorial/assets/14-headless-modes.gif
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-dashboard.png b/docs/tutorial/assets/screenshot-dashboard.png
new file mode 100644
index 0000000..0eee11f
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-dashboard.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-files-grouped.png b/docs/tutorial/assets/screenshot-files-grouped.png
new file mode 100644
index 0000000..b2a206a
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-files-grouped.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-flamegraph.png b/docs/tutorial/assets/screenshot-flamegraph.png
new file mode 100644
index 0000000..ae79335
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-flamegraph.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-latency.png b/docs/tutorial/assets/screenshot-latency.png
new file mode 100644
index 0000000..43b6cd8
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-latency.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-overview.png b/docs/tutorial/assets/screenshot-overview.png
new file mode 100644
index 0000000..eac3138
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-overview.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-pidpicker-open.png b/docs/tutorial/assets/screenshot-pidpicker-open.png
new file mode 100644
index 0000000..22a7b93
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-pidpicker-open.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-pidpicker.png b/docs/tutorial/assets/screenshot-pidpicker.png
new file mode 100644
index 0000000..4b8f025
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-pidpicker.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-probes.png b/docs/tutorial/assets/screenshot-probes.png
new file mode 100644
index 0000000..df0664a
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-probes.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-processes.png b/docs/tutorial/assets/screenshot-processes.png
new file mode 100644
index 0000000..c1873d2
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-processes.png
Binary files differ
diff --git a/docs/tutorial/assets/screenshot-recording-active.png b/docs/tutorial/assets/screenshot-recording-active.png
new file mode 100644
index 0000000..e50d588
--- /dev/null
+++ b/docs/tutorial/assets/screenshot-recording-active.png
Binary files differ
diff --git a/docs/tutorial/assets/screensh