Overhaul docs tone guidance and rewrite platform overview as example

.agents/rules/oz-style-guidelines.md

@@ -144,6 +144,8 @@ Avoid framing Warp as:
 
 ## Voice and Style
 
+The authoritative tone rules live in the "Voice & tone" section of the docs style guide (`AGENTS.md`), including the lists of AI-generated-sounding words and structural patterns to avoid. The points below cover positioning-specific guidance.
+
 ### Do's:
 - **Talk about outcomes, not hype** - Show what changes when agents are reliable and orchestrated
 - **Emphasize control and trust** - Warp augments developers, doesn't replace them
@@ -159,6 +161,10 @@ Avoid framing Warp as:
 - Don't use corporate or disconnected language
 - Skip theoretical posts without practical value
 - Don't list features without context or problem-solving
+- Don't use AI-slop buzzwords ("seamless," "powerful," "robust," "leverage," "streamline"): name the specific capability instead
+- Don't open pages with meta-text ("This page covers...") or narrate the page's structure
+- Don't document internal architecture (orchestrators, control planes, lifecycle states): describe the user-visible model the reader acts on
+- Don't stack an em dash and a colon in the same sentence: pick one, or split into two direct sentences
 
 ## Writing Guidelines
 
@@ -172,9 +178,11 @@ Avoid framing Warp as:
 - Descriptive text and captions end in periods
 
 ### Preferred Phrases
-- ✅ "Ask Oz to..."
-- ✅ "Oz can help you..."
-- ✅ "What would you like Oz to do?"
+- ✅ "Ask the agent to..."
+- ✅ "Run an agent on the Automation Platform"
+- ✅ "The Automation Platform can run this on a schedule"
+- ❌ "Ask Oz to..." (stale: Oz was renamed to the Automation Platform on 2026-08-18)
+- ❌ "Ask the Automation Platform to..." (you ask an agent, not a platform)
 
 ## Problem Framing
 

.agents/skills/draft_conceptual/SKILL.md

@@ -29,6 +29,7 @@ These rules are specific to conceptual pages (from the "Drafting by content type
 - **Do NOT include step-by-step procedures** — link to a procedural or quickstart page instead
 - Show real-world scenarios, not just abstract descriptions
 - Title convention: noun or "About [subject]"
+- Apply the tone rules in AGENTS.md → Voice & tone: no marketing buzzwords or meta-openers, and no internal architecture the reader can't act on. Run a deletion-only "Cut again" pass before presenting the draft — a short page is a finished page.
 
 ## Heading case
 

.agents/skills/draft_docs/SKILL.md

@@ -111,7 +111,9 @@ These rules are frequently violated by agents. Apply them carefully during draft
 - **Cover team-wide and admin effects** — For integrations and team features, state who can install, whether every teammate gets access immediately, and any per-user auth or admin steps on the external system. ✅ "A Jira admin must install the app; each teammate links their own account for run attribution." ❌ setup steps that only describe the installer's happy path
 - **Section order follows reader chronology** — Prerequisites and requirements before setup, setup before usage, usage before advanced options. ✅ `## Prerequisites` → `## Set up the integration` → `## Start a run` ❌ setup steps before the reader knows what they need
 - **Keep error messages out of the main flow** — Do not weave full error strings through conceptual or procedural sections. Put them in a dedicated `## Troubleshooting` section near the end, formatted symptom → cause → fix. ✅ one Troubleshooting section with the exact error as a bold lead-in ❌ repeating the same error callout after every step
-- **Use callouts sparingly** — Prefer body prose. At most one or two callouts per page unless the content type template requires more. ✅ a single `:::note` for a non-obvious prerequisite ❌ a `:::note` / `:::tip` after every subsection
+- **Use callouts sparingly** — Prefer body prose. At most one or two callouts per page unless the content type template requires more, never two callouts back to back, and at most one per section. ✅ a single `:::note` for a non-obvious prerequisite ❌ a `:::note` / `:::tip` after every subsection
+- **No AI-ism buzzwords or meta-openers** — Never open with "This page covers/explains/walks through..."; state the thing itself. Avoid marketing adjectives (seamless, powerful, robust, comprehensive), inflated verbs (leverage, streamline, empower, unlock), restated cause-and-effect ("This process ensures..."), and recap lines. See AGENTS.md → Voice & tone for the full lists. ✅ "Run agents directly in your GitHub Actions workflows using `oz-agent-action`." ❌ "This page covers how the integration works, how to set it up, and common automation patterns."
+- **Document the user-visible model, not internal architecture** — Internal components (orchestrators, control planes, lifecycle state machines) get at most one sentence, and only when the reader can act on them. ✅ "Warp tracks every run. Check its status from the CLI, the API, or the dashboard." ❌ "The orchestration layer runs on Warp's servers (cloud control plane) and tracks lifecycle state (created → running → completed/failed)."
 - **Descriptive link text, and no dead-end pages** — Never use "here", "this page", or a bare URL as link text. End every new page with a `## Related pages` section (or the type-equivalent, such as `## Next steps` on a quickstart) containing at least one internal link whose anchor names the destination topic. ✅ `Learn more about [Codebase Context](/code/codebase-context/)` ❌ `Click [here](/code/codebase-context/)` ❌ ending a new feature page with no cross-links
 - **Disambiguate conditional and multi-clause wording** — If a sentence has two plausible readings (especially with "when", "if", "can", or stacked clauses), rewrite it so only one meaning remains. Prefer one idea per sentence. ✅ `Cloud handoff keeps your conversation's model only when that model is available in the cloud.` ❌ `Cloud handoff keeps your conversation's model when it can run in the cloud.` (keeps the model when it can? or only when cloud supports the model?)
 - **Lead instructional sentences with the action or goal** — In steps, keyboard shortcuts, and "how to" sentences, put the action or goal first, then the control or condition. Readers should not need prior context to know what values or targets you mean. ✅ `To open the searchable environment and model selectors, press Ctrl+E.` ❌ `To change either value, press Ctrl+E.` (which values?)
@@ -143,7 +145,10 @@ Before presenting the draft, verify against the quality checklist in `AGENTS.md`
 - [ ] Content follows the structure for its content type
 - [ ] Section order follows reader chronology (requirements → setup → usage → advanced → troubleshooting)
 - [ ] Error messages and failure modes live in Troubleshooting, not woven through the main flow
-- [ ] Callouts are sparse (usually 0–2 per page) and not used as a substitute for body prose
+- [ ] Callouts are sparse (usually 0–2 per page), never consecutive, and not used as a substitute for body prose
+- [ ] Prose passes the tone rules: no marketing buzzwords, no meta-openers ("This page covers..."), no restated cause-and-effect or recap lines, and it reads naturally aloud (AGENTS.md → Voice & tone)
+- [ ] Internal architecture (orchestrators, control planes, lifecycle states) appears only where the reader can act on it, and relocated detail landed on a maintainer-facing surface instead of being deleted
+- [ ] A deletion-only second pass removed framing lines, self-commentary, rule justifications, and boilerplate a parent page already covers (AGENTS.md → Voice & tone → Cut again)
 - [ ] Terminology matches the glossary (`.agents/references/terminology.md`)
 - [ ] Headers use sentence case (with proper feature name capitalization)
 - [ ] Headers name a specific topic (not bare Overview / More details / Other)

.agents/skills/draft_feature_doc/SKILL.md

@@ -27,6 +27,7 @@ These rules are specific to feature documentation pages (from the "Drafting by c
 - Apply the **procedural** rules to the step-by-step sections (motivate steps, expected outcomes, focused steps).
 - **Keep the conceptual and procedural sections clearly separated with distinct headers.** Don't let explanation creep into procedures or vice versa.
 - Title convention: feature name as noun
+- Apply the tone rules in AGENTS.md → Voice & tone: no marketing buzzwords or meta-openers, and no internal architecture the reader can't act on. Run a deletion-only "Cut again" pass before presenting the draft — a short page is a finished page.
 
 ## Heading case
 

.agents/skills/draft_quickstart/SKILL.md

@@ -31,6 +31,7 @@ These rules are specific to quickstart pages (from the "Drafting by content type
 - All procedural rules apply (focused steps, motivate steps, expected outcomes).
 - End with 2-3 actionable next steps linking to deeper content.
 - Title convention: "[Feature] quickstart" or "Quickstart for [product]"
+- **Length is the constraint, not just the tone.** A quickstart has a hard ~600-word budget — tighter than any other content type, because speed to a working result is the entire point. Cut every section that isn't on the critical path (AGENTS.md → Voice & tone → Cut again) before adding a word of new content. Also apply the general tone rules: no marketing buzzwords, no meta-openers.
 
 ## Heading case
 

.agents/skills/draft_troubleshooting/SKILL.md

@@ -30,6 +30,7 @@ These rules are specific to troubleshooting pages (from the "Drafting by content
 - Link to related troubleshooting pages and support channels.
 - Include workarounds even when no fix exists — documenting a known issue without a workaround still saves the user time searching.
 - Title convention: "Troubleshooting [feature]" or "Error: [error name]"
+- Apply the tone rules in AGENTS.md → Voice & tone: lead with the fix, not framing; no marketing buzzwords or meta-openers. Delete any category or symptom section you don't have real content for — a short page is a finished page.
 
 ## Heading case
 

.agents/skills/review-docs-pr/SKILL.md

@@ -27,7 +27,9 @@ Focus on:
 4. **Code snippets**: Verify that any code examples, commands, or configuration snippets are correct and will work as documented. If you're unsure about technical details, use the `answer_question` skill to verify against the docs or search the source code.
 5. **Astro Starlight structure**: Verify `src/sidebar.ts` updates if files were added, moved, or renamed, and that redirects are added to the `redirects` array in `vercel.json` when needed.
 6. **Product name variables**: Check whether any product names with a corresponding entry in `src/data/vars.ts` are hardcoded as literal strings instead of using `{VARS.KEY}` (prose) or `{{TOKEN}}` (frontmatter). Key strings to watch for: "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run". Flag as `⚠️ [IMPORTANT]` if a new file adds these without using the variable system. For existing files, flag as `💡 [SUGGESTION]`.
-7. **AEO/source-data fit**:
+7. **Tone and AI-isms**: Flag marketing buzzwords (seamless, powerful, robust, comprehensive, leverage, streamline), meta-openers ("This page covers/explains/walks through..."), restated cause-and-effect ("This process ensures..."), recap lines, consecutive callouts or more than one callout per section, and internal-architecture detail the reader can't act on (orchestrators, control planes, lifecycle states). Reference the "Voice & tone" section of `AGENTS.md`. Use `💡 [SUGGESTION]` for isolated instances; use `⚠️ [IMPORTANT]` when the pattern is pervasive in new content.
+8. **Length and brevity**: Flag a page that could be materially shorter, not just wordy sentences — a 2,000-word page that should be 600 is a more expensive problem than an isolated buzzword. Check whether a deletion-only "Cut again" pass (AGENTS.md → Voice & tone → Cut again) happened before the page was split into sub-pages, since splitting a bloated page produces two bloated pages. Use `💡 [SUGGESTION]` unless the page is far outside its content type's expected length, then use `⚠️ [IMPORTANT]`.
+9. **AEO/source-data fit**:
 
 Provide actionable, constructive feedback. Focus on documentation quality issues, not code bugs.
 

.agents/skills/style_lint/SKILL.md

@@ -63,24 +63,36 @@ python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr
 - **Warp Factories naming**: A bare capitalized "Factory" used as a proper noun. "Warp Factories" is the product and is written in full; an individual "factory" is lowercase. Sentence-, heading-, bullet-, quote-, and cell-initial capitals are positional and stay, as do frontmatter titles and labels, the shipped feature name "Factory MCP", and verbatim UI strings such as **Factory name** and **Add your Factory to your team**. Regression cases live in `test_factory_proper_noun.py`.
 - **Hardcoded product name strings**: Product name strings that have a corresponding key in `src/data/vars.ts` but appear as literal text rather than variable syntax. Reports instances of known strings like "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run" (any value currently in `src/data/vars.ts`) in body prose and frontmatter. These are flagged as `⚠️ [IMPORTANT]` in PR context and reported (not auto-fixed) — they should use `{VARS.KEY}` in prose and `{{TOKEN}}` in frontmatter.
 
+### Tone checks (report-only, never auto-fixed)
+
+These enforce the "Voice & tone" section of `AGENTS.md`. Every hit needs a human rewrite, so they are always warnings and never auto-fixed:
+
+- **Buzzwords** (`tone-buzzword`): AI-ism words like "seamless", "powerful", "robust", "comprehensive", "leverage", "streamline", "empower", "delve", abstract metaphors ("landscape", "realm", "tapestry", "testament to"), and filler frames ("it's important to note", "designed to", "ensures that", "allows you to", "in order to"). Words with legitimate technical uses in these docs ("harness", "unlock", "elevated", "journey") are deliberately excluded from the lint and covered by prose guidance only.
+- **Meta-openers** (`tone-meta-opener`): Page-narrating text like "This page covers/explains/walks through...". The fix is to cut the sentence and state the thing itself.
+- **Consecutive callouts** (`callout-consecutive`): Two `:::` asides back to back with nothing between them. Merge them or move one into body prose.
+- **Callout budget** (`callout-density`): More than 4 callouts on one page. The style guide allows at most one per section; the per-page count is the lintable proxy.
+
 ## Auto-fix behavior
 
 When run with `--fix`:
 - **High-confidence fixes applied automatically**: Settings path format, UI element format, product name casing, external product name casing
 - **Low-confidence issues reported but not auto-fixed**: link quality, VideoEmbed title specificity, list format, header case (due to feature name exceptions), ambiguous terminology
+- **Tone checks are never auto-fixed**: buzzwords, meta-openers, and callout budget issues always need a human rewrite
 
 ## Relationship to validate_ui_refs
 
 This skill checks broader formatting and terminology. The `validate_ui_refs` skill validates UI paths and Command Palette names against the warp-internal codebase. They complement each other with no overlap. Both can run in scheduled cloud agent workflows.
 
 ## Tests
 
-Two checks have regression suites, because both are narrow rules where the hard
-part is not firing on legitimate text. Run them after touching either check:
+Three checks have regression suites, because each is a narrow rule where the
+hard part is not firing on legitimate text. Run them after touching any of
+these checks:
 
 ```bash
 python3 .agents/skills/style_lint/test_platform_determiner.py
 python3 .agents/skills/style_lint/test_factory_proper_noun.py
+python3 .agents/skills/style_lint/test_tone_checks.py
 ```
 
 ## Dependencies