docs: consolidate the Warp Agent CLI docs into the Agents section

.agents/references/terminology.md

@@ -135,6 +135,8 @@ For the summary of the most critical terms (core features, Oz terms, terms to av
 ### Warp Agent vs Oz
 
 - **Warp Agent** — Warp's built-in agent harness. Use "Warp Agent" when specifically referring to the built-in harness, especially when contrasting with third-party agents (Claude Code, Codex, etc.), or when referencing the Settings label (**Settings** > **Agents** > **Warp Agent**).
+- **Warp Agent CLI** — The standalone terminal program (the `warp` binary) that runs the Warp Agent in any terminal, including over SSH and on machines without the Warp app. Documented at `/agents/cli/`.
+  *Usage note:* Distinct from the Oz CLI (the `oz` binary), which runs and manages cloud agents. At the next launch (approximately August 18, 2026) the Oz CLI is retired and wrapped into the Warp Agent CLI, leaving a single CLI under this name. Until that ships, keep the two clearly separate in prose; afterwards, "Warp Agent CLI" covers both.
 - **Oz** — Warp's programmable platform for running and coordinating agents at scale
 - There is typically one Warp environment per user session. Oz can run many agents concurrently, across machines, repos, and teams.
 
@@ -209,7 +211,7 @@ For the summary of the most critical terms (core features, Oz terms, terms to av
 
 - **Trigger** — The event that starts a run (Slack mention, schedule, CI event, API call).
 
-- **Warp CLI** — The command-line tool for running and managing Warp Platform workflows. Formerly called `warp-cli`, now `oz`.
+- **Warp CLI** — Ambiguous since the Warp Agent CLI launched; avoid the bare term. Use "Oz CLI" for the `oz` binary that runs and manages cloud agents (formerly called `warp-cli`), or "Warp Agent CLI" for the `warp` binary that runs the Warp Agent in any terminal.
 
 ## Technical terms
 

.agents/skills/style_lint/style_lint.py

@@ -108,7 +108,22 @@
 
 TERMINOLOGY_FILE = Path(".agents/references/terminology.md")
 
-STANDARD_SCREENSHOT_WIDTHS = {"300px", "350px", "375px", "563px"}
+# Standard figure widths for screenshots. See AGENTS.md § "Screenshot sizing
+# standards".
+#
+# 736px is full content width: it matches `.main-pane .sl-container`'s
+# `max-width: 46rem` in src/styles/custom.css. Because the container already
+# caps at that width, 736px renders identically to omitting maxWidth entirely.
+# It is listed explicitly so authors can signal "this screenshot is
+# deliberately full width" and so this check can tell that apart from a figure
+# that is simply missing a width. If the content column in custom.css ever
+# changes, update this value to match.
+STANDARD_SCREENSHOT_WIDTHS = {"300px", "350px", "375px", "563px", "736px"}
+
+# Rendered as "300px, 350px, 375px, 563px, or 736px" in check messages, derived
+# from the set above so the two can never drift apart.
+_SORTED_WIDTHS = sorted(STANDARD_SCREENSHOT_WIDTHS)
+STANDARD_WIDTHS_PHRASE = f"{', '.join(_SORTED_WIDTHS[:-1])}, or {_SORTED_WIDTHS[-1]}"
 
 SCREENSHOT_PATH_HINTS = (
     "/assets/",
@@ -556,7 +571,7 @@ def check_screenshot_widths(lines: List[str], filepath: str) -> List[Issue]:
             if figure_start_line is None:
                 issues.append(Issue(
                     filepath, i, "screenshot-width",
-                    "Likely screenshot image should be wrapped in a <figure> with a standard maxWidth (300px, 350px, 375px, or 563px)",
+                    f"Likely screenshot image should be wrapped in a <figure> with a standard maxWidth ({STANDARD_WIDTHS_PHRASE})",
                     "warning",
                 ))
             else:
@@ -568,13 +583,13 @@ def check_screenshot_widths(lines: List[str], filepath: str) -> List[Issue]:
                 if width is None:
                     issues.append(Issue(
                         filepath, figure_start_line, "screenshot-width",
-                        "Screenshot figure is missing a standard maxWidth (300px, 350px, 375px, or 563px)",
+                        f"Screenshot figure is missing a standard maxWidth ({STANDARD_WIDTHS_PHRASE})",
                         "warning",
                     ))
                 elif width not in STANDARD_SCREENSHOT_WIDTHS:
                     issues.append(Issue(
                         filepath, figure_start_line, "screenshot-width",
-                        f"Screenshot figure uses non-standard maxWidth \"{width}\"; use one of {', '.join(sorted(STANDARD_SCREENSHOT_WIDTHS))}",
+                        f"Screenshot figure uses non-standard maxWidth \"{width}\"; use one of {STANDARD_WIDTHS_PHRASE}",
                         "warning",
                     ))
             figure_start_line = None

AGENTS.md

@@ -228,15 +228,17 @@ Use screenshots to clarify product surfaces, configuration points, or visual sta
 Use consistent screenshot widths so docs pages feel visually balanced. Crop unnecessary empty space before resizing, then choose the closest standard size.
 
 **Standard widths:**
-- **Large screenshots: default content width** — Use normal `<figure>` or Markdown image rendering for full-window, full-pane, or broad product-surface screenshots where the surrounding layout matters. In legacy GitBook screenshots, this was usually `563px`.
+- **Full content width: 736px** — Use for wide screenshots whose content cannot be cropped narrower without clipping, such as full-width terminal strips, wide status bars, and wide tables. `736px` equals the content column (`46rem`, set on `.main-pane .sl-container` in `src/styles/custom.css`), so it renders the same as omitting `maxWidth`. Set it explicitly anyway: it records that the width is deliberate rather than forgotten, and the style lint treats a missing width as an error. Reach for this tier only when a narrower size would make text illegible.
+- **Large screenshots: 563px** — The default for full-window, full-pane, or broad product-surface screenshots where the surrounding layout matters. This was the usual width in legacy GitBook screenshots. Prefer this over `736px` unless the content genuinely needs the extra room.
 - **Medium screenshots: ~375px** — Use for narrow UI surfaces such as popovers, command menus, side panes, dropdowns, and focused interaction flows. This is the preferred constrained size for most small Warp UI screenshots.
 - **Small screenshots: ~300-350px** — Use for tightly cropped controls, chips, buttons, tooltips, and small menus. Use a smaller width only when the UI remains legible and the crop is intentionally compact.
 
 **Rules:**
 - **Avoid arbitrary widths** — Choose the nearest standard size instead of one-off values. If a screenshot needs a different size, the reason should be clear from the UI being shown.
 - **Keep sequences consistent** — Screenshots in the same section or step sequence should use the same width unless they show meaningfully different UI surfaces.
-- **Preserve legibility** — Text in the screenshot must remain readable at the chosen size on the docs page.
-- **Prefer the default figure size for large screenshots** — Only constrain width when the screenshot is a narrow UI element that looks oversized at full content width.
+- **Preserve legibility** — Text in the screenshot must remain readable at the chosen size on the docs page. This rule outranks the preference for a smaller tier: if text is unreadable at `563px`, move up to `736px` rather than shipping an illegible image.
+- **Crop before widening** — Widening is the last resort. First crop out empty space and anything that is not the subject, and re-capture at a narrower terminal or window size if you can. Only step up a tier when the content itself sets the floor, as with a status bar that clips instead of reflowing.
+- **Prefer the default figure size for large screenshots** — Only constrain width below `563px` when the screenshot is a narrow UI element that looks oversized at full content width.
 
 #### Image caption guidelines
 Captions orient the reader — they identify what the image shows so the reader knows where to look. They are not a place for instructions, marketing language, or exhaustive descriptions.

astro.config.mjs

@@ -167,7 +167,7 @@ export default defineConfig({
 					customSets: [
 						{ label: 'Terminal', description: 'Warp Terminal features and configuration.', paths: ['terminal/**'] },
 						{ label: 'Agents', description: 'Warp\'s agents: capabilities, local agents, and CLI agents.', paths: ['agents/**'] },
-						{ label: 'Warp Agent CLI', description: 'The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal.', paths: ['cli/**'] },
+						{ label: 'Warp Agent CLI', description: 'The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal.', paths: ['agents/cli/**'] },
 						{ label: 'Oz Platform', description: 'Warp\'s Oz platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] },
 						{ label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] },
 						{ label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] },

src/content/docs/agents/cli-agents/overview.mdx

@@ -11,6 +11,8 @@ Warp auto-detects supported CLI agents and enhances them with IDE-level features
 
 This feature set is also known as **universal agent support**.
 
+Looking for Warp's own CLI instead? The [Warp Agent CLI](/agents/cli/) runs the Warp Agent itself in any terminal. This page covers running third-party coding agents inside the Warp app.
+
 :::note
 Claude Code and Codex are also supported as harnesses in Oz for cloud orchestration. See [Harnesses in Oz](/platform/harnesses/).
 :::

src/content/docs/cli/agent-conversations.mdx → src/content/docs/agents/cli/agent-conversations.mdx

@@ -20,12 +20,12 @@ Every tool call the agent makes appears inline in the transcript, in the order i
 
 Some tool calls render richer, interactive content:
 
-* **[Shell commands](/cli/input-and-shell-commands/#shell-mode)** - Commands run in your session, with output streamed into the transcript.
+* **[Shell commands](/agents/cli/input-and-shell-commands/#shell-mode)** - Commands run in your session, with output streamed into the transcript.
 * **[File edits](#code-diffs)** - Expandable diffs with per-file headers.
 * **[Questions](#agent-questions)** - Interactive option prompts.
 * **[Plans](#planning)** - Inline plan documents.
 
-When a tool call needs your approval before it runs, an approval card appears in place of the input. See [permissions in the CLI](/cli/permissions-and-profiles/) to learn how approvals work.
+When a tool call needs your approval before it runs, an approval card appears in place of the input. See [permissions in the CLI](/agents/cli/permissions-and-profiles/) to learn how approvals work.
 
 ## Code diffs
 
@@ -109,7 +109,7 @@ The menu lists your Warp Agent conversations, including conversations started in
 If the CLI can't load conversation data from Warp's servers, the menu shows conversations from your local device only and displays a warning. Conversations from other devices reappear once the connection recovers.
 :::
 
-To continue a cloud agent run from the CLI, or to hand the current conversation off to a cloud agent, see [cloud handoff and orchestration](/cli/cloud-and-orchestration/).
+To continue a cloud agent run from the CLI, or to hand the current conversation off to a cloud agent, see [cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/).
 
 ### Resuming conversations
 
@@ -125,7 +125,7 @@ To continue this conversation, run:
 warp --resume YOUR_CONVERSATION_TOKEN
 ```
 
-`YOUR_CONVERSATION_TOKEN` is a conversation identifier generated by Warp. For the complete list of command-line flags, see the [CLI reference](/cli/reference/).
+`YOUR_CONVERSATION_TOKEN` is a conversation identifier generated by Warp. For the complete list of command-line flags, see the [CLI reference](/agents/cli/reference/).
 
 ### Compacting context
 
@@ -138,9 +138,9 @@ After compaction, a collapsed **Conversation summary** block appears in the tran
 
 ## Related pages
 
-* [Permissions and profiles](/cli/permissions-and-profiles/) - Approve, reject, or auto-approve the agent's tool calls.
-* [Input and shell commands](/cli/input-and-shell-commands/) - How commands the agent (or you) run appear in the transcript.
-* [Cloud handoff and orchestration](/cli/cloud-and-orchestration/) - Hand off conversations to cloud agents and resume cloud runs.
-* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts.
+* [Permissions and profiles](/agents/cli/permissions-and-profiles/) - Approve, reject, or auto-approve the agent's tool calls.
+* [Input and shell commands](/agents/cli/input-and-shell-commands/) - How commands the agent (or you) run appear in the transcript.
+* [Cloud handoff and orchestration](/agents/cli/cloud-and-orchestration/) - Hand off conversations to cloud agents and resume cloud runs.
+* [{VARS.WARP_CLI} reference](/agents/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts.
 * [Planning](/agents/capabilities/planning/) - The full planning workflow.
 * [Task lists](/agents/capabilities/task-lists/) - How agents create and update task lists.

src/content/docs/cli/cloud-and-orchestration.mdx → src/content/docs/agents/cli/cloud-and-orchestration.mdx

@@ -53,7 +53,7 @@ Resuming in the CLI has two constraints:
 * **The run must be finished** - Cloud runs that are still in progress or blocked can't be opened in the CLI.
 * **Warp Agent runs only** - Conversations that ran with a different harness, such as Claude Code or Codex, can't be opened in the CLI.
 
-You can also open a conversation directly at startup with `warp --resume <token>`. See [managing conversations in the CLI](/cli/agent-conversations/#managing-conversations) to learn more about conversation history and resume details.
+You can also open a conversation directly at startup with `warp --resume <token>`. See [managing conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) to learn more about conversation history and resume details.
 
 ## Multi-agent orchestration
 
@@ -65,7 +65,7 @@ You can also shape the configuration in your prompt. For example, ask for a spec
 
 When the agent decides to spawn child agents, the CLI shows an approval card titled **Can I start additional agents for this task?** that summarizes the agents it wants to launch and the run-wide configuration.
 
-By default, no child agents launch until you approve. The **Run orchestrated agents** permission in your profile controls this: **Always allow** skips the approval card, and **Never** blocks child agents entirely. See [Permissions and profiles](/cli/permissions-and-profiles/).
+By default, no child agents launch until you approve. The **Run orchestrated agents** permission in your profile controls this: **Always allow** skips the approval card, and **Never** blocks child agents entirely. See [Permissions and profiles](/agents/cli/permissions-and-profiles/).
 
 From the approval card:
 
@@ -75,8 +75,8 @@ From the approval card:
 
 After launch, a tab bar labeled **Agents:** appears above the session with one tab for the orchestrator and one tab per child agent. Messages between the parent and child agents appear in each agent's transcript.
 
-<figure>
-![The Agents: tab bar in the Warp Agent CLI, showing the orchestrator tab and three child agent tabs with status glyphs](../../../assets/cli/tui-agents-tab-bar.png)
+<figure style={{ maxWidth: "563px" }}>
+![The Agents: tab bar in the Warp Agent CLI, showing the orchestrator tab and three child agent tabs with status glyphs](../../../../assets/agents/cli/tui-agents-tab-bar.png)
 <figcaption>The Agents: tab bar with one child agent running and two finished.</figcaption>
 </figure>
 
@@ -116,5 +116,5 @@ In the orchestrator's own session, `Ctrl+C` keeps its usual behavior.
 * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Prerequisites, the Warp app flow, and troubleshooting.
 * [Multi-agent orchestration](/platform/orchestration/) - The parent/child model, run states, and orchestration patterns.
 * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the {VARS.WEB_APP}.
-* [Agent conversations in the CLI](/cli/agent-conversations/#managing-conversations) - Conversation history, `/conversations`, and `--resume`.
+* [Agent conversations in the CLI](/agents/cli/agent-conversations/#managing-conversations) - Conversation history, `/conversations`, and `--resume`.
 * [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with.

src/content/docs/cli/configuration.mdx → src/content/docs/agents/cli/configuration.mdx

@@ -67,8 +67,8 @@ In auto mode, detection runs at startup, so if you switch your terminal's colors
 
 The statusline is the row below the CLI's input box that shows session information at a glance. By default it shows the auto-approve indicator, the active model, the working directory, the Git branch, and the Git diff status inside a repository, plus the Vim mode indicator when Vim mode is on. You can enable any of these items:
 
-<figure>
-![The Warp Agent CLI statusline showing the auto-approve, model, working directory, Git branch status, Git diff status, credit usage, context window usage, and agent to-do list chips](../../../assets/cli/tui-statusline.png)
+<figure style={{ maxWidth: "736px" }}>
+![The Warp Agent CLI statusline showing the auto-approve, model, working directory, Git branch status, Git diff status, credit usage, context window usage, and agent to-do list chips](../../../../assets/agents/cli/tui-statusline.png)
 <figcaption>The statusline with credit usage, context window usage, and task list chips enabled.</figcaption>
 </figure>
 
@@ -160,4 +160,4 @@ Press `Enter` on a server to start, stop, or retry it depending on its state. Fa
 * [Skills](/agents/capabilities/skills/) - Authoring skills, skill arguments, and skill locations.
 * [MCP servers](/agents/capabilities/mcp/) - Config format, server examples, and authentication.
 * [Codebase Context](/agents/capabilities/codebase-context/) - Codebase indexing in the Warp app.
-* [{VARS.WARP_CLI} reference](/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts.
+* [{VARS.WARP_CLI} reference](/agents/cli/reference/) - Command-line flags, slash commands, and keyboard shortcuts.