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>
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