docs(cli): customization (settings, themes, statusline, rules, skills, MCP)

src/content/docs/cli/configuration.mdx

@@ -1,31 +1,133 @@
 ---
-title: "Configuring the {{WARP_CLI}}"
+title: "Customizing the Warp Agent CLI"
 description: >-
-  Configure the {{WARP_CLI}} with its TOML settings file, themes, statusline,
-  and keybindings.
+  Customize the Warp Agent CLI: settings file, themes, statusline, and agent
+  context with project rules, skills, and MCP servers.
 ---
 import { VARS } from '@data/vars';
 
-{/* TODO(cli-configuration): draft per drafts/warp-cli-launch-plan.md — "cli/configuration.mdx" section. Feature-doc content type. */}
-
-The {VARS.WARP_CLI} documentation for this page is in progress.
+The {VARS.WARP_CLI} keeps its configuration in a plain TOML settings file on your machine. You can change settings by editing the file directly, by running slash commands like `/theme` and `/statusline`, or by asking the agent to update a setting for you. Beyond the CLI's own settings, this page also covers the agent's context: the project rules, skills, and MCP servers the agent picks up as you work.
 
 ## The settings file
 
-{/* TODO(cli-configuration): TOML settings file location and behavior; settings are local to the CLI and not synced. */}
+The CLI reads its settings from a `settings.toml` file:
+
+* **macOS** - `~/.warp_cli/settings.toml`
+* **Linux** - `~/.config/warp-terminal/cli/settings.toml` (respects `$XDG_CONFIG_HOME`)
+* **Windows** - `%LOCALAPPDATA%\warp\Warp\config\cli\settings.toml`
+
+The file is created the first time you change a setting, and you can also create it yourself. Settings use dotted TOML sections. For example:
+
+```toml title="settings.toml"
+[appearance]
+theme = "dark"
+```
+
+The CLI watches the settings file while it's running and reloads values as you save, so most edits take effect without a restart. The color theme is the exception: theme edits made directly in the file are applied when you run `/theme` or the next time the CLI starts. If a value is invalid, the CLI logs the problem and uses the default for that setting instead. If the file can't be parsed at all, the CLI starts with default settings.
+
+:::note
+CLI settings are local to your machine and are never synced to the cloud. They are also independent from the Warp app's settings: the app and the CLI keep separate settings files, so changing one never affects the other.
+:::
 
 ## Edit settings with the agent
 
-{/* TODO(cli-configuration): asking the agent to update settings via the bundled skill. */}
+The fastest way to change a setting is to ask the agent in plain language. The CLI ships with a bundled skill and a schema of every available setting, which the agent uses to find the right key, validate the value, and update the settings file for you. Try prompts like:
+
+* "Switch my theme to light."
+* "Add the time to my statusline."
+* "What CLI settings can I change?"
+
+Because the CLI hot-reloads the settings file, most changes the agent makes apply immediately. Theme changes are the exception: they take effect when you run `/theme` or restart the CLI. For the full list of built-in skills, see [Bundled skills](#bundled-skills).
 
 ## Themes
 
-{/* TODO(cli-configuration): /theme auto|light|dark, terminal background detection. */}
+The CLI renders with a light or dark color theme. Set it with the `/theme` slash command:
+
+* **`/theme auto`** - Matches the host terminal's background. This is the default.
+* **`/theme light`** - Always uses the light theme.
+* **`/theme dark`** - Always uses the dark theme.
+
+Running `/theme` applies the change immediately and persists it across sessions as the `theme` key under `[appearance]` in the settings file.
+
+In auto mode, the CLI probes the host terminal's default colors when it starts and picks the theme that matches the background: light backgrounds get the light theme, and dark or undetectable backgrounds get the dark theme. Detection runs at startup, so if you switch your terminal's colors while the CLI is running, restart it or set a theme explicitly.
 
 ## Statusline
 
-{/* TODO(cli-configuration): statusline contents and /statusline customization — confirm shipped before merge. */}
+The statusline is the row below the CLI's input box that shows session information at a glance. By default it shows the active model, the working directory, and, inside a Git repository, the Git branch and diff status. You can enable any of these items:
+
+* **Model** - The active model. Click it to open the model picker.
+* **Git branch** - The current branch, when the directory is a Git repository.
+* **Git branch status** - How far the branch is ahead of or behind its upstream.
+* **Git diff status** - Uncommitted line additions and deletions.
+* **Credit usage** - Credits used by the current conversation. Click it to switch between credits and provider cost.
+* **Context window usage** - How much of the model's context window the conversation has used.
+* **Agent to-do list** - The agent's progress through its current task list.
+* **Auto-approve indicator** - Appears when auto-approve is on.
+* **Auto-queue next prompt indicator** - Appears when auto-queue is on.
+
+You can also add the working directory, the date, the time (12- or 24-hour), and a voice input control.
+
+Items only appear when they have something to show. For example, the Git items appear only inside a repository. In shell mode, the statusline always leads with a shell mode label.
+
+### Customizing the statusline
+
+Choose which items appear and in what order:
+
+1. Run `/statusline`. The **Configure statusline** panel opens with every available item.
+2. Select an item and press `Enter` to toggle its visibility.
+3. Press `←` and `→` to move the highlighted item earlier or later in the row.
+4. Press `Esc` to save and close. Press `Ctrl+C` to cancel without saving.
+
+Your choices are saved to the settings file, so the layout persists across sessions.
+
+## Project context and rules
+
+The CLI gives its agent the same layered context system as the Warp app: your working directory, project rules, skills, and MCP servers, all scoped to the directory you're working in.
+
+The agent works in your session's current directory; when you `cd`, project rules and skills re-scope to the new directory automatically.
+
+Within a project, the CLI picks up the same rule files as the Warp app:
+
+* **Project rules** - `AGENTS.md` (or `WARP.md`) files in your repository apply automatically, starting from the repository root and your current directory. See [Rules](/agent-platform/capabilities/rules/) for the file format, nested rules in subdirectories, and precedence.
+* **Global rules** - A rule file at `~/.agents/AGENTS.md` applies across all projects on your machine.
+
+Because rules and skills are discovered from these shared file locations, a repository that's already set up for agents in the Warp app (or other agent tools that read `AGENTS.md`) works in the CLI with no extra setup.
+
+## Skills
+
+[Skills](/agent-platform/capabilities/skills/) are reusable instruction sets the agent can invoke to perform specific tasks. The CLI discovers the same skills as the Warp app: project skills from your repository's skill directories (such as `.agents/skills/`) and personal skills from your home directory (such as `~/.agents/skills/`), scoped to your current working directory.
+
+Run `/skills` to browse every skill in scope. Selecting a skill inserts `/skill-name ` into the input so you can add extra instructions before running it; any text after the skill name is passed along, either as [skill arguments](/agent-platform/capabilities/skills/#skill-arguments) or as additional context for the agent. You can also invoke a skill directly by typing `/` followed by its name, for example `/deploy push the latest changes to staging`.
+
+## Bundled skills
+
+The CLI ships with built-in skills that appear in the skills menu alongside your own:
+
+* **`/modify-settings`** - Updates CLI settings for you, using the bundled settings schema to find and edit the right key. See [Edit settings with the agent](#edit-settings-with-the-agent).
+* **`/tui-migrate-setup`** - Sets up the CLI from an existing Warp app installation. The agent copies compatible settings and global MCP server definitions from the desktop app, and asks for your approval before changing anything. Credentials and OAuth state are never copied, so MCP servers that require authentication prompt you to re-authenticate. Rules and skills don't need migration because both surfaces discover them from the same locations.
+
+## MCP servers
+
+[MCP servers](/agent-platform/capabilities/mcp/) extend the agent with external tools and data sources. The CLI keeps its own MCP server configuration, separate from the Warp app's, so each can run its own set of servers.
+
+Servers are defined in a JSON config file using the same `mcpServers` format as [file-based MCP servers](/agent-platform/capabilities/mcp/#file-based-mcp-servers) in the Warp app (on macOS, the file is `~/.warp_cli/.mcp.json`). Edit the file to add or remove servers; the CLI picks up changes automatically. Configured servers start automatically once you're logged in.
+
+:::note
+The CLI reads MCP servers from its global config file only. Project-scoped MCP config files in repositories are not detected. To copy global server definitions from the Warp app, use the `/tui-migrate-setup` bundled skill.
+:::
+
+### Managing servers with /mcp
+
+Type `/mcp` to open the MCP management view. The header shows the path to the config file the CLI is reading.
+
+Each configured server is listed with its transport (`stdio` or `HTTP/SSE`) and current status, including the number of tools a running server exposes.
+
+Press `Enter` on a server to start, stop, or retry it depending on its state; failed rows show the error message. Servers awaiting authentication reopen the OAuth page in your browser, and servers with saved credentials show a **Log out** row that clears them.
 
-## Keybindings
+## Related pages
 
-{/* TODO(cli-configuration): customizing keybindings. */}
+* [Rules](/agent-platform/capabilities/rules/) - Full guide to project and global rules
+* [Skills](/agent-platform/capabilities/skills/) - Authoring skills, skill arguments, and skill locations
+* [MCP servers](/agent-platform/capabilities/mcp/) - Config format, server examples, and authentication
+* [Codebase Context](/agent-platform/capabilities/codebase-context/) - Codebase indexing in the Warp app
+* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts