Add Phase 3 citation blocks to 32 high-value pages

rachaelrenk · oz-agent · rachaelrenk · commit 6321b2f7f237 · 2026-05-12T07:47:44.000-10:00
Add 40-60 word answer-first citation blocks to remaining high-value pages:
- Capabilities: Full Terminal Use, Slash Commands, Task Lists
- Cloud agents: Slack integration, cloud providers, demo issue triage
- Local agents: Active AI, code diffs, interactive code review,
  interacting with agents, terminal/agent modes, generate, voice,
  and all 5 agent-context sub-pages (blocks, images, selections,
  URLs, @ context)
- Code: Vim keybindings, file tree, find and replace
- Warp Drive: Workflows, Notebooks, Prompts, Environment Variables,
  Agent Mode Context, Warp on the Web
- Reference: CLI agent profiles, troubleshooting, Warp Drive context,
  reference index
- Getting started: Agents in Warp, Agent FAQs

42 pages already had good intros and were left unchanged.
10 deep procedural pages (self-hosting) were skipped.

Co-Authored-By: Oz &lt;oz-agent@warp.dev&gt;
diff --git a/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx b/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx
@@ -7,7 +7,7 @@ description: >-
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
-Full Terminal Use lets Warp's agent operate directly inside interactive terminal applications, such as database shells, debuggers, text editors, long-running servers, and more.
+Full Terminal Use lets Warp's agent operate directly inside interactive terminal applications like database shells, debuggers, text editors, and long-running servers. The agent can see the live terminal buffer, write commands, respond to prompts, and hand control back to you at any time.
 
 The agent can see the live terminal buffer (terminal state), write to the PTY to run commands, respond to prompts, and continue working inside the running process while you stay in control.
 
diff --git a/src/content/docs/agent-platform/capabilities/slash-commands.mdx b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
@@ -5,7 +5,7 @@ description: >-
   built-in actions or saved prompts without leaving the input field.
 ---
 
-When using Agent Mode or Auto-Detection Mode, typing `/` in the input field opens the Slash Commands menu.
+Slash Commands are quick actions and saved prompts you can invoke by typing `/` in Agent Mode or Auto-Detection Mode. They provide instant access to built-in actions like starting conversations, creating environments, switching models, and running saved prompts from Warp Drive.
 
 <figure>
 ![Slash Commands menu](../../../../assets/agent-platform/slash-commands-menu.png)
diff --git a/src/content/docs/agent-platform/capabilities/task-lists.mdx b/src/content/docs/agent-platform/capabilities/task-lists.mdx
@@ -6,9 +6,7 @@ description: >-
   time.
 ---
 
-The Agent can automatically break down complex requests into clear, trackable steps in the form of a task list with to-do items.\
-\
-When you make a sufficiently complex request that requires multiple actions, the Agent will automatically create a list of steps, execute them in order, and track progress from start to finish. There’s no need to adjust settings or enable a special mode—the Agent detects and creates task lists automatically.
+Task Lists let Warp's agent automatically break down complex requests into clear, trackable steps. When a request requires multiple actions, the agent creates a structured list, executes each step in order, and tracks progress in real time. No configuration is needed—the agent detects and creates task lists automatically.
 
 <figure>
 ![An example of a task list in progress.](../../../../assets/agent-platform/in-progress-tasklist.png)
diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx
@@ -6,11 +6,7 @@ sidebar:
   label: "AWS, GCP, and other cloud providers"
 ---
 
-Oz cloud agents can securely access cloud providers using short-lived OpenID Connect credentials.
-
-This page explains how to configure a cloud agent environment to automatically authenticate to your
-cloud provider. Oz has built-in support for AWS and GCP, and can work with any provider that
-supports OIDC tokens.
+Oz cloud agents can securely access AWS, GCP, and other cloud providers using short-lived OpenID Connect (OIDC) credentials. Configure your cloud agent environment to automatically authenticate to your cloud provider without storing long-lived keys, using Warp's built-in OIDC federation support.
 
 ---
 
diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/demo-issue-triage-bot.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/demo-issue-triage-bot.mdx
@@ -8,6 +8,8 @@ sidebar:
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+This demo shows how to trigger Warp's coding agent from a GitHub Action to automate bug report handling. The agent evaluates whether a report is actionable, requests missing details when needed, and escalates directly into a draft pull request when the issue is ready for a fix.
+
 <VideoEmbed url="https://www.youtube.com/watch?feature=youtu.be&v=dK2eohQ2Yow" />
 
 :::note
diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
@@ -7,6 +7,8 @@ description: >-
   pull requests.
 ---
 
+The Slack integration lets your team trigger Oz cloud agents directly from Slack conversations. Tag @Oz in a message or DM the bot to start a cloud agent that clones your repos, works through the task, posts progress updates, and opens pull requests back into the same thread.
+
 ### Overview
 
 The Slack integration lets your team trigger agents directly from conversations in Slack. When you tag **@Oz** in a message or DM the bot, Warp will start an agent in the cloud, clone the repositories defined in your environment, and begin working through the task with full context from your codebase and the Slack thread.
diff --git a/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx b/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx
@@ -6,6 +6,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Warp includes Oz agents that help you write code, debug issues, and complete terminal workflows from natural language prompts. Agents operate with full context from your codebase, Warp Drive, and connected tools while you control their autonomy, permissions, and model choices.
+
 <VideoEmbed url="https://youtu.be/qiQtD1jPF6s" title="Agent Mode Overview" />
 
 Warp includes Oz agents. These coding agents are designed to help you build, test, deploy, and debug while keeping you in control. Describe what you want to do in natural language (_you can even use your voice_), and Oz will take action using your environment, codebase, and saved context.
diff --git a/src/content/docs/agent-platform/getting-started/faqs.mdx b/src/content/docs/agent-platform/getting-started/faqs.mdx
@@ -7,6 +7,8 @@ description: >-
   models, privacy practices, credit limits, billing, and usage guidelines.
 ---
 
+Answers to frequently asked questions about Warp's agents, including supported models, data privacy, credit limits, billing, and common error messages. For billing-specific questions, see the pricing FAQs.
+
 ## General
 
 ### What data is sent and/or stored when using Agents in Warp?
diff --git a/src/content/docs/agent-platform/local-agents/active-ai.mdx b/src/content/docs/agent-platform/local-agents/active-ai.mdx
@@ -5,6 +5,8 @@ description: >-
   on your command line errors, inputs, and outputs.
 ---
 
+Active AI Recommendations proactively suggest fixes and next actions based on your terminal errors, inputs, and outputs. Features include Prompt Suggestions that activate Agent Mode, Next Command predictions from your shell history, and Suggested Code Diffs that automatically surface fixes for command-line errors.
+
 :::note
 Active AI features can be disabled in **Settings** > **Agents** > **Warp Agent** with the Active AI toggle.
 :::
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
@@ -6,6 +6,8 @@ description: >-
 ---
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 
+Attach terminal output blocks to your agent prompts so the agent can understand errors, commands, and outputs from your current or previous sessions. Blocks can be attached with keyboard shortcuts, mouse clicks, or automatically within agent conversations.
+
 ## Attaching blocks as context
 
 Warp’s Agent can use blocks from your Agent conversations as context to better understand your queries and generate more relevant responses.
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
@@ -5,6 +5,8 @@ description: >-
   can use visual context when generating responses.
 ---
 
+Attach screenshots, diagrams, or other images directly to agent prompts so the agent can use visual context when generating responses. Warp supports drag-and-drop, copy-paste, and file upload for up to 5 images per request across all supported models.
+
 ## **Attaching images as context**
 
 To provide visual context, you can attach images directly to an agent prompt. This is useful for including screenshots, diagrams, or other visual references alongside your query.
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
@@ -5,6 +5,8 @@ description: >-
   context for your Agent prompts.
 ---
 
+Attach text selections or diff hunks directly from Warp's code editor or Code Review panel as context for agent prompts. Select code, press a keyboard shortcut, and Warp inserts the file path, line numbers, and content into your prompt automatically.
+
 ### Attaching selections from Warp's native code editor
 
 When you have Warp’s [native code editor](/code/code-editor/) open beside a regular pane, you can easily attach specific lines of code as context:
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
@@ -5,6 +5,8 @@ description: >-
   content.
 ---
 
+Attach a public URL to any agent prompt to provide page content as context. Warp scrapes the page and surfaces the extracted text directly to the model, giving the agent access to documentation, references, or any publicly accessible web content.
+
 ## Referencing websites via URLs
 
 You can attach a public URL to any prompt to provide page content as context. Warp will scrape the page and surface the extracted text directly to the model.
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
@@ -6,6 +6,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Use the @ symbol in agent prompts to reference files, folders, code symbols, Warp Drive objects, and blocks from other sessions as context. The @ menu searches your entire Git repository from the project root and works immediately without codebase indexing.
+
 ## How the @ context menu works
 
 You can attach specific files, folders, code symbols, Warp Drive objects, and blocks from other sessions as context to a prompt using the @ symbol. When you’re inside a **Git repository**, typing @ opens a context menu that allows you to search for and select files or directories to include.
diff --git a/src/content/docs/agent-platform/local-agents/code-diffs.mdx b/src/content/docs/agent-platform/local-agents/code-diffs.mdx
@@ -8,6 +8,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+When Warp's agent generates code changes, they appear as visual diffs in a built-in editor. Review proposed changes line by line, refine them with natural language, make manual edits, or accept them to apply the modifications to your files.
+
 ## Reviewing code diffs
 
 During an Agent Conversation, Warp can generate code diffs that open directly in a built-in diff editor.
diff --git a/src/content/docs/agent-platform/local-agents/generate.mdx b/src/content/docs/agent-platform/local-agents/generate.mdx
@@ -8,6 +8,8 @@ description: >-
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Generate (Legacy) turns natural language queries into precise terminal commands or contextual suggestions inside interactive CLI tools. Type `#` in the command line to describe what you want, and Warp generates the matching command in real time.
+
 ## What is Generate?
 
 Generate helps turn natural language queries into precise commands as terminal input or contextual suggestions inside interactive commands and programs, whether you're using psql, gdb, git, mysql, or any other CLI tool.
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
@@ -7,6 +7,8 @@ description: >-
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Agent conversations in Warp are multi-turn interactions tied to terminal sessions. Continue previous threads with follow-ups, manage conversation history, attach context from blocks and files, and run multiple conversations simultaneously across windows, tabs, or panes.
+
 ## Conversations with Warp's Agent
 
 Conceptually, a conversation is a sequence of AI queries and blocks. Conversations are tied to sessions and you can run multiple Agent Mode conversations simultaneously in different windows, tabs, or panes.
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
@@ -6,7 +6,7 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
-Warp provides two distinct modes: a clean terminal for commands, and a dedicated conversation view for multi-turn conversations with [Oz, Warp's agent](/agent-platform/local-agents/interacting-with-agents/).
+Warp provides two distinct modes: a clean terminal for running shell commands, and a dedicated conversation view for multi-turn interactions with Oz, Warp's agent. Terminal mode keeps the interface minimal by default, while Agent Mode surfaces full controls for model selection, voice input, image attachments, and conversation management.
 
 <VideoEmbed url="https://youtu.be/J715YW5VC18" />
 
diff --git a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx
@@ -6,6 +6,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Interactive Code Review lets you review agent-generated code, leave inline comments on specific lines, batch your feedback, and send all requested changes to the agent in a single pass. It works with Warp's native agent and supported third-party CLI agents like Claude Code and Codex.
+
 ### Overview
 
 Interactive Code Review lets you review, annotate, and refine code generated by any supported agent, whether that's Warp's native Agent or a third-party CLI agent running in Warp. Instead of relying on an AI to review another AI's output, Warp keeps the developer in control.
diff --git a/src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx b/src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx
@@ -7,6 +7,8 @@ sidebar:
   label: "Code editor Vim keybindings"
 ---
 
+Warp's built-in code editor supports native Vim keybindings for keyboard-driven navigation and editing. Enable Vim mode to use familiar motions, text objects, visual mode, registers, and editing commands directly in Warp without switching to an external editor.
+
 ## About Vim keybindings
 
 The Vi family of programs (including Vim and Neovim) are modal text editors that allow for keyboard-driven text editing. Vi-style keybindings are especially popular among developers for their speed and precision in navigating and manipulating code. Warp’s [code editor](/code/code-editor/) now includes native support for Vim keybindings (also known as Vim mode), offering a familiar editing experience directly within your coding workflows.
diff --git a/src/content/docs/code/code-editor/file-tree.mdx b/src/content/docs/code/code-editor/file-tree.mdx
@@ -5,6 +5,8 @@ description: >-
   context menu actions.
 ---
 
+The File Tree is Warp's built-in project explorer for browsing, opening, and managing files alongside your terminal. It automatically reflects your project structure and supports context menu actions like attaching files as agent context, copying paths, and creating new files.
+
 ![Warp's native file tree showing the project's file and folder structure in the left panel.](../../../../assets/terminal/filetree-main.png)
 
 Warp includes a **native file tree** that makes it easy to explore and manage project files. The file tree is available whenever in any directory and it automatically reflects your project structure as files are added, removed, or changed.
diff --git a/src/content/docs/code/code-editor/find-and-replace.mdx b/src/content/docs/code/code-editor/find-and-replace.mdx
@@ -8,6 +8,8 @@ sidebar:
 ---
 import DemoVideo from '@components/DemoVideo.astro';
 
+Warp's code editor includes built-in find and replace with support for regex, case sensitivity, and smart case preservation. Search across a file, jump between matches, and replace text with automatic casing adjustments for PascalCase, camelCase, and hyphenated patterns.
+
 ## Find
 
 Press `CMD-F` on macOS or `CTRL-SHIFT-F` on Windows and Linux to open the find menu. As you type, all matches in the file are highlighted, and the match closest to your cursor is selected.
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/agent-mode-context.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/agent-mode-context.mdx
@@ -7,7 +7,7 @@ sidebar:
   label: "Agent Mode context"
 ---
 
-[Agent Mode](/agent-platform/local-agents/interacting-with-agents/) can leverage your [Warp Drive](/knowledge-and-collaboration/warp-drive/) contents to tailor responses to your personal and team developer workflows and environments.
+Warp's agents automatically pull context from your Warp Drive contents, including Workflows, Notebooks, Environment Variables, Rules, and MCP Servers, to generate responses tailored to your personal and team developer workflows. Referenced objects appear as citations in the conversation.
 
 ## Objects used as context
 
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx
@@ -4,6 +4,8 @@ description: >-
   Save or sync environment variables to load into your terminal sessions.
 ---
 
+Environment Variables in Warp Drive let you save, sync, and load environment variables into your terminal sessions with a click. Support for both static values and dynamic secrets from external managers like 1Password, LastPass, and Hashicorp Vault keeps credentials secure and out of source code.
+
 ## What are environment variables in Warp?
 
 Environment variables in Warp are similar to .env files, except you can:
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
@@ -7,6 +7,8 @@ sidebar:
 ---
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 
+Notebooks are interactive, runnable documents in Warp Drive that combine markdown text with executable shell command blocks. Use them for onboarding playbooks, debugging runbooks, and development workflows that teammates can search, share, and execute directly from the terminal.
+
 ### What is a Notebook?
 
 Notebooks are runnable documentation consisting of markdown text and list elements, code blocks, and runnable shell snippets that can be automatically executed in your terminal session. Notebooks are searchable and accessible through the [Command Palette](/terminal/command-palette/) so you can access and run your documentation without ever leaving the terminal. You can also export Notebooks in .md format at any time.
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
@@ -7,6 +7,8 @@ sidebar:
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Prompts are parameterized natural language queries you can save in Warp Drive and reuse with agents. Name a prompt, add arguments for dynamic values, and execute it from the Command Palette or Warp Drive to repeat complex agent workflows without retyping.
+
 ## What is a prompt?
 
 A prompt is a parameterized natural language query you can name and save in Warp to use with [Agent Mode](/agent-platform/local-agents/interacting-with-agents/).
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
@@ -5,6 +5,8 @@ description: >-
   screen device, including mobile phones, tablets, and touch-enabled laptops.
 ---
 
+Warp Drive on the Web lets you view and edit Warp Drive objects and shared sessions directly in any browser, including mobile devices and tablets. Access Workflows, Notebooks, Prompts, and session transcripts from anywhere without installing the Warp desktop app.
+
 ## What is Warp on the web?
 
 Warp Drive on the Web lets you view and edit your Warp Drive objects and shared sessions directly in the browser, on any device.
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
@@ -9,6 +9,8 @@ sidebar:
 import DemoVideo from '@components/DemoVideo.astro';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Workflows are parameterized commands you can name, save, and share in Warp Drive. Define arguments with default values, add descriptions for search, and execute workflows from the Command Palette or Warp Drive to run frequently used commands without retyping them.
+
 ## What is a workflow?
 
 A workflow is a parameterized command you can name and save in Warp with descriptions and arguments. Workflows are searchable and easily accessed from the [Command Palette](/terminal/command-palette/) so you can find and execute them without switching contexts.
diff --git a/src/content/docs/reference/cli/agent-profiles.mdx b/src/content/docs/reference/cli/agent-profiles.mdx
@@ -7,6 +7,8 @@ sidebar:
   label: "Agent Profiles"
 ---
 
+Agent profiles control what the agent can do, how it behaves, and where it can act when running from the Oz CLI. Create profiles in the Warp app to configure file access, command execution, MCP server usage, model selection, and directory permissions, then reference them by ID in CLI commands.
+
 Agent profiles control three things:
 
 * **What the agent can do** — file access, command execution, and MCP server usage
diff --git a/src/content/docs/reference/cli/troubleshooting.mdx b/src/content/docs/reference/cli/troubleshooting.mdx
@@ -5,6 +5,8 @@ description: >-
   failures, environments, GitHub access, and Docker image issues.
 ---
 
+Solutions for common Oz CLI errors, including authentication issues, agent failures, environment configuration, GitHub access problems, and Docker image compatibility. Use `oz help` for built-in documentation on any command.
+
 ## Getting help
 
 The CLI includes built-in documentation for all commands:
diff --git a/src/content/docs/reference/cli/warp-drive.mdx b/src/content/docs/reference/cli/warp-drive.mdx
@@ -7,6 +7,8 @@ sidebar:
   label: "Warp Drive Context"
 ---
 
+Reference saved Warp Drive objects in Oz CLI commands to reuse prompts, notebooks, workflows, and rules as agent context. Pass a saved prompt ID with `--saved-prompt` or inline Warp Drive references using `<workflow:id>`, `<notebook:id>`, or `<rule:id>` syntax.
+
 ## Reusing saved prompts
 
 When you find prompts that work well, save them in [Warp Drive](/knowledge-and-collaboration/warp-drive/) to reuse across sessions, share with teammates, and integrate into automated workflows. For more information, see [Prompts](/knowledge-and-collaboration/warp-drive/prompts/).
diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx
@@ -4,7 +4,7 @@ description: >-
   Technical reference documentation for the Oz CLI, API, and SDK.
 ---
 
-This section covers the programmatic interfaces for running and managing Oz agents in CI pipelines, scripts, backend services, and custom tooling.
+Technical reference documentation for the Oz CLI, API, and SDKs. Use these programmatic interfaces to run and manage Oz agents from CI pipelines, scripts, backend services, and custom tooling without requiring the Warp desktop app.
 
 ## CLI
 
