docs: restructure factories documentation - #748
Open
rachaelrenk wants to merge 46 commits into
Open
rachaelrenk wants to merge 46 commits into
rachaelrenk wants to merge 46 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>
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— [IMPORTANT] The restructure dropped the API/SDK config-based routing example for self-hosted workers. The oldplatform/self-hosting/index.mdxhad a full 'From the API and SDKs' subsection showingworker_hostin thePOST /api/v1/agent/runconfig body; the new page only says 'Route factory work to a managed worker through the factory definition' and the API/SDK config-field path is now mentioned nowhere except a passing aside atfactories/self-hosting/troubleshooting.mdx:77('Verify the--host(orworker_host) value...'). CLI (--host), schedule, and integration routing equivalents were all preserved (agents/cli/oz-cli/index.mdx:273,platform/triggers/scheduled-agents.mdx,agents/cli/oz-cli/integration-setup.mdx), so this is an asymmetric content loss, not a full-content move. Requested change: add theworker_hostconfig-field example (or a link to where it now lives) tofactories/api-and-sdk/index.mdxorfactories/self-hosting/index.mdx.src/content/docs/changelog/2026.mdx:1676— [NIT] The link anchor text "API and CLI reference" was repointed from/reference/to/factories/developer-tools/, which covers only the API/SDK, Factory API, Factory MCP, and webhooks — the CLI reference itself moved to/agents/cli/oz-cli/and isn't covered by that target. Requested change: drop "CLI" from the anchor text or point to a page that documents both, since the new target no longer matches what the anchor text promises.
Verdict
Request changes
Co-Authored-By: Warp <agent@warp.dev>
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] The section states "Requested engineering reviewers: none — no single source owner resolved for this cross-cutting documentation restructure," but the GitHub Pulls API (/repos/warpdotdev/docs/pulls/748/requested_reviewers) shows hongyi-chen is currently an actively requested reviewer on this PR at this head. The declared field contradicts the live PR state. Requested change: update theRequested engineering reviewersfield to name hongyi-chen (or otherwise reconcile the declared value with the actual GitHub review-request state) so the human-gate metadata is accurate.src/data/vars.ts:19,54— [IMPORTANT] The existingWARP_AGENT_CLIkey still holds the value "Oz CLI" (with its original comment expecting it to eventually become "Warp Agent CLI"), while this PR adds a newWARP_CLIkey whose value is exactly "Warp Agent CLI" for a different, newwarp-binary product. This inverts the file's own "key uses the future/conceptual name" rule and creates two variables with overlapping future-name expectations for two distinct CLIs, risking future mislabeling. Requested change: rename one of the two keys (e.g.WARP_AGENT_CLI→OZ_CLI) or add an explicit cross-reference comment on both keys clarifying they refer to different products.src/content/docs/platform/transitioning-from-oz.mdx:28— [IMPORTANT] "Moving an existing workflow into a factory is optional and evaluated case by case with an engineering DRI" introduces undefined internal jargon ("DRI") with no link, definition, or actionable path for an external reader, and this operational claim isn't covered by a{/* VERIFY: ... */}marker or listed in the PR's## Unverified claimssection. Requested change: replace with a reader-actionable path (e.g. "talk to your account team") or define the term inline per AGENTS.md's "sequence basics before jargon" guidance..github/workflows/agent-docs-review.yml(new "Run independent review-docs-pr agent" step) — [SUGGESTION] The step hardcodes GPG fingerprint0913165C78D5B7A41B42AC657FF7AB39D60F803Fand a new apt-basedoz-stableinstall flow with no inline comment on where/when the fingerprint was verified, and it isn't listed in the PR'sSource files consulted. I independently confirmed this fingerprint matches the primary key currently published at releases.warp.dev/linux/keys/warp.asc, so it is correct today, but Requested change: add a short comment noting the verification source/date so future key rotations don't silently drift undetected.src/content/docs/factories/developer-tools.mdx:22-23— [NIT] The bullet list (ending "* Webhooks...") runs directly into## Get startedwith no blank line between them, tripping standard markdownlint blank-lines-around-headings/lists rules. Requested change: add a blank line before the## Get startedheading.
Verdict
Request changes
Co-Authored-By: Warp <agent@warp.dev>
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/factories/developer-tools.mdx:2and:4— [SUGGESTION] The frontmattertitle("Warp Platform API & SDKs") anddescriptionhardcode "Warp Platform API" as a literal string instead of using the{{WARP_PLATFORM_API}}frontmatter token thatVARS.WARP_PLATFORM_APIdefines and that this same PR already uses in frontmatter elsewhere (e.g.platform/transitioning-from-oz.mdxtokenizes{{WEB_APP}}). Requested resolution: change the frontmatter totitle: "{{WARP_PLATFORM_API}} & SDKs"and tokenize "Warp Platform API" in the description so a future rename updates this page automatically.src/content/docs/platform/transitioning-from-oz.mdx:22— [NIT] The "New software factories" table row hardcodes the URLhttps://platform.warp.devinstead of{VARS.FACTORY_WEB_APP_URL}, whichsrc/data/vars.tsdefines for exactly this value and which every other reference to the Warp Factories web app URL in this PR uses. Requested resolution: replace the literal URL with{VARS.FACTORY_WEB_APP_URL}.
Verdict
Approve with nits
Co-Authored-By: Warp <agent@warp.dev>
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.mdxexceeds the quickstart compression-contract budget at 1,026 words (budget 600) with 3 callouts (budget 2), per check_compression_contract.py. The PR's Validation section only ran the compression check against self-hosting/quickstart.mdx. Requested resolution: run a deletion-only cut pass on this quickstart (AGENTS.md → Cut again) or record a justified-overage rationale in the PR body.src/content/docs/platform/quickstart.mdxexceeds the quickstart compression-contract budget at 1,174 words (budget 600) with 3 callouts (budget 2), per check_compression_contract.py. Requested resolution: run a deletion-only cut pass or record a justified-overage rationale in the PR body, since neither is present for this page.src/content/docs/factories/api-and-sdk/index.mdx(new '## Route a run to a self-hosted worker' section) states 'Omit it, or set it towarp, to use Warp-hosted workers' for theworker_hostfield. This review environment has no access to the cited warp-server source (agent_config.go, worker_routing.go), so the default-value claim is unverified here. Requested resolution: have the requested engineering reviewer (hongyi-chen) explicitly confirm the worker_host default/omit behavior against source before merging.src/content/docs/factories/deployment-patterns.mdx:24-25has two consecutive blank lines before the '## Warp-hosted execution' heading, inconsistent with the single blank line used between every other section on the page. Requested resolution: remove the extra blank line.- Several PR-added lines introduce bolded terms not in terminology.md (e.g.
src/content/docs/index.mdx:11'Agentic Development Environment',src/content/docs/factories/self-hosting/index.mdx:32-33'Kubernetes'/'Direct',src/content/docs/factories/api-and-sdk/index.mdx:32'Python SDK'/'TypeScript SDK'), per style_lint's unrecognized-term check (19 total instances on lines actually added by this PR). Requested resolution: add the recurring terms to .agents/references/terminology.md or un-bold incidental mentions that aren't glossary terms.
Verdict
Approve with nits
Co-Authored-By: Warp <agent@warp.dev>
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
vercel.json:5206— [SUGGESTION] The pre-existing redirect from/agent-platform/cloud-agents/self-hosting/managed-worker-referencestill targets/platform/self-hosting/, a path this same PR moves (see the new redirect atvercel.json:6571sending/platform/self-hosting/→/factories/self-hosting/), creating an unnecessary two-hop redirect chain and contradicting the PR body's validation claim that affected self-hosting redirects 'point directly to canonical destinations.' Requested resolution: update this entry's destination directly to/factories/self-hosting/..github/workflows/agent-docs-review.yml:47— [SUGGESTION] The new install step runssudo apt-get install -y oz-stablewithout pinning a specific package version, so this security-sensitive independent-review pipeline will silently pick up whatever build is currently tagged 'stable' on each run, even though the step already pins the signing-key fingerprint. Requested resolution: pin an explicitoz-stableversion (or log the resolved installed version) so pipeline behavior stays reproducible and auditable across runs.
Verdict
Approve with nits
Co-Authored-By: Warp <agent@warp.dev>
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 1026 words and 3 callouts against the quickstart budget (600 words, 2 callouts); this pre-dates the PR (only one sentence on this page changed here) but is now a live compression-contract finding on a touched file. Requested resolution: trim the page to the quickstart budget or record a justification for the overage in a follow-up PR, per the compression contract in doc-quality-policy.md.
Verdict
Approve with nits
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
astro.config.mjs:231— [IMPORTANT] ThestarlightLlmsTxtcustomSetsentry{ label: 'API & Reference', description: 'CLI and API reference.', paths: ['reference/**'] }still targetssrc/content/docs/reference/**, but this PR deletes every page under that directory (moved toagents/cli/oz-cli/**andfactories/api-and-sdk/**, withreference/index.mdxandreference/api-and-sdk/troubleshooting/index.mdxremoved outright). The directory no longer exists, so this customSet now generates an empty/dangling category in/llms.txt,/llms-full.txt, and/llms-small.txt, directly contradicting the PR's own claim of removing the standalone 'API & Reference' tab. Requested resolution: remove this customSet entry or repoint itspathsandlabelto the new CLI/API locations (agents/cli/oz-cli/**,factories/api-and-sdk/**) in the same PR.- PR body
Documentation risksection — [SUGGESTION] The risk section citeswarp-server/logic/ai/ambient_agents/sources/agent_config.go,worker_routing.go, andworkers/selfhosted/worker.goto support theworker_hostrouting and self-hosted-worker dispatch claims made infactories/deployment-patterns.mdx(managed self-hosting description) andfactories/self-hosting/index.mdx. Thewarp-serverrepository is not accessible from this independent-review environment, so these specific technical claims could not be re-verified against source in this pass. Requested resolution: have the requested engineering reviewer (hongyi-chen) explicitly confirm these claims against the citedwarp-serverfiles before merge, since risk classification and engineering review remain pending.
Verdict
Request changes
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
developers/agent-api-openapi.yaml:3— [IMPORTANT] This generated file is hand-edited to renameinfo.titletoWarp Platform API, but.agents/skills/sync-openapi-spec/references/sync-policy.mdrule 4 keeps top-levelopenapi,info, andserversverbatim fromwarp-server/public_api/openapi.yaml, whose release workflow it calls the authoritative publisher, so the next sync reverts the title and description and/apiand/openapi.yamlsilently flip back. The PR body'sSource files consultedalso cites only GROW-6127 and theworker_hostrouting files, nothing that confirms the new public API name. Requested change: rename the API upstream in warp-server and re-sync, or record theinfooverride insync-policy.mdandscripts/sync_openapi.py, and cite a confirming source for "Warp Platform API" in the## Documentation riskblock.src/data/vars.ts:45— [IMPORTANT] RemovingAPI_SDK_NAMEin favor ofWARP_PLATFORM_APIleaves.agents/skills/style_lint/style_lint.py:111telling authors to write{VARS.API_SDK_NAME}/{{API_SDK_NAME}}(a key that no longer exists, and an unresolved frontmatter token fails the build) and.agents/references/terminology.md:251still documenting{VARS.API_SDK_NAME}as rendering "Oz API & SDK". Requested change: update both references toWARP_PLATFORM_APIand add a("Warp Platform API", "WARP_PLATFORM_API", ...)entry to the style_lint hardcoded-var table.src/content/docs/factories/developer-tools.mdx:17— [IMPORTANT] This new page hardcodes the literal "Warp Platform API reference" instead of the variable the PR just added, contrary to AGENTS.md → Content variables; the same literal also appears insrc/content/docs/factories/api-and-sdk/index.mdx(32, 81, 134),src/content/docs/factories/api-and-sdk/quickstart.mdx(79, 98),src/content/docs/factories/factory-api.mdx:129, andsrc/content/docs/platform/architecture.mdx:18. Requested change: use{VARS.WARP_PLATFORM_API}in body prose (and{{WARP_PLATFORM_API}}in frontmatter) at each of those sites.src/content/docs/factories/api-and-sdk/index.mdx:37— [IMPORTANT] Promoting the former### SDK overviewto## SDKscreates a second H2 with the identical title already present at line 158, producing duplicate slugs (#sdksand#sdks-1) and two sections repeating the same typed-requests/retries/error-handling pitch. Requested change: merge the two sections into the single## SDKsat line 158, or retitle this one distinctly (for example## Choose the SDK or raw REST).src/content/docs/factories/api-and-sdk/index.mdx:32— [SUGGESTION] The:::cautionat line 29 carries no caveat — it states the page is a high-level overview and links the reference — and the page now holds three callouts (note at 15, cautions at 29 and 55), above the AGENTS.md budget. Requested change: unwrap this caution into body prose and fold the duplicate SDK-repo caution at line 55 into the## SDKssection.src/content/docs/factories/quickstart.mdx:21— [SUGGESTION]check_compression_contract.py --content-type quickstartreports 757 words against the 600-word budget; the overage is justified in the PR body so it is non-blocking, but the## What you'll decidesection restates every decision (code host, repositories, factory and foreman name, default agents, Slack and issue tracker) that the numbered wizard steps below already cover. Requested change: delete the## What you'll decidesection to approach budget without losing the wizard screenshots or the first-work-item path.src/content/docs/factories/deployment-patterns.mdx:37— [SUGGESTION] The new page exposes internal architecture the reader cannot act on:Orchestration: {VARS.WARP_AUTOMATION_PLATFORM} orchestratorhere andcalls the {VARS.WARP_AUTOMATION_PLATFORM} orchestrator API/SDKat line 65, which AGENTS.md → "Document the user-visible model, not our architecture" rules out, and "orchestrator API/SDK" conflicts with the Warp Platform API name this PR standardizes. Requested change: drop theOrchestrationbullet and refer to{VARS.WARP_PLATFORM_API}with a link to/factories/api-and-sdk/at line 65.src/content/docs/platform/architecture.mdx:111— [SUGGESTION] The Related-pages description still promises "CLI-only, Warp-hosted, and self-hosted deployments", but the retargeted/factories/deployment-patterns/is factory-scoped with only Warp-hosted and managed self-hosting, linking unmanaged execution out to/platform/unmanaged-execution/;src/content/docs/platform/index.mdx:71repeats the same stale framing for the same destination. Requested change: reword both to match the destination page's actual scope.src/content/docs/platform/architecture.mdx:57— [SUGGESTION] The--hostcross-reference was dropped rather than retargeted, even thoughsrc/content/docs/factories/self-hosting/index.mdx:41deliberately preserves<a id="routing-runs-to-self-hosted-workers"></a>for it, so readers lose the pointer to run routing. Requested change: relink--hostto/factories/self-hosting/#routing-runs-to-self-hosted-workers.src/data/vars.ts:45— [NIT]WARP_PLATFORM_API:pads its value one space short of the aligned column used byWARP_AUTOMATION_PLATFORMandPLATFORM_RUN. Requested change: add one space so the value starts in the same column (WARP_PLATFORM_API: "Warp Platform API",).
Verdict
Request changes
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.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 - 757 words and two callouts. This intentional overage retains visual wizard confirmation and the full first-work-item path; detailed repository sizing, Foreman, integration, and agent configuration guidance links to its owning pages.
Unverified claims
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