diff --git a/drafts/warp-cli-launch-plan.md b/drafts/warp-cli-launch-plan.md
new file mode 100644
index 00000000..5882c150
--- /dev/null
+++ b/drafts/warp-cli-launch-plan.md
@@ -0,0 +1,157 @@
+# Warp CLI launch — internal docs plan
+
+Status: planning scaffold for the Warp CLI (TUI) launch docs.
+Docs owner: Hong Yi Chen. Eng lead: Kevin Yang.
+Feature source of truth: Linear project "TUI" (linear.app/warpdotdev/project/tui-47ce492eb0d5). Milestones: Dogfood (done), **Stable = launch scope**, Fast follows (post-launch unless already Done).
+
+This file is internal planning material: do not publish it or link it from published pages. It intentionally contains Linear IDs and engineer names; **published pages must contain neither**.
+
+## Naming
+
+- Product name in docs: **Warp Agent CLI** (confirmed via the launch blog draft, 2026-07-28).
+- Body prose uses `{VARS.WARP_CLI}` (key stays `WARP_CLI`; value is "Warp Agent CLI"). Frontmatter uses the literal string — `{{TOKEN}}` substitution does not work in content-layer frontmatter (Astro parses it outside Vite), so titles/descriptions are literals.
+- UNRESOLVED: the pre-existing `WARP_AGENT_CLI` var ("Oz CLI") was reserved for renaming the Oz CLI to "Warp Agent CLI" — the TUI product now takes that name, so the Oz CLI rename plan conflicts. Needs Kevin/marketing decision before launch.
+- The command is `warp` (binary renamed from `warp-tui`, CODE-1875). It runs the Warp Agent harness (`platform/harnesses/warp-agent`).
+
+## Scope rules
+
+- Public-facing behavior only. Never mention: feature flags, dogfood/preview gating, internal crate/module names (`warp_tui`, `blocklist`, "HoA", etc.), Linear IDs, or engineer names.
+- Launch scope = Stable-milestone tickets that are Done (or verified shipped in code), plus Dogfood-milestone work. Fast-follow items are excluded unless already Done (e.g. tab completions CODE-1853 is Done — verify, then include).
+- Verify every claim against the `warpdotdev/warp` repo on `master` (`crates/warp_tui/`, `app/src/search/slash_command_menu/static_commands/commands.rs`, `specs/tui-*`, `specs/code-1822-*`) — not against Linear titles alone.
+- Cross-link canonical concept docs instead of duplicating them (skills, MCP, BYOK, model choice, handoff, profiles under `agent-platform/` and `platform/`). CLI pages document CLI-specific behavior and UI only.
+- Open-source messaging: overview gets a short "Open source" section — "we plan to open source the Warp CLI", no dates, no license commitments. Needs marketing sign-off before launch.
+
+## Skeleton
+
+New sidebar topic **Warp CLI** → `src/content/docs/cli/` (URLs under docs.warp.dev/cli/):
+
+- `cli/index.mdx` — overview + open source section
+- `cli/quickstart.mdx` — install, login, first prompt
+- `cli/agent-conversations.mdx` — transcript, tool calls, diffs, questions, tasks, planning
+- `cli/shell-commands.mdx` — shell mode, NLD, history, long-running commands
+- `cli/input-and-editing.mdx` — slash menu, completions, mouse, images, voice, vim
+- `cli/permissions-and-profiles.mdx` — approvals, auto-approve, fast-forward, profiles
+- `cli/conversations.mdx` — persistence, history, compact, resume
+- `cli/cloud-and-orchestration.mdx` — handoff, cloud resume, multi-agent
+- `cli/context.mdx` — rules/AGENTS.md, skills, MCP
+- `cli/configuration.mdx` — settings file, themes, statusline, keybindings
+- `cli/models-and-usage.mdx` — model picker, BYOK, routing, cost
+- `cli/reference.mdx` — flags, env vars, slash commands, shortcuts
+- `cli/troubleshooting.mdx` — logs, login issues, updating
+
+## Page inventory (features → tickets → reviewer)
+
+### cli/index.mdx + cli/quickstart.mdx — agent `cli-overview` — reviewer: Kevin
+- What the Warp CLI is; relationship to the Warp app and Oz; Warp Agent harness link.
+- Install + supported platforms: macOS now; Linux/Windows bundling CODE-1874 **in progress — confirm before merge**; binary bundling CODE-1803; rename CODE-1875.
+- Autoupdate CODE-1812 (managed versioned layout).
+- Login: device-auth flow, login screen (APP-4937, CODE-1860); `--api-key` / `WARP_API_KEY` for non-interactive auth; `/logout` + web sign-out (APP-4919, APP-4977).
+- Zero state (CODE-1823, CODE-1876): directory path, hints, version line.
+- Open source section (messaging only).
+- Bundled migration skill for GUI users (CODE-1872) — mention in overview "coming from the Warp app".
+
+### cli/agent-conversations.mdx — agent `cli-agent-conversations` — reviewers: harry + ian (moira for markdown)
+- Streaming transcript view (CODE-1798), markdown rendering (CODE-1849, APP-4886), mermaid (CODE-1850).
+- Tool-call rendering (CODE-1799, CODE-1815, CODE-1814), file-edit diffs (CODE-1810, CODE-1800), expand/collapse + `e` expand-all (APP-5011).
+- Thinking blocks (CODE-1801).
+- Agent questions: interactive ask-question tool (CODE-1846, CODE-1855), "(recommended)" answers (APP-5018 — in review, confirm).
+- Agent task lists (CODE-1829).
+- Planning with `/plan` (CODE-1817).
+- Selection/copy in transcript (CODE-1806, CODE-1883, APP-4994 auto-copy opt-in).
+
+### cli/shell-commands.mdx — agent `cli-shell-commands` — reviewer: Kevin (moira for manual attach)
+- Shell mode + prompt styling (CODE-1805, CODE-1892); yellow command rows (APP-4900).
+- Natural language detection: opt-in, `/natural-language-detection` toggle (CODE-1848, CODE-1893).
+- Shell command history in up-arrow menu (CODE-1906).
+- Long-running/interactive commands (CODE-1819, CODE-1838, CODE-1857): input passthrough, typed-char carryover (CODE-1895), ghost hints during LRC (CODE-1900).
+- Alt-screen/full-screen apps (CODE-1844, CODE-1922); manual attach (CODE-1915 — in progress, confirm).
+- Ctrl+C stop vs double-Ctrl+C exit (CODE-1811); exit confirmation.
+
+### cli/input-and-editing.mdx — agent `cli-input` — reviewers: Kevin + moira (ian for hints)
+- Slash command menu UI (CODE-1818); argument hints.
+- Up-arrow prompt history (CODE-1871).
+- Tab completions for shell commands (CODE-1853 — Done under Fast follows, verify shipped).
+- Mouse: selection in input (CODE-1804), inline-menu clicks (APP-5008 — in review, confirm), selection persistence (CODE-1841).
+- Attach images (CODE-1881).
+- Voice input: `/voice`, Ctrl+S, configurable keybinding (CODE-1884, APP-4988).
+- Vim mode (CODE-1926 — in review, confirm before merge).
+- Ghost-text keybinding hints (CODE-1889 + CODE-1897/1898/1899/1901).
+- Shortcuts menu (CODE-1907).
+- Soft-wrapping (CODE-1843) — mention only if user-visible behavior worth documenting.
+
+### cli/permissions-and-profiles.mdx — agent `cli-permissions` — reviewer: harry
+- Permission request cards for tool calls (CODE-1809); code-diff approval card behavior (APP-5011).
+- Default execution profile: "agent decides" for shell commands (CODE-1908).
+- Settings-file-based execution profiles (CODE-1880, APP-5021).
+- `/auto-approve` toggle.
+- Fast-forward mode (CODE-1858) + `/fast-forward` toggle & dynamic hint (APP-4901).
+- `--dangerously-skip-permissions` (APP-4992 — **backlog, confirm shipped or drop**).
+- Cross-link: agent-platform/capabilities/agent-profiles-permissions.
+
+### cli/conversations.mdx — agent `cli-conversations` — reviewer: harry
+- Conversation persistence + restore (CODE-1820, CODE-1917 diff rehydration fixed).
+- Conversation management: `/conversations` menu, left-arrow at start opens list (CODE-1821, CODE-1868).
+- `/new`, `/agent`, `/clear` (APP-5023).
+- `/compact` + styling (CODE-1919); context management.
+- Exit summary + `--resume <token>` (session exit prints resume command).
+- Multiple in-progress conversations (CODE-1845 — **backlog, confirm or drop**).
+
+### cli/cloud-and-orchestration.mdx — agent `cli-cloud-orchestration` — reviewer: harry
+- `/handoff` to cloud agents (CODE-1827); what carries over.
+- Resuming/viewing cloud conversations in the CLI (CODE-1925 public angle: continue cloud runs in the CLI; keep internal compat details out).
+- Multi-agent orchestration (CODE-1822 family): tab bar, child agents, cloud children.
+- Kill a child agent with Ctrl+C (APP-5031 — in progress, confirm).
+- Orchestration-aware hints (CODE-1901).
+- Cross-link: platform/orchestration, platform/handoff.
+
+### cli/context.mdx — agent `cli-context` — reviewers: Kevin + moira
+- Project context: AGENTS.md/rules pickup (CODE-1826); working-directory context.
+- Skills: `/skills` invoke, skills menu (CODE-1824); bundled skills: update-settings (CODE-1869), migrate-from-GUI (CODE-1872).
+- MCP: `/mcp` manage view (CODE-1825); project-scoped servers (CODE-1863 — **confirm shipped**); import/discovery (CODE-1864 — fast follow, exclude unless Done).
+- Cross-link: agent-platform/capabilities/skills, agent-platform/capabilities/mcp.
+
+### cli/configuration.mdx — agent `cli-configuration` — reviewers: Kevin + moira
+- TOML settings file (CODE-1802): location, local-only (never cloud-synced — settings mode is TUI-specific), schema pointers.
+- Edit settings by asking the agent (bundled skill CODE-1869).
+- Themes: `/theme` auto|light|dark (CODE-1916), terminal-background detection (CODE-1807), live refresh (CODE-1909 — in review, confirm).
+- Statusline: V2 (CODE-1890) + `/statusline` customization (CODE-1891 — in review, confirm).
+- Keybindings: customization support; cmd-modified keys (CODE-1920 — backlog, likely drop).
+
+### cli/models-and-usage.mdx — agent `cli-reference` (bundle) — reviewers: harry + ian + moira
+- `/model` picker; footer model click (APP-4908); per-profile default model (APP-4916 fixed behavior).
+- BYOK: `/add-api-key`, `/clear-provider-api-key`, `--set-provider-api-key`, `--clear-provider-api-key` (CODE-1923); Grok (APP-5024 — in review, confirm); no-credit-charge behavior when BYOK active.
+- Custom model routing (CODE-1914 — in progress, confirm or drop).
+- Cost transparency (CODE-1828): footer credits + click-to-toggle (CODE-1831), `/cost` (APP-4924), last-response duration + credits (CODE-1832).
+- Cross-link: agent-platform/inference/* pages.
+
+### cli/reference.mdx — agent `cli-reference` — reviewers: harry + Kevin
+- Flags (from `crates/warp_tui/src/session.rs`): `--resume`, `--api-key` (env `WARP_API_KEY`), `--set-provider-api-key`, `--clear-provider-api-key`, `--version`, `--help`.
+- `--list-models`, headless run (APP-4993, CODE-1924 — **not shipped, exclude unless landed**).
+- Slash command table — source: `static_commands/commands.rs`, include only `TuiOnly` + `GuiAndTui` commands actually reachable in the CLI. Currently: /agent, /new, /clear, /plan, /compact, /model, /cost, /conversations, /skills, /handoff, /export-to-clipboard, /export-to-file, /create-new-project, /theme, /statusline, /auto-approve, /natural-language-detection, /mcp, /add-api-key, /clear-provider-api-key, /voice, /view-logs, /version, /logout, /exit. Confirm at write time: /status (APP-4973), /copy-debugging-link (APP-5030), /fast-forward (APP-4901), /pr-comments display (CODE-1918).
+- Keyboard shortcuts table (shortcuts menu CODE-1907 as source).
+
+### cli/troubleshooting.mdx — agent `cli-reference` — reviewers: harry + Kevin
+- `/view-logs` bundle (CODE-1882); log locations (CODE-1902).
+- `/copy-debugging-link` (APP-5030 — in progress, confirm).
+- Login troubleshooting (device-auth issues); `/version`; updating (autoupdate CODE-1812).
+- Sending feedback; link to support pages.
+
+## Reviewer map (summary)
+
+- **Kevin Yang** — overview/install/login/autoupdate, shell & NLD & long-running commands, MCP & project context, settings file & themes, vim mode, images, shortcuts menu.
+- **harry** — permissions/profiles/fast-forward, conversations/resume, handoff & orchestration, BYOK, transcript/tool calls/diffs, logs & troubleshooting.
+- **moira** — slash command UI, skills, planning, markdown/mermaid, statusline, custom routing, tab completions, login/logout UX, /cost /logout.
+- **ian** — agent questions, task lists, cost transparency, keybinding hints.
+
+## Workflow
+
+- Base branch: `hyc/launch-cli` (this skeleton). One agent per page bundle, branch `hyc/launch-cli-<name>`, git worktree, PR into `hyc/launch-cli`.
+- Each PR body lists: pages, features covered, dropped "confirm" items with reasons, and the suggested eng reviewer (Hong Yi tags them).
+- Validation per PR: `npm run build` green.
+- Launch: single PR `hyc/launch-cli` → `main`, timed with the release.
+
+## Open questions
+
+- Final name: "Warp CLI" vs "Warp Agent CLI" (and the `WARP_AGENT_CLI` var collision with the Oz CLI rename).
+- Distribution/install channels (brew? curl script? winget?) and Linux/Windows timing — need Kevin's confirmation.
+- Screenshot/asciinema pass: do after content lands; assets go to `src/assets/cli/`.
diff --git a/src/content/docs/cli/agent-conversations.mdx b/src/content/docs/cli/agent-conversations.mdx
new file mode 100644
index 00000000..76bd0dc9
--- /dev/null
+++ b/src/content/docs/cli/agent-conversations.mdx
@@ -0,0 +1,43 @@
+---
+title: "Agent conversations in the {{WARP_CLI}}"
+description: >-
+  How agent conversations work in the {{WARP_CLI}}: streaming responses, tool
+  calls, code diffs, agent questions, task lists, and planning.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-agent-conversations): draft per drafts/warp-cli-launch-plan.md — "cli/agent-conversations.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## The conversation transcript
+
+{/* TODO(cli-agent-conversations): streaming responses, markdown and Mermaid rendering, scrolling. */}
+
+## Tool calls
+
+{/* TODO(cli-agent-conversations): how tool calls render (commands, file reads, etc.), expand/collapse. */}
+
+## Code diffs
+
+{/* TODO(cli-agent-conversations): file-edit diffs, expanded by default, `e` to expand/collapse all. */}
+
+## Thinking blocks
+
+{/* TODO(cli-agent-conversations): collapsed reasoning blocks. */}
+
+## Agent questions
+
+{/* TODO(cli-agent-conversations): interactive question prompts, option selection, recommended answers. */}
+
+## Task lists
+
+{/* TODO(cli-agent-conversations): agent task list rendering and progress. */}
+
+## Planning
+
+{/* TODO(cli-agent-conversations): /plan command and plan review flow; cross-link agent-platform/capabilities/planning. */}
+
+## Selecting and copying output
+
+{/* TODO(cli-agent-conversations): transcript selection, copy behavior, opt-in auto-copy on select. */}
diff --git a/src/content/docs/cli/cloud-and-orchestration.mdx b/src/content/docs/cli/cloud-and-orchestration.mdx
new file mode 100644
index 00000000..70107975
--- /dev/null
+++ b/src/content/docs/cli/cloud-and-orchestration.mdx
@@ -0,0 +1,27 @@
+---
+title: "Cloud handoff and orchestration in the {{WARP_CLI}}"
+description: >-
+  Hand off {{WARP_CLI}} conversations to cloud agents, resume cloud runs, and
+  run multi-agent orchestration from your terminal.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-cloud-orchestration): draft per drafts/warp-cli-launch-plan.md — "cli/cloud-and-orchestration.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Hand off to a cloud agent
+
+{/* TODO(cli-cloud-orchestration): /handoff flow, what context carries over; cross-link platform/handoff. */}
+
+## Resume cloud conversations
+
+{/* TODO(cli-cloud-orchestration): continuing cloud runs in the CLI (--resume, conversation list). */}
+
+## Multi-agent orchestration
+
+{/* TODO(cli-cloud-orchestration): orchestrating child agents from the CLI, tab bar navigation; cross-link platform/orchestration. */}
+
+## Managing child agents
+
+{/* TODO(cli-cloud-orchestration): switching between child agents, stopping a child agent. */}
diff --git a/src/content/docs/cli/configuration.mdx b/src/content/docs/cli/configuration.mdx
new file mode 100644
index 00000000..b83640bf
--- /dev/null
+++ b/src/content/docs/cli/configuration.mdx
@@ -0,0 +1,31 @@
+---
+title: "Configuring the {{WARP_CLI}}"
+description: >-
+  Configure the {{WARP_CLI}} with its TOML settings file, themes, statusline,
+  and keybindings.
+---
+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 settings file
+
+{/* TODO(cli-configuration): TOML settings file location and behavior; settings are local to the CLI and not synced. */}
+
+## Edit settings with the agent
+
+{/* TODO(cli-configuration): asking the agent to update settings via the bundled skill. */}
+
+## Themes
+
+{/* TODO(cli-configuration): /theme auto|light|dark, terminal background detection. */}
+
+## Statusline
+
+{/* TODO(cli-configuration): statusline contents and /statusline customization — confirm shipped before merge. */}
+
+## Keybindings
+
+{/* TODO(cli-configuration): customizing keybindings. */}
diff --git a/src/content/docs/cli/context.mdx b/src/content/docs/cli/context.mdx
new file mode 100644
index 00000000..2b6fbd89
--- /dev/null
+++ b/src/content/docs/cli/context.mdx
@@ -0,0 +1,27 @@
+---
+title: "Agent context in the Warp Agent CLI: rules, skills, and MCP"
+description: >-
+  Give the Warp Agent CLI agent context with project rules (AGENTS.md), skills,
+  and MCP servers.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-context): draft per drafts/warp-cli-launch-plan.md — "cli/context.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Project context and rules
+
+{/* TODO(cli-context): AGENTS.md/rules pickup, working-directory context; cross-link agent-platform/capabilities/rules. */}
+
+## Skills
+
+{/* TODO(cli-context): /skills invocation and skills menu; cross-link agent-platform/capabilities/skills. */}
+
+## Bundled skills
+
+{/* TODO(cli-context): built-in skills (updating settings, migrating from the Warp app). */}
+
+## MCP servers
+
+{/* TODO(cli-context): /mcp management view, configuring servers; cross-link agent-platform/capabilities/mcp. */}
diff --git a/src/content/docs/cli/conversations.mdx b/src/content/docs/cli/conversations.mdx
new file mode 100644
index 00000000..88e23ec4
--- /dev/null
+++ b/src/content/docs/cli/conversations.mdx
@@ -0,0 +1,31 @@
+---
+title: "Managing conversations in the Warp Agent CLI"
+description: >-
+  Start, switch, compact, and resume agent conversations in the Warp Agent CLI,
+  including conversation history and the --resume flag.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-conversations): draft per drafts/warp-cli-launch-plan.md — "cli/conversations.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Conversation persistence
+
+{/* TODO(cli-conversations): conversations persist across sessions and restore with full detail. */}
+
+## Starting a new conversation
+
+{/* TODO(cli-conversations): /new, /agent, /clear. */}
+
+## Conversation history
+
+{/* TODO(cli-conversations): /conversations menu and navigation into past conversations. */}
+
+## Compacting context
+
+{/* TODO(cli-conversations): /compact, when to use it, what the summary block looks like. */}
+
+## Resuming conversations
+
+{/* TODO(cli-conversations): exit summary with resume command; `--resume` flag. */}
diff --git a/src/content/docs/cli/index.mdx b/src/content/docs/cli/index.mdx
new file mode 100644
index 00000000..5688a9d7
--- /dev/null
+++ b/src/content/docs/cli/index.mdx
@@ -0,0 +1,35 @@
+---
+title: "{{WARP_CLI}} overview"
+description: >-
+  The {{WARP_CLI}} brings Warp's agent to any terminal. Learn what the CLI
+  does, how it relates to the Warp app and Oz, and how to get started.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-overview): draft per drafts/warp-cli-launch-plan.md — "cli/index.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## What is the {VARS.WARP_CLI}?
+
+{/* TODO(cli-overview): what it is (agent in any terminal, `warp` command), also referred to as the Warp Agent CLI. */}
+
+## Key features
+
+{/* TODO(cli-overview): bulleted key features list (bold term - dash - description). */}
+
+## How it relates to the Warp app and Oz
+
+{/* TODO(cli-overview): CLI vs Warp app vs Oz platform; Warp Agent harness cross-link. */}
+
+## Supported platforms
+
+{/* TODO(cli-overview): confirm platform availability with eng before merge. */}
+
+## Open source
+
+{/* TODO(cli-overview): planned open-sourcing messaging; no dates or license commitments. */}
+
+## Next steps
+
+{/* TODO(cli-overview): links to quickstart and feature pages. */}
diff --git a/src/content/docs/cli/input-and-editing.mdx b/src/content/docs/cli/input-and-editing.mdx
new file mode 100644
index 00000000..0269b281
--- /dev/null
+++ b/src/content/docs/cli/input-and-editing.mdx
@@ -0,0 +1,47 @@
+---
+title: "Input and editing in the {{WARP_CLI}}"
+description: >-
+  The {{WARP_CLI}} input editor: slash commands, history, completions, mouse
+  support, images, voice input, and Vim mode.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-input): draft per drafts/warp-cli-launch-plan.md — "cli/input-and-editing.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Slash commands
+
+{/* TODO(cli-input): slash command menu, filtering, argument hints; link to reference page for the full table. */}
+
+## Prompt history
+
+{/* TODO(cli-input): up-arrow history for prompts and shell commands. */}
+
+## Tab completions
+
+{/* TODO(cli-input): completions for shell commands — confirm shipped before merge. */}
+
+## Mouse support
+
+{/* TODO(cli-input): text selection in the input, clicking inline menu rows, selection persistence. */}
+
+## Selection and clipboard
+
+{/* TODO(cli-input): copying, opt-in auto-copy of highlighted input text. */}
+
+## Attach images
+
+{/* TODO(cli-input): attaching images as context. */}
+
+## Voice input
+
+{/* TODO(cli-input): /voice, `Ctrl+S`, configurable keybinding; cross-link voice docs. */}
+
+## Vim mode
+
+{/* TODO(cli-input): vim input mode — confirm shipped before merge. */}
+
+## Keyboard hints and the shortcuts menu
+
+{/* TODO(cli-input): ghost-text hints in the input, shortcuts menu. */}
diff --git a/src/content/docs/cli/models-and-usage.mdx b/src/content/docs/cli/models-and-usage.mdx
new file mode 100644
index 00000000..0e0511a3
--- /dev/null
+++ b/src/content/docs/cli/models-and-usage.mdx
@@ -0,0 +1,27 @@
+---
+title: "Models and usage in the {{WARP_CLI}}"
+description: >-
+  Choose models in the {{WARP_CLI}}, bring your own API key, and track credit
+  usage and per-response cost.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/models-and-usage.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Choosing a model
+
+{/* TODO(cli-reference): /model picker, footer model entry; cross-link agent-platform/inference/model-choice. */}
+
+## Bring your own API key
+
+{/* TODO(cli-reference): /add-api-key, /clear-provider-api-key, --set-provider-api-key, --clear-provider-api-key; supported providers; cross-link agent-platform/inference/bring-your-own-api-key. */}
+
+## Custom model routing
+
+{/* TODO(cli-reference): custom routers in the CLI — confirm shipped before merge; cross-link agent-platform/inference/custom-routers. */}
+
+## Usage and cost
+
+{/* TODO(cli-reference): footer credits entry, /cost toggle, last-response duration and credits. */}
diff --git a/src/content/docs/cli/permissions-and-profiles.mdx b/src/content/docs/cli/permissions-and-profiles.mdx
new file mode 100644
index 00000000..0d68e0cf
--- /dev/null
+++ b/src/content/docs/cli/permissions-and-profiles.mdx
@@ -0,0 +1,35 @@
+---
+title: "Permissions and profiles in the {{WARP_CLI}}"
+description: >-
+  Control what the agent can do in the {{WARP_CLI}}: permission requests,
+  auto-approve, fast-forward mode, and execution profiles.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-permissions): draft per drafts/warp-cli-launch-plan.md — "cli/permissions-and-profiles.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## How permissions work
+
+{/* TODO(cli-permissions): permission model summary; default behavior; cross-link agent-platform/capabilities/agent-profiles-permissions. */}
+
+## Approving agent actions
+
+{/* TODO(cli-permissions): permission request cards, command edit/escape behavior, diff approval. */}
+
+## Auto-approve
+
+{/* TODO(cli-permissions): /auto-approve toggle and when to use it. */}
+
+## Fast-forward mode
+
+{/* TODO(cli-permissions): fast-forward mode and /fast-forward toggle. */}
+
+## Execution profiles
+
+{/* TODO(cli-permissions): settings-file-based execution profiles and defaults. */}
+
+## Unattended use
+
+{/* TODO(cli-permissions): flags for skipping permissions — confirm shipped before merge; include safety caution. */}
diff --git a/src/content/docs/cli/quickstart.mdx b/src/content/docs/cli/quickstart.mdx
new file mode 100644
index 00000000..732a02c7
--- /dev/null
+++ b/src/content/docs/cli/quickstart.mdx
@@ -0,0 +1,39 @@
+---
+title: "{{WARP_CLI}} quickstart"
+description: >-
+  Install the {{WARP_CLI}}, log in, and run your first agent conversation in
+  your own terminal in a few minutes.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-overview): draft per drafts/warp-cli-launch-plan.md — "cli/quickstart.mdx" section. Quickstart content type (~10 min to working result). */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Prerequisites
+
+{/* TODO(cli-overview): minimal prerequisites (Warp account). */}
+
+## Install the {VARS.WARP_CLI}
+
+{/* TODO(cli-overview): install command(s) — confirm distribution channels with eng before merge. */}
+
+## Log in
+
+{/* TODO(cli-overview): device-auth login flow; `--api-key` / `WARP_API_KEY` alternative for non-interactive auth. */}
+
+## Run your first prompt
+
+{/* TODO(cli-overview): first agent prompt; what the zero state shows. */}
+
+## Run a shell command
+
+{/* TODO(cli-overview): shell input alongside agent prompts. */}
+
+## Exit and resume
+
+{/* TODO(cli-overview): double Ctrl+C to exit; resume command printed on exit. */}
+
+## Next steps
+
+{/* TODO(cli-overview): links to agent conversations, configuration, reference. */}
diff --git a/src/content/docs/cli/reference.mdx b/src/content/docs/cli/reference.mdx
new file mode 100644
index 00000000..b59d26d0
--- /dev/null
+++ b/src/content/docs/cli/reference.mdx
@@ -0,0 +1,27 @@
+---
+title: "{{WARP_CLI}} reference"
+description: >-
+  Reference for the {{WARP_CLI}}: command-line flags, environment variables,
+  slash commands, and keyboard shortcuts.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/reference.mdx" section. Reference content type (exhaustive, lookup-oriented). */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Command-line flags
+
+{/* TODO(cli-reference): warp [flags] — --resume, --api-key, --set-provider-api-key, --clear-provider-api-key, --version, --help; one example per flag. */}
+
+## Environment variables
+
+{/* TODO(cli-reference): WARP_API_KEY and any other public env vars. */}
+
+## Slash commands
+
+{/* TODO(cli-reference): full table of slash commands available in the CLI with descriptions and arguments. */}
+
+## Keyboard shortcuts
+
+{/* TODO(cli-reference): default shortcuts (source: the in-app shortcuts menu). */}
diff --git a/src/content/docs/cli/shell-commands.mdx b/src/content/docs/cli/shell-commands.mdx
new file mode 100644
index 00000000..1e4f9ce3
--- /dev/null
+++ b/src/content/docs/cli/shell-commands.mdx
@@ -0,0 +1,35 @@
+---
+title: "Running shell commands in the Warp Agent CLI"
+description: >-
+  Run shell commands directly in the Warp Agent CLI, including interactive and
+  long-running commands, full-screen apps, and natural language detection.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-shell-commands): draft per drafts/warp-cli-launch-plan.md — "cli/shell-commands.mdx" section. Feature-doc content type. */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Shell mode
+
+{/* TODO(cli-shell-commands): entering shell commands vs agent prompts; command row styling. */}
+
+## Natural language detection
+
+{/* TODO(cli-shell-commands): opt-in NLD, /natural-language-detection toggle. */}
+
+## Command history
+
+{/* TODO(cli-shell-commands): shell commands in the up-arrow history menu. */}
+
+## Long-running and interactive commands
+
+{/* TODO(cli-shell-commands): interactive input passthrough, typed-character carryover, hints during execution. */}
+
+## Full-screen terminal apps
+
+{/* TODO(cli-shell-commands): alt-screen apps (editors, pagers, TUIs) support. */}
+
+## Stopping commands and exiting
+
+{/* TODO(cli-shell-commands): Ctrl+C to stop, double Ctrl+C to exit. */}
diff --git a/src/content/docs/cli/troubleshooting.mdx b/src/content/docs/cli/troubleshooting.mdx
new file mode 100644
index 00000000..23c332e7
--- /dev/null
+++ b/src/content/docs/cli/troubleshooting.mdx
@@ -0,0 +1,27 @@
+---
+title: "Troubleshooting the Warp Agent CLI"
+description: >-
+  Fix common Warp Agent CLI issues: gather logs, resolve login problems, and
+  update to the latest version.
+---
+import { VARS } from '@data/vars';
+
+{/* TODO(cli-reference): draft per drafts/warp-cli-launch-plan.md — "cli/troubleshooting.mdx" section. Troubleshooting content type (problem → cause → solution). */}
+
+The {VARS.WARP_CLI} documentation for this page is in progress.
+
+## Viewing and sharing logs
+
+{/* TODO(cli-reference): /view-logs bundle, log file locations, sharing a debugging link if shipped. */}
+
+## Login issues
+
+{/* TODO(cli-reference): device-auth problems and solutions; /logout and re-login. */}
+
+## Updating
+
+{/* TODO(cli-reference): how autoupdate works, checking the version with /version and --version. */}
+
+## Getting help
+
+{/* TODO(cli-reference): feedback and support channels; link to support-and-community pages. */}
diff --git a/src/data/vars.ts b/src/data/vars.ts
index a9447ff4..0df1f6e0 100644
--- a/src/data/vars.ts
+++ b/src/data/vars.ts
@@ -15,6 +15,12 @@ export const VARS = {
   DASHBOARD:                "Oz dashboard",   // future name TBD
   PLATFORM_RUN:             "Oz run",         // future name TBD
 
+  // Warp Agent CLI — the standalone terminal front-end (the `warp` binary).
+  // Launch name confirmed via the launch blog draft (2026-07-28). NOTE: the
+  // WARP_AGENT_CLI key above was reserved for renaming the Oz CLI to the
+  // same name — that overlap now needs a product/marketing decision.
+  WARP_CLI:                 "Warp Agent CLI",
+
   // Feature names (stable — keys and values expected to remain unchanged)
   AGENT_MODE:               "Agent Mode",
   WARP_DRIVE:               "Warp Drive",
diff --git a/src/sidebar.ts b/src/sidebar.ts
index 565d4e16..9ae5200b 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -333,6 +333,41 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 				},
 			],
 		},
+		{
+			label: 'Warp Agent CLI',
+			link: '/cli/',
+			icon: 'seti:shell',
+			items: [
+				{ slug: 'cli', label: 'Overview' },
+				{ slug: 'cli/quickstart', label: 'Quickstart' },
+				{
+					label: 'Using the agent',
+					items: [
+						{ slug: 'cli/agent-conversations', label: 'Agent conversations' },
+						{ slug: 'cli/shell-commands', label: 'Shell commands' },
+						{ slug: 'cli/input-and-editing', label: 'Input & editing' },
+						{ slug: 'cli/permissions-and-profiles', label: 'Permissions & profiles' },
+						{ slug: 'cli/conversations', label: 'Managing conversations' },
+						{ slug: 'cli/cloud-and-orchestration', label: 'Cloud & orchestration' },
+					],
+				},
+				{
+					label: 'Context & customization',
+					items: [
+						{ slug: 'cli/context', label: 'Rules, skills, & MCP' },
+						{ slug: 'cli/configuration', label: 'Configuration' },
+						{ slug: 'cli/models-and-usage', label: 'Models & usage' },
+					],
+				},
+				{
+					label: 'Reference',
+					items: [
+						{ slug: 'cli/reference', label: 'CLI reference' },
+						{ slug: 'cli/troubleshooting', label: 'Troubleshooting' },
+					],
+				},
+			],
+		},
 		{
 			label: 'Oz',
 			link: '/platform/',