1 files changed, 175 insertions, 0 deletions
diff --git a/docs/tui-reference.md b/docs/tui-reference.md
new file mode 100644
index 0000000..d6a7266
--- /dev/null
+++ b/docs/tui-reference.md
@@ -0,0 +1,175 @@
+# 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.