u

README.md

@@ -44,6 +44,7 @@ model tool call
 | `bin/fido` | Installed/source launcher; loads user configuration and creates per-workspace state paths. |
 | `src/fido.js` | Process entry point; checks for the required API key and starts the REPL. |
 | `src/repl.js` | Owns conversation state, provider turns, cancellation, tool events, and transcript compaction. |
+| `src/turn-state.js` | Closed enum of connection states plus the pure `(state, event) -> state` reducer that drives the command-bar label. |
 | `src/config.js` | Loads `.env` files and resolves the model, workspace root, and state locations. |
 | `src/system-prompt.js` | Builds the workspace-aware model instructions sent at session start. |
 | `src/commands.js` | Implements local slash commands without spending a model turn. |
@@ -124,6 +125,22 @@ The UI is a React application rendered by Ink in the terminal's alternate screen
 
 The store retains the latest 1,000 logical history entries, while the view mounts only the lines that fit in the current terminal. Mouse reporting can be disabled with `FIDO_NO_MOUSE=1`.
 
+### Connection States
+
+While a turn runs, the command bar shows an animated spinner plus one of five states. The state is a closed enum (`src/turn-state.js`) and every transition is driven by an observable provider event rather than a timer, so the label always names what the stream is currently doing.
+
+| State | Label | Entered when |
+| --- | --- | --- |
+| `idle` | *(the `› (idle)` placeholder)* | Session start, after a turn completes, after cancel, after an error. |
+| `connecting` | `connecting…` | The turn started and the request is in flight, but no delta has arrived yet. |
+| `thinking` | `thinking…` | Every reasoning delta. |
+| `working` | `working…` | Every tool-call delta. |
+| `streaming` | `streaming…` | Every content delta. |
+
+A turn therefore reads as `connecting → streaming` for a plain answer, `connecting → thinking → streaming` when the model reasons first, and `connecting → thinking → working → streaming` when it also calls a tool. Each delta wins immediately, so a later reasoning delta can move the label back from `streaming` to `thinking`; the label tracks the newest activity rather than the furthest point reached. Cancel and error are terminal: both fall back to `idle` so the prompt always returns.
+
+The REPL (`src/repl.js`) is the only module that decides a transition, and it does so through a pure `(state, event) -> state` reducer, so the machine is unit-testable without React, the store, or a live provider. Text supplied by the provider's `onStatus` is treated as a non-authoritative detail shown next to the state label, never as a replacement for it.
+
 ## File Mentions
 
 Press `Ctrl+O` in the main prompt to open the file browser.