docs: add AEO drafting workflow guidance

.agents/skills/aeo_brief/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: aeo_brief
+description: Build a source-grounded AEO brief for Warp docs using Peec data, existing docs, and product terminology. Use whenever a docs request mentions AEO, answer-engine optimization, SEO visibility, Peec recommendations, AI search prompts, content gaps, search-query vocabulary, or deciding whether to create new docs versus update existing docs.
+---
+
+# AEO brief
+
+Create a concise, source-grounded brief before drafting or revising AEO-driven Warp documentation. The brief should help the human reviewer decide what content is worth creating and help the drafting agent use the right vocabulary without turning the doc into a keyword dump.
+
+## When to use
+
+Use this skill when the user asks for docs work based on:
+- AEO, answer-engine optimization, AI search visibility, or SEO goals
+- Peec recommendations, prompts, topics, search queries, or source URLs
+- A content gap, competitive/source-data comparison, or ranking opportunity
+- A question about whether to create a new page, update an existing page, or avoid duplicative content
+
+If the task is not AEO-driven, use the normal docs drafting workflow instead.
+
+## Inputs to gather
+
+Start with the smallest set of inputs that can support a useful brief:
+- **Goal** - What decision or draft should this brief support?
+- **Target topic** - The feature, workflow, product area, or user problem.
+- **Known source data** - Peec project, prompts, topics, recommendations, source URLs, or notes supplied by the user.
+- **Target docs area** - Existing page, section, or proposed new page if known.
+- **Open questions** - Anything that affects scope, placement, or product accuracy.
+
+Ask the user only when a missing input blocks the brief. Otherwise, use the available context and flag assumptions as open questions.
+
+## Peec research workflow
+
+Use the Peec MCP when available. Prefer source data over invented SEO advice.
+
+1. **Resolve the project.** Use `list_projects` if the project ID is not already known.
+2. **Find relevant prompts.** Use `list_prompts` to identify prompts tied to the topic, tag, or project. Capture the exact prompt text when it informs the brief.
+3. **Extract search-query vocabulary.** Use `list_search_queries` for the relevant prompts, topic, or date range. Group repeated phrasing and note user-language variants, not every raw query.
+4. **Inspect recommendations.** Use `get_actions` with `scope=overview` first, then drill into the highest-opportunity slices that matter for docs content. Use the returned recommendation text as the source of truth.
+5. **Review source URLs when useful.** Use `get_url_content` for specific source URLs when the brief needs to compare content coverage, language, or examples.
+
+Keep Peec output compact. The brief should explain what the data suggests, not reproduce a full report.
+
+## Repo research workflow
+
+Ground every recommendation in the current docs:
+- Read `AGENTS.md` and `.agents/references/terminology.md` when drafting language or naming product surfaces.
+- Search existing docs for the target topic before recommending a new page.
+- Identify the best existing pages to update, link from, or avoid duplicating.
+- Note when a proposed topic risks becoming a thin page or junk-drawer doc.
+
+## Vocabulary translation
+
+Translate AEO/source-data language into user-facing docs language:
+- Preserve high-intent search terms when they are accurate and useful.
+- Replace vague or internal shorthand with precise product names and UI surfaces.
+- Explain the feature or workflow in plain developer language before using branded terms.
+- Avoid keyword stuffing. AEO vocabulary should appear where it helps readers understand the page.
+
+Example pattern:
+- **Source-data language** - “Track or observe AI agents in real time.”
+- **Docs translation** - “Track and review cloud agent runs in the Agent Management Panel in the Warp app or the Runs page in the Oz web app.”
+
+## Brief format
+
+Return the brief in this structure:
+
+## AEO brief
+
+**Goal:** [What this brief supports.]
+
+**Recommendation:** [Create a new page, update an existing page, merge into another page, or do not pursue yet.]
+
+**Source signals:**
+- [Peec prompt, search-query cluster, action recommendation, or source URL.]
+- [Existing docs signal, gap, or duplication risk.]
+
+**Vocabulary map:**
+- **Users/answer engines say:** [Raw or clustered phrase.]
+  **Docs should say:** [Natural, accurate Warp docs phrasing.]
+
+**Content scope:**
+- **Include** - [High-value topics, procedures, examples, or links.]
+- **Avoid** - [Junk-drawer coverage, duplicate explanations, unsupported claims, or outdated terms.]
+
+**Existing docs to touch or link:**
+- `[path]` - [Why it matters.]
+
+**Open questions for human review:**
+- [Question that affects accuracy, positioning, or scope.]
+
+## Handoff rules
+
+- If the user asked for a plan, use the brief as research context before creating the plan.
+- If the user asked for a draft, use the brief before drafting and include only the decisions that matter in the final summary.
+- If the brief shows the content should not be created, recommend the smaller update instead of forcing a new page.
+- If Peec or Notion data is unavailable, say what could not be verified and proceed with repo-grounded recommendations.

.agents/skills/draft_docs/SKILL.md

@@ -14,6 +14,7 @@ Invoke this skill with any context that describes what you want to document:
 - Slack threads or meeting notes
 - Existing documentation that needs updating
 - A description of a feature or concept
+- AEO, SEO, Peec, or answer-engine source data that should inform a draft
 
 Example: "Use the draft_docs skill to write docs for [feature name] based on this PRD: [context]"
 
@@ -27,8 +28,16 @@ Review all provided context (PRD, spec, existing doc, etc.). Identify:
 - Key user benefits and capabilities
 - Technical details that need explaining
 
+### 1.5. Create an AEO brief when source data drives the request
+If the request mentions AEO, SEO, Peec, answer-engine visibility, search-query vocabulary, content gaps, or whether to create a new page versus update an existing page, read `.agents/skills/aeo_brief/SKILL.md` and create the brief before drafting. Use the brief to decide:
+- Which page or section should change
+- Which user/search vocabulary belongs in the draft
+- Which product terms or UI surfaces need precise naming
+- Which topics to avoid because they duplicate existing docs or create a junk-drawer page
+- Which questions require human review before publishing
+
 ### 2. Clarify placement
-Ask the user where the doc should live. The docs are organized into sections, each with its own `astro.config.mjs (sidebar config)`:
+Ask the user where the doc should live. The docs are organized into sections, with navigation configured in `src/sidebar.ts`:
 - `src/content/docs/` - Warp Terminal and IDE → `docs.warp.dev/`
 - `src/content/docs/agent-platform/` - Agent Platform → `docs.warp.dev/agent-platform/`
 - `src/content/docs/reference/` - Technical reference (CLI, API & SDK) → `docs.warp.dev/reference/`
@@ -46,14 +55,14 @@ Using the "Drafting by content type" section in `AGENTS.md`, determine which con
 
 | Content type | Use when | Template | Skill |
 |---|---|---|---|
-| **Conceptual** | Explains what/why, no procedures | `.warp/templates/conceptual.md` | `draft_conceptual` |
-| **Procedural** | Step-by-step task instructions | `.warp/templates/procedural.md` | `draft_procedural` |
-| **Quickstart** | Fast path to a working result | `.warp/templates/quickstart.md` | `draft_quickstart` |
-| **Reference** | Structured information for lookup | `.warp/templates/reference.md` | `draft_reference` |
-| **Troubleshooting** | Problem → cause → solution | `.warp/templates/troubleshooting.md` | `draft_troubleshooting` |
-| **FAQ** | Question-and-answer format | `.warp/templates/faq.md` | `draft_faq` |
-| **Guide** | Task-oriented walkthrough (Guides section) | `.warp/templates/guide-page.md` | `draft_guide` |
-| **Feature documentation** | Combined conceptual + procedural (most common) | `.warp/templates/feature-doc.md` | `draft_feature_doc` |
+| **Conceptual** | Explains what/why, no procedures | `.agents/templates/conceptual.md` | `draft_conceptual` |
+| **Procedural** | Step-by-step task instructions | `.agents/templates/procedural.md` | `draft_procedural` |
+| **Quickstart** | Fast path to a working result | `.agents/templates/quickstart.md` | `draft_quickstart` |
+| **Reference** | Structured information for lookup | `.agents/templates/reference.md` | `draft_reference` |
+| **Troubleshooting** | Problem → cause → solution | `.agents/templates/troubleshooting.md` | `draft_troubleshooting` |
+| **FAQ** | Question-and-answer format | `.agents/templates/faq.md` | `draft_faq` |
+| **Guide** | Task-oriented walkthrough (Guides section) | `.agents/templates/guide-page.md` | `draft_guide` |
+| **Feature documentation** | Combined conceptual + procedural (most common) | `.agents/templates/feature-doc.md` | `draft_feature_doc` |
 
 Once the content type is identified:
 - Use the corresponding **template** as the starting scaffold for the page.
@@ -82,25 +91,28 @@ These rules are frequently violated by agents. Apply them carefully during draft
 - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` ``
 
 ### 7. Draft the doc
-Create the documentation using the appropriate template from `.warp/templates/`. Follow the structure for the identified content type and all rules in `AGENTS.md`. Each template includes visible bracketed instructions explaining what to put in each section.
+Create the documentation using the appropriate template from `.agents/templates/`. Follow the structure for the identified content type and all rules in `AGENTS.md`. Each template includes visible bracketed instructions explaining what to put in each section.
 
 ### 8. Run style lint
-Run `python3 .warp/skills/style_lint/style_lint.py --changed` on the drafted file to catch formatting and terminology issues before presenting to the user.
+Run `python3 .agents/skills/style_lint/style_lint.py --changed` on the drafted file to catch formatting and terminology issues before presenting to the user.
 
 ### 9. Review against checklist
 Before presenting the draft, verify against the quality checklist in `AGENTS.md`:
 - [ ] Frontmatter includes clear description written as a standalone summary
 - [ ] Content follows the structure for its content type
-- [ ] Terminology matches the glossary (`.warp/references/terminology.md`)
+- [ ] Terminology matches the glossary (`.agents/references/terminology.md`)
 - [ ] Headers use sentence case (with proper feature name capitalization)
 - [ ] Lists use bold term + dash + explanation format
 - [ ] Cross-references to related features are included
 - [ ] Instructions include expected outcomes
+- [ ] Procedures are scannable: dense sections are split into numbered steps, short bullets, or concise subsections
+- [ ] UI surfaces and product terms use canonical names from `.agents/references/terminology.md`
+- [ ] If AEO-driven, the draft follows the AEO brief, uses source vocabulary naturally, and avoids duplicative or junk-drawer coverage
 - [ ] Images have descriptive alt text
 
 ### 10. Update navigation and redirects
 If this is a new page, remind the user to:
-- Add it to the relevant section's `astro.config.mjs (sidebar config)`.
+- Add it to the relevant section in `src/sidebar.ts`.
 
 If this page replaces, renames, or moves an existing page, remind the user to add a redirect:
 - **Same-space redirect**: Add an entry to the space's `vercel.json (redirects)` file under `redirects:`.