docs: editorial review pass on Warp Agent CLI launch docs

.agents/skills/draft_conceptual/SKILL.md

@@ -11,6 +11,14 @@ Draft a conceptual documentation page that explains what a feature or concept is
 
 Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **conceptual template** at `.warp/templates/conceptual.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, saying what the concept is and why it matters. Start with the subject.
+- ✅ `Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.`
+- ❌ `Learn about environments and why they are useful.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to conceptual pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_faq/SKILL.md

@@ -11,6 +11,14 @@ Draft an FAQ page with questions grouped by theme and answers that lead with a d
 
 Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **FAQ template** at `.warp/templates/faq.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, naming the topic area the questions cover.
+- ✅ `Answers to common questions about cloud agent billing, credits, and plan limits.`
+- ❌ `Frequently asked questions.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to FAQ pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_feature_doc/SKILL.md

@@ -11,6 +11,14 @@ Draft a feature documentation page that combines conceptual and procedural conte
 
 Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **feature-doc template** at `.agents/templates/feature-doc.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, saying what the feature does and its primary benefit.
+- ✅ `Control what the agent can do with permission cards, auto-approve, and execution profiles.`
+- ❌ `Documentation for permissions and profiles.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to feature documentation pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_guide/SKILL.md

@@ -28,6 +28,14 @@ The sidebar nav is defined in `src/sidebar.ts`, which organizes guides into topi
 - **DevOps & infrastructure** — Cloud logs, Docker, Kubernetes, testing, database optimization
 - **Frontend & UI** — Building and refining UI components with coding agents
 
+## Frontmatter description
+
+One sentence, 50-160 characters, saying what the reader will build or accomplish, using the non-branded phrasing they would search for.
+- ✅ `Set up Claude Code and run your first agentic coding session from the terminal.`
+- ❌ `A guide to using Claude Code with Warp.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to guide pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_procedural/SKILL.md

@@ -11,6 +11,14 @@ Draft a procedural documentation page with step-by-step instructions to accompli
 
 Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **procedural template** at `.agents/templates/procedural.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, naming the task the reader will complete. Start with an imperative verb.
+- ✅ `Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs.`
+- ❌ `This page explains the Slack integration setup process.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to procedural pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_quickstart/SKILL.md

@@ -11,6 +11,14 @@ Draft a quickstart that gets the reader from zero to a working result in about 1
 
 Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **quickstart template** at `.warp/templates/quickstart.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, saying what the reader ends up with plus the time budget. Start with an imperative verb.
+- ✅ `Install the Warp Agent CLI, log in, and run your first agent conversation in about five minutes.`
+- ❌ `Get started with the Warp Agent CLI.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to quickstart pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_reference/SKILL.md

@@ -11,6 +11,14 @@ Draft a reference documentation page with structured, exhaustive information for
 
 Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **reference template** at `.warp/templates/reference.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, saying what the reader can look up. Name the artifacts, not the genre.
+- ✅ `Look up Warp Agent CLI flags, environment variables, slash commands, and keyboard shortcuts.`
+- ❌ `Reference documentation for the Warp Agent CLI.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to reference pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/skills/draft_troubleshooting/SKILL.md

@@ -11,6 +11,14 @@ Draft a troubleshooting page that helps users diagnose and fix common issues.
 
 Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **troubleshooting template** at `.warp/templates/troubleshooting.md`.
 
+## Frontmatter description
+
+One sentence, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting.
+- ✅ `Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.`
+- ❌ `Troubleshooting information for common problems.`
+
+See "Descriptions by content type" under Frontmatter in `AGENTS.md` for the full rules.
+
 ## Content type rules
 
 These rules are specific to troubleshooting pages (from the "Drafting by content type" section of `AGENTS.md`):

.agents/templates/conceptual.md

@@ -2,8 +2,10 @@
 title: [Feature or concept name — sentence case. Title convention: noun or "About [subject]". The title field renders as the page H1; do not add a separate H1 in the body.
   Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 description: >-
-  [1-2 sentences: what the concept/feature is + why it matters.
-  Write as a standalone summary for search results. Lead with user benefit.
+  [One sentence, 50-160 characters: what the concept is and why it matters.
+  Start with the subject, not "Learn about" or "This page covers."
+  Example: "Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
   Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.

.agents/templates/faq.md

@@ -1,7 +1,9 @@
 ---
 description: >-
-  [1-2 sentences: what topic area these FAQs cover.
-  Example: "Answers to common questions about cloud agents, billing, and environments."
+  [One sentence, 50-160 characters: name the topic area these questions cover.
+  Don't just say "Frequently asked questions."
+  Example: "Answers to common questions about cloud agent billing, credits, and plan limits."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
   Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.

.agents/templates/feature-doc.md

@@ -1,9 +1,10 @@
 ---
 description: >-
-  [1-2 sentences: what the feature does + primary user benefit.
-  Lead with the benefit, include key terms for SEO.
-  Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.
-  Example: "Use the {{WARP_AGENT_CLI}} to run agents."]
+  [One sentence, 50-160 characters: what the feature does and its primary benefit.
+  Start with the verb or the feature, not "Documentation for."
+  Example: "Control what the agent can do with permission cards, auto-approve, and execution profiles."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
+  Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
 `import { VARS } from '@data/vars';`

.agents/templates/guide-page.md

@@ -1,8 +1,10 @@
 ---
 title: [Task-oriented title in sentence case — reads like a search query. Capture the non-branded query a developer would actually search for, not "How to do X in Warp." The title field renders as the page H1; do not add a separate H1 in the body.]
 description: >-
-  [1-2 sentence summary of what this guide covers and what the reader will
-  achieve. Keep under 160 characters for SEO.]
+  [One sentence, 50-160 characters: what the reader will build or accomplish,
+  using the non-branded phrasing they would actually search for.
+  Example: "Set up Claude Code and run your first agentic coding session from the terminal."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.]
 ---
 
 [One sentence: what you'll accomplish by following this guide. Mention Warp by name. Include a time estimate if possible (e.g., "takes about 10 minutes").]

.agents/templates/procedural.md

@@ -1,7 +1,9 @@
 ---
 description: >-
-  [1-2 sentences: what the reader will accomplish.
-  Task-oriented: "Create and manage X" or "Configure Y for Z."
+  [One sentence, 50-160 characters: the task the reader will complete.
+  Start with an imperative verb, not "This page explains."
+  Example: "Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
   Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.

.agents/templates/quickstart.md

@@ -1,7 +1,9 @@
 ---
 description: >-
-  [1-2 sentences: what the reader will accomplish + time estimate.
-  Example: "Learn how to run your first cloud agent in ~10 minutes."
+  [One sentence, 50-160 characters: what the reader ends up with, plus the time budget.
+  Start with an imperative verb, not "Learn how to" or "Get started with."
+  Example: "Install the {{WARP_AGENT_CLI}}, log in, and run your first agent conversation in about five minutes."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
   Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.

.agents/templates/reference.md

@@ -1,7 +1,9 @@
 ---
 description: >-
-  [1-2 sentences: what is documented and how to use this reference.
-  Example: "Use the {{WARP_AGENT_CLI}} to run, configure, and manage agents from the terminal."
+  [One sentence, 50-160 characters: what the reader can look up here.
+  Name the artifacts (flags, endpoints, shortcuts), not the genre.
+  Example: "Look up {{WARP_AGENT_CLI}} flags, environment variables, slash commands, and keyboard shortcuts."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
   Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.

.agents/templates/troubleshooting.md

@@ -1,7 +1,8 @@
 ---
 description: >-
-  [1-2 sentences describing common issues covered on this page.
-  Example: "Solutions for common issues with cloud agents, environments, and integrations."
+  [One sentence, 50-160 characters: name the symptoms covered, not the act of troubleshooting.
+  Example: "Fix sign-in failures, failed conversation resumes, and update problems in the {{WARP_AGENT_CLI}}."
+  See AGENTS.md > Frontmatter > Descriptions by content type for the full rules.
   Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
 [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.

AGENTS.md

@@ -94,16 +94,48 @@ Every page must include YAML frontmatter with a `description` field.
 ```yaml
 ---
 description: >-
-  A concise 1-2 sentence summary that explains what the page covers and
-  what value it provides to the reader.
+  One sentence, 50-160 characters, stating what the reader gets from this page.
 ---
 ```
 
-Write descriptions as standalone summaries that would make sense in a search result. Lead with the user benefit, include key terms for the topic.
-- ✅ `description: Environments ensure your cloud agents run with consistent toolchains across all triggers. Learn when to use environments and how to configure them.`
+The `description` field is the meta description in search results and the snippet AI engines read before deciding whether to cite the page. Write it as a standalone summary for someone who has never seen the page.
+- ✅ `description: Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.`
 - ❌ `description: This page describes environments.`
 
-The `description` field is used as the meta description in search results — write it as a summary that would make someone click.
+#### Description rules
+These apply to every page, regardless of content type.
+- **One sentence, 50-160 characters.** Search engines truncate past roughly 160. Two sentences almost always overshoot the budget, so prefer one that earns its length.
+- **Cut filler openers.** "Learn about," "This page covers," "A guide to," and "Documentation for" spend characters without adding meaning. Start with the verb or the subject instead.
+- **Describe what the reader gets, not what the page is.** "This page explains X" is always weaker than explaining X.
+- **Lead with the primary keyword** when it reads naturally, ideally within the first few words.
+- **Match the page's actual scope.** A description that promises more than the page delivers reads as a bait-and-switch in search results.
+
+#### Descriptions by content type
+Every description answers "what will I get from this page?" The shape of that answer depends on the type.
+- **Conceptual** - Say what the thing is and why it matters. Start with the subject.
+  - ✅ `Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.`
+  - ❌ `Learn about environments and why they are useful.`
+- **Procedural** - Say what task the reader will complete. Start with an imperative verb.
+  - ✅ `Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs.`
+  - ❌ `This page explains the Slack integration setup process.`
+- **Quickstart** - Say what the reader ends up with, plus the time budget. Start with an imperative verb.
+  - ✅ `Install the Warp Agent CLI, log in, and run your first agent conversation in about five minutes.`
+  - ❌ `Get started with the Warp Agent CLI.`
+- **Reference** - Say what the reader can look up. Name the artifacts rather than the genre.
+  - ✅ `Look up Warp Agent CLI flags, environment variables, slash commands, and keyboard shortcuts.`
+  - ❌ `Reference documentation for the Warp Agent CLI.`
+- **Troubleshooting** - Name the symptoms covered, not the act of troubleshooting.
+  - ✅ `Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.`
+  - ❌ `Troubleshooting information for common problems.`
+- **FAQ** - Name the topic area the questions cover.
+  - ✅ `Answers to common questions about cloud agent billing, credits, and plan limits.`
+  - ❌ `Frequently asked questions.`
+- **Feature documentation** - Say what the feature does and its primary benefit.
+  - ✅ `Control what the agent can do with permission cards, auto-approve, and execution profiles.`
+  - ❌ `Documentation for permissions and profiles.`
+- **Guide** - Say what the reader will build or accomplish, using the non-branded phrasing they would search for.
+  - ✅ `Set up Claude Code and run your first agentic coding session from the terminal.`
+  - ❌ `A guide to using Claude Code with Warp.`
 
 ### Headers
 - Use sentence case for all headers (not title case)
@@ -715,8 +747,9 @@ Add the key-value pair to `src/data/vars.ts` only. Both Option A (TypeScript imp
 All documentation should be written with search discoverability in mind — both for traditional search engines (Google) and AI engines (ChatGPT, Gemini, Perplexity, Copilot).
 
 ### Frontmatter descriptions
-- Every page must have a `description` in frontmatter. Write it as a standalone summary (50-160 characters) that includes the primary keyword naturally.
+- Every page must have a `description` in frontmatter. Write it as a standalone summary (one sentence, 50-160 characters) that includes the primary keyword naturally.
 - Descriptions appear in search results and AI citations. Write for humans, but include the key terms a developer would search for.
+- For the full rules and per-content-type patterns with examples, see [Frontmatter](#frontmatter) under Content structure. That section is the source of truth.
 
 ### Title framing
 - For guides and educational content: capture the **non-branded query** when possible. Write the title a developer would actually search for.
@@ -731,7 +764,7 @@ When creating or updating content, use SEO and AEO data to inform titles, descri
 
 Before publishing any documentation, verify:
 
-- [ ] Frontmatter includes a clear, 1-2 sentence description written as a standalone summary
+- [ ] Frontmatter includes a one-sentence description (50-160 chars) written as a standalone summary, with no filler opener
 - [ ] Content type is identified and the page follows the structure for that type (see `.warp/templates/`)
 - [ ] Headers use sentence case (with proper feature name capitalization)
 - [ ] Lists use bold term + dash + explanation format