diff --git a/.agents/rules/oz-style-guidelines.md b/.agents/rules/oz-style-guidelines.md index 99675b24d..56449717f 100644 --- a/.agents/rules/oz-style-guidelines.md +++ b/.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,9 @@ 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 ## Writing Guidelines @@ -172,9 +177,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 diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 782d2f357..9799a7c83 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.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) diff --git a/.agents/skills/review-docs-pr/SKILL.md b/.agents/skills/review-docs-pr/SKILL.md index cb54d4144..20e67a5de 100644 --- a/.agents/skills/review-docs-pr/SKILL.md +++ b/.agents/skills/review-docs-pr/SKILL.md @@ -27,7 +27,8 @@ 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. **AEO/source-data fit**: Provide actionable, constructive feedback. Focus on documentation quality issues, not code bugs. diff --git a/.agents/skills/style_lint/SKILL.md b/.agents/skills/style_lint/SKILL.md index 94c45f25f..97444efa8 100644 --- a/.agents/skills/style_lint/SKILL.md +++ b/.agents/skills/style_lint/SKILL.md @@ -63,11 +63,21 @@ 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", and filler frames like "it's important to note". 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 diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index 014dad031..5358d1505 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -195,6 +195,46 @@ (r"\b[Aa]mbient [Aa]gents?\b", "Use 'cloud agent(s)' — 'ambient' is no longer a product term"), ] +# Tone: AI-generated-sounding words from AGENTS.md → Voice & tone → "Words to +# avoid". Report-only (never auto-fixed): every hit needs a human rewrite that +# names the specific capability, not a mechanical substitution. +# +# Deliberately narrower than the prose guidance. Words with legitimate +# technical uses in these docs are excluded so warnings stay trustworthy: +# "harness" (agent harness), "unlock" (login/keychain unlock), "elevate(d)" +# (elevated permissions), and "journey" stay out of the lint and are covered +# by AGENTS.md only. +TONE_BUZZWORDS: List[Tuple[str, str]] = [ + (r"\bseamless(?:ly)?\b", "Marketing adjective; describe the specific behavior instead"), + (r"\beffortless(?:ly)?\b", "Marketing adjective; describe the specific behavior instead"), + (r"\bpowerful\b", "Marketing adjective; name what the feature does instead"), + (r"\brobust\b", "Marketing adjective; name what the feature does instead"), + (r"\bcomprehensive(?:ly)?\b", "Marketing adjective; say what is included instead"), + (r"\bcutting-edge\b", "Marketing adjective; delete it or name the capability"), + (r"\bgame-chang\w+\b", "Marketing adjective; delete it or name the capability"), + (r"\bsupercharg\w+\b", "Marketing verb; name the specific improvement instead"), + (r"\bleverag(?:e|es|ed|ing)\b", "Use 'use'"), + (r"\bstreamlin(?:e|es|ed|ing)\b", "Say what gets shorter or removed instead"), + (r"\bempower(?:s|ed|ing)?\b", "Use 'let' or name the capability"), + (r"\bdelv(?:e|es|ed|ing)\b", "Use 'cover' or name the topic directly"), + (r"\btapestry\b", "Abstract metaphor; name the concrete thing"), + (r"\btestament to\b", "Filler phrase; state the fact directly"), + (r"\b(?:it'?s|it is) (?:important to note|worth noting)\b", "Filler frame; cut it and state the fact directly"), +] + +# Tone: meta-text that narrates the page instead of stating the thing itself. +# AGENTS.md → Voice & tone → "Every sentence earns its place". +META_OPENER = re.compile( + r"\bThis (?:page|guide|section|article|document) (?:covers|explains|describes|walks(?: you)? through)\b" +) + +# Starlight aside fences, for the callout-budget checks. +CALLOUT_OPEN = re.compile(r"^\s*:::(note|tip|caution|danger)\b") +CALLOUT_CLOSE = re.compile(r"^\s*:::\s*$") +# More callouts than this on one page almost always means caveats that belong +# in body prose. AGENTS.md allows at most one callout per section. +CALLOUT_PAGE_BUDGET = 4 + # Action verbs that precede UI elements (should be bold, not backtick) UI_ACTION_VERBS = r"(?:click|select|toggle|enable|disable|choose|check|uncheck|expand|collapse|open|close|tap)" @@ -1274,6 +1314,111 @@ def check_factory_proper_noun(lines: List[str], filepath: str) -> List[Issue]: return issues +# --------------------------------------------------------------------------- +# Tone checks (report-only, never auto-fixed) +# --------------------------------------------------------------------------- + +def _strip_inline_code(line: str) -> str: + """Remove inline code spans so CLI flags and API fields never trip tone checks.""" + return re.sub(r"`[^`]*`", "", line) + + +def check_tone_buzzwords(lines: List[str], filepath: str) -> List[Issue]: + """Flag AI-ism buzzwords (AGENTS.md → Voice & tone → Words to avoid). + + Report-only: the fix is a rewrite that names the specific capability, + which cannot be automated. Frontmatter is scanned too — a buzzword in a + description is still a buzzword in search results. + """ + issues = [] + in_code_block = False + for i, line in enumerate(lines, 1): + stripped = line.strip() + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block: + continue + prose = _strip_inline_code(line) + for pattern, suggestion in TONE_BUZZWORDS: + for m in re.finditer(pattern, prose, re.IGNORECASE): + issues.append(Issue( + filepath, i, "tone-buzzword", + f'"{m.group(0)}": {suggestion}', + "warning", + )) + return issues + + +def check_meta_openers(lines: List[str], filepath: str) -> List[Issue]: + """Flag meta-text that narrates the page ("This page covers..."). + + The title and description already frame the page; body prose should state + the thing itself. AGENTS.md → Voice & tone → Every sentence earns its place. + """ + issues = [] + in_code_block = False + for i, line in enumerate(lines, 1): + stripped = line.strip() + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block: + continue + if META_OPENER.search(_strip_inline_code(line)): + issues.append(Issue( + filepath, i, "tone-meta-opener", + "Meta-text that narrates the page ('This page covers...'). " + "Cut it and state the thing itself", + "warning", + )) + return issues + + +def check_callout_density(lines: List[str], filepath: str) -> List[Issue]: + """Flag back-to-back callouts and pages over the callout budget. + + AGENTS.md → Callouts and hints: never consecutive, at most one per + section. Per-page count is the lintable proxy for the per-section rule. + """ + issues = [] + in_code_block = False + in_callout = False + open_lines: List[int] = [] + last_close_line: Optional[int] = None + for i, line in enumerate(lines, 1): + stripped = line.strip() + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block: + continue + if not in_callout and CALLOUT_OPEN.match(line): + open_lines.append(i) + if last_close_line is not None and all( + not lines[j].strip() for j in range(last_close_line, i - 1) + ): + issues.append(Issue( + filepath, i, "callout-consecutive", + "Two callouts back to back; merge them or move one into " + "body prose (AGENTS.md → Callouts and hints)", + "warning", + )) + in_callout = True + continue + if in_callout and CALLOUT_CLOSE.match(line): + in_callout = False + last_close_line = i + if len(open_lines) > CALLOUT_PAGE_BUDGET: + issues.append(Issue( + filepath, open_lines[CALLOUT_PAGE_BUDGET], "callout-density", + f"{len(open_lines)} callouts on one page; keep to at most one per " + "section and move the rest into body prose", + "warning", + )) + return issues + + # Cache glossary terms once at module level _glossary_cache: Optional[set] = None @@ -1299,6 +1444,9 @@ def run_all_checks(filepath: Path) -> List[Issue]: issues.extend(check_screenshot_widths(lines, str(filepath))) issues.extend(check_video_embed_titles(lines, str(filepath))) issues.extend(check_callout_syntax(lines, str(filepath))) + issues.extend(check_tone_buzzwords(lines, str(filepath))) + issues.extend(check_meta_openers(lines, str(filepath))) + issues.extend(check_callout_density(lines, str(filepath))) issues.extend(check_product_casing(lines, str(filepath))) issues.extend(check_oz_terms(lines, str(filepath))) issues.extend(check_deprecated_terms(lines, str(filepath))) diff --git a/AGENTS.md b/AGENTS.md index 86dfd21ba..a4b11b55f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,9 +11,77 @@ This guide establishes standards for writing Warp documentation. It covers voice ### Voice & tone - **Professional yet approachable**: Write with authority but remain accessible to developers of all skill levels - **Direct and action-oriented**: Lead with what users can accomplish, not just what features exist -- **User-focused**: Use second person ("you can", "allows you to") rather than passive voice +- **User-focused**: Use second person ("you") and active voice - **Confident without jargon**: Explain technical concepts clearly without oversimplifying -- **Avoid copy that reads as AI-generated**: Watch for over-explained cause-and-effect, excessive hedging, or the same rhetorical pattern repeated across sections. Read a paragraph aloud — if it doesn't sound like something a person would say to a colleague, rewrite it plainly. +- **Plain over polished**: Prefer the short word and the declarative sentence. A page should read like a capable colleague explaining something, not like a spec or a launch post. + +Our reference points are the GitHub and Vercel docs: short declarative sentences, concrete examples, restrained formatting, and no selling. + +#### Define, show, link +Introduce a concept in one to three plain sentences, give a concrete example, then link out for depth. Repeat that pattern instead of front-loading the page with context. +- ✅ "A workflow is an automated process that runs one or more jobs. For example, a workflow can label new issues automatically. For more information, see [Writing workflows](...)." +- ❌ "Before diving into the components, it helps to align on a few terms:" followed by a glossary of everything the page explains later anyway. + +#### Document the user-visible model, not our architecture +Describe what the reader sees and does. Internal components get at most one sentence, and only when the reader can act on them. GitHub Actions runs on an orchestrator and a control plane; its docs never mention either. They describe workflows, events, jobs, and runners, because those are what users touch. +- ✅ "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), creates tasks when triggers fire, and tracks lifecycle state (created → running → completed/failed)." + +This is the voice-level version of "Don't over-specify counts or internals that will drift" (see General guidance): internals aren't just a staleness risk, they're noise between the reader and the task. + +When a page carries real information in the wrong register (provenance, pinned versions, maintainer process), relocate it to the surface whose audience needs it: a reference page, a script docstring, a code comment. Leave a pointer if the reader might follow the thread. Cutting for tone must not lose facts; it changes where they live. + +#### Every sentence earns its place +Cut sentences that narrate the page, restate what the reader just read, or explain the obvious consequence of the previous sentence. +- **No meta-openers** - Never open with "This page covers/explains/walks through...". The title and description already frame the page; state the thing itself. + - ✅ "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 for development teams." +- **No restated cause-and-effect** - Don't follow a fact with a sentence explaining why that fact is good. + - ✅ "The container is destroyed after each run, so every run starts clean." + - ❌ "The container is destroyed after each run. This process ensures every run starts from the same baseline, making results reproducible and debugging straightforward." +- **No recap lines** - Don't end a section by summarizing it ("In practice: triggers create tasks; tasks produce outputs."). +- **Say it once** - Don't repeat a caveat or definition across multiple sections of the same page. Put it where it matters most. The same goes for sibling pages: boilerplate like validation steps or shared prerequisites lives once on the parent or reference page, linked from the rest. + +#### Words to avoid +These words are the strongest tell of an AI-generated draft and rarely add meaning. Replace them with the specific fact they're hiding, or delete them. +- **Marketing adjectives** - seamless(ly), powerful, robust, comprehensive, effortless, cutting-edge, game-changing, supercharged +- **Inflated verbs** - leverage (→ use), streamline (→ remove steps), empower (→ let), unlock (→ name the capability, or delete), delve into (→ cover), elevate, harness +- **Filler frames** - "designed to", "ensures that", "allows you to", "it's important to note", "it's worth noting", "in order to" (→ to) +- **Abstract dramatics** - landscape, realm, journey, tapestry, testament to + +**Examples:** +- ✅ "The agent runs in your CI pipeline. It can review code, triage issues, and fix failing checks." +- ❌ "The agent integrates seamlessly into your CI pipeline, automating tasks like code review, issue triage, bug fixing, and maintenance." + +If the claim is true, the reader notices without the adjective. If it isn't, the adjective won't save it. + +#### Structural patterns to avoid +AI-drafted pages share a rhythm. Break it. +- **Rule-of-three padding** - Triplets of adjectives or clauses used for cadence rather than information ("scalable, autonomous, and auditable"). Keep the items that carry weight and cut the rest. +- **Rhetorical question openers** - Don't open a section with a question you immediately answer. Use a descriptive header and a declarative first sentence. +- **Hedging stacks** - Chains of "typically", "often", "generally", "where supported", and "as applicable" read as evasive. State what happens, then note the exception if there is one. +- **Bold-everything** - Bolding several phrases per paragraph kills emphasis. Reserve bold for UI elements and lead terms of list items (see Emphasis). +- **Bullets as a substitute for prose** - Bullets are for short, parallel, scannable items. If every bullet is a full paragraph, or the bullets tell a story in order, write prose. +- **Slashed shorthand** - Write "mentions and assignments", not "mention/assignment", and "4 vCPU / 8 GB", not "4/8". Slashed pairs and bare number pairs read as notes, not prose. +- **Callout spam** - Callouts follow the same restraint: never consecutive, at most one per section (see Callouts and hints). + +#### Keep the author out of it +The reader came for the product, not the writer's presence in the page. +- **No self-commentary** - Don't narrate authorial intent: "deliberately unremarkable", "each prompt is worth reading", "that is the point of this example". State the fact and let it stand. +- **State rules calmly, once** - Defensive phrasing ("Do not describe or imply otherwise", "CI green is not the bar") argues with an imagined reader. Write the rule once, plainly, and give a reason only when the reason changes what the reader does. +- **Describe the present** - Write how the product works now. Renames and history belong in time-boxed transition notes or the changelog, not woven through pages ("the built-in harness is the Warp Agent harness", not "Oz is retired product language"). + +#### The read-aloud test +Read the paragraph aloud. If it doesn't sound like something you'd say to a colleague, rewrite it plainly. This catches over-explained cause-and-effect, hedging, and repeated rhetorical patterns faster than any checklist. + +#### Cut again +A plain-language rewrite still under-cuts on the first pass. Follow it with a deletion-only pass that removes: +- Framing lines that describe the docs instead of the product ("Each example demonstrates one concept"). +- Explanations of command output that the command already prints, or that a linked page already owns. +- Recaps and comparison sections that restate what the reader just read. +- Justifications for rules and defaults that don't change what the reader does. + +Expect the second pass to find real deletions even after a careful first one; review feedback on past copy passes has consistently asked for more cutting, not less. ### Language guidelines - Use consistent terminology throughout (see [Terminology standards](#terminology-standards) and the full glossary in `.agents/references/terminology.md`) @@ -306,7 +374,12 @@ For important caveats, limitations, or things to watch out for ::: ``` -Use callouts sparingly. A page with 5+ callouts loses its visual impact. +Use callouts sparingly: +- Never place two callouts back to back, and keep to at most one per section. +- Keep callouts to a sentence or two. Information that needs a list or several sentences belongs in the body under a header. +- A caveat that applies to one step belongs in that step's prose, not in a callout. + +Callouts interrupt the reader. Each one spends attention the page can't get back. ### Placeholders and dynamic text - Use ALL_CAPS for placeholder values in commands: `git clone REPO_URL` diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index 70d0dc4ec..8d7521d6f 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -82,7 +82,7 @@ Host options: * **[Self-hosted](/platform/self-hosting/)** – You provide the infrastructure (runners in your cloud or network). Best for compliance requirements, on-premise execution, or custom hardware needs. * Local (coming soon) – Run environments on your local machine for sandbox development and testing. -The same environment can run on different hosts with identical behavior. For more details on hosting options, see [Deployment Patterns](/platform/deployment-patterns/) and [execution hosts](/platform/overview/#execution-hosts). +The same environment can run on different hosts with identical behavior. For more details on hosting options, see [Deployment Patterns](/platform/deployment-patterns/) and [hosts](/platform/overview/#hosts). ### What happens at runtime diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index b4f315516..2e0fe0882 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -1,15 +1,17 @@ --- title: "{{WARP_AUTOMATION_PLATFORM}} overview" description: >- - The {{WARP_AUTOMATION_PLATFORM}} provides the CLI, API/SDK, orchestration, environments, and - observability for cloud agents. + How cloud agent runs work on the {{WARP_AUTOMATION_PLATFORM}}: triggers start + tasks, tasks run in environments on a host, and every run leaves a record. sidebar: label: "{{WARP_AUTOMATION_PLATFORM}}" --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Cloud agents run on the **{VARS.WARP_AUTOMATION_PLATFORM}**. The platform gives you a consistent way to **trigger work**, **orchestrate and track tasks**, **execute agents** (in an optional [environment](/platform/environments/), on a host), and inspect outcomes with team visibility. First-party [integrations](/platform/integrations/) connect external events — like Slack messages, GitHub PRs, or CI failures — to cloud agents automatically. +[Cloud agents](/platform/) run on the {VARS.WARP_AUTOMATION_PLATFORM}. You define the work (a prompt or a skill) and what starts it, and the platform runs the agent and records what it did. For example, an agent can triage each new issue as it's filed, or start fixing a build the moment CI fails. + +If you're new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes. {/* Transition notice for the 2026-08-18 rename. Remove after 2026-09-15, when the CLI and web app take their new names and the old one stops appearing. */} @@ -21,287 +23,62 @@ The `oz` CLI and the {VARS.WEB_APP} keep the Oz n -:::note -**New to cloud agents?** Start with the [Cloud agents quickstart](/platform/quickstart/) to run your first agent in ~10 minutes. -::: +## How a run works -**Most production setups follow the same flow:** +Every run follows the same path, whatever starts it: -1. A **trigger** fires (schedule, integration event, CI step, webhook, API call, or manual run). -2. Warp's **orchestration layer** creates a cloud agent task and tracks its lifecycle. -3. The agent executes on a **host**, optionally inside an environment, using the required configuration and credentials. -4. The task produces a **persistent record** (status, metadata, transcript, outputs) your team can review and manage. +1. A **trigger** fires: a schedule, an integration event like a Slack mention or a CI failure, an API call, or a manual start. +2. Warp creates a **task**, the tracked record of the run. The trigger's context travels with it: the Slack thread, the PR metadata, the CI logs. +3. The agent executes on a **host**, optionally inside an [environment](/platform/environments/) that defines its image, repos, and setup. +4. The task produces **outputs**: a pull request, a Slack reply, a report, or just a transcript and summary. ![Flow diagram: a trigger kicks off an agent, which runs in an environment and creates artifacts, on either Warp-hosted or self-hosted infrastructure](../../../assets/agent-platform/most-flexible-platform-for-building-with-agents.png) -![Architecture diagram: Warp-designed and customer-defined triggers create an agent task, which the agent orchestrator routes to agent runners on Warp or customer infrastructure](../../../assets/agent-platform/platform-architecture.png) - -The sections below describe the {VARS.WARP_AUTOMATION_PLATFORM} primitives that power this flow, and how they compose. - ---- - -### Key concepts - -Before diving into the components, it helps to align on a few terms: - -* **Trigger**: The event that starts work (for example: cron, Slack mention, PR opened, CI failure, “run now”). -* **Task:** The unit of work Warp tracks. A task includes inputs, state, metadata, and an execution record (where it ran, what it did, and what it produced). -* **Context**: Additional inputs attached to a task (for example: a Slack message, PR metadata, CI logs, repository diffs). -* **Outputs:** What the task produced (for example: created a PR, posted a Slack reply, emitted a report, or just a transcript + summary). - -In practice: **triggers create tasks; tasks execute on a host (optionally in an environment); tasks produce outputs.** - ---- - -### Warp Factories - -[Warp Factories](/factories/) builds on the primitives described on this page to run persistent, multi-agent development workflows. A factory coordinates specialized cloud agents that move each work item through triage, specification, implementation, and review. It's in Early Access — [request access](https://www.warp.dev/factories/request-access) to use it with your team. - ---- - -### CLI - -The [{VARS.WARP_AGENT_CLI}](/reference/cli/) is the **headless interface** for running agents in non-interactive mode. It's commonly used in CI, scripts, and server environments where there is no interactive UI. For interactive workflows, use the [agent](/agents/) embedded in Warp's desktop app. - -A key property of the CLI is that it is **cloud-connected**. Even when an agent is started on a local machine or in CI, it reports progress to Warp’s servers. This enables team visibility, session sharing (where supported), and programmatic tracking through the API. - -#### When to use the CLI - -Use the CLI when: - -* You want to run an agent anywhere (local machine, CI runner, remote dev box, server). -* An external system is orchestrating runs (for example GitHub Actions, custom automation, incident tooling). -* You want task observability and auditing without requiring Warp desktop. - -#### How the CLI fits into cloud agent runs - -Depending on the command, the CLI typically: - -* Authenticates as you (or as a member of your team, if applicable). -* Starts work by creating a task in the orchestrator (either directly via CLI commands, or indirectly via an integration/schedule). -* Streams progress back to Warp for live observability and a persistent record. -* Optionally attaches an environment and other configuration. - -#### Example (no environment) +## Integrations and triggers -You can also run an agent locally without an environment using a command like: +Every run starts with a trigger. [Integrations](/platform/integrations/) turn events in other tools into runs: mention @warp in [Slack](/platform/integrations/slack/) and the agent gets the message and its thread, or run agents inside your [GitHub Actions](/platform/integrations/github-actions/) workflows with your CI context. [Scheduled agents](/platform/triggers/scheduled-agents/) start runs on a cron schedule. For event sources Warp doesn't cover, receive the event in your own system and start the run through the [API](/reference/api-and-sdk/); it becomes a normal, fully tracked task. -```bash -oz agent run ... -``` +Set up a first-party integration with `oz integration create` on the {VARS.WARP_AGENT_CLI}; the [integration setup guide](/reference/cli/integration-setup/) covers it end to end. ---- - -### Warp Orchestrator - -The orchestration layer manages the lifecycle of cloud agent tasks. It creates tasks, tracks state transitions, and is the system of record for what’s running and what ran. - -#### What the orchestrator does - -The orchestrator: - -* Runs on Warp's servers (cloud control plane). -* Creates tasks when triggers fire (integrations, schedules, API calls, or explicit starts). -* Tracks lifecycle state (created → running → completed/failed) and associated metadata. -* Exposes task lifecycle operations via the [{VARS.WARP_AGENT_CLI}](/reference/cli/) and a [REST API](/reference/api-and-sdk/) (create tasks, query history, and inspect status/outputs). -* Powers SDKs (TypeScript/Python) for programmatic usage on top of the orchestrator API. -* Supports [multi-agent orchestration](/platform/orchestration/) for parent/child workflows, fan-out, and review swarms. - -#### When teams use the API/SDK - -Teams typically use the API/SDK when: - -* Triggering agents from custom internal systems (incident tools, bots, internal automation). -* Building internal dashboards or monitoring (success rates, runtime, failure reasons). -* Coordinating many runs (fanout, sharding, queueing, retries, rate limiting at the app layer). -* Creating higher-level workflows that treat tasks as building blocks. - ---- - -### Environments - -[Environments](/platform/environments/) define the execution context an agent should run in. - -**An Environment typically includes:** - -* A Docker image (toolchain and runtime). -* One or more repositories (or a workspace definition). -* Startup commands and configuration (setup steps, dependency install, bootstrapping). -* Optional environment variables and other runtime settings. - -:::note -Environments are how teams make agent runs consistent across triggers (Slack, CI, schedules) and across hosts. -::: - -#### Environments are optional - -Agents can run without an environment (for example, against an existing local checkout or a CI workspace). Teams usually move to environments when they want stronger reproducibility, isolation, and standardization. - -#### When to use environments - -Environments are recommended when: - -* The agent needs a consistent toolchain (linters, build tools, language runtimes). -* You want repeatable execution across CI and cloud execution. -* You want standard execution across a team (same repo state rules, same setup steps). -* You want to reduce “works on my machine” variability across tasks. - ---- +## Tasks and tracking -### API and SDK +Warp tracks every run as a task: its status, transcript, and outputs stay available after the run finishes. Watch or steer a live run with [session sharing](/agents/local-agents/session-sharing/), browse history in the [management UI](/platform/managing-cloud-agents/), or query it from the [{VARS.WARP_AGENT_CLI}](/reference/cli/) and the [API](/reference/api-and-sdk/). Access control decides who can run, view, or intervene in tasks. -The {VARS.WARP_AUTOMATION_PLATFORM} [Agent API](/reference/api-and-sdk/) is the HTTP interface to the {VARS.WARP_AUTOMATION_PLATFORM}. It lets you create and inspect cloud agent tasks from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. +To fan work out across parent and child agents, see [multi-agent orchestration](/platform/orchestration/). -**What you can do with the API** +## Environments -* Run an agent by submitting a prompt plus optional configuration (model, environment, MCP servers, base prompt, etc.). -* Monitor execution by listing tasks and tracking state transitions over time (for example: `QUEUED` → `INPROGRESS` → `SUCCEEDED/FAILED`). -* Inspect results and provenance by fetching a task’s full details, including the original prompt, creator/source metadata, session link, and resolved agent configuration. - -**SDKs** - -Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDKs](https://github.com/warpdotdev/oz-sdk-typescript) that wrap the {VARS.API_SDK_NAME} with: - -* Typed requests/responses (autocomplete, fewer schema mistakes) -* Built-in retries and timeouts (with per-request overrides) -* Consistent error types mapped to API status codes -* Helpers for raw responses when you need headers/status/custom parsing - -If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the [SDKs](/reference/api-and-sdk/) are typically the quickest and safest starting point. - -**SDK vs raw REST** - -* Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns. -* Use raw REST when you want minimal dependencies or full control over your HTTP client. - -:::note -For full endpoint semantics and schema definitions, see the dedicated [API docs](/reference/api-and-sdk/) and Models/Schema reference, plus the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repos for the latest usage/examples. -::: - ---- - -### Execution hosts - -A host describes where the agent actually executes. Warp supports multiple execution models depending on your security, compliance, and operational requirements. - -#### Warp-hosted execution - -With Warp hosting: - -* Warp runs the environment on Warp-managed infrastructure. -* This is the default model for teams that want the simplest setup and do not need execution to occur inside their network boundary. -* For more details, see [Warp-hosted execution](/platform/warp-hosting/). - -#### Self-hosted execution - -With self-hosting: - -* The agent runs on customer-managed infrastructure. -* The {VARS.WARP_AUTOMATION_PLATFORM} orchestrator still manages lifecycle and observability. -* This is used when teams want code and execution to remain on their own systems rather than being cloned or executed in Warp's cloud. - -:::note -**Enterprise feature**: Self-hosted execution requires an Enterprise plan. See [Self-hosting](/platform/self-hosting/) for setup instructions. -::: - ---- - -### Integrations - -[Integrations](/platform/integrations/) connect external events to cloud agent tasks. When an event occurs in a third-party system, Warp creates a task with the relevant context and starts it automatically. - -Warp supports two integration models: - -* **First-party integrations** — Warp manages the event subscription and context extraction end to end. -* **Custom integrations** — you handle event ingestion and filtering, then call the API or SDK to create tasks. - -#### First-party integrations - -First-party integrations can be configured with a simple setup flow (for example via CLI): - -```bash -oz integration create … -``` - -Warp registers webhooks with the third-party system, receives events, extracts context (payload, metadata, links, logs), and creates a task — optionally in an [Environment](/platform/environments/). - -Examples of context extracted by first-party integrations: - -* [Slack](/platform/integrations/slack/): message text, channel, thread, and user identity -* [GitHub](/platform/integrations/github-actions/): PR metadata, diffs, labels, and check results -* CI: logs, job metadata, and artifacts - -#### Custom integrations - -With custom integrations, you own the webhook and event-handling logic. Your system receives an event, applies any filtering or enrichment you need, and then calls the API (directly or via an SDK) to create a task. The resulting task is still a full cloud agent run — observable, manageable, and auditable like any other. - -Custom integrations are a good fit when: - -* You have internal event sources (custom tooling, proprietary systems). -* You need custom filtering, routing, or enrichment before triggering an agent. -* You want to implement your own permissioning, queueing, or governance around triggers. - ---- - -### Secrets - -Cloud agents often need credentials to access external systems (APIs, cloud providers, databases, internal tools, MCP servers). Warp provides a [secrets store](/platform/secrets/) that can inject secrets at runtime so agents can use authenticated tools without exposing secret values in logs or UI. - -#### What secrets are for - -In most deployments, secrets power: - -* API keys and tokens (GitHub, Slack, Linear, internal APIs). -* Shared team credentials (cloud providers, CI identities). -* Database credentials (read-only query bots, reporting). -* Credentials required by MCP servers (static tokens/keys). - -#### Scoping and control - -Today, secrets support two scopes: - -* **Team secrets:** shared credentials available to the team (useful for shared infrastructure). -* **Personal secrets**: credentials tied to an individual (useful when actions must be attributable to a specific person). - ---- +An [environment](/platform/environments/) defines what a run needs: a Docker image with your toolchain, the repositories to clone, and setup commands. Automated runs (integrations, schedules, API calls) use an environment so every run starts from the same setup; interactive local runs use your machine as-is and don't need one. Define one environment per codebase and reuse it across triggers. -### Management and observability +## Hosts -Cloud agents are designed so task execution is visible to the team. +A host is where the agent executes. By default runs execute on [Warp-hosted infrastructure](/platform/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/platform/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs. -While a task is executing, the agent reports progress and status back to Warp. After completion, the task retains a persistent record for review and debugging. +![Architecture diagram: Warp-designed and customer-defined triggers create an agent task, which is routed to agent runners on Warp or customer infrastructure](../../../assets/agent-platform/platform-architecture.png) -Warp provides multiple surfaces for observability: +## The CLI -* [Management UI](/platform/managing-cloud-agents/): lists tasks, status, timing, metadata, and history. -* [Agent Session Sharing](/agents/local-agents/session-sharing/): authorized teammates can attach to a running task to monitor and, where supported, steer it. -* [APIs](/reference/api-and-sdk/) and SDKs: query task history, build monitoring, and generate reports. +The [{VARS.WARP_AGENT_CLI}](/reference/cli/) starts and manages runs where there's no UI: CI jobs, scripts, and remote servers. Start a run with `oz agent run`, and it reports progress to Warp like any other task, so work that starts on a CI runner shows up alongside everything else your team runs. For interactive sessions, use [agents in the Warp app](/agents/). -#### Access control +## API and SDKs -**Access control is part of the model:** +The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. -* Teams can restrict who can run, view, or intervene in agent tasks. -* At the same time, organizations can enable system-wide visibility where appropriate for auditing and operations. +## Secrets -### Centralized configuration +Agents often need credentials for APIs, cloud providers, databases, and MCP servers. Store them as [secrets](/platform/secrets/), and Warp injects them at runtime without exposing the values in logs or the UI. Secrets can be scoped to the whole team or to one person. -Cloud agent setups often include shared configuration such as: +## Shared configuration -* [MCP Servers](/platform/mcp/) -* [rules / guardrails](/agents/capabilities/rules/) -* [saved prompts](/knowledge-and-collaboration/warp-drive/prompts/) -* [environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/) -* [secrets](/platform/secrets/) +Runs pick up your team's shared setup no matter what triggered them: [MCP servers](/platform/mcp/), [rules](/agents/capabilities/rules/), [saved prompts](/knowledge-and-collaboration/warp-drive/prompts/), and [environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/). Configure these once and every trigger uses them. -Warp supports centralized configuration so these settings apply consistently regardless of where a task is launched. +## Warp Factories -This is especially useful when the same workflow can be triggered from multiple places (for example Slack, CI, and schedules). Instead of duplicating setup across systems, teams can keep configuration in one place and reuse it across triggers. +[Warp Factories](/factories/) builds on these pieces to run persistent, multi-agent development workflows: specialized cloud agents move each work item through triage, specification, implementation, and review. It's in Early Access. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. -### Where to go next +## Where to go next -* [Cloud agents](/platform/) — what cloud agents are, how they get triggered, and how to run them with or without the Warp app. -* [Cloud agents quickstart](/platform/quickstart/) — run your first cloud agent in about ten minutes. -* [Warp Factories](/factories/) — build a software factory on these primitives. -* [Environments](/platform/environments/) — define the toolchain and repos a run executes against. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — drive the platform programmatically. +* [Cloud agents](/platform/) - what cloud agents are, how they get triggered, and how to run them with or without the Warp app. +* [Cloud agents quickstart](/platform/quickstart/) - run your first cloud agent in about ten minutes. +* [Environments](/platform/environments/) - define the toolchain and repos a run executes against. +* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - drive the platform programmatically.