docs: restructure factories documentation - #748
Open
rachaelrenk wants to merge 50 commits into
Open
rachaelrenk wants to merge 50 commits into
rachaelrenk wants to merge 50 commits into
Conversation
|
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 |
![warp-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 reorganizes Factory, Automation Platform, Agent API/SDK, and legacy Oz CLI documentation, with sidebar updates and redirects for moved pages. The overall structure is directionally clear, but several changed lines introduce broken or corrupted public documentation.
Concerns
src/content/docs/factories/developer-tools.mdxcontains duplicated/corrupted prose in the new API and SDK section.- Two external documentation URLs were accidentally rewritten to non-existent paths.
- The redirect list omits
/platform/deployment-patternseven though that page moved to/factories/deployment-patterns/. - Comment audit: no new explanatory code comments were added; existing comments were removed or retained in sidebar context only.
- Test audit: no tests were added or changed.
- Spec/security audit: no approved spec context was attached; the docs/security pass found no secret exposure or unsafe examples beyond the broken documentation links called out inline.
Verdict
Found: 3 critical, 1 important, 0 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
PR body ## Documentation risk section— [IMPORTANT] Risk is correctly declared 'engineering-review-required' for this 114-file restructure, but the block omits 'Source files consulted' and 'Requested engineering reviewers', even though new/rewritten pages (e.g. src/content/docs/factories/self-hosting/index.mdx, src/content/docs/factories/deployment-patterns.mdx) restate Enterprise-plan gating, ZDR/network, and self-hosting behavior claims. Without cited sources the independent review pass in .agents/references/doc-quality-policy.md step 2 cannot verify claims against source, and source-owner review-request resolution has nothing to key off. Requested change: add a 'Source files consulted' line (or an explicit 'N/A — reorganization of previously published content, no new technical claims' note naming the pages it was cross-checked against) so the engineering-review-required declaration is actionable.src/content/docs/platform/skills-as-agents.mdx:15— [SUGGESTION] Newly added sentence 'This page describes skills that run independently of a factory.' is a meta-opener that narrates the page instead of stating the distinction directly (AGENTS.md → Voice & tone → No meta-openers). Requested change: rewrite to state the scope directly, e.g. 'Skills that run independently of a factory are covered here; for skills scoped to a factory or its agents, see factory skills.'src/content/docs/platform/integrations/github-actions.mdx:51— [NIT] The touched line (link target updated to /agents/cli/oz-cli/api-keys/) still bolds 'Warp API Key' with a capital K, the only such casing in the repo; every other instance (e.g. src/content/docs/platform/integrations/quickstart-github-actions.mdx:17) uses 'Warp API key'. Requested change: lowercase to 'Warp API key' for consistency.
Verdict
Request changes
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
PR body:39— [CRITICAL] The## Documentation risksection hasEngineering review status: pending.(with a trailing period).check_pr_contract.py's field parser captures the raw remainder of the line as the value, so it readspending.instead of the valid enum valuepending, and the required 'Docs technical references' CI check fails withinvalid engineering review status 'pending.'; must be one of ('not-applicable', 'pending', 'approved'). Verified by runningcheck_pr_contract.py --bodyagainst this PR body and the 108 changed docs files at head 9162794: it failed with exactly this error, and passed once the trailing period was removed. Requested resolution: edit the PR body so the line reads exactlyEngineering review status: pending(no trailing period).
Verdict
Request changes
Contributor
Author
|
/warp-agent-review |
Contributor
|
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 |
Contributor
There was a problem hiding this comment.
Overview
This PR restructures the Factory, API/SDK, legacy CLI, deployment, self-hosting, sidebar, and redirect documentation. I reviewed the attached PR description, annotated diff, empty spec context, docs guidance, and supplemental security guidance.
Concerns
- The new managed self-hosting overview drops the cross-surface routing examples that the migrated backend pages still link to for CLI, schedule, integration, API, and web UI routing guidance.
- No security findings were identified in the docs and workflow changes. The spec context was empty, so there was no implementation-spec drift to check.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
rachaelrenk
force-pushed
the
rrenk/grow-6127-factories-ga
branch
from
September 16, 2026 17:40
2af3dc8 to
687a2f7
Compare
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
rachaelrenk
force-pushed
the
rrenk/grow-6127-factories-ga
branch
from
September 21, 2026 17:06
73ff63f to
98cc0cf
Compare
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/factories/quickstart.mdx— [SUGGESTION] PR body Validation section reports the Factory quickstart compression overage as 715 words, but running check_compression_contract.py --content-type quickstart against the current head (98cc0cf) reports 735 words. Requested resolution: re-run the compression check against the current head and update the Validation entry so the documented word count matches, keeping the justified-overage trail accurate.
Verdict
Approve with nits
rachaelrenk
commented
Sep 21, 2026
| ### Key endpoints | ||
| ## Route a run to a self-hosted worker | ||
|
|
||
| Set `worker_host` in the request configuration to select a connected self-hosted worker. Omit it, or set it to `warp`, to use Warp-hosted workers. |
Contributor
Author
There was a problem hiding this comment.
@hongyi-chen Could you confirm this routing behavior against the implementation before merge?
Specifically: (1) worker_host selects a connected self-hosted worker for a standalone API run; (2) omitting it, or setting it to warp, uses Warp-hosted workers; and (3) factory work routes through workerHost in the factory definition to a managed worker.
The PR cites agent_config.go, worker_routing.go, and workers/selfhosted/worker.go. A confirmation or correction here will resolve the remaining engineering-review item.
rachaelrenk
commented
Sep 21, 2026
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/factories/quickstart.mdx— [SUGGESTION] check_compression_contract.py reports 736 words against the 600-word quickstart budget. The PR body already discloses and justifies this overage (retaining the wizard confirmation, code-forge path, and first-work-item path). Requested resolution: keep that justification note current at merge time, or trim further if the page grows past this budget again without new justification.src/content/docs/factories/self-hosting/index.mdxandsrc/content/docs/factories/infrastructure-and-security.mdx— [SUGGESTION] The## Documentation risksection citeswarp-server/logic/ai/ambient_agents/sources/agent_config.go,worker_routing.go, andworkers/selfhosted/worker.goto support the worker_host routing and self-hosted dispatch claims used on these pages. This review pass ran in a sandbox with no warp-server checkout available, so those citations could not be independently verified against source. Requested resolution: ensure the requested engineering reviewer (hongyi-chen) confirms these specific file citations before merge, sinceEngineering review statusis stillpending.src/content/docs/changelog/2025.mdx:195— [NIT] The updated CLI reference link uses a hardcoded absolute URL (https://docs.warp.dev/agents/cli/oz-cli) rather than a relative internal link, per AGENTS.md link guidance (Within an Astro Starlight space, use relative paths). Requested resolution: use/agents/cli/oz-cli/instead — low priority since it mirrors the absolute-URL style already used in this historical changelog entry before the PR's path fix.
Verdict
Approve with nits
rachaelrenk
commented
Sep 21, 2026
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
.agents/references/terminology.md:286and:293— [IMPORTANT] The 'SDK' entry still says 'Official client libraries for the Agent API' and the 'Automation Platform' entry still says '...and the Agent API/SDK', but this same PR renamed the 'Agent API' glossary entry (line 264) to 'Warp Platform API' with a {VARS.WARP_PLATFORM_API} usage note. Requested resolution: update both remaining bullets to reference Warp Platform API (or {VARS.WARP_PLATFORM_API}) so the glossary this PR edited is internally consistent.scripts/generate-og-api.mjs:40— [IMPORTANT] The generated OG/Twitter share image for/apistill bakes in the text 'Agent API Reference', butsrc/pages/api.astrowas updated in this PR to title the page 'Warp Platform API reference' and setog:image:altto 'Warp Platform API reference — Warp'. The renderedpublic/assets/og/api.png(not regenerated by this PR, last touched by an unrelated commit) now contradicts its own page's metadata when the link is shared on social platforms. Requested resolution: update the subtitle text to 'Warp Platform API reference' and rerunnpm run og:apito regeneratepublic/assets/og/api.png.src/content/docs/factories/quickstart.mdx— [SUGGESTION] Confirmed viacheck_compression_contract.py: 736 words against the 600-word quickstart budget (the PR body's own accounting cites 735 words, off by one but materially correct). This is an already-disclosed, justified overage per the PR body's Validation section, so no action is required beyond what's documented; flagging only so the justified-overage decision is visible to the human reviewer.
Verdict
Request changes
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/factories/self-hosting/index.mdx:41-45— [IMPORTANT] The page preserves therouting-runs-to-self-hosted-workersanchor but drops the routing guidance it was written for; the replacedplatform/self-hosting/index.mdxdocumentedoz agent run-cloud --host,oz schedule create --host, andoz integration create --host, while the new section says only that routing happens "through the factory definition".src/content/docs/platform/architecture.mdx:57deep-links[--host ID](/factories/self-hosting/#routing-runs-to-self-hosted-workers)and now lands on a section that never mentions--host, and standalone (non-factory) worker routing is no longer documented anywhere as a set. Requested change: restore a short "Route runs to a worker" subsection covering the--hostCLI, schedule, and integration forms alongside the factory-definition path, or repoint the anchor andplatform/architecture.mdx:57at the page that now owns that guidance.src/sidebar.ts:524— [IMPORTANT]slug: 'platform/transitioning-from-oz'is registered in the Warp Factories topic here and again at line 552 under Automation Platform > Cloud Agents; it is the only duplicatedslug:in the file, so the page is claimed by two topics and its topic, breadcrumb, and active-item highlighting resolve by match order. Requested change: keep the canonicalslug:entry under Automation Platform > Cloud Agents and convert this one to a cross-topic link,{ label:Transitioning from the ${VARS.WEB_APP}, link: '/platform/transitioning-from-oz/' }.src/content/docs/factories/deployment-patterns.mdx:46-53— [SUGGESTION] The page is scoped to factories ("Choose an execution model for your factory") but "Common ways to trigger" and the recipes below it describe standalone cloud agent workflows (oz agent run-cloud, Warp Environments plus a schedule, a Sentry webhook calling the API) with no factory definition, foreman, or work item involved. Requested change: rescope the section to factory triggering (automations, integrations, factory API) and move the standalone recipes to an Automation Platform page, or retitle the page to cover both execution paths explicitly.vercel.json:6621— [SUGGESTION] The new/reference(/?)redirect sends the former CLI-and-API landing page to/agents/cli/oz-cli/, the surface this PR itself labels(legacy). Requested change: point it at/factories/developer-tools/, the closest equivalent of the old reference landing page.src/content/docs/factories/quickstart.mdx:15— [SUGGESTION]check_compression_contract.py --content-type quickstartreports 736 words against the 600-word budget; the PR body justifies the overage, but this intro repeats "software development lifecycle" twice in four sentences and restates the foreman dispatch role covered again in the steps. Requested change: cut the trailing "each owning one part of the software development lifecycle" clause and let the foreman definition stand at first mention.developers/agent-api-openapi.yaml:5— [SUGGESTION] The committedinfo.descriptiondoes not byte-matchDOCS_INFO_OVERRIDES["description"]in.agents/skills/sync-openapi-spec/scripts/sync_openapi.py(a newline appears afterlist runs,where the override has a space), and the script's self-test asserts equality, so the next sync will rewrite the line for no upstream reason. Requested change: regenerate the file with the sync script so the committed description matches the override exactly.src/content/docs/platform/transitioning-from-oz.mdx:2— [SUGGESTION] The PR's content design plan declares this page conceptual, but the gerund titleTransitioning from the {{WEB_APP}}follows the procedural title convention in AGENTS.md → "Titles by content type", and the body is a status table with no procedure. Requested change: retitle to a noun phrase such as "About the transition from the {{WEB_APP}}" and update the matchingsidebar.labeland bothsrc/sidebar.tsentries.src/content/docs/index.mdx:2— [SUGGESTION] Retitling the docs homepage from "Getting started with Warp" to "Warp products" gives up a high-intent query title on the site's strongest page; the URL is unchanged so no redirect is needed, but<title>and H1 are what search and answer engines read first. Requested change: retain the getting-started intent (for example "Warp products and getting started") or record in the PR body that the homepage is deliberately ceding that query.src/content/docs/factories/deployment-patterns.mdx:25— [NIT] Doubled blank line before the first##heading. Requested change: delete the extra blank line (empty suggestion block provided).src/content/docs/factories/deployment-patterns.mdx:76— [NIT] Stray---thematic break, the only one on the page, where the##headings already separate the two execution models. Requested change: delete the rule (empty suggestion block provided).
Verdict
Request changes
This branch was successfully deployed
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
Completes the revised pre-GA Phase 1 documentation restructure around Warp Factories while preserving the current top-level order, Factory topic link, and Early Access treatment.
Changes
Content design plan
draft_conceptualand.agents/templates/conceptual.md.Validation
python3 .agents/skills/style_lint/style_lint.py --changed- completed; The full PR delta has existing findings unrelated to the reviewed transition guide. The hardcoded-variable and factory-proper-noun findings on the transition page were corrected after this validation run.python3 .agents/skills/check_for_broken_links/check_links.py --internal-only- passed with 0 broken links across 4,126 internal links.python3 .agents/skills/doc_quality_policy/check_compression_contract.py src/content/docs/factories/self-hosting/quickstart.mdx --content-type quickstart- passed at 573 words.git diff --check- passed.API terminology and redirect audit - confirmed no legacy shared-API labels remain in
src; affected deployment, self-hosting, API/SDK, and CLI redirect families parse successfully, preserve trailing-slash variants, and point directly to canonical destinations.python3 .agents/skills/check_for_broken_links/check_links.py --internal-only- passed with 0 broken links across 4,233 internal links.npm run build- passed after the API and Factory navigation update.python3 .agents/skills/sync-openapi-spec/scripts/sync_openapi.py --mode self-test- passed after adding the documented docs-specific OpenAPIinfo.titleandinfo.descriptionoverride for the Scalar reference.python3 .agents/skills/check_for_broken_links/check_links.py --internal-only- passed with 0 broken links across 4,232 internal links after the review fixes.npm run build- passed after the review fixes.Direct review-output capture, review publication, workflow structure, and verification tests - passed.
Representative redirect families for moved Platform, API/SDK, legacy CLI, unmanaged execution, and execution-security paths - verified in
vercel.json.npm run build- passed in a fresh worktree afternpm ciand in CI. Removing the empty API troubleshooting landing page resolved the Astro content-collection failure; #757 is closed.Factory quickstart compression - 735 words and two callouts. This intentional overage retains visual wizard confirmation, the new code-forge path, and the full first-work-item path; detailed repository sizing, Foreman, integration, and agent configuration guidance links to its owning pages.
Unverified claims
Warp Platform APIand the docs-specific OpenAPIinfooverride are pending confirmation from the requested engineering reviewer. The upstream OpenAPI file still uses its legacy title.Documentation risk
Risk: engineering-review-required
Rationale: Moves published documentation across top-level sections, revises navigation, changes the product-context framing for infrastructure and developer interfaces, and hardens the independent review workflow.
Source files consulted: GROW-6127 for the currently scheduled October 6 Factories GA and the Oz web-app retirement in the following weeks; previously published Platform sources for managed self-hosting, execution security, runners, deployment patterns, and Warp-hosted execution; the former API & SDK and legacy Oz CLI references;
src/content/docs/factories/factory-dashboard.mdx;warp-server/logic/ai/ambient_agents/sources/agent_config.goandworker_routing.goforworker_hostrouting; andwarp-server/logic/ai/ambient_agents/workers/selfhosted/worker.gofor dispatch through a connected self-hosted worker.Requested engineering reviewers: hongyi-chen
Engineering review status: pending
Docs override: none
Co-Authored-By: Warp agent@warp.dev