docs: restructure factories documentation - #748
rachaelrenk wants to merge 17 commits into
Conversation
Co-Authored-By: Warp <agent@warp.dev>
…ries-ga # Conflicts: # src/sidebar.ts # vercel.json
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
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}
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
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>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
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
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
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
|
/warp-agent-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 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
|
|
||
| ## Configure a factory to use a worker | ||
|
|
||
| Define the worker host and a compatible runner in your [factory definition](/factories/factory-as-code/). The factory dashboard shows each configured runner and the worker that executes its work. Use the [worker reference](/factories/self-hosting/reference/) to configure the worker process and the [factory dashboard](/factories/factory-dashboard/) to inspect its runs. |
There was a problem hiding this comment.
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
1 participant
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 Phase 1 delta has no actionable structural or terminology findings. Existing report-only warnings remain elsewhere in moved source.python3 .agents/skills/check_for_broken_links/check_links.py --internal-only- passed with 0 broken links across 4,126 internal links.git diff --check- passed.vercel.json.npm run build- compiled the updated MDX, variables, and sidebar, then failed on the existing/_llms-txt/support.txtprerender withRangeError: Maximum call stack size exceededinhast-util-to-text.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; and
src/content/docs/factories/factory-dashboard.mdx.Requested engineering reviewers: none — no single source owner resolved for this cross-cutting documentation restructure.
Engineering review status: pending
Docs override: none
Co-Authored-By: Warp agent@warp.dev