docs: editorial review of product overviews, factories, and quickstarts

[rachaelrenk]

Summary

Clarify Warp's product entry points and factory workflows, reduce repetition, and make setup requirements easier to follow. This is an editorial review of existing documentation, not a new pricing or availability policy.

Changes

• Tighten the products overview and factory lifecycle explanations; standardize quickstart and integration prerequisites, keeping access separate from usage funding.
• Split factory agents into conceptual, configuration, and creation pages. Preserve the “About” titles, original URLs and compatibility anchors; update navigation, crosslinks, and setup screenshots.
• Simplify skills and automations guidance, and reorganize the factory definition reference. Link canonical schemas, examples, and the bundled-skill catalog instead of duplicating reference material.
• Clarify execution, inference, credential, permission, and runner boundaries across the infrastructure, deployment, and hosting docs.
• Record reusable authoring guidance in AGENTS.md and the terminology glossary, and protect the agent-page routes with redirect regression tests.

Review follow-up

Pushed in 97a116ac.

• Correct existing-agent prerequisites to factory-scoped Editor access rather than a team-level role.
• State the example validator's file coverage and deferred checks.
• Separate the default foreman's PR handoff from completion after a merge notification or confirmation.
• Correct worker-host versus task-platform guidance, including related lifecycle and self-hosting references.
• Standardize the flagged billing and quickstart link labels in sentence case.
• Restore a compact custom-skills tree beside the scope choices.
• Link directly to the canonical directory structure, labeled-issue example, and filter reference.
• Clarify team-owned usage attribution in the API reference; keep the bundled-skill table there rather than duplicating it.

Content design plan

Audience and task: Developers choosing a Warp product, starting a factory, or configuring its agents and infrastructure.

Content ownership: The agent concept page owns roles and human decision points; configuration owns existing-agent settings and authentication; creation owns custom roles and dispatch. Skills, automations, and definition syntax retain their respective procedures and references.

Editorial verdict: Preserve page purposes and useful setup context. Remove duplicate catalogs and repeated explanations, link their canonical owners, and retain old anchors when content moves. The agent split uses procedural pages; the conceptual titles remain “About factory agents” and “About factory infrastructure and security.”

Validation

The local review follow-up passed typecheck, heading-variable tests, the standard build, generated heading/TOC checks, homepage JSON-LD validation, UI-reference validation, whitespace checks, all six redirect tests, and an internal-link scan covering 4,469 links with zero broken links. Generated HTML confirms the skill tree stays inside step 2 of the four-step procedure. The three teaching-material pages pass compression checks and have no blocking style errors. Earlier checks confirmed the unchanged “About” titles and that the removed skill table exactly matches its linked API reference.

The earlier broader style scan reported 157 findings; it is not a clean style pass. Targeted checks covered the newly edited API reference as well. Trunk is unavailable. Existing build warnings include deprecated Astro settings, large chunks, the /404 route conflict, and Node 25/Vercel runtime fallback.

CI, automated review, and Vercel are running on the new head (97a116ac). For the previous head (bd3c6759), build/link-audit and Vercel passed; the reviewer reported a review-publication failure with Argument list too long, not a docs-build failure.

Editorial exceptions

All reported overages already exist on the reviewed base (df1cc389). Retain these pages for this scoped review rather than splitting or cutting necessary teaching to meet a count. Counts below exclude fenced code:

• agents/cli/quickstart.mdx: 874 words (base 887). Keep cross-platform installation, login, approvals, shell use, and resume guidance. Its three inherited callouts cover Homebrew updates, update controls, and headless credential handling; update guidance overlaps and remains a candidate for a CLI-focused cleanup.
• platform/integrations/quickstart.mdx: 678 words (base 664). Keep connection, authorization, first trigger, and run confirmation together; the added usage requirement explains funding without replacing the billing reference.
• platform/triggers/scheduled-agents-quickstart.mdx: 726 words (base 709). Keep run identity beside setup because it changes PR authorship and billing; preserve the first-run test and CLI limitation.
• quickstart.mdx: 758 words (base 760). Retain the continuous path from installation through Blocks, editing, completions, and the first agent conversation.
• factories/self-hosting/managed-kubernetes.mdx: 2,066 words (base 2,074). Retain Helm setup, RBAC, worker/task resource distinctions, secret injection, preflight limitations, disruption controls, and capacity guidance.
• factories/webhooks.mdx: 2,073 words (base 2,081). Retain authentication choices, setup, delivery confirmation, rotation, filtering, delivery rules, and recovery guidance.
• platform/integrations/github.mdx: 2,526 words (base 2,514). Retain team setup, per-user linking, thread continuation, installation-token permissions, and troubleshooting. Its three inherited callouts distinguish GitHub surfaces, the non-CLI setup path, and the installation-access security boundary.
• platform/harnesses/authentication.mdx: 817 words, unchanged. Keep its three inherited callouts distinguishing local BYOK, API funding versus a ChatGPT subscription, and the consequences of deleting credentials.

These are scoped exceptions, not a claim that the pages have no further redundancy.

Screenshot publication exception

On 2026-10-16, Rachael approved retaining the documentation-repository names docs-factory-config and docs-internal in src/assets/factories/quickstart-connect-repo.png and src/assets/factories/quickstart-factory-details.png. She considers these names non-sensitive and approved keeping the images unchanged. This exception is limited to publishing those repository names in these two screenshots; it does not change repository access or authorize publishing repository contents or credentials.

Source verification

The four accuracy corrections were checked against:

• Factory role resolution and authorization tests.
• Example validator and default foreman instructions.
• Docker backend and the worker's Direct/Kubernetes implementations at the same revision.

Unverified claims

Live factory setup, third-party authentication, self-hosting, and billing were not exercised end to end. Earlier human team-switching and reviewer preview checks remain supporting evidence, not full workflow verification. Source revisions verify implementation or default instructions, not deployment or general availability.

Documentation risk

Risk: engineering-review-required
Rationale: Includes permissions, workflow/default behavior, configuration, credential boundaries, self-hosting, and platform-support claims. Page-specific compression exceptions are documented above.
Docs override: none

Agent context

Original review conversation · Continuation and review fixes · Approved agent-page split plan

Co-Authored-By: Warp agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 16, 2026 4:12pm UTC

[warp-for-oss]

@rachaelrenk

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 /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

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

[rachaelrenk]

Pricing review requested: HYC

We are simplifying the Warp Factories quickstart prerequisites into a direct, scannable list. The proposed usage bullet is:

Eligible team usage for factory runs.

@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.

[warp-agent-staging]

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), and quickstart.mdx (758), against the approximately 600-word quickstart budget; factories/self-hosting/managed-kubernetes.mdx (2,066), factories/webhooks.mdx (2,073), and platform/integrations/github.mdx (2,526) exceed the 1,500-word combined-page budget. Three callouts remain in agents/cli/quickstart.mdx, platform/integrations/github.mdx, and platform/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

[hongyi-chen]

curious why we need "about" here?

[warp-agent-staging]

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

[hongyi-chen]

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

[warp-agent-staging]

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

[rachaelrenk]

Correct, this title was incorrectly capitalized, per the style guide we should use sentence-case for page titles

[hongyi-chen]

similar comment to above here

[warp-agent-staging]

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

[hongyi-chen]

Hmm curious why we're adding "About" to the beginning? is this the convention across other docs platforms

[warp-agent-staging]

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

[hongyi-chen]

hmm why did we remove all of this content here previously?

i think the custom file-based factory skills could be helpful

[warp-agent-staging]

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

[rachaelrenk]

Restored a compact directory tree beside the shared-versus-agent-specific scope choices in Add or edit a skill. The setup instructions and both file paths remain inline, and the definition link now goes directly to the canonical directory-structure section. Included in 97a116ac.

[hongyi-chen]

same with this table, is it somewhere else now?

[warp-agent-staging]

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

[rachaelrenk]

The bundled-skill table remains in the canonical Skill actions in conversation data section, and the skills page links directly there rather than duplicating it. Also clarified attribution at that source: exclude actions with input.bundled_skill_id, and count path-only loads as team-owned only after confirming the path belongs to a skill root the team manages. Included in 97a116ac.

[hongyi-chen]

why did we remove this in place of a visual?

[warp-agent-staging]

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

[rachaelrenk]

Added explicit links to the canonical labeled-issue example and trigger-filter reference in Filters in definitions as code. The local pull-request example and default-automation guidance remain. The VISUAL marker was already present and does not replace the example; readers now have a direct route to the simpler labeled-issue example. Included in 97a116ac.

[warp-agent-staging]

Overview

Re-reviewed f8ef2e93: the four accuracy fixes and page-specific compression exceptions are verified. The agent-page split and restored skills tree preserve reader tasks and canonical ownership; the retained “About” titles are permitted, with one nonblocking screenshot-publication decision below.

Verdict

Checks: standard build and tests pass; CI red because automated-review publication failed with Argument list too long; visual proof present. That review reported no blocking findings, not a docs-build failure.

Review checks passed: links, navigation/anchors, redirects, generated headings, UI references, and risk/VERIFY accounting. Style scan: 160 advisory findings, not a clean lint pass; Trunk unavailable. Live factory setup, authentication, self-hosting, and billing were not exercised.

Found: 0 critical, 0 important, 1 suggestion, 0 nits.

Responding as Docs Factory (V2): Open session · View in factory

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• No findings.

Verdict

Approve