docs(factories): address launch review feedback - #563
Conversation
Six changes from review on #508: - Link the Early Access callouts to www.warp.dev/factories/request-access, so a reader who can't use Factories yet has somewhere to go. - Rename "control room" to "factory dashboard". The old term appeared nowhere in the product; the app calls this surface a dashboard. Renames the page and slug (never published, so no redirect) and disambiguates it from **Dashboard**, the metrics page inside it. - Rewrite the quickstart around the decisions a reader makes rather than the setup wizard's click path. Also corrects the agent roster: all four subagents ship enabled, so the step is turning things off, not on. - Add GitLab everywhere the other integrations are enumerated. It landed after the alignment passes, so nothing referenced it — including the trigger provider list, which was missing `gitlab` entirely. - Restructure troubleshooting into symptom categories with per-source routing, and move it out of Management & observability to its own top-level sidebar entry. - Write down the Warp Factories naming rule and make the guidance match. vars.ts, AGENTS.md, and terminology.md all instructed writers to use the banned capitalized "Factory" form; a new `factory-proper-noun` lint check now enforces the rule. Also corrects three product-accuracy defects found while verifying the above, each checked against warp-server: - The **Code** tab is labeled **Factory definition**, and renders only for Warp-managed factories (FactoryNavGroup.tsx). - There is no **Runners** page; runners are a section of **Settings** (FactoryRunners/RunnerSettingsSection.tsx). - A factory definition cannot be hosted in GitLab. FactoryForge accepts only `github` and `code_storage` (model/types/factory_files.go). Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR was generated with Warp. Comment |
|
Your Warp account is not a member of any team with access to this repository. |
|
Your GitHub account is not connected to Warp. Connect it here. |
|
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 |
There was a problem hiding this comment.
Overview
This PR updates the Warp Factories launch docs with the factory dashboard rename, GitLab coverage, a rewritten quickstart, troubleshooting restructuring, and a new factory-proper-noun lint rule. I found two merge-blocking issues: the new access CTA points at a URL the PR says currently 404s, and the new lint rule has a false negative for the banned singular product name. No approved spec context was available, and I found no security-specific findings.
Concerns
- The Early Access CTA should not ship while its linked request-access page returns 404.
- The
factory-proper-nouncheck currently letsWarp Factorypass even though the new rule forbids that singular form.
Verdict
Found: 1 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
|
||
| :::note | ||
| Warp Factories is in **Early Access** and available to a limited set of teams. | ||
| Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. |
There was a problem hiding this comment.
🚨 [CRITICAL] This CTA points to a URL the PR description says currently 404s. Don't merge a user-facing docs link that fails; point it to a live access channel or hold this change until the marketing page is live.
| for m in FACTORY_BARE.finditer(prose): | ||
| before = prose[:m.start()] | ||
| after = prose[m.end():] | ||
| if before.rstrip().endswith("Warp"): |
There was a problem hiding this comment.
Warp Factory through, but the new terminology rule says the product is only Warp Factories and an instance is lowercase. FACTORY_BARE doesn't match Factories, so this exception only hides the banned singular form; remove it and let the existing Factory MCP exception handle the shipped feature name.
PR #563 (merged to the staging branch after our review rounds, then squash-merged to main) restructured 'Set up your factory' from a numbered list into ### subheadings with prose paragraphs -- the exact anti-pattern flagged repeatedly on the GitHub/GitLab integration docs. It also broke 'Setup asks you for the following,' which no longer led into an actual list. - Flatten the section back into a single numbered list, preserving #563's content improvements (GitLab support, Foreman name terminology, dashboard naming). - Move the Factory MCP skip-the-wizard aside into a :::note so it doesn't interrupt the numbered flow. - Rewrite the 'What you'll decide' bullets as plain one-sentence statements instead of bold-phrase-dash-definition pairs. Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): make web app name the hyperlink in quickstart.mdx and github.mdx Match the pattern already applied to gitlab.mdx: the Warp Factories web app name itself is the link, instead of a separate 'at platform.warp.dev' link fragment following the name. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): rename @oz-agent -> @warp-agent, Oz by Warp -> Warp Factories Consolidates PR #549 review-fix work into this fast-follow PR: - Renames the legacy GitHub integration mention handle and GitHub App name across platform docs to match the Warp Factories launch naming. - Resolves the factories/integrations/gitlab.mdx and platform/integrations/gitlab.mdx content, adopting Foreman-name terminology and fixing stale control-room links to factory-dashboard. - Flags two open product questions inline for tech review: whether GitLab is supported as a definitions-as-code host, and whether a native GitLab.com OAuth integration exists today. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): restore numbered steps in quickstart's setup section PR #563 (merged to the staging branch after our review rounds, then squash-merged to main) restructured 'Set up your factory' from a numbered list into ### subheadings with prose paragraphs -- the exact anti-pattern flagged repeatedly on the GitHub/GitLab integration docs. It also broke 'Setup asks you for the following,' which no longer led into an actual list. - Flatten the section back into a single numbered list, preserving #563's content improvements (GitLab support, Foreman name terminology, dashboard naming). - Move the Factory MCP skip-the-wizard aside into a :::note so it doesn't interrupt the numbered flow. - Rewrite the 'What you'll decide' bullets as plain one-sentence statements instead of bold-phrase-dash-definition pairs. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): make 'What you'll decide' bullets direct sentences Use imperative verbs (Choose/Name/Decide) so each item states the decision directly instead of reading as an indirect question. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): add Early Access note to common entrance-point pages Add the same Early Access note used on the overview page to quickstart.mdx, how-factories-work.mdx, and factory-agents.mdx, since readers may land on these directly via search or a shared link without passing through the overview first. Also standardize placement: the note now sits at the very top of the page content on all four pages, immediately after the frontmatter (and import, where present), before any intro prose. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): tighten decide bullets, prerequisites, and split setup steps - 'What you'll decide': reword the intro to avoid the semicolon and to set up the list as noun phrases (the intro's 'you decide' already supplies the verb, so bullets no longer repeat 'choose'/'decide'). Replace the closing sentence with a direct statement that these are editable after setup. - Prerequisites: drop the implied 'if your team doesn't have it yet.' - Set up your factory: step 1 now names the actual action (click + next to Factories). Split the old step 2 into choosing/authorizing a code host and organization, then a separate step for selecting repos and clicking Add repos, matching the real wizard flow. Rewrote the Factory MCP note to describe what create_factory covers directly instead of a step-number cross-reference that breaks when steps are renumbered. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): add setup wizard screenshots and fix step order in quickstart.mdx - Add cropped screenshots for 5 of the 6 'Set up your factory' steps (open wizard, connect organization, select repos, name factory, pick agents), sourced from a real walkthrough. - Swap the order of the agent-toggle and chat/tracker-connection steps to match the actual wizard flow: connecting Slack/an issue tracker happens before the agent-picker screen, not after. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): split issue tracker into its own step after agent picker Clarifies the real wizard order: connecting a chat tool (Slack) happens before the agent picker, and connecting an issue tracker is a separate screen that comes after it, not bundled into the same step. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): polish quickstart wording per review - Add missing comma after 'Optionally' in steps 5 and 7. - Simplify the post-procedure sentence to 'Warp creates the factory and opens its dashboard.' - Introduce 'setup wizard' plainly in the procedure's lead-in sentence instead of only in a screenshot caption, then reference it directly in the skip-the-wizard note ('Want to skip the wizard? ...'). Co-Authored-By: Warp <agent@warp.dev> * docs(factories): tighten quickstart intro paragraph and decide bullets - Reduce repeated 'team' in the opening sentence ('team of cloud agents' / 'your team's requests') by rewording to 'a group of cloud agents that turns incoming requests into pull requests.' - Split the comma-heavy second sentence into two shorter ones so it reads more cleanly. - Drop the redundant 'now' from the last decide-bullet and rework the closing sentence to 'a best guess is fine for now.' Co-Authored-By: Warp <agent@warp.dev> * docs(factories): tighten skip-the-wizard note in quickstart.mdx Two shorter, more direct sentences instead of one long clause-chained sentence. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address Aloke's video feedback (gaps 1-3 + code comment fix) - connect-your-factory.mdx: weave the 'Good to know' bullets into the sections they relate to (source table, connect-a-source steps, and how-work-reaches-your-factory) instead of an appendix-style dump. - factory-dashboard.mdx: remove the exhaustive 'Pages at a glance' table (redundant with the per-page sections below it) and lead with the Dashboard metrics page instead, matching the actual landing experience. - factory-dashboard.mdx / measure-and-improve.mdx: clarify what counts as human input for the Autonomy metric. - sidebar.ts: update the stale 'pending ZL naming sign-off' comment now that the Automation Platform name is confirmed. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): add self-hosted worker example to factory-as-code.mdx Grounded in the existing workerHost field and infrastructure-and-security.mdx's 'Choose an execution host' section, not new/unverified specifics. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): feature the Factory MCP creation path up front in quickstart.mdx Aloke felt the agent-driven create_factory flow was underselling a real differentiator by being a footnote-style :::note after all 7 wizard steps. Move it to the top of 'Set up your factory,' presented as a real alternative before the numbered wizard steps rather than an afterthought. Co-Authored-By: Warp <agent@warp.dev> * docs: bake Aloke's general feedback themes into the style guide and feature-doc template AGENTS.md: - Voice & tone: add a rule against AI-sounding copy. - General guidance (all content types): add rules to sequence basics before jargon, avoid appendix-style/bolted-on content, avoid over-specifying counts/internals that drift, feature real differentiators structurally instead of as footnotes, and verify claims against the live product. Strengthen the practical-examples rule to prefer complete examples for enterprise/infra features. - Procedural rules: add 'explain the default before the override' for configurable infrastructure and advanced settings. .agents/templates/feature-doc.md: add inline reminders in Key features and How it works to not bury real differentiators as footnotes and to avoid citing exact tool/component counts that can go stale. draft_conceptual and draft_feature_doc skills already defer to AGENTS.md's 'Drafting by content type' section directly, so these additions flow through automatically without needing separate skill edits. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
* docs(factories): make web app name the hyperlink in quickstart.mdx and github.mdx Match the pattern already applied to gitlab.mdx: the Warp Factories web app name itself is the link, instead of a separate 'at platform.warp.dev' link fragment following the name. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): rename @oz-agent -> @warp-agent, Oz by Warp -> Warp Factories Consolidates PR #549 review-fix work into this fast-follow PR: - Renames the legacy GitHub integration mention handle and GitHub App name across platform docs to match the Warp Factories launch naming. - Resolves the factories/integrations/gitlab.mdx and platform/integrations/gitlab.mdx content, adopting Foreman-name terminology and fixing stale control-room links to factory-dashboard. - Flags two open product questions inline for tech review: whether GitLab is supported as a definitions-as-code host, and whether a native GitLab.com OAuth integration exists today. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): restore numbered steps in quickstart's setup section PR #563 (merged to the staging branch after our review rounds, then squash-merged to main) restructured 'Set up your factory' from a numbered list into ### subheadings with prose paragraphs -- the exact anti-pattern flagged repeatedly on the GitHub/GitLab integration docs. It also broke 'Setup asks you for the following,' which no longer led into an actual list. - Flatten the section back into a single numbered list, preserving #563's content improvements (GitLab support, Foreman name terminology, dashboard naming). - Move the Factory MCP skip-the-wizard aside into a :::note so it doesn't interrupt the numbered flow. - Rewrite the 'What you'll decide' bullets as plain one-sentence statements instead of bold-phrase-dash-definition pairs. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): make 'What you'll decide' bullets direct sentences Use imperative verbs (Choose/Name/Decide) so each item states the decision directly instead of reading as an indirect question. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): add Early Access note to common entrance-point pages Add the same Early Access note used on the overview page to quickstart.mdx, how-factories-work.mdx, and factory-agents.mdx, since readers may land on these directly via search or a shared link without passing through the overview first. Also standardize placement: the note now sits at the very top of the page content on all four pages, immediately after the frontmatter (and import, where present), before any intro prose. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): tighten decide bullets, prerequisites, and split setup steps - 'What you'll decide': reword the intro to avoid the semicolon and to set up the list as noun phrases (the intro's 'you decide' already supplies the verb, so bullets no longer repeat 'choose'/'decide'). Replace the closing sentence with a direct statement that these are editable after setup. - Prerequisites: drop the implied 'if your team doesn't have it yet.' - Set up your factory: step 1 now names the actual action (click + next to Factories). Split the old step 2 into choosing/authorizing a code host and organization, then a separate step for selecting repos and clicking Add repos, matching the real wizard flow. Rewrote the Factory MCP note to describe what create_factory covers directly instead of a step-number cross-reference that breaks when steps are renumbered. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): add setup wizard screenshots and fix step order in quickstart.mdx - Add cropped screenshots for 5 of the 6 'Set up your factory' steps (open wizard, connect organization, select repos, name factory, pick agents), sourced from a real walkthrough. - Swap the order of the agent-toggle and chat/tracker-connection steps to match the actual wizard flow: connecting Slack/an issue tracker happens before the agent-picker screen, not after. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): split issue tracker into its own step after agent picker Clarifies the real wizard order: connecting a chat tool (Slack) happens before the agent picker, and connecting an issue tracker is a separate screen that comes after it, not bundled into the same step. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): polish quickstart wording per review - Add missing comma after 'Optionally' in steps 5 and 7. - Simplify the post-procedure sentence to 'Warp creates the factory and opens its dashboard.' - Introduce 'setup wizard' plainly in the procedure's lead-in sentence instead of only in a screenshot caption, then reference it directly in the skip-the-wizard note ('Want to skip the wizard? ...'). Co-Authored-By: Warp <agent@warp.dev> * docs(factories): tighten quickstart intro paragraph and decide bullets - Reduce repeated 'team' in the opening sentence ('team of cloud agents' / 'your team's requests') by rewording to 'a group of cloud agents that turns incoming requests into pull requests.' - Split the comma-heavy second sentence into two shorter ones so it reads more cleanly. - Drop the redundant 'now' from the last decide-bullet and rework the closing sentence to 'a best guess is fine for now.' Co-Authored-By: Warp <agent@warp.dev> * docs(factories): tighten skip-the-wizard note in quickstart.mdx Two shorter, more direct sentences instead of one long clause-chained sentence. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): address Aloke's video feedback (gaps 1-3 + code comment fix) - connect-your-factory.mdx: weave the 'Good to know' bullets into the sections they relate to (source table, connect-a-source steps, and how-work-reaches-your-factory) instead of an appendix-style dump. - factory-dashboard.mdx: remove the exhaustive 'Pages at a glance' table (redundant with the per-page sections below it) and lead with the Dashboard metrics page instead, matching the actual landing experience. - factory-dashboard.mdx / measure-and-improve.mdx: clarify what counts as human input for the Autonomy metric. - sidebar.ts: update the stale 'pending ZL naming sign-off' comment now that the Automation Platform name is confirmed. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): add self-hosted worker example to factory-as-code.mdx Grounded in the existing workerHost field and infrastructure-and-security.mdx's 'Choose an execution host' section, not new/unverified specifics. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): feature the Factory MCP creation path up front in quickstart.mdx Aloke felt the agent-driven create_factory flow was underselling a real differentiator by being a footnote-style :::note after all 7 wizard steps. Move it to the top of 'Set up your factory,' presented as a real alternative before the numbered wizard steps rather than an afterthought. Co-Authored-By: Warp <agent@warp.dev> * docs: bake Aloke's general feedback themes into the style guide and feature-doc template AGENTS.md: - Voice & tone: add a rule against AI-sounding copy. - General guidance (all content types): add rules to sequence basics before jargon, avoid appendix-style/bolted-on content, avoid over-specifying counts/internals that drift, feature real differentiators structurally instead of as footnotes, and verify claims against the live product. Strengthen the practical-examples rule to prefer complete examples for enterprise/infra features. - Procedural rules: add 'explain the default before the override' for configurable infrastructure and advanced settings. .agents/templates/feature-doc.md: add inline reminders in Key features and How it works to not bury real differentiators as footnotes and to avoid citing exact tool/component counts that can go stale. draft_conceptual and draft_feature_doc skills already defer to AGENTS.md's 'Drafting by content type' section directly, so these additions flow through automatically without needing separate skill edits. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>


Addresses the review feedback on #508. Targets
hyc/factory-launch, notmain.What changed
1. Early Access links out. The callouts said Factories was limited-availability without telling anyone how to get in. They now link
www.warp.dev/factories/request-access— on the Factories overview, the quickstart prerequisites, the docs home, and the platform overview. That URL 404s until the marketing page ships, so the external link checker will flag it in the meantime.2. "Control room" → "factory dashboard". Worth flagging: "control room" appeared nowhere in the product — it was a docs coinage. The app calls this surface a dashboard, and
/:factoryIdredirects todashboard. The page and slug are renamed (never published, so no redirect needed) and every mention updated.The rename collides with a real page, so there's a disambiguation rule now: bold Dashboard is the metrics page inside the surface; unbolded "factory dashboard" is the surface itself. A note at the top of the page states it.
3. Quickstart rewritten around tasks. It was eight steps of click path — the welcome screen, the
+fallback, per-screen Next presses. It's now the four decisions a reader actually makes: which code, what it's called, which agents, where work comes from. This also fixes a factual error: all four subagents ship enabled (AgentsStep.tsx), so the old "Keep Code on" described a toggle nobody had flipped.4. GitLab added everywhere the other integrations are listed. #549 merged after the alignment passes, so nothing referenced it — the source table, the default-automations list, the integration-guide list, the intake sentences, the troubleshooting routing, and
factory-as-code's trigger provider list, which was missinggitlabentirely. The stale{/* TODO */}waiting on that PR is gone. I checked the whole trigger catalogue againstwarp-server/model/types/triggers/triggers.go— GitHub, Linear, Jira, Slack, schedule, and factory all matched;gitlabwas the only gap.5. Troubleshooting restructured and moved. Was three ungrouped symptoms filed under Management & observability, next to the metrics pages. Now grouped into "Setting up a factory" / "Work isn't starting" / "Runs and work items", with a per-source routing table, and promoted to its own top-level sidebar entry at the end of the tab.
6. The Warp Factories naming rule, written down and enforced. Prose was nearly clean, but
vars.ts,AGENTS.md, andterminology.mdall instructed writers to produce the banned capitalized form ("write 'Factory dashboard' directly"). Those are flipped, the rule is documented on the GitHub Actions model, and a newfactory-proper-nounstyle_lintcheck enforces it.The check is deliberately quiet — its first draft produced 9 hits and 8 were wrong. It ignores positional capitals, frontmatter, code, the shipped Factory MCP name, verbatim UI strings, and Factory.ai (Droid's maker). 21 regression cases in
test_factory_proper_noun.py.Product-accuracy fixes
Three defects found while verifying the rename, each checked against
warp-server:FactoryNavGroup.tsx. The old "Managed in GitHub" row implied a tab that isn't rendered for GitHub-backed factories.FactoryRunners/RunnerSettingsSection.tsx. Two pages contradicted each other; Settings was right.FactoryForgeaccepts onlygithubandcode_storage, sogitlab.mdx's claim that GitLab-hosted definitions "sync the same way" was wrong.Two things for you to decide
Factory. I kept it, because the product agrees — the server registers aswarp-factoryand its skill calls itself "the Warp Factory MCP". Say the word and it becomes "Warp Factories MCP" in docs, at the cost of drifting from the shipped name.Validation
npm run buildclean · 0 broken internal links (3,694 checked) · 0 new broken anchors ·style_lint --changedshows 0factory-proper-noun,platform-determiner, andhardcoded-varissues · both lint test suites pass (21 + 11 cases) · verified in the built HTML that Troubleshooting renders as a top-level sidebar entry.Plans: