docs(factories): add launch documentation foundation - #537
Merged
Conversation
Co-Authored-By: Warp Agent <agent@warp.dev> Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR adds the Factories documentation foundation: navigation grouping, topic badge rendering, placeholder routes, llms.txt grouping, and link/terminology updates that move software-factory references toward the new Factories surface. I reviewed the attached diff for docs structure, style, changed code comments, testing expectations, security concerns, and spec drift; the spec context reports that no approved or repository spec context exists for this PR.
Concerns
- No blocking concerns found.
- Security pass: no security findings.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
This was referenced Aug 16, 2026
rachaelrenk
added a commit
that referenced
this pull request
Aug 16, 2026
Merges the five parallel article-pass branches, resolves the base merge against #537, and refines the lint check that guards this class of defect. The article pass - 188 sites across 72 files, split five ways by measured edit count and merged with no conflicts between siblings. Splitting on top-level directory alone would not have worked: platform/ is 134 of the 188, so one agent would have carried 65% of the load. Page titles - The four harness titles took the article: "Claude Code with the Automation Platform", "Codex with the ...", "Warp Agent with the ...", "Harnesses in the ...". These propagate into the <title> tag, breadcrumbs, and 18 hand-written link texts that mirror them, which is why 22 of the last 32 rendered defects traced to four strings. Leaving them bare would have put "Claude Code with Automation Platform" as an H1 directly above "Running it with the Automation Platform" in the body. - "Automation Platform overview" and "Automation Platform Open Source Partnership" stay bare: attributive, correct under both readings. - pricing-faqs.mdx:351 stays bare too -- "in Automation Platform cloud environments" modifies a noun. Resolving the merge with #537 - #537 removed the bare "Oz" entry from RENAME_SENSITIVE_VAR_STRINGS. Kept it, after measuring: it accounts for 48 findings, all in live product prose with zero in the changelog, which the linter already excludes. Post-rename those 48 are stale product names, which is precisely what we most want flagged. Dropping the entry would have silenced them. - Two quickstart pages conflicted in a way worth recording. #537 had fixed a terminology bug there, replacing the platform variable with "the Warp Agent" where the text meant the agent, not the platform. A child agent, working from the pre-#537 base, had faithfully applied the article rule to the same wrong text. Took #537's terminology fix and added the article only to the sentence that genuinely refers to the platform. Taking the child's side would have reverted a correct fix and reintroduced exactly the platform/agent conflation the glossary warns against. - Accepted #537's deletion of factories/configure-your-factory.mdx. Hardening check_platform_determiner The check flagged 103 sites when it landed; after the pass it flagged 3, and all 3 were false positives -- attributive uses like "using {...} orchestration" and "automated {...} runs". Two fixes, both found by writing the test first: - The attributive exemption now applies only to the prepositional case. Applied earlier, it swallowed "{...} provides ...", because "provides" is just a lowercase word to a regex. - Subject position now requires the token to actually begin a clause. Several subject verbs double as nouns, so "automated {...} runs" was being read as a subject and its verb. - Determiner lookback now spans one line, so a soft-wrapped sentence or wrapped frontmatter description is not falsely flagged. Two child agents independently reported this as a limitation of the audit heuristic. Added test_platform_determiner.py alongside the check. The ordering between these tests is load-bearing and I broke it twice while refining; both regressions are now covered cases. Verified in rendered output, the only place these defects are visible: dangling "the Oz" 0 (was 12 before the flip), bare referential "<preposition> Automation Platform" 0 (was 65 immediately after the flip), possessive without an article 0. Build clean at 377 pages, 0 broken internal links, style_lint total 1144 against a 1148 baseline, and 11/11 determiner regression cases pass. Co-Authored-By: Warp <agent@warp.dev>
rachaelrenk
added a commit
that referenced
this pull request
Aug 17, 2026
* docs: use Warp where it is broader and still accurate Four sites where the platform variable was doing work that the plain product name does better. All four read correctly under both the current value and the post-rename value, so they carry no rename risk and can land ahead of the naming decision. Background: #513 tokenized the phrase "Oz platform" but dropped the word "platform", leaving an orphaned article behind. Those sites render "the Oz" today. Rather than mechanically restoring the platform name at every one, each was assessed for whether the sentence is truly about the platform as distinct from Warp. Changed to "Warp" (3): - enterprise/enterprise-features/architecture-and-deployment.mdx and enterprise/security-and-compliance/security-overview.mdx — "let Warp orchestrate agents in isolated Docker containers". The adjacent bullet in the same list already reads "Warp provides cloud connectivity, shared context, visibility, and session sharing", so this is now consistent with its own neighbor. - platform/orchestration/index.mdx — the description said workflows run "on the Oz", but the page body says orchestration "works from the Warp app, the CLI, and the API & SDK, and supports local, cloud, and mixed execution". The description was narrower than the page; "in Warp" is more more more more more more more more more more more ud more more more more more more more more more moreerence for the Oz" carried no information under any product name. Now names what the CLI covers. Deliberately NOT changed: the ~12 remaining dangling sites, all under platform/. Those sentences explatform/. Those sentences explatform/. Those sentences explatform/viplatform/. Those sentences explatform/. Those sentences explatform/. s thplatform/. Those sentences explatform/. Those sentences explatform/. so collapsing them to "Warp" would break the sentence. They are handled would break the sentence. They are handled would break the sente rewould break the sentence. They are16 across 12 pages to 12 across 8, all under platform/; no VARS import left orphaned. Co-Authored-By: Warp <agent@warp.dev> * docs: flip the platform name to Automation Platform The value flip, the sidebar labels the Vite transform can't reach, and the lint guard. The 205-site article pass follows in subsequent commits on this branch; the two are only correct together, which is why they share one PR. src/data/vars.ts - WARP_AUTOMATION_PLATFORM: "Oz" -> "Automation Platform". - DASHBOARD and PLATFORM_RUN deliberately held at their Oz values rather than flipped alongside. Both name surfaces of the Oz v1 webapp, which keeps its name until 9/15, so flipping them now would make the docs disagree with what the reader sees on screen. - Added a comment recording that the new value is a common-noun phrase and needs a determiner in referential positions, since that is the non-obvious property that makes this rename more than a string change. src/sidebar.ts - 'Getting started with Warp and Oz' -> 'Getting started with Warp'. This duplicated index.mdx's frontmatter title, which IS tokenized, so the two would have disagreed the moment the variable flipped. Both shortened together; the long form is unwieldy in a sidebar row. - 'Oz API & SDK' and 'Oz web app' tokenized to VARS.API_SDK_NAME and VARS.WEB_APP. Both render VARS.WEB_APP. Both render VARS.WEB_APP. Both render VARS.WEB_APint is that the 9/15 flip now reaches the sidebar, which the Vite transform does not process. src/content/docs/index.mdx - Frontmatter title/label shortened to match the sidebar, and the article pass applied to the five referential body sites. - Taken whole rather than split, because its title is coupl- Taken whole rather than split, because its tts/skills/style_lint/style_lint.py - RENAME_SENSITIVE_VAR_STRINGS gains an "Automation Platform" entry. The bare "Oz" entries stay and now do double duty: a hardcoded "Oz" is both un-tokenized and stale. This immediately caught 5 hardcoded uses of the new name in the Factories stubs from #513. - New check_platform_determiner flags the token used possessively, after a preposition, or as a clause subject with no article. This class of defect is invisible in source -- `The {{WARP_AUTOMATION_PLATFORM}} provides` looks fine in the .mdx and only reads wrong once r provides` looks fine in the .mdx and only reads wrong once r provides` looks fine in the .mdx and only reads wrong ods are deliberately not flagged. Verified in rendered output, which is the only place either defect is visible: dangling "the Oz" drops from 12 to 0, confirming the flip fixes the pre-existing breakage rather than causing it. Bare "<preposition> Automation Platform" now measures 65, which is the article-pass backlog and is expected to be non-zero until that lands. Build clean at 370 pages. style_lint total 1256, up from 1148 baseline: +103 platform determiner (the new check) and +5 hardcoded (the Factoriedeterminer (the new check) and +5 hardcoded (the Factoriedeterminer (thcommit -F /tmp/base-msg.txt >/dev/null; git --no-pager show --stat --oneline HEAD | head -12 docs: flip the platform name to Automation Platform The value flip, the sidebar labels the Vite transform can't reach, and the lint guard. The 205-site article pass follows in subsequent commits on this branch; the two are only correct together, which is why they share one PR. src/data/vars.ts - WARP_AUTOMATION_PLATFORM: "Oz" -> "Automation Platform". - DASHBOARD and PLATFORM_RUN deliberately held at their Oz values rather than flipped alongside. Both name surfaces of the Oz v1 webapp, which keeps its name until 9/15, so flipping them now would make the docs disagree with what the reader sees on screen. - Added a comment recording that the new value is a common-noun phrase and needs a determiner in referential positions, since that is the non-obvious property that makes this rename more than a string change. src/sidebar.ts - 'Getting started with Warp and Oz' -> 'Getting started with Warp'. This duplicated index.mdx's frontmatter title, which IS tokenized, so the two would have disagreed the moment the variable flipped. Both shortened together; the long form is unwieldy in a sidebar row. - 'Oz API & SDK' and 'Oz web app' tokenized to VARS.API_SDK_NAME and VARS.WEB_APP. Both render identically today because those values hold until 9/15 -- the point is that the 9/15 flip now reaches the sidebar, which the Vite transform does not process. src/content/docs/index.mdx - Frontmatter title/label shortened to match the sidebar, and the article pass applied to the five referential b pass applied to the five referential b pass applied toitle is coupled to sidebar.ts and its body is not. .agents/skills/style_lint/style_lint.py - RENAME_SENSITIVE_VAR_STRINGS gains an "Automation Platform" entry. The bare "Oz" entries stay and now do double duty: a hardcoded "Oz" is both un-tokenized and stale. This immediately caught un-tokenized and stale. This immediately caught un-tokenized and sta Ne un-tokenized and stale. This immediately caught un-tokenized and st preposition, or as a clause subject with no article. This class of defect is invisible in source -- `The {{WARP_AUTOMATION_PLATFORM}} provides` looks fine in the .mdx and only reads wrong once rendered -- so it needs a rule rather than review attention. Attributive uses, frontmatter titles, and bold term leads are deliberately not flagged. Verified in rendered output, which is the only place either defect is visible: dangling "the Oz" drops from 12 to 0, confirming the flip fivisible: dangling "the Oz" drops from 12 to 0, confirming the flip fivisible:omation Platform" now measures 65, which is the article-pass backlog and is expected to be non-zero until that lands. Build clean at 370 pages. style_lint total 1256, up from 1148 baseline: +103 platform determiner (the new check) and +5 hardcoded (the Factories stubs). Co-Authored-By: Warp <agent@warp.dev> * Add missing "the" articles for WARP_AUTOMATION_PLATFORM references The WARP_AUTOMATION_PLATFORM var flipped from "Oz" (proper noun) to "Automation Platform" (common-noun phrase). Referential uses (subject, object, possessor) now need a definite article; attributive uses (modifying a following noun) stay bare. Fixed 33 referential sites across platform/self-hosting/, terminal/, support-and-community/, and getting-started/ — e.g. "connects to {VARS}" -> "connects to the {VARS}", "{VARS} orchestrates" -> "The {VARS} orchestrates", "{VARS}'s backend" -> "the {VARS}'s backend". Left 8 flagged sites unchanged as genuinely attributive/label uses, not referential: - platform/self-hosting/quickstart.mdx:4, monitoring.mdx:6, security-and-networking.mdx:4, troubleshooting.mdx:4 — "self-hosted Automation Platform worker(s)/cloud agents" compounds where the token modifies the following noun (worker/workers/cloud agents), parallel to "Automation Platform-hosted". - platform/self-hosting/troubleshooting.mdx:61 — "Automation Platform Cloud API Keys" is a literal Settings UI menu-path label, not a referential mention. - support-and-community/community/open-source-partnership.mdx:13 — "Free Automation Platform credits" bold-lead definition-list term, attributive compound like "Warp credits". - support-and-community/index.mdx:48 — "[Automation Platform Open Source Partnership]" is a standalone list-label link naming the program (matches the page's own bare title), not prose referencing the platform. - support-and-community/plans-and-billing/pricing-faqs.mdx:351 — "in Automation Platform cloud environments" is attributive, modifying "cloud environments". Left all oz-agent-worker/oz CLI/oz.warp.dev mentions untouched per scope instructions. Co-Authored-By: Warp <agent@warp.dev> * Add missing definite articles for WARP_AUTOMATION_PLATFORM (harnesses + reference) WARP_AUTOMATION_PLATFORM flipped from "Oz" (proper noun) to "Automation Platform" (common-noun phrase), so referential uses of the token now need a definite article. Fixed 19 genuine referential sites across platform/harnesses/ and reference/ (subjects, objects of prepositions, and possessives). Left 23 audit-flagged sites unchanged as correct-as-is: - Link text that mirrors the linked page's exact title (e.g. "Harnesses in {AUTOMATION_PLATFORM}", "Warp Agent with {AUTOMATION_PLATFORM}", standalone "[{AUTOMATION_PLATFORM}](/platform/overview/)" list items) is a name/label, not a referential clause, so it stays bare. - Attributive compound modifiers before a noun: "any {AUTOMATION_PLATFORM} trigger", "the same {AUTOMATION_PLATFORM} features", and the UI label "{AUTOMATION_PLATFORM} Cloud API Keys" (reference/cli/api-keys.mdx:41,94). - False positives from the heuristic's single-line lookback: the determiner "the" already exists but sits on a wrapped frontmatter line (integration-disabled.mdx:4-5) or before an <a> tag whose href attribute sits between "the" and the token (integration-disabled.mdx:47, integration-not-configured.mdx:59). claude-code.mdx and codex.mdx both keep the sentence "...connects it to the rest of the {AUTOMATION_PLATFORM}" as directed; only the earlier "with {AUTOMATION_PLATFORM}" in the same sentence needed the article added. Final scoped audit: 23 remaining (all documented exceptions above), 0 require further edits. Co-Authored-By: Warp <agent@warp.dev> * docs: add missing definite articles for Automation Platform rename Fixes referential uses of {VARS.WARP_AUTOMATION_PLATFORM} in platform/integrations/, platform/triggers/, and platform/handoff/ that read incorrectly now that the token renders as the common-noun phrase 'Automation Platform' instead of the proper noun 'Oz'. Inserted 'the' before subject, object, and possessive uses across cloud-providers.mdx, quickstart.mdx, jira.mdx, linear.mdx, scheduled-agents-quickstart.mdx, and handoff/index.mdx (33 sites total). Left 7 audit-flagged sites unchanged because the token is attributive (compound-noun modifier), which correctly stays bare per the style rule, matching the 'Automation Platform settings' pattern: - azure-devops.mdx, bitbucket.mdx, gitlab.mdx: 'any {TOKEN} trigger' - cloud-providers.mdx:146: 'the agent's {TOKEN} OIDC token' - cloud-providers.mdx:266: 'All {TOKEN} OIDC tokens' - quickstart.mdx:11: '{TOKEN} integrations let you trigger...' - scheduled-agents.mdx:58: '{TOKEN} scheduled agents are managed...' Left all oz-agent-action, oz-agent-worker, and @oz-agent references untouched, since those are package/handle names, not the product name. Co-Authored-By: Warp <agent@warp.dev> * Add missing definite articles for Automation Platform (platform core + guides) WARP_AUTOMATION_PLATFORM changed from "Oz" (proper noun) to "Automation Platform" (common noun), so referential uses now need a definite article. Fixed 23 sites across 14 files in scope (top-level platform/*.mdx, platform/orchestration/, guides/): subjects, objects, and possessives of {VARS.WARP_AUTOMATION_PLATFORM} now read "the Automation Platform ...". platform/environments.mdx:33 also got a light rewrite ("required for [Automation Platform] automation" -> "required for automation on the [Automation Platform]") to avoid the awkward "Automation Platform automation" doubling that a mechanical article insert would have produced. Left bare (attributive/false-positive per the audit heuristic, not edited): - platform/deployment-patterns.mdx:18,72 - "Automation Platform orchestrator" used as a parenthetical/definition-list example value, not a sentence subject. - platform/deployment-patterns.mdx:116 - "using Automation Platform orchestration" - orchestration is uncountable, attributive compound. - platfor- platfor- platfor- platfor- platfor- platfor- platfor- platfor- platibutive compound modifying "runs". - platform/index.mdx:152 and platform/warp-hosting.mdx:54 - standalone bulleted link labels ("* [Automation Platform](...) - ..."). - guides/agent-workflows/set-up-a-software-factory.mdx:166 - "a managed Automation Platform deployment" already carries Automation Platform deployment" already carries Automation Plw.mdx:194 ("Automation Platform orchestrator still manages lifecycle...") got "The" added since there it's the head of a full sentence subject, unlike the parenthetical-list uses left bare above. Final scoped audit (python3 /tmp/article_audit.py platform guides, ignoring sibling-owned platform/{integrations,triggers,handoff,harnesses, self-hosting}/): 0 remaining sites in my scope; the 7 sites listed above are the only ones still flagged and are intentional per the notes above. Co-Authored-By: Warp <agent@warp.dev> * docs: update the terminology references for the rename The two reference surfaces that tell future authors and agents how to write about the platform, plus the Factories stubs the new lint guard caught. .agents/references/terminology.md and AGENTS.md - "Oz terminology" is now "Automation Platform terminology" in both. - Added "The article rule" as its own subsection in each. This is the property that makes the rename more than a string swap, and it is not discoverable from the glossary entries themselves, so it needed to be stated rather than implied. - Rewrote the "Preferred phrases" list. It previously read "Ask Oz to...", "Oz can help you...", which contradicted the rule two paragraphs above it: "Oz is the platform, not the agent." That worked only because "Oz" was doing double duty as both the platform and an assistant you address. The rename ends the ambiguity and makes the contradiction visible -- "Ask the Automation Platform to..." is plainly wrong -- so the phrases now address the agent instead. - Added a "What still says Oz" section listing the 9/15 holdouts and the permanent ones. Without it, every remaining "Oz" reads as an oversight, which invites someone to "fix" a working `oz` command or the @oz-agent handle. Covers the binary, oz.warp.dev, DASHBOARD, PLATFORM_RUN, API_SDK_NAME, the oz-agent-* package names, the mention handles, changelog history, and literal Settings labels. - Recorded DASHBOARD, PLATFORM_RUN, WEB_APP, and API_SDK_NAME as holding their Oz values, each with the variable to use. - Dropped the "PENDING final naming confirmation" note from the Automation Platform entry, which is now resolved. src/content/docs/factories/*.mdx - Tokenized 5 hardcoded "Automation Platform" strings across 4 stub pages, adding the VARS import where absent. These are placeholder instruction blocks that HYC will replace, so tokenizing is arguably churn -- but the linter has no suppression mechanism, and 5 permanent warnings train people to ignore the guard. They render identically. These files sit outside every child agent's scope, so this lands independently of the article pass. Verified: build clean at 370 pages; the Factories stubs still render "Automation Platform tab"; hardcoded-var back to 71 from 76. Co-Authored-By: Warp <agent@warp.dev> * docs: add missing definite articles for Automation Platform rename (agents, enterprise, index, quickstart) Inserts "the" before referential uses of {VARS.WARP_AUTOMATION_PLATFORM} now that the token renders as "Automation Platform" (common noun) instead of "Oz" (proper noun). Attributive uses (e.g. "Automation Platform orchestrator", "Automation Platform Cloud API Keys") and standalone link labels are left bare per the style rule. Fixed 20 sites across 18 lines in: - agents/cli/cloud-and-orchestration.mdx, cli/index.mdx - agents/cli-agents/claude-code.mdx, codex.mdx, overview.mdx (first occurrence on each flagged line only; see notes below) - agents/index.mdx, getting-started/agents-in-warp.mdx, local-agents/interacting-with-agents/terminal-and-agent-modes.mdx - enterprise/enterprise-features/analytics-api.mdx, architecture-and-deployment.mdx (line 81 per lead's explicit note) - enterprise/getting-started/getting-started-developers.mdx, quickstart.mdx - enterprise/index.mdx - quickstart.mdx (root) Left bare as attributive uses / standalone labels / page-title link text (judgment calls, audit heuristic false positives): - agents/agent-memory/index.mdx:89 - "self-hosted Automation Platform instance" modifies "instance", attributive. - agents/cli/reference.mdx:35, enterprise/enterprise-features/ analytics-api.mdx:32,300 - "Automation Platform Cloud API Keys" is a Settings menu label, attributive. - agents/cli-agents/claude-code.mdx:18 (second occurrence) and :79, codex.mdx:18 (second occurrence) and :62, cli-agents/overview.mdx:18 (second occurrence) - "Claude Code with Automation Platform" / "Harnesses in Automation Platform" are page titles used as link text, not sentence-level referential use. - agents/local-agents/session-sharing.mdx:10 - "Automation Platform or third-party" is a parallel type-label, attributive. - enterprise/enterprise-features/architecture-and-deployment.mdx:18,98 - "Automation Platform orchestrator" / "Automation Platform orchestration" are attributive compounds. - enterprise/index.mdx:53 - "(Automation Platform, Claude Code, Codex, Copilot)" is a parallel list of proper agent names. - index.mdx:5 - already correct; "the" is on the preceding frontmatter line, audit heuristic doesn't see across the line break. - index.mdx:121 - standalone Next-steps list label, per lead's explicit note; left unchanged. - agents/index.mdx:37 - fixed with "The [**{VARS.WARP_AUTOMATION_PLATFORM}**]" but audit still flags it (heuristic doesn't detect "The" preceding a bracketed link); confirmed correct by manual inspection. Did not touch architecture-and-deployment.mdx / security-overview.mdx sentences that were deliberately changed to say "Warp" instead of the platform name. Co-Authored-By: Warp <agent@warp.dev> * docs: complete the article pass and harden the determiner check Merges the five parallel article-pass branches, resolves the base merge against #537, and refines the lint check that guards this class of defect. The article pass - 188 sites across 72 files, split five ways by measured edit count and merged with no conflicts between siblings. Splitting on top-level directory alone would not have worked: platform/ is 134 of the 188, so one agent would have carried 65% of the load. Page titles - The four harness titles took the article: "Claude Code with the Automation Platform", "Codex with the ...", "Warp Agent with the ...", "Harnesses in the ...". These propagate into the <title> tag, breadcrumbs, and 18 hand-written link texts that mirror them, which is why 22 of the last 32 rendered defects traced to four strings. Leaving them bare would have put "Claude Code with Automation Platform" as an H1 directly above "Running it with the Automation Platform" in the body. - "Automation Platform overview" and "Automation Platform Open Source Partnership" stay bare: attributive, correct under both readings. - pricing-faqs.mdx:351 stays bare too -- "in Automation Platform cloud environments" modifies a noun. Resolving the merge with #537 - #537 removed the bare "Oz" entry from RENAME_SENSITIVE_VAR_STRINGS. Kept it, after measuring: it accounts for 48 findings, all in live product prose with zero in the changelog, which the linter already excludes. Post-rename those 48 are stale product names, which is precisely what we most want flagged. Dropping the entry would have silenced them. - Two quickstart pages conflicted in a way worth recording. #537 had fixed a terminology bug there, replacing the platform variable with "the Warp Agent" where the text meant the agent, not the platform. A child agent, working from the pre-#537 base, had faithfully applied the article rule to the same wrong text. Took #537's terminology fix and added the article only to the sentence that genuinely refers to the platform. Taking the child's side would have reverted a correct fix and reintroduced exactly the platform/agent conflation the glossary warns against. - Accepted #537's deletion of factories/configure-your-factory.mdx. Hardening check_platform_determiner The check flagged 103 sites when it landed; after the pass it flagged 3, and all 3 were false positives -- attributive uses like "using {...} orchestration" and "automated {...} runs". Two fixes, both found by writing the test first: - The attributive exemption now applies only to the prepositional case. Applied earlier, it swallowed "{...} provides ...", because "provides" is just a lowercase word to a regex. - Subject position now requires the token to actually begin a clause. Several subject verbs double as nouns, so "automated {...} runs" was being read as a subject and its verb. - Determiner lookback now spans one line, so a soft-wrapped sentence or wrapped frontmatter description is not falsely flagged. Two child agents independently reported this as a limitation of the audit heuristic. Added test_platform_determiner.py alongside the check. The ordering between these tests is load-bearing and I broke it twice while refining; both regressions are now covered cases. Verified in rendered output, the only place these defects are visible: dangling "the Oz" 0 (was 12 before the flip), bare referential "<preposition> Automation Platform" 0 (was 65 immediately after the flip), possessive without an article 0. Build clean at 377 pages, 0 broken internal links, style_lint total 1144 against a 1148 baseline, and 11/11 determiner regression cases pass. Co-Authored-By: Warp <agent@warp.dev> * docs: replace the three Oz-branded graphics New exports from design, replacing the three rasterized assets that still carried Oz branding. These could not be fixed by the rename pass because the text is baked into the images. - Homepage hero: the old graphic paired "Warp" with an "Oz" logo, heading, and a browser chrome showing oz.warp.dev. The new one pairs Warp with Warp Factories. - "Most flexible platform for building with agents": the Trigger card's "Oz scheduler" bullet is now "Warp Factories scheduler". - Platform architecture diagram: "OZ CLI", "OZ-DESIGNED TRIGGERS", "OZ INFRASTRUCTURE", and "OZ-HOSTED RUNNERS" are now their Warp equivalents. Renamed two files whose names described the old branding, now that their contents no longer do. Astro content-hashes asset URLs, so there is no stable public URL to preserve and no redirect is needed: - warp-oz-welcome.png -> warp-factories-welcome.png - oz-diagram.png -> platform-architecture.png Rewrote the alt text and caption for all three. The old alt text described the old images ("Warp ... and Oz (the orchestration platform for cloud agents)"), so leaving it would have made the alt text disagree with the image -- an accessibility failure, not just a stale string. The new alt text describes what each diagram actually shows. Also tokenized the VideoEmbed title on the platform overview, which was hardcoded to "Oz Platform cloud agents overview video". Sizing: downscaled the 4K exports to match the dimensions of the assets they replace (1622, 1920, 1414 wide) so page layout is unchanged. An intermediate pass quantized them to a 256-colour palette, which cut ~65% of the weight but put visible dithering in the dark backgrounds and gradients; that was reverted. Astro re-encodes these to webp at build time, so the palette reduction was trading visible quality on the homepage for repo bytes that do not reach readers. Verified: build clean; all three serve as optimized webp under the new names; no oz-named asset remains in the build output. Co-Authored-By: Warp <agent@warp.dev> * fix(docs): resolve product-name variables in the copy-page payload The "Copy page as Markdown for LLMs" button was putting raw MDX source on the clipboard: `import` statements at the top and unsubstituted `{VARS.WARP_AUTOMATION_PLATFORM}` tokens throughout. An assistant reading the copied text learned the token, not the product name -- strictly worse than the stale name the rename replaced. Found while validating the rename. It is pre-existing, not caused by this branch: the same 7 leaks are present in a build of the pre-flip commit, so it arrived with the variable migration in #513 and has been shipping since. Fixing it here anyway, because a rename PR that leaves the LLM-facing copy surface emitting `{VARS.WARP_AUTOMATION_PLATFORM}` has not really finished the rename. Why only this surface was affected: the sibling `.md` route is generated by docs-markdown-integration.js from the *rendered* HTML after the build, by which point Astro has resolved everything. CopyPageButton runs during render and only has the source, so it now repeats the same two cleanups -- strip imports, resolve tokens. The token substitution falls back to leaving the match untouched when the key is not in vars.ts. That is load-bearing: platform/mcp.mdx documents the product's own secret-substitution syntax (`{{DBT_SERVICE_TOKEN}}`, `{{MY_SECRET}}`), which looks identical to a frontmatter token. Those three are correctly preserved. Known gap, left as a comment in the file: raw JSX (`<VideoEmbed />`) and directive syntax (`:::note`) still pass through, where the `.md` route renders them. The durable fix is for the button to fetch the page's own `.md` URL on click instead of carrying a second copy of the content. That is a behaviour change with its own error handling, so it is not folded into a rename PR. Verified across all 376 copy-page payloads in the build: leaked import statements 0 (was one per page with imports), unresolved variable tokens 3 (all the intentional MCP examples above), and the homepage payload now reads "powered by the **Automation Platform**". Co-Authored-By: Warp <agent@warp.dev> * docs: rename PLATFORM_RUN to "cloud agent run" per HYC HYC's call (8/17): the platform-level default should be the plain descriptive phrase rather than a branded one, with "Factory run" reserved for pages specifically about a factory. This reverses the hold I put on this variable in the flip commit, where I grouped it with DASHBOARD as an Oz v1 webapp surface. That grouping was wrong for this one: a run is a platform concept, not a property of the web app that displays it, so it had no reason to wait for 9/15. Checked all five call sites before changing the value. Every one is platform- or enterprise-scoped; none is factory-specific, so the single default covers them without needing a second variable. Kept the value singular so the two sites that write `{VARS.PLATFORM_RUN}s` still pluralize correctly. One site needed a prose fix rather than a substitution: interacting-with-agents/index.mdx read "Cloud agent conversations and cloud agent runs", which is correct but repetitive. Shortened to "Cloud agent conversations and runs" and dropped the variable there, since the surrounding sentence already establishes the subject. Recorded in both terminology.md and AGENTS.md, including the part the variable cannot express: it holds the general term, so factory-specific pages have to write "Factory run" directly. DASHBOARD is deliberately not changed in this commit. HYC proposed "Factory dashboard", but every current use of that variable is platform-scoped and three of them link to oz.warp.dev, so applying it uniformly would produce lines like "Factory dashboard — View task status from the Oz web app." Raised separately. Verified: build clean, style_lint 1142 against a 1148 baseline, platform-determiner still 0. Co-Authored-By: Warp <agent@warp.dev> * docs: rename DASHBOARD to "cloud agent dashboard" Completes HYC's run/dashboard terminology guidance, mirroring the shape used for PLATFORM_RUN: a plain platform-level default, with the factory-specific term written directly where it applies. HYC proposed "Factory dashboard" outright. Applying that to the variable would have been wrong, because all 24 call sites are platform- or enterprise-scoped and three of them link to oz.warp.dev. It would have produced "Factory dashboard - View task status from the Oz web app", labelled an oz.warp.dev link "Factory dashboard", and narrowed "Track all agent activity across your team" to a closed-beta product. The underlying reason is the same one that made runs easy: HYC's guidance is context-dependent, and a variable has exactly one value. Chose "cloud agent dashboard" over "Runs page". "Runs page" reads better in isolation and matches the actual URL, but it names a single page in the web app, while this surface is defined as unified across the Warp app and web -- and its Warp-app half is the Agent Management Panel, not a Runs page. The descriptive term keeps that meaning and parallels "cloud agent run". Four prose fixes so the new value reads well: - Two sites said "cloud agent ... cloud agent dashboard". Reworded to drop the duplicate rather than accept the stutter. - self-hosting/index.mdx led a bullet with the variable, which would have rendered a lowercase common noun where a capital belongs. Re-led the bullet with "Run history" and named the dashboard inside the sentence, matching the sibling bullets, which name capabilities. - run-a-software-factory-in-the-cloud.mdx is the one factory-scoped site, so it now says "Factory dashboard" directly. This is the carve-out HYC described. Two other sites keep both terms in one sentence ("in the cloud agent dashboard, the run is attributed to the bound cloud agent"). Left alone: the terms are eight words apart and refer to different things. Also fixes a bug I introduced in the previous commit. The copy-page substitution matched `{VARS.KEY}` but not the `${VARS.KEY}` form used inside JSX template literals, so `href={`${VARS.WEB_APP_URL}/runs`}` was resolving to `$https://oz.warp.dev/runs` with a stray dollar. Caught by reading the rendered dashboard mentions rather than by the build, which was green throughout. Now 0 across all 376 payloads. Verified: build clean; every dashboard mention renders as either "cloud agent dashboard" or, on the factory guide, "Factory dashboard"; no "Oz dashboard" remains. Co-Authored-By: Warp <agent@warp.dev> * docs: add rename transition callouts and corrected hero graphic Transition notices, so a reader arriving from an old link or bookmark is not left wondering whether Oz went away. Callouts on the two highest-inbound entry points: /platform/overview and /platform, which carry 16 legacy redirects each. Both state that only the name changed, that existing integrations, API keys, schedules, and scripts keep working, and that the `oz` CLI and web app hold the Oz name until 9/15 -- which is the actual question a reader has when the docs say "Automation Platform" but their terminal still says `oz`. A "(formerly Oz)" parenthetical on /platform/integrations, the single highest-redirect page at 19. Chose targets by inbound redirect count rather than intuition; of the next five candidates, three never name the platform at all, so there was nothing to attach a parenthetical to. Tried one on /platform/environments and reverted it: the sentence already ends in a parenthetical, and "(formerly Oz) (cloud agents, integrations, API runs)" is worse than no note. Both callouts carry a dated comment marking them for removal after 9/15. Hero graphic replaced again with the corrected export. The previous one still read "Use Warp's SOTA built-in agent Oz", which was doubly wrong: a stale name, and it called the built-in *agent* Oz when Oz was the platform. It now reads "Use the built in Warp Agent". Three lint guard changes, each because the guard was fighting correct copy: - Transition phrasings ("formerly Oz", "Oz is now", "the Oz name") no longer flag the old name. Without this, a rename callout cannot name the thing being renamed, and the author's only workaround is to backtick a product name. Only old-name literals are excused; a hardcoded new name on the same line still flags. - "Oz by Warp" is exempt. It is the GitHub App as it appears in GitHub's own UI at github.com/apps/oz-by-warp, and is what PRs and commits are attributed to. Renaming it in the docs would make them disagree with what the reader sees on GitHub. This alone was 39 of the 62 findings -- the guard was mostly reporting a product name that must not change. - Image alt text and figcaptions are exempt. Alt text is markdown, not JSX, so a token there renders the literal "VARS.WEB_APP" on the page. Figcaptions would substitute correctly, but a caption that flips ahead of the screenshot it captions is worse than one that stays stale. Both have to move by hand when the screenshots are retaken. Four genuinely stale references fixed, found once the exemptions cleared the noise: a VideoEmbed title, the "Oz PR review" workflow name (renamed in both the example YAML and the instruction that tells you to click it, which had to stay in sync), and alt text calling the agent "Oz". style_lint 1102 against a 1148 baseline; hardcoded-var 62 -> 22, with the remaining 22 all image descriptions that must track their screenshots. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Aug 18, 2026
* chore: gate factory launch
Placeholder commit to open a draft PR that will gate the factory launch.
Co-Authored-By: Warp Agent <agent@warp.dev>
* Factory launch (8/18): Automation Platform rename infra + Factories tab 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 763abea0, 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 763abea0. 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 248e6035, 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 248e6035 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 42b84229:
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>
* docs(factories): add launch documentation foundation (#537)
Co-authored-by: Warp Agent <agent@warp.dev>
* docs: add Warp Factories to docs landing pages (#538)
* 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 agents (#518)
* 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 and fix nav wrap (#543)
* 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 (#545)
* 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 Slack integration (#525)
* docs(factories): document Jira integration (#528)
* 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 (#531)
* 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>
* docs(factories): clarify Jira access-scoping gap is coming, not available (#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 (#521)
* 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 (#522)
* 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): use root-absolute links on merged factory pages (#550)
* docs(factories): fix relative links and non-rendering mermaid on merged pages
Convert all 31 relative internal links across factory-agents,
factory-mcp, measure-and-improve, and the Jira/Slack integration pages
to root-absolute paths with trailing slashes. Relative links resolve
against Starlight's trailing-slash page URLs (../platform/x becomes
/factories/platform/x) and 404 in the browser, while the file-path-based
CI link checker stays green — the same breakage bnavetta flagged on the
infrastructure page in #523.
Also remove the mermaid flowchart from measure-and-improve: the docs
site has no mermaid renderer, so the block displayed as a raw code
fence. The numbered improvement-loop list directly below it already
narrates every node and edge, so no information is lost.
Only pages whose owning PRs (#518, #521, #522, #525, #528) have already
merged are touched; open factory PRs own different files.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): restore improvement-loop mermaid diagram
Mermaid rendering shipped on main in c35aab4 (#515) after
hyc/factory-launch forked, so the diagram only failed to render because
the launch branch predates the renderer. Restore it; this PR now only
converts relative links to root-absolute paths.
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp <agent@warp.dev>
* docs(factories): document integrations and intake (#520)
* docs(factories): document integrations and intake
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): replace intake jargon with plain language on connect page
Rewrites Connect your factory so external readers don't need internal
vocabulary to follow it:
- Drop 'intake' everywhere (intake paths, intake boundaries, how intake
works); use plain framing like 'how work reaches your factory'.
- Dissolve the 'Intake boundaries' grab-bag table into a 'Good to know'
list scoped to user-facing behavior, and move provider authorization
mechanics to the per-provider integration guides.
- Remove internal implementation details: seeded tracker skill and
prompt appendix, retry-safety guidance for receiving workflows,
subscription-matching plumbing, and the unexplained 'managed factory'
qualifier.
- Simplify the flow diagram and setup steps; gloss 'foreman agent' and
'work item' on first mention per the terminology glossary.
Validated with npm run build (377 pages), the style_lint skill
(--changed, no findings for this page), and the broken-links checker
(0 broken links).
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): link provider mentions to their integration guides
Link Slack, GitHub, Linear, Jira, and Factory MCP from the source table,
the default-automation bullets, and the tracker-selection note so readers
can jump straight to the relevant guide from wherever a provider is
mentioned.
Validated with the style_lint skill (no findings for this page) and the
broken-links checker (0 broken links).
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): Jira work goes to Warp, surfaced through Rovo
The agent users assign or mention in Jira is Warp (the rovo:agentConnector
module named 'Warp' in forge-jira/manifest.yml), not a generic Rovo agent.
Rovo is Atlassian's framework that surfaces it; the conversation still
happens in a Rovo agent session (A2A agent_session_created ingress).
Reword the source table, Jira default-automation bullet, and integration
guides bullet accordingly, and align 'Rovo agent session' phrasing with
the Jira integration guide.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): de-emphasize Rovo on the connect overview
Lead with what matters to the reader: Jira work items are assigned to
Warp. Drop the remaining Rovo mentions from the source table, the Jira
integration-guides bullet, and the follow-ups note — the Jira guide
covers the Rovo session mechanics.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): tighten connect page from review feedback
- Drop the vague 'What you get back' table column; the intro already
covers results posting back to the source
- Expand the foreman description: what it orchestrates (triage, spec,
implementation, review) and where it pauses for humans
- Replace the marketing-toned 'You stay in control of what ships'
bullet with a factual pull-request hand-off note
- Remove em dashes from procedural steps and reduce them elsewhere
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document Linear integration (#527)
* docs(factories): document Linear integration
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): rewrite Linear page for clarity
Restructure the page in plainer language without changing any
verified claims:
- Open with the two-part mental model (connection grants access,
automations route work) instead of abstract phrasing
- Split the dense agent-session paragraph into a dedicated
'Route agent sessions' subsection
- Move the OAuth-scope-vs-routing caveat and the duplicate-run
hazard into :::caution callouts
- Rename jargon headings ('Writeback and operational boundaries'
-> 'What the factory can do in Linear') and simplify table cells
- Trim redundant sentences throughout
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): remove internal vocabulary from Linear page
Polish pass for external readers:
- Replace the Linear activity-type enumeration ('thoughts, actions,
plan changes, final responses, and errors') with plain descriptions
of what shows up in the session
- Fold the session fallback into 'Route agent sessions' and drop the
'configured fallback behavior' routing mechanics
- Rephrase 'requester attribution' and 'artifact links' in
user-facing terms
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address review feedback on Linear page
- Replace the intro with the launch-approved Linear description copy
- Split setup into first-time factory setup vs. factory settings, per review
- Move trigger configuration into its own section and note the Not
connected state in the Add trigger menu
- Editorial polish: sharper frontmatter description, prerequisite
wording, expected outcomes after connect steps, clearer link text
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): polish Linear page structure and flow
- Promote Route agent sessions to its own section directly after the
connect paths, matching the assign-or-tag flow the intro describes
- Orient trigger steps from the Automations page (New > Add trigger)
- Tighten section leads and the settings parity outcome sentence
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document infrastructure and security (#523)
* docs(factories): document infrastructure …
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
1 participant
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.
Summary
Adds the shared foundation required for independently reviewable Warp Factories feature docs:
This PR intentionally contains no final feature-page prose. After it lands, every existing feature PR can be rebuilt from the new base with one or two owned files and independent green CI.
Validation
npm run typecheck: 0 errorsnpm run build: 377 pagesProposed reviewers
@rachaelrenk@peicodesReviewers are listed for planning only and have not been requested.
Screenshots
Not applicable; this PR provides IA and route scaffolding.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plans: https://staging.warp.dev/drive/notebook/13ygGz65y7ptOxoBZVaqRA
Co-Authored-By: Warp Agent agent@warp.dev