diff --git a/README.md b/README.md
index 3e37aaba..87cf7f0a 100644
--- a/README.md
+++ b/README.md
@@ -490,6 +490,12 @@ Full shortcut catalog: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md).
 
 User config: `~/.codewhale/config.toml` (legacy `~/.deepseek/config.toml` fallback). Project overlay: `<workspace>/.codewhale/config.toml` (legacy `<workspace>/.deepseek/config.toml`) (denied: `api_key`, `base_url`, `provider`, `mcp_config_path`). [config.example.toml](config.example.toml) has every option.
 
+The TUI footer can be trimmed or reordered with `/statusline`, or by setting
+`[tui].status_items` in config. Current footer customization selects from the
+built-in chips such as `mode`, `model`, `status`, `git_branch`, `tokens`, and
+`cache`; multi-line layouts, custom colors, and external command widgets are
+not part of the current statusline surface.
+
 Custom DeepSeek-compatible endpoints usually do not need a new provider. Keep
 `provider = "deepseek"` and set `[providers.deepseek].base_url` / `model`, or
 use `provider = "openai"` for generic OpenAI-compatible gateways. Keep
diff --git a/config.example.toml b/config.example.toml
index d80a8aa4..70e54dd1 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -429,6 +429,13 @@ alternate_screen = "auto"   # auto/always use the TUI screen; never uses termina
 mouse_capture = true        # true copies only transcript user/assistant text; false uses raw terminal selection/copy
 terminal_probe_timeout_ms = 500 # optional startup terminal-mode timeout (100-5000ms)
 osc8_links = true            # emit OSC 8 escapes around URLs (Cmd+click in iTerm2/Ghostty/Kitty/WezTerm/Terminal.app 13+); set false for terminals that misrender
+# Ordered footer chips shown in the TUI status line. Omit the key to use the
+# built-in default; set [] to hide all configurable chips. You can also edit
+# this interactively with `/statusline`.
+# Supported keys: mode, model, cost, balance, status, coherence, agents,
+# reasoning_replay, prefix_stability, cache, context_percent, git_branch,
+# last_tool_elapsed, rate_limit, tokens.
+# status_items = ["mode", "model", "status", "git_branch", "tokens", "cache"]
 # notification_condition = "always" # always | never — overrides [notifications].threshold_secs.
 #                                    "always" = notify on every successful turn (no threshold);
 #                                    "never"  = suppress all turn-completion notifications;
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 8a8407a3..7deb35a6 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -180,6 +180,14 @@ The interactive TUI has a few stable regions:
 - Status and footer areas: live activity, queued follow-ups, and short command
   hints.
 
+The footer status line is configurable. Run `/statusline` to choose which
+footer chips are visible, or set `[tui].status_items` in `config.toml` for a
+stable order. Supported keys currently include `mode`, `model`, `cost`,
+`balance`, `status`, `coherence`, `agents`, `reasoning_replay`,
+`prefix_stability`, `cache`, `context_percent`, `git_branch`,
+`last_tool_elapsed`, `rate_limit`, and `tokens`. Omit `status_items` to keep
+the built-in default order; set it to `[]` to hide configurable chips.
+
 The transcript is the audit trail. When CodeWhale reads files, runs commands,
 or edits code, the action appears there. If a command fails, use the visible
 failure output as part of your next instruction instead of starting over.
@@ -256,6 +264,7 @@ Common commands for first-time users:
 | `/models` | Fetch or list models from the active endpoint |
 | `/provider` | Pick the active API provider |
 | `/config` | Edit runtime and provider settings |
+| `/statusline` | Choose which footer status chips are visible |
 | `/settings` | Inspect persistent UI preferences |
 | `/compact` | Summarize long context to recover token budget |
 | `/review` | Ask for a structured review workflow |