Repository navigation
docs: editorial review of product overviews, factories, and quickstarts - #910
rachaelrenk wants to merge 27 commits into
Conversation
Co-Authored-By: Warp <agent@warp.dev>
|
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 retitles the docs home page to "Warp products overview" and tightens the introductory paragraph to separate Warp Agent, cloud automation, and Warp Factories positioning.
Concerns
- No blocking concerns found. The prose-only changes align with the page's overview purpose, keep CLI details in the existing Warp Agent section, and do not introduce security-sensitive behavior.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
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>
Pricing review requested: HYCWe are simplifying the Warp Factories quickstart prerequisites into a direct, scannable list. The proposed usage bullet is:
@hongyi-chen: please advise on the customer-facing requirement and wording, including any plan eligibility, balance, purchase-setting, or Enterprise exceptions needed before someone can complete the quickstart. We want a concrete prerequisite without duplicating the billing reference or applying standalone integration rules to factories without verification. This wording is provisional pending your input. The edits are currently local and will be included in the next push. Any equivalent cloud-run prerequisites will need the same billing review. |
Co-Authored-By: Warp <agent@warp.dev>
rachaelrenk
changed the title
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>
Preserve the networking section and use the current team-settings lookup for hosted-agent egress ranges. Co-Authored-By: Warp <agent@warp.dev>
warp-agent-staging
Bot
added
the
factory:docs-factory
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This reorganizes factory agent docs and tightens product overviews and setup guidance. Please address the new permission prerequisite and decide how to handle the retained accuracy issues and documentation-contract exceptions below.
Concerns
- [Important] Record page-specific compression exceptions or remove redundancy. The required checker finds inherited word-budget overages in
agents/cli/quickstart.mdx(874),platform/integrations/quickstart.mdx(678),platform/triggers/scheduled-agents-quickstart.mdx(726), andquickstart.mdx(758), against the approximately 600-word quickstart budget;factories/self-hosting/managed-kubernetes.mdx(2,066),factories/webhooks.mdx(2,073), andplatform/integrations/github.mdx(2,526) exceed the 1,500-word combined-page budget. Three callouts remain inagents/cli/quickstart.mdx,platform/integrations/github.mdx, andplatform/harnesses/authentication.mdx; justify necessary exceptions in the PR body rather than mechanically splitting pages or cutting teaching, and distinguish these inherited overages from new regressions. - [Suggestion] Shorten the PR description. Replace the successive per-page and per-commit chronicles with the problem, net outcome, and current validation, retaining required risk metadata and limitations.
Validation: CI build/link audit passed; typecheck, heading tests, redirect tests, internal-link checks, and UI-reference checks passed during review. The ordinary local build hit a Node stack overflow; an increased-stack build and its generated-HTML checks passed. Preview navigation, compatibility anchors, and screenshot legibility were examined, but live factory setup, authentication, self-hosting, and billing were not exercised.
Automated reviews produced content findings before their publication step failed with Argument list too long; red review CI is not a docs-build failure.
Verdict
Checks: build pass in CI (local stack caveat above), tests pass, CI red, visual proof present.
Found: 0 critical, 2 important, 4 suggestions, 0 nits. One important finding is an introduced permissions error; the accuracy suggestions and compression overages are explicitly inherited.
Responding as Docs Factory (V2): Open session · View in factory
|
|
||
| ## Prerequisites | ||
|
|
||
| * Team or workspace admin access, or the team-level [Warp Factories Editor role](/factories/infrastructure-and-security/#factory-roles-and-permissions). |
There was a problem hiding this comment.
[Important] Require the effective role on this factory, not team-level Editor. Agent management uses factory-level permissions: a factory-specific Editor qualifies without team-level Editor, and an override can restrict a team-level Editor on this factory. Replace this with “Editor access to this factory, or team/workspace admin access,” retaining the permissions link, and make the same correction in creating-custom-agents.mdx:13.
Responding as Docs Factory (V2): Open session · View in factory
| ``` | ||
|
|
||
| Pass the factory root to check cross-file references. The script reports errors by file and line. The GitHub check also validates team- and factory-dependent settings. | ||
| Replace `FACTORY_ROOT` with the directory containing `factory.yaml`. The script checks syntax and cross-file references and reports errors by file and line. Team- and factory-dependent checks, such as whether a secret or environment exists, run in the GitHub check and when the definition is applied. |
There was a problem hiding this comment.
[Suggestion; retained accuracy issue] Scope the validator assurance. The linked script collects only factory, agent, automation, runner, and scorer files, so a pass does not validate the routers, benchmarks, webhooks, or skills described here; it also defers runner-reference checks. State those limits and point to factory PR/apply validation for the remaining checks; this overstatement predates the rewrite.
Responding as Docs Factory (V2): Open session · View in factory
| The **foreman agent** assigns work and is the only default agent that communicates directly with you. It relays questions and answers between you and other agents, and continues their existing conversations for revisions and follow-ups. | ||
|
|
||
| When the work is done, the foreman presents the final pull request and its supporting evidence, then marks the work item complete. Complete means the work was handed to a human, not that the change was merged or deployed. Merging stays with your team. | ||
| When finished, it returns the pull request and supporting evidence, then marks the work item complete. Complete means handed off to your team, not merged or deployed. |
There was a problem hiding this comment.
[Suggestion; retained accuracy issue] Separate PR handoff from terminal completion. The default foreman instructions linked above explicitly stop at handoff and complete on a later merge notification or user confirmation, so this description contradicts its advertised source. Align the explanation with the intended defaults; the contradiction was already present before this PR.
Responding as Docs Factory (V2): Open session · View in factory
| 1. **Deploy a worker** - Review the [self-hosting requirements](/factories/self-hosting/), then connect a worker that authenticates to Warp with a self-hosted worker API key. Workers run on `linux/amd64` and `linux/arm64`, and the worker's platform determines which workloads it can run. | ||
| 2. **Pair it with a compatible runner** - Choose a runner that matches the worker's platform. | ||
| 3. **Select the worker in the factory definition** - Set [`workerHost`](/factories/factory-as-code/) so the factory routes work to it. | ||
| Managed self-hosting requires an Enterprise plan. Workers run on `linux/amd64` and `linux/arm64`, and the runner must match the worker's platform. |
There was a problem hiding this comment.
[Suggestion; retained accuracy issue] Distinguish worker-host OS from task platform. A native macOS/Windows worker using Docker Desktop or a remote Linux daemon runs Linux tasks: the Docker backend derives the task platform from the daemon, not the worker process OS. Replace the Linux-only host/universal matching rule with backend-specific guidance and link “Runner settings by execution host”; both restrictions already appeared in the old instructions, so this is not a new regression.
Responding as Docs Factory (V2): Open session · View in factory
| * [Full Terminal Use](/agents/capabilities/full-terminal-use/) - Let agents drive interactive terminal apps, see live output, and run commands | ||
| * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open the cloud run transcript and artifacts after a Computer Use session finishes | ||
| * [Factory agents](/factories/factory-agents/) - Roles and responsibilities for factory agents | ||
| * [About factory agents](/factories/factory-agents/) - Roles and responsibilities for factory agents |
There was a problem hiding this comment.
curious why we need "about" here?
There was a problem hiding this comment.
About matches the renamed destination title. Our conceptual-title guidance also permits a plain noun phrase, so it is optional. “Factory agents” is equally valid if the page title, sidebar, and title-based links change together.
Responding as Docs Factory (V2): Open session · View in factory
|
|
||
| * [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for creating and managing agent tasks | ||
| * [Cloud Agents Overview](/platform/) — How cloud agents work | ||
| * [Cloud agents overview](/platform/) — How cloud agents work |
There was a problem hiding this comment.
feels weird to be making it lower case when "Access, Billing, Identity" below are capitalized - let's standardize on some approach here and make sure this is reflected all throughout
There was a problem hiding this comment.
Sentence case is the current rule, preserving proper names and exact UI labels. This pass missed “Access, Billing, and Identity”; the destination title is “Access, billing, and identity permissions.” The same stale label needs a sweep in sibling error pages and the Enterprise billing page.
Responding as Docs Factory (V2): Open session · View in factory
| * [Integrations](/platform/integrations/) — Integration setup guides | ||
| * [Slack Integration](/platform/integrations/slack/) — Slack-specific setup | ||
| * [Linear Integration](/platform/integrations/linear/) — Linear-specific setup | ||
| * [Slack integration](/platform/integrations/slack/) — Slack-specific setup |
There was a problem hiding this comment.
similar comment to above here
There was a problem hiding this comment.
Slack integration and Linear integration match their destination titles: Slack and Linear are proper names, while “integration” is lowercase. The broader consistency sweep should apply that rule rather than reverting these two labels.
Responding as Docs Factory (V2): Open session · View in factory
| label: 'Infrastructure', | ||
| items: [ | ||
| { slug: 'factories/infrastructure-and-security', label: 'Overview' }, | ||
| { slug: 'factories/infrastructure-and-security', label: 'About infrastructure and security' }, |
There was a problem hiding this comment.
Hmm curious why we're adding "About" to the beginning? is this the convention across other docs platforms
There was a problem hiding this comment.
About is not required by our guide or universal across docs platforms. GitHub uses About repositories, while other docs use noun phrases or task-based titles. “Infrastructure and security” is valid too; the prefix is an editorial choice, not a requirement.
Responding as Docs Factory (V2): Open session · View in factory
| ## Factory role and integration skills | ||
|
|
||
| Every default agent starts with a baseline of role and integration skills so the factory works immediately after setup, before you write anything custom: | ||
| <span id="factory-role-and-integration-skills" /> |
There was a problem hiding this comment.
hmm why did we remove all of this content here previously?
i think the custom file-based factory skills could be helpful
There was a problem hiding this comment.
Custom-skill setup remains under “Add or edit a skill,” including shared and agent-specific paths. The illustrative directory tree was removed, not the setup instructions. Restoring a compact tree beside those scope choices would preserve a useful reader aid without duplicating the full reference.
Responding as Docs Factory (V2): Open session · View in factory
| | `tui-migrate-setup` | Migrate supported settings into the Warp Agent CLI. | | ||
| | `update-tab-config` | Update an existing Warp tab configuration. | | ||
| | `warpctrl` | Control and inspect a running Warp app with Warp Control. | | ||
| <span id="attribute-team-owned-skill-usage" /> |
There was a problem hiding this comment.
same with this table, is it somewhere else now?
There was a problem hiding this comment.
Yes—the identical table already exists in Skill actions in conversation data, and this page links there. This PR removes the duplicate table rather than moving the catalog to a new location.
Responding as Docs Factory (V2): Open session · View in factory
| ## Filters in definitions as code | ||
|
|
||
| In a [factory definition](/factories/factory-as-code/), each entry under an automation's `triggers` takes an optional `filter` whose keys mirror the filters in the automation editor: | ||
| {/* VISUAL: An automation's trigger editor with More filters expanded. */} |
There was a problem hiding this comment.
why did we remove this in place of a visual?
There was a problem hiding this comment.
The VISUAL marker already existed and is a non-rendered comment, not a new screenshot. Default-automation guidance moved above the steps, and the definitions section retains the full PR example. The simpler labeled-issue example was removed but remains in the definition reference; a local example or direct link would preserve that introductory teaching.
Responding as Docs Factory (V2): Open session · View in factory
This branch was successfully deployed
2 participants
Summary
This PR collects a manual editorial review of Warp's product overviews, Warp Factories entry points and launch docs, and main product quickstarts. The focus is clearer product explanations, less repetition, and concise, scannable wording. The review is ongoing; this description covers the edits made so far.
Products overview: Rename the homepage to "Warp products overview" while keeping the "Warp products" sidebar label. Remove the repeated capability list, describe terminal use concretely, and give teams' use of Warp Factories its own sentence. Keep CLI access details in the Warp Agent section.
Factory descriptions: Use "connected to your repositories" instead of "attached to a set of repositories." Describe factories as routing work through stages, clarify where output returns, and replace the awkward "team work" phrasing.
Factory overview: Use the source-neutral "backlog of tasks," simplify the quickstart card, and separate the work-item definition from its examples. Caption the introductory video and move the lifecycle diagram to "Stages and checkpoints," with prose distinguishing lifecycle roles from default-agent coverage.
How Warp Factories work: Use "implementation" and "review" in the description, introduce the foreman's role directly, and remove the repeated eight-bullet system-diagram walkthrough. Keep both diagrams and relocate useful intake, execution, definition, and benchmark details to their relevant sections.
Quickstart prerequisites: Use direct requirement lists in the Warp Factories, Warp app, Warp Agent CLI, cloud agents, and supported Oz CLI quickstarts. Move the conditional code-host approval guidance to the connection step and CLI account/login explanations to the login step.
Factory setup verification: Sign in only if prompted, and make team switching optional. Document the verified account-menu path: click the avatar, hover over the team name, and select another team.
Usage prerequisites: Incorporate HYC's feedback with actionable "available usage" and "add usage if needed" wording. Apply the same pattern to cloud agents, schedules, local-to-cloud handoff, the integrations quickstart, and Slack, Linear, Jira, and GitHub integration requirements. Separate feature access from funding and preserve individual/team billing, schedule attribution, and Enterprise terms.
Authoring guidance: Add rules and adaptable examples for usage prerequisites to
AGENTS.md, plus a "usage balance" definition and "add usage" usage note to.agents/references/terminology.md. Also clarify full-title link capitalization, prose-versus-UI lifecycle naming, and concise prerequisite lists for procedures and quickstarts. Canonical billing rules and credit-named identifiers remain unchanged.Factory quickstart and agent editing: Refresh setup and settings screenshots from live captures, use New Chat for work intake and team-wide Runs for tracking, and align instructions with current tabs and conditional Auth controls. Tighten agent descriptions, sidebar navigation, model guidance, and approval wording.
Three-page agent split: Separate About factory agents, Configuring factory agents, and Creating custom agents. Nest the pages in the sidebar, update task-specific crosslinks, and preserve old section anchors. The split was pushed in
4b269d7b.Agent-page review refinements: Rename the conceptual title and sidebar entry to About factory agents, match full-title links to their destinations, and use lowercase lifecycle terms in explanatory prose while preserving displayed state labels. Make spec approval and merge controls concrete, shorten resource and harness guidance, and explicitly describe dispatch as the foreman's actions rather than reader instructions. Rename the editing, code-definition, and dispatch headings, retarget crosslinks, and retain their former anchors. These refinements are pushed through
f351862a.Factory procedure prerequisites: Review 20 prerequisite sections and update 17 older pages across integrations, webhooks, code forges, API setup, and self-hosting. Use concise, unbolded requirement lists and move conditional instructions beside the steps that need them. Preserve administrator roles, credential distinctions, runtime restrictions, and existing command examples. Record the reusable guidance in
AGENTS.md. Pushed in31db8ca2.Factory skills: Shorten the page and distinguish role/integration, Warp-provided, and custom skills. Put shared and per-agent file paths beside the add/edit procedure, separate instructions from tool and credential access, and retain compatibility anchors and links to skill attribution and self-improvement.
Factory automations: Clarify matching rules, overlapping triggers, and the distinction between filtering and access control. Tighten provider and webhook filter guidance, retain concrete definition examples, and correct the editing procedure to open an automation's settings before changing its trigger filters.
Factory definition reference: Rename the page to "Factory definition syntax," reorganize file and field references, and clarify where definitions live and how validation works. Add navigable field anchors and tables, distinguish local validation from team-dependent checks, and link complete examples and the canonical pull request check guidance.
Infrastructure and security: Separate execution hosting, inference, and credential boundaries. Clarify what stays on self-hosted infrastructure and what flows through Warp, distinguish Warp Agent routing from third-party harness requests, and refine inference-support, credential, execution-host, and role/permission tables.
Deployment and hosting: Make the hosted-versus-managed-self-hosted choice more direct, distinguish standalone unmanaged execution from factory hosting, and make work-intake links action-oriented. Reduce duplicated hosting detail by linking runner and security references. Merge the latest
mainand retain its team-settings lookup for current egress ranges instead of a hard-coded IP list.Runners: Distinguish compute configuration from environment/workspace setup and execution hosting. Reorganize defaults, factory overrides, setup behavior, and backend-specific settings before OS and legacy CLI details. Preserve supported resource tables and command examples, update crosslinks, and retain the former key-features anchor.
Supported Oz CLI workflows and named factory stages remain intact. No new pricing or plan-eligibility policy is established by these edits.
Related issues
None - requested during a manual docs review.
Validation
The current merged head (
bd3c6759) passed:npm run typechecknpm run test:heading-varsnpm run buildnpm run test:heading-tocsnpm run test:homepage-json-ldgit diff --cached --checkbefore the merge commitThe hosting conflict is resolved, the working tree is clean, and GitHub reports the PR as mergeable. CI and Vercel checks were pending when the merge was pushed; local checks are not a claim that remote checks have passed.
Earlier recorded validation for the agent-page batch (
f351862a) also included the following; these were not rerun during conflict resolution:python3 .agents/skills/check_for_broken_links/check_links.py --internal-only(zero broken links)python3 scripts/test_check_redirects.py(six tests passed)python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --changed --require-provenancegit diff --checkTrunk lint was unavailable because Trunk is not installed. Local validation reported non-blocking build warnings and an unsupported Node 25/Vercel runtime warning. Dependency installation reported vulnerabilities; no dependency files were changed. Rachael verified the active-team display and team-switching flow in the live web app and supplied screenshots in the review conversation; the UI path was also checked against upstream web-app code. The full quickstart has not been verified end to end, and no agent-driven browser verification was performed.
The prerequisite batch (
31db8ca2) separately passed MDX compilation on all 17 edited pages, internal-link checks (zero broken links), UI-reference validation, targeted style checks (zero blocking errors), and whitespace checks. Code examples in that prerequisite-only batch were compared against its prior commit and were unchanged.The latest
style_lint.py --changedscan reported 157 findings across 68 pages, including factory naming, heading case, screenshot widths, tone, UI formatting, and glossary suggestions. These remain review findings; the scan is not a clean style pass.Screenshots
Rachael supplied updated factory setup and agent-settings captures. Repository assets were refreshed with page-only crops retaining titles and available progress bars, at consistent 563px display widths. The Auth image uses an anonymized credential label. The three-page split reuses these images without new assets. Existing diagram and video placement were also improved.
Follow-ups
Content design plan
The approved split was pushed in
4b269d7b, followed by the reviewed title, prose, and dispatch refinements throughf351862a.Configuring factory agents
.agents/templates/procedural.md; no specialized drafting skill is needed for this editorial extraction.Creating custom agents
.agents/templates/procedural.mdand the repository guide to the confirmed creation flow; a specialized drafting skill is unnecessary for this relocation.Editorial and compatibility verdict
The overview retains roles, foreman handles, built-in skills, and human decision points. Configuration owns settings, models, harnesses, and authentication. Creation owns the new-agent form, custom skills, and configured-agent dispatch. Repeated setup prose is removed without losing configuration inheritance, overrides, approval boundaries, or links to canonical references.
The original overview URL remains live. Internal links target the new owners; old fragments land on short pointers. No Vercel redirect is needed because no published page URL changes, and fragments are not sent to the server. A regression test protects all three routes from redirect shadowing.
Local split validation
Typecheck, heading-variable tests, build, generated heading TOCs, homepage JSON-LD, internal links (zero broken links), redirect tests, UI references including both new pages, and whitespace checks passed. The three split pages have no blocking style errors; one glossary suggestion for the shipped Identity label remains. Generated HTML verifies the old anchors, nested navigation, single H1s, and 563px screenshot widths. No browser verification was performed.
Agent context
Review conversation
Continuation: conflict resolution and description refresh
Implementation plan: split Factory agents
Unverified claims
Documentation risk
Risk: engineering-review-required
Rationale: Includes revised UI workflows, configuration examples, permissions, inference and credential boundaries, self-hosting, and platform-support claims; not limited to tone-only edits.
Docs override: none
Co-Authored-By: Warp agent@warp.dev