Add AEO citation blocks (40-60 word summaries) to 15 key docs pages

rachaelrenk · oz-agent · rachaelrenk · commit 10f91f2af4d9 · 2026-05-11T11:56:16.000-10:00
Add answer-first introductory paragraphs to Tier 1 docs pages to improve
AI answer engine citability. Each citation block is a concise 40-60 word
summary placed at the top of the page that directly answers 'What is this
feature?' in a self-contained, extractable format.

Pages updated:
- Site root (index.mdx), quickstart, agents overview
- Local agents, cloud agents, CLI agents overviews
- Capabilities, MCP, Warp Drive, Blocks, Code, Editor overviews
- Oz CLI and API/SDK references, Enterprise overview

Co-Authored-By: Oz &lt;oz-agent@warp.dev&gt;
diff --git a/src/content/docs/agent-platform/capabilities/index.mdx b/src/content/docs/agent-platform/capabilities/index.mdx
@@ -5,9 +5,7 @@ description: >-
   what context they have access to, and how they execute tasks.
 ---
 
-These capabilities are the foundational building blocks that define how agents operate. These include the context sources agents can access, the rules that guide their behavior, and the tools they can use.
-
-Understanding these capabilities helps you get the most out of agents by configuring them to match your workflows and preferences.
+Agent capabilities are the core building blocks that define how Warp's agents operate — including the context sources agents can access, the rules that guide their behavior, the tools they can use, and the models they run on. Configure these capabilities to match your workflows and preferences.
 
 ## Capabilities in this section
 
diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx
@@ -8,7 +8,7 @@ sidebar:
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
-Oz Cloud Agents are **cloud-connected**, **background agents** that run on the [Oz Platform](/agent-platform/cloud-agents/platform/).
+Oz Cloud Agents are autonomous, background agents that run on Warp's cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, auditable, and shareable across your team.
 
 **New to cloud agents?** Start with the [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) to run your first cloud agent in ~10 minutes.
 
diff --git a/src/content/docs/agent-platform/index.mdx b/src/content/docs/agent-platform/index.mdx
@@ -5,7 +5,7 @@ description: >-
   and autonomous agents for development workflows.
 ---
 
-Warp includes **Oz**, the orchestration platform for cloud agents. While Warp provides the terminal and coding surface you work in day-to-day, Oz is the underlying orchestration layer that makes running agents at scale possible.
+Warp includes **Oz**, the orchestration platform that powers all of Warp's agents. Oz runs interactive agents locally inside Warp for real-time coding assistance and deploys autonomous agents in the cloud for background automation, event-driven workflows, and parallel execution across repos and teams.
 
 Warp's client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE), so the editor and terminal that host your agents are fully auditable. See [Contributing to Warp](/support-and-community/community/contributing/) for the source and contribution flow.
 
diff --git a/src/content/docs/agent-platform/local-agents/overview.mdx b/src/content/docs/agent-platform/local-agents/overview.mdx
@@ -6,6 +6,8 @@ description: >-
   Environment.
 ---
 
+Warp's local agents are interactive agents embedded directly in the terminal that help you write code, debug issues, run commands, and automate development tasks using natural language. Agents operate with full context from your codebase, Warp Drive, and connected tools, while you stay in control of every action.
+
 ## AI in Warp
 
 Warp includes intelligent Oz agents designed to help you build, test, deploy, and debug while keeping you in control. Interactive agent conversations in Warp can look up commands, execute tasks, fix bugs, and adapt to your workflows. You can manage agent behavior directly, with full context from your Warp Drive and your team.
diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx
@@ -6,6 +6,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Warp's coding features help you go from prompt to production. They combine a dedicated coding agent — consistently ranked among the top on SWE-bench Verified — with a native code editor, inline diff review, codebase context, and project-level rules for accurate, context-aware code generation.
+
 :::note
 On macOS and Linux SSH sessions, Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) brings the file tree, native file reads, and native code diffs to remote hosts. See [Feature support over SSH](/code/ssh-feature-support/) for the current support matrix.
 :::
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -8,7 +8,7 @@ sidebar:
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
-Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment**, a modern terminal combined with powerful agents that help you build, test, deploy, and debug code. Warp's AI is powered by **Oz**, the orchestration platform for cloud agents.
+Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that combines a modern, high-performance terminal with powerful agents to help you build, test, deploy, and debug code. Warp's agents are powered by **Oz**, the orchestration platform for running agents locally or in the cloud at scale.
 
 <figure>
 ![Warp, the Agentic Development Environment: Warp (a modern terminal built for coding with agents) and Oz (the orchestration platform for cloud agents)](../../assets/terminal/warp-oz-welcome.png)
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
@@ -8,6 +8,8 @@ description: >-
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Warp Drive is a built-in workspace for saving and sharing Workflows, Notebooks, Prompts, and Environment Variables across your team. All objects sync in real time, so you and your team always have access to the latest versions — whether you're working locally or collaborating across an organization.
+
 ## What is Warp Drive?
 
 All objects stored in Warp Drive sync immediately as they’re updated, so you and your team will always have access to the latest versions.
diff --git a/src/content/docs/quickstart.mdx b/src/content/docs/quickstart.mdx
@@ -6,7 +6,7 @@ description: >-
 ---
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 
-This guide walks you through installing Warp, trying the terminal features you'll use every day, and firing off your first agent prompt. After completing the steps in this guide, you'll have a working Warp setup and a clear picture of how terminal commands and agents work together.
+Get up and running with Warp in about 10 minutes. Install the app, run your first commands using Blocks and the modern text editor, and start an agent conversation to write code, debug issues, or explore your codebase — all from natural language prompts inside the terminal.
 
 ---
 
diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/reference/api-and-sdk/index.mdx
@@ -8,6 +8,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+The Oz API and SDKs let you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling — ideal for CI pipelines, internal tools, and custom integrations.
+
 ### Oz API
 
 The Oz API lets you create and inspect [Cloud Agent](/agent-platform/cloud-agents/overview/) runs over HTTP from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app.
diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx
@@ -7,6 +7,8 @@ description: >-
 ---
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 
+The Oz CLI is the command-line tool for running and managing Warp's cloud agents from any terminal, script, or CI pipeline. Use it to start agents locally or in the cloud, connect MCP servers, configure integrations, and authenticate — all without requiring the Warp desktop app.
+
 :::note
 **`warp-cli` is deprecated and has been replaced by `oz`.** If you have `warp-cli` installed, it will auto-update to `oz`. All the same commands are available, just replace `warp-cli` with `oz` in your scripts and workflows.
 :::
diff --git a/src/content/docs/terminal/blocks/index.mdx b/src/content/docs/terminal/blocks/index.mdx
@@ -5,6 +5,8 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Blocks are Warp's fundamental unit for organizing terminal output. Every command and its output is grouped into a single Block that you can copy, search, filter, bookmark, share, and navigate independently — replacing the endless scroll of traditional terminals with structured, actionable output.
+
 ## What are Blocks?
 
 Blocks enable us to easily:
diff --git a/src/content/docs/terminal/editor/index.mdx b/src/content/docs/terminal/editor/index.mdx
@@ -7,6 +7,8 @@ description: >-
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+Warp's input editor works like a modern IDE text editor, with cursor movement, click-to-place, multi-line editing, copy-paste, word selection, and soft wrapping built in. Unlike traditional terminals, you can edit commands the same way you edit code — no memorizing shell-specific shortcuts required.
+
 :::note
 Text Editor Input also works for [SSH sessions](/terminal/warpify/ssh/).
 :::
