docs(factories): full content pass over the launch stack — link fixes and cross-page seams - #557
Merged
Merged
Conversation
Relative links resolve against the page's trailing-slash URL at runtime (./x becomes /factories/<page>/x), so they 404 even though the file-based CI link checker passes. #550 swept the pages merged before it; the pages that landed after (#516 overview/how-it-works, #520 connect, #527 Linear) reintroduced the pattern. Converts all of them to the repo's root-absolute trailing-slash convention. Co-Authored-By: Warp <agent@warp.dev>
- Map the setup wizard's Code toggle to the Implement role (quickstart vs factory-agents used different names for the same role) - Map lifecycle stage names to the Activity view's UI names (Planning, Building), which how-factories-work never connected - Define a Factory MCP task as the factory's work item; the page used 'task' throughout without bridging to the term the rest of the section uses - Link connect-your-factory to the automation-filters page (#551 added the page after #520 merged, so the hub never referenced it) - Align 'cancelled' spelling on the Jira page with the rest of the section - Replace two 'cloud agent identity' usages with 'cloud agent' per the terminology glossary (platform/agents.mdx) Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Collaborator
Author
|
This PR was generated with Warp. Comment   |
Contributor
|
Your Warp account is not a member of any team with access to this repository. |
hongyi-chen
marked this pull request as ready for review
August 17, 2026 23:43
Contributor
|
I'm starting a first review of this pull request. I cancelled the in-progress review run because this pull request was closed. Powered by Oz |
guyscherzer8
pushed a commit
that referenced
this pull request
Aug 18, 2026
…and cross-linking (#558) * docs(factories): deep content pass — accuracy, tone, and cross-linking Follow-up to #557's mechanical pass, addressing the deeper audit asked for on #508: tone consistency, missing cross-links, and accuracy against the product. Accuracy (verified against warp-server's factory frontend): - Drop the Time saved metric from control-room and measure-and-improve; the dashboard card was removed (client/packages/factory api/metrics.ts). - Rename PR latency to PR cycle time to match the card label, and align the metric's definition on both pages (kickoff → PR → first review → merge, per-stage medians). - Align the Autonomy definition on both pages with the product semantics: no human input beyond an approving review and the merge itself. - Align control-room's Live-managed description with the product copy (managed through the API). Links: - Convert 9 relative links in factory-as-code to root-absolute; they resolved to /factories/... paths and 404'd in production (same class of bug #557 fixed; this page landed after that sweep). - Add missing cross-links: quickstart → control room + platform credits, factory-agents → control room, control-room/infrastructure → credentialStrategy, control-room → Self-improvement anchor, how-factories-work → PR checks anchor, Slack Home tab → Activity view, Linear prereq → GitHub connection, troubleshooting → integration troubleshooting sections. - Add the missing Linear entry to connect-your-factory's default automations list. Tone and consistency: - Rewrite the Linear intro: present tense, correct stage names (it claimed a spec/implement/review/verify pipeline), direction consistent with sibling pages, and a lifecycle link. - Normalize Scorer / Self-improvement capitalization across pages. - Replace the 'Oz model ID' coinage with a model_id reference linked to the model catalog. - Trim inward-facing phrasing (Early Access note) and a roadmap promise (Jira caution); fix future tense and em dashes in the quickstart. Validated: npm run build passes, style_lint clean on touched files, link checker reports 0 broken links. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): drop redundant team/credits note from quickstart The Prerequisites section already states a factory needs a team with credits. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Aug 18, 2026
…uide references (#560) Second consistency pass over the launch stack, cross-checking the docs against the product and against each other after #557/#558/#559 landed. Verified against warp-server (no change needed): - The alias constraints in factory-as-code match the shared factoryalias.Normalize contract (60 runes; letters, digits, spaces, '-', '_', '.'; case-insensitive uniqueness). - Activity's terminal stage really is labeled 'Complete' while the Slack Home tab uses 'Completed' (slack_app_home.go) — both pages correctly reflect their own surface, so the apparent mismatch stands. Aligned: - factory-as-code: bridge the alias key to its control-room label, Foreman name (#559 introduced the label in the quickstart), and say it @-mentions the foreman, matching the UI copy. - control-room Settings: name the identity fields (name, avatar, Foreman name) and link Foreman name to the alias reference. - run-a-software-factory-in-the-cloud: DIY-loop runs appear in the cloud agent dashboard, not the Factories product's dashboard — use {VARS.DASHBOARD}. - The five DIY-factory guides framed the Factories product page as 'the conceptual overview of the full loop'; their next-step descriptions now say what the destination is (the managed product), and build-a-self-improving-agent deep-links the Self-improvement section it parallels (the reverse link already existed). - set-up-a-software-factory and run-a-software-factory-in-the-cloud intros now point readers to Warp Factories as the managed alternative. Validated: npm run build passes; link checker 3,664 internal / 1,522 external, 0 broken; style_lint adds no new findings on touched files. Co-authored-by: hongyi-chen <hongyigma@gmail.com> Co-authored-by: Warp <agent@warp.dev> Co-authored-by: Hong Yi Chen <hongyi@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
Full editorial pass over the combined Factories launch content on
hyc/factory-launch(#508) — the first single-context read of all 16 pages (~14,900 words) after the stack landed as ~20 independent PRs. Two commits: one mechanical link sweep, one set of cross-page seam fixes.What was validated (all clean)
npm run build— passes, no content errorsstyle_lint --changed— factories pages have zero violations beyond glossary-candidate advisories#configure-and-review-self-improvement,#track-work-items-on-activity,#setup,#connecting-your-jira-account-to-warp, etc.) — all resolve/platform/software-factory/redirect exists invercel.jsonfactories/Fixes in this PR
Commit 1 — broken-at-runtime links. #550 converted factory pages to root-absolute links, but #516 (overview, how-factories-work), #520 (connect-your-factory), and #527 (Linear) landed after the sweep with
./and../links. Those resolve against the page's trailing-slash URL (./x→/factories/<page>/x) and 404 in production while passing the file-based CI checker. Converted ~40 links across 4 pages to the root-absolute trailing-slash convention.Commit 2 — seams from combining disparate branches:
factory-agentscalls the same role Implement, with no bridge between them. Added a mapping sentence to the quickstart.how-factories-workdescribes stages as Triage/Specification/Implementation/Review, but the Activity view groups them as Triage/Planning/Building/Reviewing. Added the mapping where the page hands readers to Activity.factory-mcpsays "task" ~50 times without ever connecting it to "work item", the term every other page uses. Added a one-line definition tying tasks to the Activity view.automation-filters(docs(factories): add automation filters page #551) consolidated filter semantics from seven pages, butconnect-your-factory— the intake hub — never linked to it because docs(factories): document integrations and intake #520 merged first. Linked it from the connect steps and the Good-to-know filters bullet.platform/agents.mdx→ "cloud agent" per the glossary.Deferred to outstanding branches
factory-as-code.mdxandintegrations/github.mdxare placeholder stubs; untouched here.automation-filters.mdxhas an inline TODO to link the GitLab table row once the page exists; the sidebar also needs the GitLab entry.infrastructure-and-security.mdx; left its prose alone since docs(factories): editorial pass on infrastructure and security #540 rewrites it.how-factories-workfrontmatter label ("How Factories work") differs from thesidebar.tsoverride ("How Warp Factories work").Observations for DRIs (not changed — need a product-truth check)
control-roomsays a scorer "classifies completed runs";measure-and-improveconsistently says "completed conversations" (and capitalizes Scorer, where control-room lowercases it). Worth aligning once someone confirms which object the judge actually evaluates.factory-mcphardcodeshttps://app.warp.dev/api/v1/mcp/factorywhile the factory web app var points atplatform.warp.dev— assumed intentional (API host vs web app), flagging for confirmation.Overall: content quality across the section is high — zero broken links, complete frontmatter, consistent callout/style usage. The fixes here are the integration seams you'd expect from parallel authorship, nothing structural.
Plans: