chore: gate factory launch - #508
Merged
Merged
Conversation
Placeholder commit to open a draft PR that will gate the factory launch. Co-Authored-By: Warp Agent <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…ab scaffold (#513) * feat: scaffold Factories tab and Automation Platform rename infra - Add new top-level Factories sidebar topic with 6 stub pages (Overview, Quickstart, How Factories work, Configure your Factory, Connect your Factory, Infrastructure & security) per HYC's IA doc - Relabel the Oz tab to Automation Platform and reorganize its 10 subsections into 6 groups (Cloud Agents, Environments, Integrations, Orchestration, Self-hosting, API/SDK); all page slugs unchanged - Add vars.ts entries: API_SDK_NAME (rename-sensitive) and FACTORY_WEB_APP/FACTORY_WEB_APP_URL (net-new, for platform.warp.dev) - Extend style_lint.py RENAME_SENSITIVE_VAR_STRINGS to catch bare "Oz" and "Oz Platform", with longest-match dedup so specific matches (Oz CLI, Oz Platform, etc.) aren't double-flagged by the general bare "Oz" entry - Add Automation Platform + Warp Factories terminology.md entries - Migrate platform/index.mdx prose to the vars system - Add redirect for /platform/software-factory -> /factories/ (content migration to the new tab flagged for HYC, not deleted) Co-Authored-By: Warp Agent <agent@warp.dev> * docs: migrate hardcoded Oz product names to vars in agents/terminal/getting-started Replace hardcoded rename-sensitive Oz-branded strings (Oz, Oz CLI, Oz web app, Oz API, Oz API & SDK, Oz Platform, Oz run) with {VARS.*} references in body prose (and {{TOKEN}} in frontmatter) across: - src/content/docs/agents/** - src/content/docs/terminal/comparisons and terminal/input/classic-input - src/content/docs/getting-started/migrate-to-warp-from-claude-code - src/content/docs/index.mdx and quickstart.mdx Left unmigrated (intentional, per scope): image alt/figcaption text that transcribes actual on-screen branding of existing screenshots/graphics, and Oz mentions inside fenced code blocks (example prompts). Co-Authored-By: Warp Agent <agent@warp.dev> * docs: migrate reference/ Oz-branded strings to vars, add CLI deprecation banner Migrate hardcoded Oz product-name strings (Oz CLI, Oz web app, oz.warp.dev, Oz dashboard, Oz run, Oz API & SDK, Oz Platform, bare Oz) to the vars system across src/content/docs/reference/cli/** and src/content/docs/reference/api-and-sdk/**, using {VARS.KEY} in MDX body prose and {{TOKEN}} in frontmatter. Add a shared deprecation callout to the top of every reference/cli/* page pointing to the Warp Agent CLI as the replacement for the Oz CLI. Relabel the Reference tab's CLI sidebar entry to 'Oz CLI (legacy)' in src/sidebar.ts. Co-Authored-By: Warp Agent <agent@warp.dev> * docs: migrate hardcoded Oz strings to vars system in guides, support-and-community, enterprise, changelog Replace hardcoded rename-sensitive Oz-branded strings (Oz CLI, Oz web app, oz.warp.dev, Oz dashboard, Oz run, Oz API & SDK, Oz Platform, bare Oz) with src/data/vars.ts references ({VARS.KEY} in body prose, {{TOKEN}} in frontmatter) across all guides/, support-and-community/, enterprise/, and changelog/ files containing product-name mentions. Left unmigrated (intentional, per style_lint OZ_TERMS_TO_AVOID / screenshot alt-text exceptions): - changelog/2026.mdx:501 'Oz agents' (wording issue, not vars issue) - changelog/2026.mdx:629 'Oz cloud agent' (wording issue) - changelog/2026.mdx:787 'the Oz agent' (wording issue) - changelog/2026.mdx:1362 image alt text describing the 2026.02.10 launch screenshot Co-Authored-By: Warp Agent <agent@warp.dev> * docs: migrate Oz platform strings to vars in platform/ directory Replace hardcoded rename-sensitive strings (Oz, Oz Platform, Oz CLI, Oz web app, Oz dashboard, Oz run, Oz API & SDK) with {VARS.*} in body prose and {{TOKEN}} in frontmatter across src/content/docs/platform/, excluding index.mdx and software-factory.mdx which are handled separately. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: resolve topic-resolution build failures and lint false positives - Add back platform/oz-web-app to the Automation Platform sidebar (accidentally dropped during the reorg, broke the build) - Give the Automation Platform topic an explicit id and associate the orphaned platform/software-factory page with it via topic frontmatter, since it's no longer listed in any sidebar but still needs a topic to resolve (content stays as source material for HYC's Factories migration) - Fix style_lint.py's check_hardcoded_vars to match on word boundaries instead of plain substring search, so short literals like bare "Oz" don't false-positive inside unrelated tokens (e.g. a YouTube share link's si=OzvuInMl8DoNR97R query param) - Fix style_lint.py's video-title check to recognize JSX expression titles, not just quoted string literals Co-Authored-By: Warp Agent <agent@warp.dev> * fix: convert broken VARS markdown links to JSX anchors MDX doesn't evaluate {} expressions inside plain markdown link destination syntax [text](url) -- only inside JSX. 12 links across 8 reference/ pages used [label]({VARS.WEB_APP_URL}/path) syntax, which the internal link checker correctly flagged as broken (the literal string "{VARS.WEB_APP_URL}/path" isn't a real path). Converted all 12 to the <a href={...}>label</a> JSX pattern already used elsewhere in the codebase, using a template literal when a path suffix is appended to the base URL. Verified with: - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only (0 broken links, was 12) - npm run build (370 pages, clean) Co-Authored-By: Warp Agent <agent@warp.dev> * fix: merge software-factory redirect entries to stay under Vercel's route limit Vercel deployment was failing with errorCode "too_many_routes": "Maximum number of routes (rewrites, redirects, etc) exceeded. Max is 2048, received 2049." The repo's vercel.json is already right at that ceiling (~2047 processed routes on the base branch), and my two separate redirect entries for /platform/software-factory (trailing and non-trailing slash) each counted as a route, pushing the total over by one. Merged the two entries into a single rule using an optional trailing slash pattern ("/platform/software-factory/?"), matching both URL forms with one redirect instead of two. Verified with npm run build (370 pages, clean). Note for follow-up: the docs repo is now sitting almost exactly at Vercel's 2048-route hard limit. Any future redirect addition (by anyone) risks tripping this same failure. Worth a separate pass to audit and consolidate redundant slash-variant redirect pairs across vercel.json to create headroom. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: use valid Vercel redirect syntax for software-factory redirect The previous fix used /platform/software-factory/? as the source pattern to match both trailing-slash variants in one entry, but Vercel rejected it with errorCode invalid-route-source-pattern (? is not valid syntax in this position for Vercel redirect sources). Reverted to a single plain entry using only the trailing-slash canonical form (matching the simple, proven syntax used by the adjacent /agent-platform/ entry), still keeping the net route count at +1 instead of +2 to stay under the 2048 route cap. Verified with npm run build (370 pages, clean) and a JSON validity check on vercel.json. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: address PR review feedback Automated (oz-for-oss) review comments: - Revert incorrect variableization of the "Oz by Warp GitHub App" proper noun in reference/cli/integration-setup.mdx, reference/cli/api-keys.mdx, and enterprise/team-management/ admin-panel.mdx. This is a literal, external GitHub App display name, not a docs-rename-sensitive string -- flipping WARP_AUTOMATION_PLATFORM would otherwise make these pages document a GitHub App name that doesn't actually exist. - Fix sidebar.ts's hardcoded "Oz API & SDK reference" cross-link label to use {VARS.API_SDK_NAME} via a template literal, so it participates in the rename. Also imported VARS in sidebar.ts and applied the same fix to the "Oz CLI (legacy)" label I introduced earlier in this PR. - (The flagged broken-markdown-link issue in reference/cli/api-keys.mdx was already fixed in a prior commit on this branch.) Human review feedback (rachaelrenk): - Fixed several places where "{VARS.WARP_AUTOMATION_PLATFORM} platform" would read as a duplicated word once the var's value changes to something like "Automation Platform" (e.g. "Automation Platform platform"). Removed the redundant literal "platform" suffix in 5 MDX body occurrences and 2 frontmatter occurrences, since the var's value already conveys "platform" on its own. - Wrapped the 6 Factories stub pages in an explicit sidebar group (matching how every other topic in sidebar.ts organizes its items) instead of leaving them as bare top-level entries, which is what was likely causing them to render as headings instead of pages under one collapsible "Factories" section. Verified with npm run build (370 pages, clean), the internal link checker (0 broken links), and style_lint.py --all (confirmed the "Oz by Warp" reversions and "platform platform" fixes landed as expected, no regressions). Co-Authored-By: Warp Agent <agent@warp.dev> * fix: remove {VARS.X} expressions from heading text (breaks TOC/anchors) Starlight's "On this page" TOC and heading-anchor-id generation extract heading text from the raw MDX AST before JSX expressions are evaluated, so a heading like `### {VARS.WARP_AGENT_CLI}` doesn't render "Oz CLI" in the TOC/anchor -- it renders the literal, unevaluated expression source ("VARS.WARP_AGENT_CLI"), producing anchor ids like "#varswarp_agent_cli" and a "On this page" entry reading "VARS.WARP_AGENT_CLI" verbatim. The heading text in the page body renders correctly (full MDX/JSX evaluation), so this only surfaces in the TOC sidebar and in the URL fragment for that heading. Found and fixed 40 occurrences across 21 files. In each case, reworded the heading to avoid embedding a {VARS.X} expression, while keeping {VARS.X} usable in the body prose beneath it (unaffected by this bug): - Headings that were only "{VARS.X}" (e.g. "### {VARS.WEB_APP}") became static, descriptive text ("### Web app", "### CLI", "### API", etc.) - Headings mixing static text + a var were reworded to drop the var while preserving meaning (e.g. "## How runners fit into the {VARS.WARP_AUTOMATION_PLATFORM}" -> "## How runners fit into cloud agent runs") - The one historical changelog heading ("Introducing Oz: orchestration for cloud agents") was set to literal "Oz" text instead of the var, since it's a dated historical announcement and shouldn't silently reword itself when the var flips Also fixed a related, unrelated heading collision on agents/capabilities/computer-use/index.mdx: its own "## Overview" heading collided with Starlight's synthetic top-of-page "Overview" TOC entry (auto-generated for intro content before the first heading), producing two adjacent "Overview" rows in the TOC. Renamed to "## Capabilities" to match its actual content. Per review feedback, also normalized the Computer Use API section to consistently use {VARS.API_SDK_NAME} (matching the page's own later, correct usage) instead of "{VARS.WARP_AUTOMATION_PLATFORM} API", since both phrases link to the same /reference/api-and-sdk/ page and the future name for that page is "Warp API & SDK", not "Automation Platform API". Verified with: - npm run build (370 pages, clean) - Inspected the built HTML for agents/capabilities/computer-use/index.html: TOC and anchor ids now read "Capabilities", "CLI", "API", "Web app" instead of "VARS.WARP_AGENT_CLI" / duplicate "Overview" / broken ids - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only (0 broken links) - style_lint.py --all (no new hardcoded-var regressions) Co-Authored-By: Warp Agent <agent@warp.dev> * fix: use plain Warp instead of the automation-platform var on Agent Memory page Per review feedback: "Agent Memory gives agents in Automation Platform persistent memory..." reads awkwardly once the WARP_AUTOMATION_PLATFORM var flips. Since "Warp" is already a locked, stable product name (not rename-sensitive), it's the safer and more natural choice here. Applied the same reasoning consistently across the rest of the page, not just the flagged frontmatter line, since the same "lives on Automation Platform" / "runs on Automation Platform" pattern recurs in several other sentences and would have reintroduced the same awkwardness once the var value changes: - Frontmatter description - "lives on Warp" / "part of Warp" / "run on Warp" - "Warp extracts/saves/searches/creates..." (subject of a sentence) Left one occurrence alone ("self-hosted {VARS.WARP_AUTOMATION_PLATFORM}") since that specifically references the self-hostable orchestration platform as a technical concept, not a generic "in Warp" phrasing. Also normalized the "Programmatic API access" bullet to use {VARS.API_SDK_NAME} instead of "{VARS.WARP_AUTOMATION_PLATFORM} API", consistent with the same fix applied elsewhere in this PR (both link to /reference/api-and-sdk/, and the correct future name is "Warp API & SDK", not "Automation Platform API"). Verified with npm run build (370 pages, clean). Co-Authored-By: Warp Agent <agent@warp.dev> * fix: correct WARP_AUTOMATION_PLATFORM -> API_SDK_NAME mismatches (post-flip audit, round 1) Following up on the "Automation Platform API" bug caught in review: audited every {VARS.WARP_AUTOMATION_PLATFORM} usage across the docs for the same class of issue and found it recurring in 14 more files (~25 occurrences). Root cause: whenever prose names the actual API/SDK product surface (usually as "the [X] API" linking to /reference/api-and-sdk/, or an "[X] API and SDK" phrase), it must use {VARS.API_SDK_NAME} (future value "Warp API & SDK"), not {VARS.WARP_AUTOMATION_PLATFORM} + a literal " API"/" SDK" suffix (which would render the invented, non-canonical name "Warp Automation Platform API" once the platform var flips). This is a wrong-var bug, not just a grammar/redundancy issue -- the two vars name different things. Fixed across: platform/overview.mdx, platform/quickstart.mdx, reference/api-and-sdk/{index,quickstart,demo-sentry-monitoring-with-sdk}.mdx, reference/api-and-sdk/troubleshooting/{index,errors/index}.mdx, reference/cli/{index,artifacts}.mdx, reference/index.mdx, platform/team-access-billing-and-identity.mdx, support-and-community/plans-and-billing/{credits,platform-credits}.mdx, guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx. Where a sentence names the API/SDK as a generic noun without further qualification (not the proper name of the product), simplified to plain "API"/"the API" instead of introducing an unnecessary var, e.g. "calls the API (directly or via an SDK)" and "The Python SDK ... calls the API from Python services". Also applied the same generic-scaffolding-to-plain-"Warp" simplification established on the Agent Memory page fix earlier in this PR, for sentences like "another agent CLI outside of {var}" and "uploads to {var} -- screenshots...", since "Warp" is the stable, locked product name and reads correctly regardless of how WARP_AUTOMATION_PLATFORM resolves. One grammar fix: "An {VARS.WARP_AUTOMATION_PLATFORM} cloud environment" (reference/api-and-sdk/quickstart.mdx) used "An" for agreement with "Oz" today, but "Warp Automation Platform" needs "A" -- reworded to "A cloud environment" to avoid the var/article dependency entirely. Broader audit scope covered in this pass (per user direction, judging DASHBOARD/PLATFORM_RUN under the same-shape assumption where their future value is still TBD): swept the whole docs tree for the API_SDK_NAME mismatch class, redundant trailing-word duplication (e.g. "platform platform"), and "an {VAR}" article-agreement breaks across all six rename-sensitive vars (WARP_AUTOMATION_PLATFORM, WARP_AGENT_CLI, WEB_APP, DASHBOARD, PLATFORM_RUN, API_SDK_NAME). No further redundant-word or article-agreement issues were found beyond what's fixed here. Not yet exhaustively reviewed: the full ~300-occurrence long tail of plain {VARS.WARP_AUTOMATION_PLATFORM} usages for subtler phrasing/tone issues (the kind fixed on the Agent Memory page) -- flagging as a follow-up since that requires reading full sentence context per occurrence rather than pattern-matching, and is lower risk than the two bug classes fixed here. Verified with: - npm run build (370 pages, clean) - check_for_broken_links.py --internal-only (0 broken links, 3495 checked) Co-Authored-By: Warp Agent <agent@warp.dev> * fix: round 2 of post-rename vars audit across the site Continues the systematic sweep of {VARS.X} usages for issues that would only surface after the Oz -> Warp Automation Platform rename ships. Fixes applied: - "platform...platform" duplicate wording (7 more instances across agents/index.mdx, enterprise/index.mdx, enterprise/getting-started/*, and root index.mdx), matching the earlier computer-use/index.mdx fix. - Leftover un-migrated literal "Oz agents" / "@oz" mentions in reference/cli/integration-setup.mdx (missed in the original migration). - Leftover un-migrated VideoEmbed title in platform/oz-web-app.mdx. - Reworded platform/team-access-billing-and-identity.mdx:160, which incorrectly described personal-token auth as "authenticating as {platform}" instead of authenticating as the triggering user. Policy decision (confirmed with user): changelog/2026.mdx entries are dated historical records of what shipped under the Oz brand at the time. Reverted all ~58 rename-sensitive var usages in that file (WARP_AUTOMATION_PLATFORM, WARP_AGENT_CLI, PLATFORM_RUN, DASHBOARD, WEB_APP, WEB_APP_URL) back to their current literal Oz-branded text, so historical entries don't get silently rewritten when the rename ships. This is consistent with the earlier "Introducing Oz" launch-heading fix in the same file. Removed the now-unused VARS import from that file. Verified: clean build (370 pages), 0 broken internal links, and no new hardcoded-var lint regressions (all 71 remaining findings are pre-existing exceptions in files untouched by this round). Co-Authored-By: Warp Agent <agent@warp.dev> * fix: swap Factories tab icon from server to setting (gear) Starlight's built-in icon set has no literal factory glyph, so a true factory-with-smokestack icon would need an icon-library plugin (e.g. Phosphor or Material Symbols via starlight-plugin-icons) plus a Sidebar component override -- out of scope for now. Using 'setting' (gear) as a placeholder since it's the closest built-in match to automated machinery, and it's visually distinct from the icons on the Terminal (laptop) and Automation Platform (cloud-download) tabs. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: remove redundant top-level API tab, fix stale Oz icon check The horizontal "API" tab duplicated a link already present in the Reference tab's sidebar (API & SDK > API Reference > /api). Both pointed to the same standalone Scalar-rendered page. The original reason for splitting /api into its own top-level topic was that Scalar is a different rendering framework than the rest of the Astro/Starlight site, so /api can't have a normal per-topic sidebar tree (hence it was a link-only topic with no `items`). That constraint only explains why /api itself can't be a full Starlight topic -- it doesn't require /api to also have its own top-level nav pill. The destination remains fully reachable: - From the Reference tab's existing "API Reference" sidebar link - From WarpTopbar.astro's own breadcrumb/nav on the /api page itself, which already links back to "API & SDK" and "Quickstart" Removing the topic entry needed no other changes: WarpTopicNav.astro just renders whatever topics exist, and the search breadcrumb label map in CustomSidebar.astro is keyed off URL segments, not the topic list. Also fixed a related stale reference in WarpTopicNav.astro: the custom cloud-icon override still checked `topic.label === 'Oz'`, left over from before the Automation Platform rename. Updated to `'Automation Platform'` so the custom SVG actually renders again instead of silently falling back to Starlight's generic cloud-download icon. Removed the now-dead `</>`-bracket icon branch for the deleted API topic. Verified: clean build (370 pages, /api page itself untouched) and 0 broken internal links. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: rename Reference tab to "API & Reference", surface API Reference link Per HYC/Rachael's Slack discussion following the top-level API tab removal: HYC flagged that dropping the tab could make the standalone Scalar-rendered /api page harder to discover. Two changes address that without re-adding the redundant top-level tab: 1. Renamed the "Reference" tab to "API & Reference" so the tab label itself signals that API docs live there. 2. Promoted the "API Reference" link from 3 levels deep (Reference > API & SDK > 3rd item) to a new "Technical Reference" group at the very top of the tab's sidebar, as the first item -- immediately visible without expanding anything. The group's second item is a renamed self-link ("Overview") to the former bare "Technical reference" page link, following the same self-link-as-first-child pattern already used by other groups in this file (e.g. Self-hosting > Overview). Also updated two lower-priority, non-interactive spots that mirrored the old "Reference" label for consistency: the llms.txt generator's customSets list (astro.config.mjs) and the search-result breadcrumb label map (CustomSidebar.astro). Verified: clean build (370 pages) and 0 broken internal links. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: put Overview before API Reference under Technical Reference Order flip only, per feedback on the previous commit. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: restructure Cloud Agents group per HYC feedback Addresses HYC's follow-up feedback on the Automation Platform tab: 1. Renamed the bare "Agents" sidebar item to "Cloud agent accounts", matching the page's own H1 exactly. The generic "Agents" label was confusing sitting inside a "Cloud Agents" group, and easily conflated with the different "agents" meaning used under Harnesses (Warp Agent, Claude Code, Codex). 2. Converted it into a small group and nested Skills as agents, MCP servers, and Secrets beneath it, replacing the removed "API / SDK" group entirely (which is now empty since its 4th item, a duplicate cross-link to /reference/api-and-sdk/, was already identified as actively breaking topic-detection for that page and removed). Skills and Secrets are literal properties of a cloud agent identity (POST /agent/identities accepts `skills` and `secrets` directly); MCP is per-run rather than identity-scoped, so added a bridging "## Capabilities" section to agents.mdx explicitly covering both identity-level and run-level capabilities. 3. Reordered the Cloud Agents group per HYC's note that individual cloud agents should be introduced before the tooling for monitoring them: Quickstart -> Oz platform -> Cloud agent accounts (+ capabilities) -> Viewing cloud agent runs -> Managing cloud agents -> Oz web app -> Handoff -> Harnesses -> Access/billing/identity -> FAQs. ("Managing cloud agents" was previously positioned above the page that actually defines what a cloud agent is.) Verified: clean build (370 pages) and 0 broken internal links. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: rename subgroup to Warp Cloud Agents, relabel Overview to Cloud agent accounts The subgroup label 'Cloud agent accounts' was too narrow for its actual contents -- Skills as agents, MCP servers, and Secrets are cloud-agent capabilities generally (per HYC/Rachael Slack discussion), not account/identity-specific. Renamed the subgroup to 'Warp Cloud Agents' (broader, factually accurate: all 4 pages are genuinely about cloud agents) and moved the more specific 'Cloud agent accounts' label down to just the Overview item (platform/agents.mdx), where it's fully accurate. Accepted a slight nesting redundancy with the parent 'Cloud Agents' group per explicit direction. Verified: clean build (370 pages) and 0 broken internal links. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: lead Warp Cloud Agents with the Warp Agent page, move it above Oz platform HYC review feedback on the restructured Cloud Agents group. - Move the Warp Agent harness page into the Warp Cloud Agents subgroup as its Overview, and drop it from the Harnesses subgroup. - Move the Warp Cloud Agents subgroup above the Oz platform entry. - Point the Warp Agent page at its new siblings, splitting Related pages into the agents in this section and the harness comparison. The page keeps its /platform/harnesses/warp-agent slug, so all six inbound links stay valid and no redirects are needed. The Harnesses overview still links to it, so it remains reachable from that group. Cloud agent accounts stays its own page: it carries the /agent/identities endpoint table, plan limits, service accounts, and pull request authorship rules, none of which the harness page covers. Co-Authored-By: Warp Agent <agent@warp.dev> * fix: land the Automation Platform tab on the platform overview The tab pointed at /platform/, so clicking "Automation Platform" opened a page titled "Cloud agents overview". The platform overview it should have opened already exists at /platform/overview. Retarget the tab to /platform/overview/ and move /platform/ into the Cloud Agents group as that group's Overview. Did not swap the two page bodies, which was the other option considered. The URLs are already aligned with their content, and each carries 16 legacy redirects that match: /platform/overview <- /agent-platform/warp-platform, /cloud-agents-platform, /agent-platform/platform /platform/ <- /agent-platform/ambient-agents, /cloud-agents-overview Swapping the bodies would have sent all 32 legacy URLs to the opposite of what they ask for, inverted 17 internal links across 10 files that read "the Automation Platform" and point at /platform/overview/, and broken an #execution-hosts anchor link from platform/environments.mdx. Precedent for a non-root tab target: the Changelog tab links to /changelog/2026/. Also on the platform overview: - Add a Warp Factories section, framed as composing the primitives the page describes. The page previously mentioned Factories zero times, which is a gap now that Factor which is a gap now that Factor which is th which is a gap now that Factor which is a gap now that Factor whicexp which is a gap now that Factor which is a gap now that Factor duplicated "Using cloud agents with or without the Warp app" section with a "Where to g app" section with a "Where to g app" section with a "Where to g appch app" section with a "Where to g app" section with aunt stays at 2037. Co-Authored-By: Warp Agent <agent@warp.dev> * refactor(sidebar): split agent runtime from agent configuration Per HYC's review on 8/14, which chose Option 1 from the three proposed. This supersedes 763abea, which made the Warp Agent harness page the Overview of a "Warp Cloud Agents" group. That group mixed one Warp-Agent-specific page with four cross-harness ones, so a Codex user looking for Secrets had to find it under a Warp-branded heading. Cloud Agents now reads: Overview / Quickstart Harnesses Overview, Warp Agent (Default), Claude Code, Codex, Authentication Agent configuration Cloud agent accounts, Skills as agents, MCP servers, Secrets Operations Session sharing, Managing cloud agents, Oz web app Handoff Access, billing, and identity / Cloud agent FAQs HYC asked to confirm everything in Agent configuration is cross-harness, and flagged Cloud agent accounts as a likely exception. Audited all four: - platform/agents zero references to any harness, Warp Agent, Claude, or Codex - skills-as-agents - skills-as-agents - skills-as-agents - skills-as-agent uses OPENAI_API_KEY as its example; both third third thirdharness constraint So nothing needed calling out. Recorded in a sidebar comment so the group does not silently reacquire Warp-specific pages. Operations groups the three surfaces HYC lisOperations groups the three surfaces HYC lisOperations groups theg Operations groups the three surfaces HYC lup. The name mirrors the "Management and observability" section of the platform overview, which covers thessection of the platform overview, which covers thessection of the platrom "Viewing cloud agent runs" to "Session sharing". The page is titled "Cloud agent session sharing", so the old label sent readers somewhere they did not expect. - Revert the Related pages split on warp-agent.mdx from 763abea. The "agents in this section" framing only held while that page was a section overview. - Delete the old collapsed Harnesses group, which would otherwise have listed the same four pages twice. No slugs change: no redirects, no broken links, route count still 2037. Co-Authored-By: Warp Agent <agent@warp.dev> * fix(platform): correct group label, heading levels, and two content issues From a top-to-bottom review of the Automation Platform tab. Sidebar - Rename the 'Self-hosting' group to 'Deployment and hosting'. The group holds a comparison page, a Warp-HOSTED page, and the self-hosting set, so the old label filed 'Warp-hosted agents' under its own opposite. - Qualify two labels inside that group. With the group renamed, a bare 'Overview' and 'Quickstart' read as the group's rather than self-hosting's. Both now match their page titles. deployment-patterns.mdx - Promote every heading one level. The page had no H2 at all: it opened with an H4, used H3 for its three patterns, and H4 beneath. Starlight builds the on-page table of contents from H2s, so the page had none. integrations/bitbucket.mdx - 'Step 4: Test your environment' was an H2 while Steps 1-3 were H3s under the two H2 deployment variants, so Step 4 rendered as a sibling of the variants rather than continuing either sequence. It is a of the variants rather than continuing either sequence. It is a ofso. integrations/index.mdx - Drop the second of two consecutive :::note ca- Drop the second of two coegration setup, which the Get started list alr- Drop the second of two consecutive :::note ca- Drop the second of he {WARP_AGENT_CLI}'. Integrations run on the platform; the CLI is one trigger among six, which the Triggers page states plainly. The replacem Triggers page states plainly. The replacem Triggers page slugs change: no redirects, no broken links, route count still 2037. Co-Authored-By: Warp Agent <agent@warp.dev> * refactor(sidebar): split Triggers and Integrations into sibling groups Triggers was nested inside Integrations, which inverted the concept. platform/triggers lists integrations as one of six trigger types, alongside schedules, the CLI, the API, GitHub, and GitHub Actions. So the content said Triggers contains Integrations while the nav said the reverse. The sidebar comment showed the nesting was inherited from an earlier prototype rather than chosen. They are now siblings: Triggers Triggers overview, Scheduled agents quickstart, Scheduled agents Integrations Integrations overview, Integrations quickstart, Slack, Linear, Jira, GitHub, GitHub Actions, Azure DevOps, Bitbucket, GitLab, cloud providers Siblings rather than nesting Integrations under Triggers, which would have pushed 11 pages four levels deep for a relationship the overview pages can state in prose. Also add the return cross-link. Triggers already pointed at Integrations three times; Integrations did not point back. Its intro now names Triggers as the full set of ways to start a run. Grouping is independent of slugs, so no files move, no redirects, and no links change. 52 pages links change. 52 pages links change. 52 pages links change. 52 pt@warp.dev> * refactor(sidebar): merge Triggers & integrations, collapse level-2 groups Supersedes 248e603, which split Triggers and Integrations into sibling groups. Siblings implied the two are peers, which they are not: platform/triggers lists integrations as one of six trigger types. But nesting either inside the other is also wrong -- Triggers under Integrations inverts the concept, and Integrations under Triggers buries 11 pages four levels deep. A single group named for both sidesteps the question, and the overview pages carry the actual relationship in prose. The return cross-link added in 248e603 stays. Triggers overview is still a distinct page, and the Integrations intro still needs to name it as the full set of ways to start a run. Separately, collapse the three level-2 groups added in 42b8422: Harnesses, Agent configuration, and Operations. Every other level-2 group on the site already sets collapsed: true -- Blocks, Capabilities, Interacting with agents, Handoff, GitHub Actions -- so these three were the only ones expanding on load, which made the tab open long and inconsistent with the rest of the docs. Also normalize the indentation of the ClouAlso normalize the indentation of the ClouAlso han its siblings. No rendering change. 52 pages in the tab, none listed twice. No slugs change. Co-Authored-By: Warp Agent <agent@warp.dev> * refactor(sidebar): nest Scheduled agents and Integrations subgroups Shortens the Triggers & integrations group from 14 visible rows to 3. Overview platform/triggers Scheduled agents collapsed: Overview, Quickstart Integrations collapsed: Overview, Quickstart, Slack, Linear, Jira, GitHub, GitHub Actions, Azure DevOps, Bitbucket, GitLab, cloud providers Both new subgroups follow the Overview-then-Quickstart shape the GitHub Actions subgroup already uses. Nesting GitHub Actions one level deeper matches existing precedent: the Agents tab nests Computer Use inside Capabilities inside Warp Agents. platform/triggers becomes the group overview, so its intro now names integrations explicitly instead of only 'schedules, webhooks, or other automation patterns'. Kept both overview pages rather than merging them into one. Merging would mean deleting a page, and the two are not comparable: platform/integrations has 20 inbound links and 19 legacy redirect sources, against 4 and 0 for platform/triggers. Deleting the more established of the two to save a single sidebar row is a bad trade, and with Integrations now a subgroup it needs its own overview regardless. 52 pages in the tab, none listed twice. No slugs change. Co-Authored-By: Warp Agent <agent@warp.dev> * fix(platform): hardcode @oz mention handle instead of variabilizing it 18 places across 9 files wrote the Slack and Linear mention handle as @{VARS.WARP_AUTOMATION_PLATFORM}. That renders as "@oz" today, so it looks correct, but the variable flips to the new product name at rename. Every one of these would have silently become "Tag @automation Platform in a message" -- an invalid handle -- with nothing failing in CI to catch it. A mention handle is a literal string a user types. It is not the product name appearing in prose, and it does not necessarily change when the product name changes. The GitHub handle was already correctly hardcoded as @oz-agent in 31 places; this brings Slack and Linear in line. Rendering is unchanged: WARP_AUTOMATION_PLATFORM is currently "Oz", so these already displayed as "@oz". Also teaches the style linter the same distinction. The hardcoded-var rule matched "Oz" inside "@oz" via its word boundary, so hardcoding raised the repo total from 1148 to 1167. The rule now skips an "@"-prefixed occurrence. The exemption is per-occurrence, not per-line: a line containing both "@oz" and "Oz web app" still flags the latter. Repo total is back to 1148. The correct post-rename handle is still an open product question. It is flagged inline on the changed lines for review. Co-Authored-By: Warp Agent <agent@warp.dev> * Add a hairline separator above the page footer CTA HYC's review asked for a visual break between page content and the "See something wrong? Edit this page or open an issue" CTA, which previously ran on directly after the last line of prose and read like a trailing sentence of the article. Adds a border-top to the page footer in FeedbackFooter.astro, using the same treatment already applied to the "On this page" panel footer in CustomPageSidebar.astro (1px, --sl-color-hairline-light). The rule sits inside .sl-container, so it spans the content column rather than full-bleed like Starlight's ContentPanel divider. Also drops a dead `margin-top: 2rem` from the same rule. The footer is a sibling of .sl-markdown-content inside Starlight's ContentPanel, whose `.sl-container > * + *` rule (0,1,1) outranks a bare `footer` selector (0,0,1), so the gap above the footer has always been 1.5rem. Space below the rule is now set with padding-top, which nothing else targets, so the 1.5rem above and below is symmetric and under our control. The /api reference is unaffected: it renders DocsFeedbackLinks in its own fixed-position card, not through this footer. Verified: build clean at 370 pages; the separator renders on standard and splash (404) pages; /api emits no page footer. Co-Authored-By: Warp <agent@warp.dev> * refactor(sidebar): shorten the Support tab and relabel two platform groups Addresses HYC's final round of structural feedback on the tab bar and the Automation Platform tab. - 'Support & Community' -> 'Support'. The horizontal tab bar was wrapping to a second line early; this was the longest label after 'Automation Platform'. Total tab-label length drops from 102 to 89 characters across the 9 tabs, a 13% trim, and 'Automation Platform' (19) and 'API & Reference' (15) are now the longest remaining. - Community group moved to the bottom of the Support tab. Readers enter this tab for help far more often than for community links, so troubleshooting, plans and billing, and privacy now come first. - 'Deployment and hosting' -> 'Deployment & hosting'. - 'Operations' -> 'Management & Observability', matching the section name already used on the platform overview. Labels only. No slugs, redirects, or page content change. Verified in built output: the Support tab renders with group order Troubleshooting -> Plans -> Privacy -> Community; 'Operations' and 'Deployment and hosting' no longer appear anywhere; build clean at 370 pages. Co-Authored-By: Warp <agent@warp.dev> * refactor(sidebar): label follow-ups on the Support and platform tabs Two consistency fixes on top of the previous commit. - Support tab's bare first item: 'Support and Community' -> 'Overview'. The tab is now 'Support', so repeating the old two-part name in the first item was stale. 'Overview' also matches the bare first item on the Automation Platform, API & Reference, and Enterprise tabs. The page's own 'Support & Community' H1 and title are intentionally left alone, so the page keeps its search and SEO surface. - 'Management & Observability' -> 'Management & observability', matching the sentence case used by its sibling labels ('Triggers & integrations', 'Infrastructure & security') and by the platform overview section of the same name. Verified in built output: no 'Support and Community' left in the sidebar, the page title still renders, and no capital-O variant survives. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev>
Co-authored-by: Warp Agent <agent@warp.dev>
* docs: add Warp Factories cross-links
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs: clarify Factories cross-link copy for external readers
Rewrite the four Warp Factories blurbs in plain, benefit-led language:
- Replace the repeated 'coordinates specialized cloud agents across
software development workflows' phrasing with concrete descriptions
grounded in the terminology glossary (triage, spec, implement,
review, verify; humans approve key decisions).
- Drop internal implementation jargon ('Oz primitives',
'cloud-run primitives') from user-facing copy.
- Fix the dangling modifier on the Guides landing page.
- Simplify the Enterprise product-list intro and make the Factories
bullet parallel with the other product bullets.
- Match the root landing page's section pattern (divider, bold name,
arrow link) and move 'Early Access' into prose.
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document factory agent roles Co-Authored-By: Warp Agent <agent@warp.dev> * docs(factories): rewrite factory agents page in plain language Remove undefined jargon that confused readers: 'intake' becomes plain descriptions of work entering the factory, 'seeded' becomes 'default', and phrases like 'advisory verdict', 'prompt appendix', 'parent-child lineage', and 'correlated mistakes' are rewritten to say what they mean. Same verified facts, human approval gates, and security caveats; clearer sentences, second-person voice, and simpler section names. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address feedback on factory agents page Drop 'specialists' wording in favor of plain 'agents', link computer use from the implement and verification sections, surface custom agents and automations in the default roles section, and call out that agent configuration can be stored as version-controlled code. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address harness plan gating and config-editing review feedback - Note that third-party harnesses require a Build plan or higher, with a link to warp.dev/pricing (verified against warp-server billing tiers: free.yaml sets third_party_enabled false; all paid bases set it true) - Rework 'Configure agent behavior' to state clearly that a Warp-managed factory repo supports both the visual agent editor and the code-based editing flow, while a team-owned GitHub repo is file-only with read-only control room settings - Reword the custom-agents opener to drop the 'aren't a ceiling' phrasing Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev>
* Restyle the Factories "Early Access" topic badge The topic nav rendered Starlight's default <Badge>, a monospace bordered box that clashed with the nav's Inter type and was wide enough to wrap "Guides" onto a second header row at common laptop widths (~1300-1460px). - Render the badge as a compact brand pill (Inter 11px/600, accent tint, fully rounded) in both the top nav and the mobile drawer topic list. - Retune the nav's responsive fallbacks: drop per-item icons below 94rem (the ten-topic row no longer fits with icons below ~1460px) and hide the badge below 80rem so the row survives down to ~1160px before wrapping. Co-Authored-By: Warp <agent@warp.dev> * Temporarily add PR screenshot assets (removed in next commit) * Remove temporary PR screenshot assets The images stay referenceable in the PR description via the previous commit's raw.githubusercontent.com URLs; the tree stays clean. --------- Co-authored-by: Warp <agent@warp.dev>
* Anchor the active topic tab underline to the header divider The 2px accent underline for the active topic tab hugged the tab label mid-header, floating ~14px above the header's bottom hairline. Anchor it to the divider instead (the Cursor/Devin docs pattern): - Stretch the nav -> ul -> li -> a chain to the header's full content height, with tab content centered by the link's own flex alignment. - Offset the underline by --sl-nav-pad-y so it rests flush on the 1px border-bottom drawn by Starlight's header. - In the crowded <=80rem band, where the tab list may wrap to two rows inside the taller header, fall back to the previous tab-hugging underline so a wrapped row-one tab doesn't leave the line stranded between rows. - Inset the focus-visible ring since the links now span the full header content height. Verified in headless Chromium from 900-1600px: single row >=1160px, line flush on the divider >=1300px (1281+ once icons drop), correct fallbacks below. Co-Authored-By: Warp <agent@warp.dev> * Temporarily add PR screenshot assets (removed in next commit) * Remove temporary PR screenshot assets The images stay referenceable in the PR description via the previous commit's raw.githubusercontent.com URLs; the tree stays clean. --------- Co-authored-by: Warp <agent@warp.dev>
* docs(factories): document Jira integration Co-Authored-By: Warp Agent <agent@warp.dev> Co-Authored-By: Warp <agent@warp.dev> * docs(factories): clarify Jira integration page Editorial pass for external readers: - Lead with the user flow in plain language instead of internal routing vocabulary - Restructure setup into three clean steps with the automation example nested under its step, and explain the example inline - Consolidate trigger/filter behavior into one section, removing repeated explanations of when the event fires and keyword case-insensitivity - Replace internal jargon (seeds, intake, factory admission, issue mutations) with plain wording - Surface the filters-vs-access caveat as a caution callout and group permissions/reliability notes into a scannable list - Align title and headers with the sibling Linear page; use root-relative link for the platform setup page Co-Authored-By: Warp <agent@warp.dev> * docs(factories): center Jira page on Warp, not Rovo Reduce Rovo mentions from six to one. The remaining mention is a recognition pointer in prerequisites (Jira lists the Warp agent among Atlassian's Rovo agents); everywhere else the actors are Warp and the factory agent, and sessions are just agent sessions. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address Jira page review feedback - Inline the app install and workspace connection steps instead of bouncing readers to the platform setup page mid-procedure; keep that page as a supplementary deep link and plainly note that its warp-agent label flow is for standalone cloud agents, not factories. - Note the agent runs in the cloud and link cloud agent session sharing for watching the full run from the factory. - Drop the repeated-deliveries bullet (internal dedup detail with no user action). - Reword the code-access bullet: connecting Jira grants no repository access, and agent PRs go through the usual review process. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address Jira page review feedback (round 2) - Document the automation editor's Jira trigger (Add trigger > Jira > Agent session created), now that the control room editor supports it alongside GitHub, GitLab, Linear, and Slack triggers. Keep definitions as code as the alternative path. - Correct the access caution: Jira access is workspace-wide today (no per-team or per-project scoping exists yet), so drop the inaccurate suggestion that the Warp app's Jira authorization can be scoped by project. - Remove the now-false claim that a new session on the same work item always starts a separate run. - Rewrite the Permissions bullet: the Jira user who starts a session must connect their Jira account to Warp before a run starts (new user-binding gate); the run still executes as the automation's agent, not as that Jira user. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): fix four accuracy issues from adversarial review - Add the missing per-factory Jira connection step (Settings > Jira > Connect/Install, select projects, Enable). Without it, the automation editor's Add trigger > Jira entry stays a disabled not-connected item (confirmed via AutomationEditor.tsx/TriggerMenu.tsx/ JiraIntegrationConnect.tsx and the editor's own test suite). - Correct the access caution: project_keys does control whether a given automation fires (provider_jira.go's evalFilter), it just isn't an access boundary across teams in the same workspace. Left the last sentence about no team/project scoping untouched. - Rewrite the Permissions bullet: a bound Jira actor becomes the run's creator/ActorUserID (automation_dispatch_jira.go), while the automation's agent remains the ExecutionPrincipal either way. - Make the definitions-as-code alternative self-contained (factory.yaml integration declaration + automation file path) instead of depending on the still-stubbed factory-as-code page. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): remove em dashes from Jira setup steps per style guide Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev> Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com>
* docs(factories): document the control room
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): clarify control room copy
Editorial pass on the control room page for external readers:
- Replace internal jargon (web surface, source mode, terminal state,
polling interval, atomic commit) with plain language
- State Activity's default filters directly instead of "two defaults
shape what you see"
- Restructure dense comma lists into scannable bullets (dashboard
metrics, run pane actions, Code tab source modes, editor boundaries)
- Explain what the scorer Self-improvement toggle does, per the UI copy
- Fix inverted phrasing ("the automation editor overrides no execution
settings") and cut duplicated sidebar orientation
No factual changes; all labels and behavior stay as verified.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): trim UI narration from control room page
Cut prose that describes what UI elements do rather than documenting
behavior: search/filter/sort control walkthroughs, filter chip and URL
state mechanics, pane field inventories, refresh cadence, and editor
form-field enumerations. Kept the semantics readers can't infer from
the UI: default Activity filters, metric definitions and cost caveats,
the Stop task warning, source-mode boundaries, and read-only rules.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): control room feedback — session steering, self-improvement, code tab
- Replace the 'no way to steer' note: View session opens the run's shared
agent session (cloud agent session sharing) for real-time follow-ups.
- Add the Self-improvement page to the pages table and scorer section;
drop the stale claim that the Dashboard lists self-improvement PRs.
- Link the Code tab section to Factory definitions as code, align its
source modes with the current UI (GitHub links out; live-managed), and
document the in-room branch review (Request changes / Approve & merge).
- Refresh details: harness is editable in the agent editor, Scorers are
read-only for file-managed factories, work-item pane shows origin and
View agent, Cost per PR expands into most expensive PRs.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address control room review feedback
- List Integrations among the team-level sidebar pages
- Clarify Settings manages the integrations the factory can access
- Mention the Complete and Cancelled terminal stages on Activity
- Contrast runs with Activity work items
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
moirahuang
reviewed
Aug 17, 2026
|
|
||
| - **Warp CLI** — Ambiguous since the Warp Agent CLI launched; avoid the bare term. Use "Oz CLI" for the `oz` binary that runs and manages cloud agents (formerly called `warp-cli`), or "Warp Agent CLI" for the `warp` binary that runs the Warp Agent in any terminal. | ||
|
|
||
| - **Automation Platform** — Working name for Warp's cloud agent platform (the proposed successor branding for "Oz" as of the ~2026-08-18 launch), covering environments, integrations, orchestration, self-hosting, and the Agent API/SDK. |
There was a problem hiding this comment.
Automation Platform is no longer a working name, right? I believe this is the finalized name now, so we can update this entry and remove the pending-name caveat.
| ("Oz dashboard", "DASHBOARD", "{VARS.DASHBOARD} in prose or {{DASHBOARD}} in frontmatter"), | ||
| ("Oz run", "PLATFORM_RUN", "{VARS.PLATFORM_RUN} in prose or {{PLATFORM_RUN}} in frontmatter"), | ||
| ("Oz API & SDK", "API_SDK_NAME", "{VARS.API_SDK_NAME} in prose or {{API_SDK_NAME}} in frontmatter"), | ||
| ("Oz Platform", "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"), |
There was a problem hiding this comment.
Do we need to add Oz here, or should this use Factory instead? Similarly, should we update the other relevant places to use the finalized terminology?
Collaborator
Author
There was a problem hiding this comment.
The entries here are stale-string detectors, not recommendations: each row flags the old literal (e.g. "Oz API & SDK") when it appears hardcoded in prose and points authors at the var that replaces it. Adding "Factory" wouldn't fit that purpose — per the comment block in src/data/vars.ts, FACTORY_WEB_APP is deliberately not rename-sensitive because it's a net-new surface rather than a flip of existing Oz-branded text. The finalized-terminology sweep landed in .agents/references/terminology.md (renamed from Oz on 2026-08-18, with the 9/15 holdouts listed).
| label: "Connect your Factory" | ||
| --- | ||
|
|
||
| [STUB — pending content from HYC/content team for the 8/18 closed-beta soft launch. Owner: HYC. |
There was a problem hiding this comment.
Is this meant to remain a stub? Same question for the other stub pages.
…able (#548) PR #528 (already merged) left the access caution flat: 'Warp doesn't yet offer a way to scope Jira access by team or project.' The requester asked to verify whether installing the Warp Jira app itself supports scoping access to specific projects before deciding on wording. Checked forge-jira/manifest.yml: the app requests classic, site-wide scopes (read:jira-work, read:jira-user, write:jira-work), not project-scoped grants, and neither platform/integrations/jira.mdx's install flow nor the factory's own Settings > Jira connection (JiraIntegrationConnect.tsx) offers a way to restrict the app's own Jira access by project — project selection there only seeds automation defaults. So install-level project scoping does not exist today, confirming the requester's own suspicion. Reworded the caution's last sentence to state the coming Warp team-level Jira scoping feature instead of a flat 'not available', leaving the already-correct project_keys-is-not-an-access-boundary guidance untouched. Kept the ':::caution' aside type per this repo's own convention (limitations/caveats, not destructive/irreversible actions) rather than introducing an unsupported type. Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com> Co-authored-by: Warp <agent@warp.dev>
* docs(factories): document Factory MCP Co-Authored-By: Warp Agent <agent@warp.dev> * docs(factories): make the Factory MCP page reader-focused - Lead with what you can do and add example prompts; make clear your agent calls the tools for you - Replace the tool-by-tool sequence diagram (Mermaid isn't rendered by this site) and the agent operating rules (error-code handling, reference resolution order, fan-out restrictions) with two plain workflows: send new work, and pick up a task locally - Keep the load-bearing caveats: full-permission auth, non-locking pickup, push-before-handback, handback vs complete - Simplify the tool table to purpose-only and add a Related pages section Co-Authored-By: Warp <agent@warp.dev> * docs(factories): give Factory MCP setup instructions directly Replace "get connection details from Warp or your factory administrator" with the actual quickstart: the endpoint URL (https://app.warp.dev/api/v1/mcp/factory, verified against warp-server route registration and the client's builtin server config), a Claude Code one-liner, the standard mcpServers JSON snippet, and the bearer header form for API-key automation. Browser OAuth on first connect is backed by the server's RFC 8414/9728 discovery metadata for this endpoint. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): cross-link factory pages and enrich MCP-in-Warp link - Point the MCP-in-Warp related-pages entry at the catalog of MCP servers you can add to Warp directly - Link foreman to the factory agents page and control room to its page - Include Jira in the intake paths alongside Slack, Linear, and GitHub Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document measurement and improvement Co-Authored-By: Warp Agent <agent@warp.dev> * Simplify measure-and-improve language Rewrite the page in plainer language based on review feedback: - Rename the jargon table headers (Boundary/Limitation -> Keep in mind) - Drop the 25-lines-per-engineer-hour heuristic explanation; describe Time saved simply as a directional estimate - Merge the two dense metric-caveat paragraphs into one - Shorten Scorer, benchmark, Self-improvement, and improvement-loop sections without changing verified behavior claims Co-Authored-By: Warp <agent@warp.dev> * Drop Keep in mind columns; state facts in descriptions Reviewer feedback: docs should read as objective statements, not advice. Both tables are now two columns, with measurement facts folded into the metric descriptions and coverage facts kept in the caution block. Co-Authored-By: Warp <agent@warp.dev> * Remove remaining implementation details and duplication - Metric rows describe only what each metric shows; GitHub App coverage facts live in the caution block alone - Cut UI inventory (median/mean/By complexity/By size views, scoreboard, scatter plot) and billing-rate conversion detail - Replace jargon: eligible, lower-bound, freeze, clusters, PR signals, webhook data - Dedupe Self-improvement paragraphs and the three-newest-PRs fact, fix the ambiguous pronoun, drop the closing aphorism and generic benchmark advice already covered by loop step 4 Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address measure-and-improve review feedback - Trim the dashboard caution to the actionable GitHub App coverage caveat; move the run-count composition into the interpretation paragraph and drop the opaque merge-rate sentence - Add a Mermaid diagram to the practical improvement loop showing the monitoring cycle and where Self-improvement joins it - Link definitions as code from the Self-improvement section, explaining that follow-up runs improve the versioned factory definition through reviewable pull requests Co-Authored-By: Warp <agent@warp.dev> * docs(factories): align Scorer docs with current UI per review - Replace the all-agents/pause framing with the actual model: Scorers apply to selected agents, and setting the sample rate to 0 stops automatic scoring. - Drop the Manual/Periodic mode table; describe automatic scoring at sample rate > 0 plus on-demand scoring of a single conversation. - Remove the Analysis model setting paragraph, which may be dropped from the product. - Polish: list the Agent(s) to evaluate field in UI order, introduce 'benchmark suite' before use, and update improvement-loop steps to match the pause-less model. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document GitLab integration Replace nothing (new page): add factories/integrations/gitlab covering the service-account access model, group connect flow, merge_request and bot_mentioned triggers with their filters, bot mentions, run behavior on GitLab, permissions, definitions-as-code triggers, and troubleshooting. Add the page to the Factories sidebar Integrations group. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): polish GitLab integration page Tighten compound sentences, drop em dashes from instructional text, use the gitlab-bot-mentions automation name consistently, rename the access section to 'Service accounts and access', and sharpen troubleshooting symptoms. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): apply GitHub-review learnings to gitlab.mdx Top-to-bottom pass for brevity, directness, and clarity, mirroring the fixes from the GitHub integration doc review (PR 526): - Rewrite the intro sentence to remove the indirect 'so' framing. - Tighten the prerequisites and service-account bullets, merging redundant sentences and dropping the restated one-to-one clause. - Remove unclear colons (bot identity bullet, Actions filter cell). - Fix the setup step to name the actual web app, URL, and UI element (+ next to Factories) that opens the setup wizard, matching quickstart.mdx's and github.mdx's established terminology. - Link 'control room' to its doc page on both mentions. - Split the overloaded Automations/Triggers step into three steps. - Match github.mdx's phrasing for 'choose the projects to provide...' and the 'continues that work item instead of starting a new one' pattern. - Widen the Supported triggers table's first column (same colgroup fix as github.mdx) so 'Merge request' and 'Bot mentioned' don't wrap. - Rewrite the Permissions bullet to match github.mdx's direct three-sentence structure instead o three-sentence structure instead o three-sentence inks to absolute paths (../factory-as-code, ../connect-your-factory) matching the convention used elsewhere in factories/ docs. - Trim the 'Nothing starts work' troubleshooting entry, which dupli dupli dupli dupli dupli dupli dupli dupli dupli dupli dink back to it instead of restating it. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): split overloaded setup step in gitlab.mdx Break the setup-wizard step into two: opening the wizard, then choosing the GitLab repo source and authorizing. Matches the one-action-per-step pattern applied to the rest of the procedure. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address latest round of review feedback on gitlab.mdx - Make 'Warp Factories web app' itself the hyperlink instead of spelling out the URL text separately. - Fix 'shown read-only' to 'shown as read-only'; keep Bot mentioned bolded since it names a defined trigger, consistent with how Merge request is bolded elsewhere on the page. - Add an explicit lead-in sentence before the mention-the-factory steps per suggestion. - Remove the remaining two semicolons and tighten both sentences for brevity. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): remove remaining semicolons in gitlab.mdx per review feedback Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev> Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Six changes from review on #508: - Link the Early Access callouts to www.warp.dev/factories/request-access, so a reader who can't use Factories yet has somewhere to go. - Rename "control room" to "factory dashboard". The old term appeared nowhere in the product; the app calls this surface a dashboard. Renames the page and slug (never published, so no redirect) and disambiguates it from **Dashboard**, the metrics page inside it. - Rewrite the quickstart around the decisions a reader makes rather than the setup wizard's click path. Also corrects the agent roster: all four subagents ship enabled, so the step is turning things off, not on. - Add GitLab everywhere the other integrations are enumerated. It landed after the alignment passes, so nothing referenced it — including the trigger provider list, which was missing `gitlab` entirely. - Restructure troubleshooting into symptom categories with per-source routing, and move it out of Management & observability to its own top-level sidebar entry. - Write down the Warp Factories naming rule and make the guidance match. vars.ts, AGENTS.md, and terminology.md all instructed writers to use the banned capitalized "Factory" form; a new `factory-proper-noun` lint check now enforces the rule. Also corrects three product-accuracy defects found while verifying the above, each checked against warp-server: - The **Code** tab is labeled **Factory definition**, and renders only for Warp-managed factories (FactoryNavGroup.tsx). - There is no **Runners** page; runners are a section of **Settings** (FactoryRunners/RunnerSettingsSection.tsx). - A factory definition cannot be hosted in GitLab. FactoryForge accepts only `github` and `code_storage` (model/types/factory_files.go). Co-authored-by: Warp Agent <agent@warp.dev>
Follow-up sweep for the launch, from the original audit: - The llms.txt site description still said "the Oz platform" and never mentioned Factories. It is the first thing an AI engine reads about Warp and the most-consumed AI-facing artifact we publish, so the rename skipping it was the costliest miss of the set. - The /platform/software-factory redirect only matched the trailing-slash form. Every internal link that used to point there had no slash, and 1,231 of the 1,292 existing entries use the bare or `(/?)` form. Now matches both. - CopyPageButton stripped `import ... from ...` lines from anywhere in the page, not just the leading MDX import block, so "Copy page" silently removed `import OpenAI from "openai";` from the Node sample in the Ollama guide. Now walks the leading block only. - The API reference page's screen-reader h1 still said "Warp & Oz". - Platform credits never mentioned factories, though the quickstart sends readers there to learn what a factory costs. Factory runs are cloud agent runs, so the existing rule already covers them; now it says so. - factory-as-code listed `gemini` as an accepted harness and linked to a page documenting three. The list is right (the schema enum derives from AllAgentHarnesses), so the sentence now separates what the schema validates from what a team can run. Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): bridge factory:<alias> to the Foreman name label on the GitHub page The Foreman name alignment pass in #560 updated control-room.mdx and quickstart.mdx to link the control room's **Foreman name** field to the definition's `alias` key, but it skipped the GitHub integration page because that page was still in the open PR for #526. The page uses `factory:<alias>` three times without ever saying where <alias> comes from, so a reader who only knows the control room label has no way to work out what their label is actually called. Bridge it on first use, matching the link convention the sibling pages now use. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address Maggie's review on the GitHub page Two review comments on #526, which merged before they could be applied. Handle: the page said the shared account is @oz-agent. Maggie confirmed it will be @warp-factory. That matches warp-server's factoryGitHubHandleDefault, where FactoryGitHubHandle() is "permanently distinct from GitHubAgentHandle(): callers pick whichever applies, never fall back between them", and githubSeedAutomations materializes it into the seeded mention and assignment filters. Automations: the connect procedure ran to seven steps, of which the last five built an automation by hand. Default GitHub automations are seeded at factory creation, so that work isn't required to connect GitHub, and presenting it as part of setup implied the factory does nothing until you configure a trigger. Connecting is now the two steps it actually takes, followed by what the defaults already do and how to verify, with the custom-automation walkthrough moved to its own section for the cases the defaults don't cover. Sequencing: warp-server#15306 carries the handle rename and is still an open draft, so this page leads the server until it lands. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
* docs(factories): lead the GitHub page with what the reader does Follow-up to #562. The page explained how mention routing is built before it said what to do with it, which put the reader through the architecture to answer "how do I hand this issue to my factory?" - "Mention the factory" opened on an internal fact ("a factory doesn't get its own GitHub handle") and asked the reader to expand `factory:<alias>` themselves, with `<alias>` defined mid-sentence via a link into the definition-syntax reference. It now leads with the two actions and a worked example (`factory:payments`), and explains the shared account only where it changes behavior: the label is what picks which factory answers. The Foreman name now links to Settings, where you read it, rather than to the YAML key. - The default automations were one dense paragraph; they are two bullets. - Dropped mechanism the reader can't act on: "both passes are best-effort", "CI payloads don't carry issue or label data", and "managed GitHub factories". - Replaced remaining internal vocabulary: "Warp-owned check" and "the registered factory directory". - GitLab carried the same `factory:<alias>` placeholder; same fix. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): clarity sweep over the launch pages Net -80 lines across the section, almost all of it interface narration and mechanism a reader can't act on. The pages were written as separate PRs, so each was reasonable alone and repetitive together. UI narration replaced with the task: - Slack's five-step connect was two actions (install the app, invite it to channels); two of the steps were the wizard describing itself. - GitLab's eight-step connect mixed factory creation, project selection, and hand-building an automation. - Linear had two near-identical connect procedures ending in "Both paths end in the same state." - Jira's step 3 was ~90 words and four actions. - Slack and Jira each walked through screens Warp doesn't own (Slack's app-removal flow, Atlassian's install flow); both now link out, so they can't drift silently. - The generic four-step "add an automation" walkthrough appeared on four integration pages. automation-filters owns it now; each integration page keeps only its own events and filters. Mechanism removed: Slack's managed-apps model and manager authorization, GitLab's manager service account, credential minting, one-year provisioning token and generated-ID naming, the per-run short-lived token, compute resolution precedence, and "this declares the `jira` integration for the factory." Said once instead of five to nine times: "filters route work, they don't restrict access" (now owned by automation-filters) and "the factory hands off at the pull request" (owned by how-factories-work). Also: - /platform/harnesses/ never mentioned that third-party harnesses need a Build plan, so a Free-plan reader found out at the error. Verified in warp-server/logic/agent_entitlements.go:114. - Dropped the `topic: factories` frontmatter key from ten pages. Every factories page is listed in sidebar.ts, so the key does nothing there and implied it was required. Co-Authored-By: Warp <agent@warp.dev> * Apply suggestion from @oz-for-oss[bot] Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --------- Co-authored-by: Warp Agent <agent@warp.dev> Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
Editorial audit of the factories section and touched factory copy:
- Fix vague pronouns and garden-path phrasing ("the model runs execute
with" -> "the model that runs execute with"; triage "reproduces it" ->
"reproduces the problem")
- Remove conversational interjections ("say,") and em dashes from
procedural text per the style guide
- Convert the run-on Settings sentence on the factory dashboard page
into a scannable bulleted list
- Reconcile the dashboard claim that automations never override
execution settings with the definition schema's execution overrides
- Reserve "Warp Factories" for the product: "your Warp Factories" ->
"your team's factories" on the Factory MCP page
- Add GitLab to the connect-your-factory description; align the
automation-filters example repo with the definition-syntax page
- Capitalize list fragments after dashes; make link text match target
page titles; "bound" -> "connected" Jira user
- Drop "seamless" from a touched enterprise line; add the definite
article to "the Warp Agent" on the comparisons page
Co-Authored-By: Warp <agent@warp.dev>
liliwilson
approved these changes
Aug 18, 2026
…rm (#568) Per ZL's suggestion, the factories overview now explains how a factory relates to the Automation Platform: a factory assembles the platform's primitives (runs, environments, runners, harnesses, secrets, MCP servers, credits, self-hosting) into one standing workflow, what the factory layer adds on top, and when to reach for a standalone cloud agent instead. The heading follows the 'The platform behind the agent' precedent on the agents landing page so the rename-sensitive product name stays out of heading slugs. Also notes on the lifecycle page that a factory agent run is an ordinary cloud agent run, viewable and steerable through session sharing. Co-authored-by: Warp <agent@warp.dev>
#570) * docs(platform): fix outdated integration pages after warp-server audit gitlab.mdx rewritten: native GitLab.com support (web app OAuth env picker, auto-clone, glab, MRs as run outputs); PAT flow scoped to self-managed. Fixed: Slack/Linear email-mapping claims (account binding now), Slack button names, GitHub error-string quotes + per-team repo scoping, stale plan/credit gates, GHA skills anchor, federate --run-id, GCP principalSet group form, teams-claim wording, index GitLab bullet, bitbucket framing. Co-Authored-By: Warp <agent@warp.dev> * docs: rename GitHub integration handle @oz-agent -> @warp-agent warp-server #15306: platform App handle is warp-agent, factory handle is warp-factory. GHA oz-agent user references left as-is (separate surface). Co-Authored-By: Warp <agent@warp.dev> * docs: strip Oz language from edited lines (@oz -> @warp, drop 'View run in Oz', warp-agent token example) Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
* docs(factories): reframe the quickstart around the foreman (Aloke's review) From Aloke's Loom review of the launch docs, quickstart items: - Intro now leads with his framing: you talk to one agent, the foreman, from whichever tool the request starts in, and it dispatches agents that each own part of the SDLC. Adds the missing humans-in-the-loop sentence (spec approval, PR merge) up front. - "Name the factory and its foreman" -> "Name your factory": you name the factory and give it an alias you @-mention. The Foreman name field is mentioned once as where the alias lives in setup. - "Confirm the agent roster" -> "Design your factory": explains the foreman concept and the four default agents as components of the factory. Drops "roster"/"subagents" vocabulary. - "Send your first work item" now leads with Slack or your tracker -- the Runs page is the fallback and the place you watch, not the recommended intake. - Notes the agent-driven creation path: create_factory via Factory MCP, which the docs previously undersold as one table row. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): apply the rest of Aloke's review Second round from the Loom, covering the pages beyond the quickstart. how-factories-work: - Opens by explaining what a factory is, instead of leading cold with inner loop / outer loop. - Scorers no longer appear up front; they arrive in "How the factory improves itself", framed as "your factory is self-improving, and you define what better means." - "Work items and agent runs" deleted; the one useful fact (Activity's stage names, runs are ordinary cloud agent runs) folded into Stages. - "What humans decide" moved above self-improvement, rewritten as "Where your team stays in charge" in plainer language. factory-agents: - Cut the Auto-memory store paragraph: Agent Memory is a research preview, so pointing factory readers at it overstated the product. - Rewrote the closing paragraphs Aloke screenshotted; the conventions vs. access distinction is now stated directly. - Simplified per "much simpler than this": dropped the "Where verification happens" section, which existed to explain a feature that doesn't exist, and tightened the four agent descriptions. - Intro now leads with the foreman and the four SDLC agents. infrastructure-and-security: - "Environments and runners" is now just "Runners" — environments are opaque to a factory reader, so the comparison table is gone. - Documents per-agent runner selection, which customers want and which only existed as a key in the syntax reference: agents inherit agentDefaults.runner and any agent can name its own, so implement can run on macOS while the rest stay on Linux. Factory MCP is now framed bidirectionally on both its own page and the connect page: send work to the factory, or take work over from it. The tool count is gone. Also swept role/roster/subagent vocabulary to "agents" across the section, and removed the remaining environment-facing prose from the overview, dashboard, troubleshooting, and Linear pages. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address review feedback (em dashes, implement agent wording) Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp Agent <agent@warp.dev>
Consistency and style cleanup across the factories section, plus one fix flagged on #508: - Align the overview's human-in-the-loop line with the quickstart (approving specs when needed) - Refer to the implement agent explicitly in the model-choice table - Name the Dashboard page consistently in measure-and-improve - Replace em dashes in procedural/instructional text (GitHub label step, GitLab trigger pointers, Jira caution) per the style guide - Bold and link the Foreman name field on the GitLab page to match GitHub - Parallelize the no-PR troubleshooting fix sentence - Clarify that a finished work item links to the pull request (quickstart) - Use descriptive anchor text for the factory-as-code example link - reference/cli: fold the stale warp-cli note into the deprecation caution so the page no longer tells readers to migrate to a deprecated binary (addresses open review comment on #508) Co-authored-by: Warp <agent@warp.dev>
* docs(factories): call out paid GitLab plan requirement with GitLab doc links Co-Authored-By: Warp <agent@warp.dev> * Apply suggestions from code review Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com> --------- Co-authored-by: Warp <agent@warp.dev> Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Gates the factory launch. Implementation to follow.
Conversation: https://staging.warp.dev/conversation/7451da22-6397-4ae3-a494-9f167301b6ef
Run: https://oz.staging.warp.dev/runs/019ff6fe-37b6-7588-b397-a62d8c9e2a5a
This PR was generated with Oz.