docs(factories): editorial pass on infrastructure and security

[hongyi-chen]

Summary

Editorial pass on top of #523. The content and verified facts are unchanged — this is a clarity and house-voice rewrite of factories/infrastructure-and-security.mdx, plus the same treatment for the two self-hosting paragraphs that PR touches.

Targets hyc/factories-infra so it can be merged into #523 before that PR lands.

What was unclear

The page read like a compliance memo rather than Warp docs:

• Hedged, third-person phrasing. "supported factory data," "the applicable provider account," "available controls depend on your team's configuration and agreement with Warp," "customer-owned" throughout. The style guide calls for second person and plain language.
• Four stacked decision tables, the third of which (Choose execution, inference, and storage independently) largely restated the two above it.
• Inconsistent bolding inside those tables — **Environment** bold, Runner not; **Checkout and commands** bold, Compute not. This appears to have been driven by the style linter's glossary check rather than by meaning.
• Relative page links (../platform/environments). Every other page in the repo uses root-relative links with trailing slashes; this was the only file using the other form.
• Missing house conventions: no callouts, no --- section breaks, no Related pages section, and no Early Access / Enterprise gating treatment even though most of the page describes Enterprise-gated controls.
• Implementation detail that belongs on the pages this one links to: runner file resolution mechanics, "Warp rejects a hosted shape above that limit," "workers authenticate to Warp with a supported principal."

What changed

• Opens with what the reader controls, leading with the product name for search and answer engines.
• Reuses the orchestration-vs-execution framing already established in platform/self-hosting/, instead of introducing fresh "control plane / execution plane" vocabulary for the same idea.
• One comparison table (Warp-hosted vs self-hosted) survives, with consistent bolding. Environments/runners, the independent-choice matrix, and credentials become bold-term lists in the standard * **Term** - description format.
• Callouts carry the gating and the caveats: :::note[Early access] for Early Access and Enterprise features, :::caution for "self-hosting is customer-hosted execution, not a guarantee that factory data stays in your network."
• Adds a Related pages section and converts all links to root-relative form with trailing slashes.
• Simplifies the Mermaid diagram — the previous version carried a three-line sentence on one edge.
• Same clarity pass on the self-hosting wording: "Warp stores applicable orchestration and conversation data according to your product configuration and agreement" → "Warp stores orchestration and conversation data according to your team's configuration and its agreement with Warp," and the BYOLLM section keeps its BYOLLM link.

No new product claims. Every fact, caveat, and eligibility statement from #523 is preserved.

Validation

• npm run typecheck — 0 errors
• npm run build — 377 pages built, Complete!
• Every internal link on the three edited pages resolves against the built routes — 0 broken
• Style lint — clean except two unrecognized-term warnings on the bold table header row, the identical pattern platform/self-hosting/index.mdx already produces

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 16, 2026 6:00am

[hongyi-chen]

This PR was generated with Warp.

 

[hongyi-chen]

Closing after comparing this branch against hyc/factory-launch post-#523 merge.

This pass was written against the pre-review copy of #523 (edd03ac). After this branch was cut, #523 took three revision rounds before merging (ec7c866, a57f26f, edbe60d → merged as a9c5f5a), which landed most of what this PR set out to fix, often in near-identical wording:

• Root-relative links with trailing slashes across the page
• Consistent table bolding and clearer column headers, with one-line lead-ins before each table
• Second-person, active phrasing ("machines you control", "your infrastructure")
• Jargon spelled out ("supported principal" → agent API key, "hosted shape" → instance shape)
• The dense self-hosting paragraph broken into a numbered 3-step deploy flow
• Enterprise gating stated in a :::note

The remaining deltas here were explicitly considered and decided the other way during #523's review:

• The :::caution was removed as redundant — the data-boundary point lives in the control/execution-plane prose ("Self-hosting moves only the execution plane: …").
• Bedrock/Gemini Enterprise specifics were deliberately removed from the self-hosting index, the security page, and the factories page in favor of the BYOLLM / team-managed-keys pages; this branch reintroduces them.
• The gating note was placed mid-page next to the choices it gates; a top-of-page Early Access banner would duplicate the note on the Factories overview, which sibling pages don't repeat.
• The merged page documents implicit environment management (added in edbe60d); this branch's environments section predates that fact.

A few edits would now regress the base if merged:

• The security page rewrite drops "Warp does not persistently store your source code or train on it."
• The branch predates the Google Cloud Storage egress bullet on the security page.
• Dropping the article before {VARS.WARP_AUTOMATION_PLATFORM} goes against the usage documented in src/data/vars.ts ("with the {VARS.WARP_AUTOMATION_PLATFORM}").
• ## Related pages sections and --- body breaks aren't the convention in the factories section, and the merged page already inline-links everything the Related pages list contains.

Nothing left here needs salvaging, so closing rather than resolving conflicts. The branch is left intact.