docs: allow one-to-two-sentence frontmatter descriptions consistently

.agents/skills/draft_conceptual/SKILL.md

@@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **concept
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, saying what the concept is and why it matters. Start with the subject.
+One to two sentences, 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.`
 

.agents/skills/draft_faq/SKILL.md

@@ -32,7 +32,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **FAQ tem
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, naming the topic area the questions cover.
+One to two sentences, 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.`
 

.agents/skills/draft_feature_doc/SKILL.md

@@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **feature
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, saying what the feature does and its primary benefit.
+One to two sentences, 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.`
 

.agents/skills/draft_guide/SKILL.md

@@ -41,7 +41,7 @@ The sidebar nav is defined in `src/sidebar.ts`, which organizes guides into topi
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, saying what the reader will build or accomplish, using the non-branded phrasing they would search for.
+One to two sentences, 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.`
 

.agents/skills/draft_procedural/SKILL.md

@@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **procedu
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, naming the task the reader will complete. Start with an imperative verb.
+One to two sentences, 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.`
 

.agents/skills/draft_quickstart/SKILL.md

@@ -21,7 +21,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **quickst
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, saying what the reader ends up with plus the time budget. Start with an imperative verb.
+One to two sentences, 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.`
 

.agents/skills/draft_reference/SKILL.md

@@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **referen
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, saying what the reader can look up. Name the artifacts, not the genre.
+One to two sentences, 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.`
 

.agents/skills/draft_troubleshooting/SKILL.md

@@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **trouble
 
 ## Frontmatter description
 
-One sentence, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting.
+One to two sentences, 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.`
 

.agents/templates/conceptual.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case. Use "About [subject]" or a plain noun phrase naming the subject. Not "Understanding how X works". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: what the thing is and why it matters. Start with the
+  [One to two sentences, 50-160 characters: what the thing is and why it matters. Start with the
   subject, not "Learn about". Example: "Environments give cloud agents the same toolchain
   and setup on every run, no matter what triggers them."
   Use {{TOKEN}} syntax for product names in src/data/vars.ts.]

.agents/templates/faq.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case. Use "[Feature] FAQs" or "Frequently asked questions". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: name the topic area these questions cover. Not just
+  [One to two sentences, 50-160 characters: name the topic area these questions cover. Not just
   "Frequently asked questions". Example: "Answers to common questions about cloud agent
   billing, credits, and plan limits."
   Use {{TOKEN}} syntax for product names in src/data/vars.ts.]

.agents/templates/feature-doc.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case, task-based gerund when the page contains a procedure. Keep it general enough to cover the range of tasks on the page and agnostic about which option the reader picks: "Setting repository visibility", not "Making a private repository public". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: what the feature does and its primary benefit. Example:
+  [One to two sentences, 50-160 characters: what the feature does and its primary benefit. Example:
   "Control what the agent can do with permission cards, auto-approve, and execution profiles."
   Use {{TOKEN}} syntax for product names in src/data/vars.ts.]
 ---

.agents/templates/guide-page.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case, task-oriented, reading like a search query. Capture the non-branded query a developer would actually type: "How to set up Claude Code", not "How to set up Claude Code in Warp". Do not put "tutorial" or "guide" in the title. This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: what the reader will build or accomplish, in the
+  [One to two sentences, 50-160 characters: what the reader will build or accomplish, in the
   non-branded phrasing they would search for. Example: "Set up Claude Code and run your
   first agentic coding session from the terminal."]
 ---

.agents/templates/procedural.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case, beginning with a gerund that names the task. Example: "Configuring a self-hosted GitLab integration". Not "Self-hosted GitLab integration setup". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: the task the reader will complete. Start with an
+  [One to two sentences, 50-160 characters: the task the reader will complete. Start with an
   imperative verb, not "This page explains". Example: "Connect Slack to the Automation
   Platform so mentions and channel messages can trigger cloud agent runs."
   Use {{TOKEN}} syntax for product names in src/data/vars.ts.]

.agents/templates/quickstart.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case, naming the feature. Use "Quickstart for [product]" or "[Feature] quickstart". Never a bare "Quickstart". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: what the reader ends up with, plus the time budget.
+  [One to two sentences, 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." Use {{TOKEN}} syntax for product names in src/data/vars.ts.]

.agents/templates/reference.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case. A noun phrase naming what can be looked up. Break up stacked nouns with prepositions: "Keyboard shortcuts for the code editor", not "Code editor keyboard shortcut reference". Never a bare "Overview" or "Reference". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: what the reader can look up here. Name the artifacts —
+  [One to two sentences, 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."
   Use {{TOKEN}} syntax for product names in src/data/vars.ts.]

.agents/templates/troubleshooting.md

@@ -1,7 +1,7 @@
 ---
 title: [Sentence case. Use "Troubleshooting [feature]" or "Known issues with [feature]". This renders as the page H1 — do not add an H1 in the body.]
 description: >-
-  [One sentence, 50-160 characters: name the symptoms covered, not the act of
+  [One to two sentences, 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}}."
   Use {{TOKEN}} syntax for product names in src/data/vars.ts.]

AGENTS.md

@@ -165,7 +165,7 @@ Every page must include YAML frontmatter with a `description` field.
 ```yaml
 ---
 description: >-
-  One sentence, 50-160 characters, stating what the reader gets from this page.
+  One to two sentences, 50-160 characters, stating what the reader gets from this page.
 ---
 ```
 
@@ -175,7 +175,7 @@ The `description` field is the meta description in search results and the snippe
 
 #### 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.
+- **One to two sentences, 50-160 characters.** Search engines truncate past roughly 160. Prefer one sentence when it earns its length; use a second only when both stay within budget and add real clarity, not padding.
 - **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.
@@ -957,7 +957,7 @@ 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 (one sentence, 50-160 characters) that includes the primary keyword naturally.
+- Every page must have a `description` in frontmatter. Write it as a standalone summary (one to two sentences, 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.
 
@@ -977,7 +977,7 @@ Before publishing any documentation, verify:
 - [ ] The change passed `.agents/references/docs-worthiness-criteria.md` — the full gate with recorded evidence for automated runs, Gate 0 (shipped and public) for human-requested pages
 - [ ] A content design plan exists per `.agents/references/content-design-plan.md` and appears in the PR body
 - [ ] An existing page was updated rather than a new page created, unless a new page is genuinely justified
-- [ ] Frontmatter includes a one-sentence description (50-160 chars) written as a standalone summary, with no filler opener
+- [ ] Frontmatter includes a one-to-two-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 `.agents/templates/`)
 - [ ] The title follows the convention for its content type (see "Titles by content type")
 - [ ] No quickstart or tutorial content is folded into a combined feature page