docs(factories): launch fast-follow fixes - #574
Conversation
…d 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>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…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>
|
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 applies launch fast-follow documentation updates, primarily replacing GitHub App naming and expanding GitLab factory integration guidance. I found unresolved internal tech-review notes in the source, including one attached to user-facing GitLab definition-hosting guidance that the PR itself marks as unverified.
Concerns
src/content/docs/platform/integrations/gitlab.mdxandsrc/content/docs/factories/integrations/gitlab.mdxaddOPEN QUESTIONMDX comments, so unresolved internal review notes would be committed.- The factory GitLab page also changes definition-hosting guidance while marking it as contradictory and unverified, so the published docs could assert incorrect product behavior.
Verdict
Found: 0 critical, 2 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
| A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out, since the bot username isn't yours to set. | ||
|
|
||
| A GitLab-backed factory can still be managed as code, but the definition itself lives either in Warp or in a GitHub repository — GitLab is not yet available as a definition host. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). | ||
| A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. {/* OPEN QUESTION for tech review (PR #549): confirm GitLab is actually supported as a definition host today. main@79f77e55 states GitLab is "not yet available as a definition host" -- this contradicts the claim below. Verify before merging. */}Factory definitions hosted in GitLab repositories sync the same way GitHub-hosted ones do. |
There was a problem hiding this comment.
| --- | ||
| import { VARS } from '@data/vars'; | ||
|
|
||
| {/* OPEN QUESTION for tech review (PR #549): confirm whether a native OAuth-based GitLab.com integration actually exists today. Our branch's prior copy claimed GitLab has no native integration (token-only); main@79f77e55 (below) claims native GitLab.com support exists. Verify against the product before merging. */} |
There was a problem hiding this comment.
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>
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>
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>
…up 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>
…uickstart.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>
…cker 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>
- 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>
- 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>
Two shorter, more direct sentences instead of one long clause-chained sentence. Co-Authored-By: Warp <agent@warp.dev>
…ent 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>
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>
…ickstart.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>
…eature-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>
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review 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 makes post-launch cleanup across the Warp Factories docs, including updated onboarding flow screenshots, naming changes from Oz by Warp to Warp Factories, and revisions to factory setup, dashboard, GitLab, and factory-as-code pages. The broad edits are directionally consistent with the docs style guidance, but two unresolved fact-check comments were added to published MDX source and one ships a claim the PR description says still needs verification.
Concerns
src/content/docs/platform/integrations/gitlab.mdxadds an unresolved open question directly above the native GitLab integration copy.src/content/docs/factories/integrations/gitlab.mdxchanges the definition-hosting guidance to say GitLab-hosted factory definitions sync like GitHub-hosted ones while leaving an inline open question that says this contradicts prior docs and needs verification.- No tests were added or changed. Security pass found no security-specific findings in the docs-only diff.
Verdict
Found: 0 critical, 2 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
| --- | ||
| import { VARS } from '@data/vars'; | ||
|
|
||
| {/* OPEN QUESTION for tech review (PR #549): confirm whether a native OAuth-based GitLab.com integration actually exists today. Our branch's prior copy claimed GitLab has no native integration (token-only); main@79f77e55 (below) claims native GitLab.com support exists. Verify against the product before merging. */} |
There was a problem hiding this comment.
| A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out, since the bot username isn't yours to set. | ||
|
|
||
| A GitLab-backed factory can still be managed as code, but the definition itself lives either in Warp or in a GitHub repository — GitLab is not yet available as a definition host. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). | ||
| A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. {/* OPEN QUESTION for tech review (PR #549): confirm GitLab is actually supported as a definition host today. main@79f77e55 states GitLab is "not yet available as a definition host" -- this contradicts the claim below. Verify before merging. */}Factory definitions hosted in GitLab repositories sync the same way GitHub-hosted ones do. |
There was a problem hiding this comment.
* 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>
Summary
Collects post-launch edits and tweaks found while reviewing the live Warp Factories docs.
Changes
quickstart.mdxgitlab.mdx(also applied togithub.mdx).###subheadings and prose, breaking the established procedural convention and leaving "Setup asks you for the following" with no actual list to follow.quickstart.mdx,how-factories-work.mdx, andfactory-agents.mdxso it's visible on likely entrance points, not just the overview.create_factorypath to the top of "Set up your factory" so it reads as a real alternative, not a footnote after all 7 wizard steps.@oz-agentto@warp-agentand "Oz by Warp" to "Warp Factories" for consistency.Stakeholder feedback (Aloke Desai video review)
connect-your-factory.mdx: weave the "Good to know" bullets into the sections they relate to instead of an appendix-style dump.factory-dashboard.mdx: remove the exhaustive "Pages at a glance" table and lead with the Dashboard metrics page, matching the actual landing experience.factory-dashboard.mdx/measure-and-improve.mdx: clarify what counts as human input for the Autonomy metric.factory-as-code.mdx: add a self-hosted worker example.sidebar.ts: update a stale "pending naming sign-off" code comment now that the Automation Platform name is confirmed.Style guide and templates
AGENTS.md: add general-guidance rules on avoiding AI-sounding copy, sequencing basics before jargon, avoiding appendix-style content, not over-specifying counts that drift, featuring real differentiators structurally, verifying claims against the live product, and explaining defaults before overrides..agents/templates/feature-doc.md: add matching inline reminders in the Key features and How it works sections.More fixes will be added to this PR as they're found.
Open questions found in code comments
While auditing this branch's files, found unresolved fact-check flags sitting in code comments rather than tracked anywhere visible. Both need verification against the live product before merging:
src/content/docs/platform/integrations/gitlab.mdx:11— "confirm whether a native OAuth-based GitLab.com integration actually exists today. Our branch's prior copy claimed GitLab has no native integration (token-only); main@79f77e55 (below) claims native GitLab.com support exists. Verify against the product before merging."src/content/docs/factories/integrations/gitlab.mdx:115— "confirm GitLab is actually supported as a definition host today. main@79f77e55 states GitLab is "not yet available as a definition host" -- this contradicts the claim below. Verify before merging."Screenshots needed (tracking list)
Screenshots identified as missing that can't be captured directly in this session. Each is tagged with who should capture it.
integrations/slack.mdx) — a screenshot of the custom Warp Slack bot/app (e.g., the app in a workspace, or its install/config screen). Needs an engineer or HYC: requires Slack workspace admin/install permissions to create the Warp Factories Slack app, which isn't available in this session.factory-as-code.mdx) — Aloke asked for a linked real example repo showing a complete factory definition, valuable for enterprise evaluation. Needs an engineer or HYC: requires creating and hosting an actual public example repository, which can't be done from docs tooling alone.Co-Authored-By: Warp agent@warp.dev