diff --git a/docs/users/configuration/settings.md b/docs/users/configuration/settings.md
index 82a2e2006..ccf44c849 100644
--- a/docs/users/configuration/settings.md
+++ b/docs/users/configuration/settings.md
@@ -98,7 +98,7 @@ Settings are organized into categories. All settings should be placed within the
 | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
 | `ui.theme`                              | string           | The color theme for the UI. See [Themes](../configuration/themes) for available options.                                                                                                                                                                                                                                                                                                                            | `undefined` |
 | `ui.customThemes`                       | object           | Custom theme definitions.                                                                                                                                                                                                                                                                                                                                                                                           | `{}`        |
-| `ui.statusLine`                         | object           | Custom status line configuration. A shell command whose output is shown below the footer. See [Status Line](../features/status-line).                                                                                                                                                                                                                                                                               | `undefined` |
+| `ui.statusLine`                         | object           | Custom status line configuration. A shell command whose output is shown in the footer's left section. See [Status Line](../features/status-line).                                                                                                                                                                                                                                                                   | `undefined` |
 | `ui.hideWindowTitle`                    | boolean          | Hide the window title bar.                                                                                                                                                                                                                                                                                                                                                                                          | `false`     |
 | `ui.hideTips`                           | boolean          | Hide helpful tips in the UI.                                                                                                                                                                                                                                                                                                                                                                                        | `false`     |
 | `ui.hideBanner`                         | boolean          | Hide the application banner.                                                                                                                                                                                                                                                                                                                                                                                        | `false`     |
diff --git a/docs/users/features/status-line.md b/docs/users/features/status-line.md
index 9bad4f90f..866e210e3 100644
--- a/docs/users/features/status-line.md
+++ b/docs/users/features/status-line.md
@@ -1,17 +1,24 @@
 # Status Line
 
-> Display custom information beneath the footer using a shell command.
+> Display custom information in the footer using a shell command.
 
-The status line lets you run a shell command whose output is displayed as a persistent line below the footer bar. The command receives structured JSON context via stdin, so it can show session-aware information like the current model, token usage, git branch, or anything else you can script.
+The status line lets you run a shell command whose output is displayed in the footer's left section. The command receives structured JSON context via stdin, so it can show session-aware information like the current model, token usage, git branch, or anything else you can script.
 
 ```
+With status line (default approval mode — 1 row):
 ┌─────────────────────────────────────────────────────────────────┐
-│  ? for shortcuts                  🔒 docker | Debug | ◼◼◼◻ 67% │
-├─────────────────────────────────────────────────────────────────┤
-│  user@host ~/project (main) qwen-3-235b  ctx:34%               │  ← status line
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line
+└─────────────────────────────────────────────────────────────────┘
+
+With status line + non-default mode (2 rows):
+┌─────────────────────────────────────────────────────────────────┐
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line
+│  auto-accept edits (shift + tab to cycle)                       │  ← mode indicator
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+When configured, the status line replaces the default "? for shortcuts" hint. High-priority messages (Ctrl+C/D exit prompts, Esc, vim INSERT mode) temporarily override the status line. The status line text is truncated to fit within the available width.
+
 ## Prerequisites
 
 - [`jq`](https://jqlang.github.io/jq/) is recommended for parsing the JSON input (install via `brew install jq`, `apt install jq`, etc.)
@@ -213,10 +220,10 @@ Then reference it in settings:
 
 - **Update triggers**: The status line updates when the model changes, a new message is sent (token count changes), vim mode is toggled, git branch changes, tool calls complete, or file changes occur. Updates are debounced (300ms).
 - **Timeout**: Commands that take longer than 5 seconds are killed. The status line clears on failure.
-- **Output**: Only the first line of stdout is used. The text is rendered with dimmed colors and truncated to terminal width.
+- **Output**: Only the first line of stdout is used. The text is rendered with dimmed colors in the footer's left section and truncated if it exceeds the available width.
 - **Hot reload**: Changes to `ui.statusLine` in settings take effect immediately — no restart required.
 - **Shell**: Commands run via `/bin/sh` on macOS/Linux. On Windows, `cmd.exe` is used by default — wrap POSIX commands with `bash -c "..."` or point to a bash script (e.g. `bash ~/.qwen/statusline-command.sh`).
-- **Removal**: Delete the `ui.statusLine` key from settings to disable. The status line disappears and the "? for shortcuts" hint returns.
+- **Removal**: Delete the `ui.statusLine` key from settings to disable. The "? for shortcuts" hint returns.
 
 ## Troubleshooting