docs(factories): section consistency pass + visual callout comments

[warp-agent-staging]

Summary

Editorial consistency pass across the Warp Factories docs (src/content/docs/factories/**), plus brief {/* VISUAL: ... */} comments at sections where a product screenshot would help. No app code changes; docs only.

Fixed

• P0 - Removed the leftover OPEN QUESTION for tech review (PR #549) comment in integrations/gitlab.mdx and corrected the claim it was attached to: factory-as-code.mdx only lists Warp-managed and GitHub as definition hosts, so GitLab is not yet a supported definition-hosting repository. The page now says so instead of asserting GitLab-hosted definitions sync like GitHub's.
• Agent naming - quickstart.mdx and troubleshooting.mdx called the fourth default agent "Code" and the default agents "subagents." Confirmed against the actual product UI (Agents list / agent settings screenshots from PR docs(factories): copy edits and screenshots from launch review #589's branch) that the shipped name is Implement Agent, matching factory-agents.mdx. Updated both pages to say "Implement" and "agents."
• Integration title pattern - integrations/gitlab.mdx's title/description were inverted ("Connect a factory to GitLab") relative to the other four integrations ("Connect X to your factory"). Normalized.
• Troubleshooting opener - Rewrote the "This page covers..." opener to lead with the fix, per docs style.
• Sidebar casing - how-factories-work.mdx's sidebar label was "How Factories work" (capitalized mid-label); changed to "How factories work" to match the sentence-case convention used by the other factories sidebar entries.
• Terminal-stage label - factory-dashboard.mdx/how-factories-work.mdx use "Complete and Cancelled"; the Slack integration page said "Completed... and Cancelled." Standardized on "Complete" (majority usage, and pairs correctly with the mermaid diagram's Complete node).
• Link-label consistency - Bolded a few unbolded Related pages/Next steps links to match the established pattern, and normalized a couple of mismatched labels for the same destination (e.g. GitLab's "connecting your factory" -> "Connect your factory"; quickstart's "Troubleshooting" -> "Troubleshooting Warp Factories" to match the dashboard page).
• Visual callouts - Added brief {/* VISUAL: ... */} comments (invisible in the rendered page) at the locations from the ticket's callout table that aren't already covered by an open PR: connect-your-factory.mdx, factory-mcp.mdx, factory-as-code.mdx, factory-dashboard.mdx (x2), measure-and-improve.mdx (x2), automation-filters.mdx, and the GitHub/GitLab/Linear/Jira integration "mention/connect" sections.

Decisions / deferred (documented per the ticket's request)

• Early Access note policy - Left as-is: only the four entry-adjacent pages (overview, quickstart, how-factories-work, factory-agents) carry the note. Documenting this as the intended policy rather than expanding it to every page, to keep the diff minimal and avoid callout fatigue.
• how-factories-work.mdx stage naming ("Specification"/"Implementation" vs. the agent's short "Spec"/"Implement" name) - Left unchanged. PR docs(factories): copy edits and screenshots from launch review #589 (open, launch-review copy edits) already rewrote this exact section and deliberately kept the long-form stage names, so renaming here would both contradict that decision and directly conflict with docs(factories): copy edits and screenshots from launch review #589's hunks.
• factory-agents.mdx visual callouts (agents list / agent settings) - Skipped. PR docs(factories): copy edits and screenshots from launch review #589 already adds the real factory-agents-list.png / factory-agent-settings.png screenshots for those exact two sections; a placeholder comment there would be immediately stale.
• Item 12 (scorers/ tree, metrics-reference contradictions) - Per the ticket, left untouched since docs(factories): document scorers/ in the definition syntax page #584 (scorers/) and docs: fold Dashboard metrics semantics into existing pages (APP-5546) #582 (metrics-reference.mdx) haven't merged yet.
• Two of the six sibling PRs (docs: fold Dashboard metrics semantics into existing pages (APP-5546) #582 factory-dashboard.mdx/measure-and-improve.mdx, Document single-prompt Factory MCP onboarding #585 factory-mcp.mdx) touch files this PR also touches; edits here were placed in different sections/lines than their diffs to minimize overlap. A rebase may still be needed depending on merge order.

Testing

• python3 .agents/skills/style_lint/style_lint.py --changed - 0 errors (83 pre-existing "unrecognized bolded term" warnings on untouched lines in files this PR also edits; not introduced by this change).
• npm run build - full Astro build succeeds; spot-checked the built HTML for factories/integrations/gitlab and factories/factory-dashboard to confirm the P0 fix rendered and that the {/* VISUAL: */} comments are stripped from the visible page (they only appear in the page's hidden raw-markdown <template>, same as the removed OPEN QUESTION comment was on main before this PR).
• No computer_use / new screenshots - this ticket's bar is comments + copy consistency; screenshot capture is an explicit follow-up.

Originating thread: https://warpdotdev.slack.com/archives/C09BVK0PL3Y/p1787266196343989

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 20, 2026 11:24pm

[warp-for-oss]

@warp-agent-staging[bot]

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 /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This docs-only PR makes a consistency pass across Warp Factories pages: it corrects GitLab definition-hosting wording, default agent terminology, link-label formatting, sidebar casing, and stage naming, and adds hidden MDX visual callout comments for future screenshot placement.

Concerns

• No blocking concerns found in the attached diff.
• No approved or repository spec context was provided, so there was no implementation/spec drift to evaluate.
• The supplemental security pass found no concerns; the changes are documentation copy and hidden MDX comments only.

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