Add AEO citation blocks (40-60 word summaries) to key pages#63
Add AEO citation blocks (40-60 word summaries) to key pages#63rachaelrenk wants to merge 7 commits into
Conversation
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 <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds answer-first citation blocks to Tier 1 docs pages. The changes are documentation-only and generally align with AEO guidance; I found one terminology/style issue in the updated landing page copy.
Concerns
- The landing page now hyphenates
open-source, but the docs terminology guide prefersopen sourcein prose.
Verdict
Found: 0 critical, 0 important, 1 suggestions
Approve with nits
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Replace 5 of 9 em dashes with commas, periods, or rewording. Keep em dashes only where they serve as strong contrast or parenthetical asides (cloud agents, code, blocks, editor). Co-Authored-By: Oz <oz-agent@warp.dev>
Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Add 40-60 word answer-first citation blocks to 9 more pages: - Model choice, Agent Profiles, Teams, Admin Panel - Code Review, Command Palette, Sessions, Supported Shells - Plans and billing Also fix 'open-source' -> 'open source' on index.mdx per style guide. 9 Phase 2 pages already had good intros and were left unchanged: Skills, Rules, Codebase Context, Environments, Secrets, Integrations, Planning, Code Editor, Managing Cloud Agents. Co-Authored-By: Oz <oz-agent@warp.dev>
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 <oz-agent@warp.dev>
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR adds answer-first citation blocks across many high-value documentation pages. The prose-only diff does not introduce security-sensitive code or configuration, but it does miss the PR's stated 40-60 word constraint on multiple added blocks.
Concerns
- Several added citation blocks are under the PR's stated 40-word minimum, including
agent-platform/getting-started/faqs.mdx(27 words),reference/cli/troubleshooting.mdx(29 words), and additional blocks in local-agent context, code editor, Warp Drive, reference, and sessions pages. Since consistent 40-60 word AEO blocks are the core acceptance criterion for this PR, expand or revise the under-length blocks before merge. - One added block introduces an additional
Hashicorp Vaultoccurrence; use the officialHashiCorp Vaultcapitalization.
Verdict
Found: 0 critical, 1 important, 1 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| 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. |
There was a problem hiding this comment.
💡 [SUGGESTION] Use the official HashiCorp capitalization for the brand name.
| 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. | |
| 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. |
2 participants
Summary
Adds answer-first introductory paragraphs (40-60 word citation blocks) to the top high-value docs pages to improve AI answer engine citability (AEO). Each citation block is a concise, self-contained summary placed at the top of the page that directly answers "What is this feature?" — optimized for extraction by ChatGPT, Perplexity, Google AI Overviews, and similar AI systems.
What changed
53 files edited across three phases. 54 pages already had good intros and were left unchanged. 10 deep procedural pages (self-hosting) were skipped.
Phase 1: Tier 1 pages (12 files edited, 3 already good)
Site root, quickstart, agents overview, local/cloud/CLI agents overviews, capabilities overview, Warp Drive overview, text editing, Blocks, Code, Oz CLI reference, API and SDK reference. Also fixed "open-source" to "open source" per style guide.
Phase 2: Tier 2 pages (9 files edited, 9 already good)
Model choice, Agent Profiles, Teams, Admin Panel, Code Review, Command Palette, Sessions, Supported Shells, Plans and billing.
Phase 3: High-value remaining pages (32 files edited, 42 already good)
Remaining pages (not in this PR)
~220 lower-priority pages are tracked in a separate Notion item for incremental rollout:
Writing guidelines followed
Each citation block:
Notion task
https://www.notion.so/warpdev/Add-citation-blocks-40-60-word-summaries-to-key-pages-for-AEO-35943263616d807ebdbbcb9d8af8d267
Plan
Add AEO Citation Blocks to Key Docs Pages
Conversation
Co-Authored-By: Oz oz-agent@warp.dev