docs: add an architecture reference page and embed the platform diagrams

src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx

@@ -19,7 +19,9 @@ Warp's cloud agent infrastructure has four key components:
 3. **Execution** - Where the agent actually runs (Warp-hosted environment, your infrastructure, or your existing CI/orchestrator).
 4. **Visibility** - How the team monitors and intervenes ({VARS.DASHBOARD}, session sharing, APIs/SDKs).
 
-{/* TODO: Insert system architecture diagram once received from design team */}
+![Warp stack overview diagram showing clients, the Warp control plane, Warp-hosted and customer-hosted execution planes, and external systems](../../../../assets/agent-platform/warp-stack-overview.png)
+
+The [stack overview](/platform/architecture/#stack-overview) reference describes each component in this diagram.
 
 ### High-level data flow
 
@@ -136,6 +138,8 @@ Understanding what data stays where is critical for security and compliance deci
 
 Consider the following when selecting a deployment model:
 
+![Deployment models diagram comparing Warp-hosted, managed self-hosted, and unmanaged self-hosted patterns by what runs on Warp versus customer infrastructure](../../../../assets/agent-platform/deployment-models.png)
+
 **Warp-hosted** is right if:
 * You want zero infrastructure management for agent execution.
 * Your security team is comfortable with SOC 2 Type II certified, ZDR-covered infrastructure.
@@ -152,6 +156,7 @@ Consider the following when selecting a deployment model:
 
 ## Related resources
 
+* [Architecture reference](/platform/architecture/) - Diagrams of the stack, the run lifecycle, self-hosted execution, and data boundaries
 * [Deployment Patterns](/platform/deployment-patterns/) - Detailed patterns for CLI-only, {VARS.WARP_AUTOMATION_PLATFORM}-hosted, and self-hosted setups
 * [Security overview](/enterprise/security-and-compliance/security-overview/) - Data handling, encryption, and compliance details
 * [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - Route inference through your own cloud infrastructure

src/content/docs/factories/how-factories-work.mdx

@@ -17,6 +17,10 @@ Deciding which repositories belong in this factory is a separate question. See [
 
 A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way.
 
+![Warp Factories system diagram showing work sources, automations, the foreman and stage agents, human handoff, the factory definition, platform execution, and the outer loop](../../../assets/agent-platform/factories-work-item-flow.png)
+
+The [Warp Factories work-item flow](/platform/architecture/#warp-factories-work-item-flow) reference explains each component in the diagram.
+
 ## How a work item moves through the factory
 
 The foreman coordinates every work item. It routes work between the factory's agents, passes each one the context it needs, and continues existing agent conversations instead of starting new ones. See [factory agents](/factories/factory-agents/) for what each agent does.

src/content/docs/factories/infrastructure-and-security.mdx

@@ -29,6 +29,10 @@ flowchart LR
 
 Self-hosting moves only the execution plane: with a managed self-hosted worker, repository checkouts, command execution, and the sandbox filesystem stay on machines you control, but content that enters prompts, results, transcripts, attachments, artifacts, or telemetry still flows through Warp and the providers you configure. See [deployment patterns](/platform/deployment-patterns/) and [self-hosting security and networking](/platform/self-hosting/security-and-networking/) for the broader data model.
 
+The diagram below maps those boundaries for self-hosted execution; factory runs follow the same data model. The [data security and boundaries](/platform/architecture/#data-security-and-boundaries) reference walks through each data class.
+
+![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png)
+
 ## Runners
 
 A runner defines the compute a factory's agents work on: the operating system and architecture, the sandbox image, and the instance shape (vCPUs and memory). It's the infrastructure choice you make for a factory. The workspace itself — repositories, setup commands, and secrets — comes from the factory's [definition](/factories/factory-as-code/), and Warp keeps it in step for you. See the [runner reference](/platform/runners/) for the available compute options.

src/content/docs/platform/deployment-patterns.mdx

@@ -10,6 +10,8 @@ import { VARS } from '@data/vars';
 
 Teams adopt cloud agents in a few repeatable ways. This page outlines the most common architectures, what they're good for, and how they fit together.
 
+![Deployment models diagram comparing Warp-hosted, managed self-hosted, and unmanaged self-hosted patterns by what runs on Warp versus customer infrastructure](../../../assets/agent-platform/deployment-models.png)
+
 ## Quick mental model
 
 Cloud agent setups usually have four moving parts:
@@ -64,7 +66,9 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte
 
 Use this when you want the {VARS.WARP_AUTOMATION_PLATFORM} to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management.
 
-![Warp enterprise SaaS architecture showing customer infrastructure, isolated tenant sandboxes, Warp backend, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png)
+![Warp-hosted execution architecture showing customer infrastructure, triggers and integrations, isolated tenant sandboxes, the Warp control plane, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png)
+
+The [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference walks through this architecture step by step.
 
 ### What it looks like
 

src/content/docs/platform/overview.mdx

@@ -78,6 +78,7 @@ Runs pick up your team's shared setup no matter what triggered them: [MCP server
 
 ## Where to go next
 
+* [Architecture](/platform/architecture/) - reference diagrams of the stack, the run lifecycle, and data boundaries.
 * [Cloud agents](/platform/) - what cloud agents are, how they get triggered, and how to run them with or without the Warp app.
 * [Cloud agents quickstart](/platform/quickstart/) - run your first cloud agent in about ten minutes.
 * [Environments](/platform/environments/) - define the toolchain and repos a run executes against.

src/content/docs/platform/self-hosting/index.mdx

@@ -34,15 +34,17 @@ Self-hosting has two architectures. The core distinction is **who orchestrates a
 | **Automatic environment setup** | Yes (via Warp [environments](/platform/environments/)) | No (you manage it) |
 | **Session tracking and steering** | Yes | Yes |
 
-The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines.
+The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines. The deployment models diagram on [Deployment patterns](/platform/deployment-patterns/) compares what runs where in each model.
 
 ## How self-hosting works
 
 Warp uses a split-plane architecture: **execution happens on your infrastructure**, while **orchestration, session management, and LLM inference route through Warp's backend**. Agent interactions — including code context in session transcripts and LLM prompts — transit Warp's control plane under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or train on it.
 
 If your security requirement is "repository clones and execution must stay on our infrastructure," self-hosting is designed for that. If your requirement is "no code context can ever route through Warp or an external LLM provider," review [Security and networking](/platform/self-hosting/security-and-networking/) with your Warp account team before deploying.
 
-![Self-hosted Oz architecture showing customer-managed execution with Oz orchestration](../../../../assets/agent-platform/customer-dedicated-saas.png)
+![Self-hosted execution architecture showing the managed worker on customer infrastructure connecting outbound to the Warp control plane](../../../../assets/agent-platform/customer-dedicated-saas.png)
+
+The [self-hosted execution flow](/platform/architecture/#self-hosted-execution-flow) reference explains each numbered step in the diagram.
 
 With any self-hosted architecture:
 

src/content/docs/platform/self-hosting/security-and-networking.mdx

@@ -38,6 +38,8 @@ Repositories are cloned and stored only on your infrastructure, but code content
 
 Self-hosted agents **do not require any network ingress**. They require outbound (egress) access to the following services:
 
+![Self-hosted worker network egress diagram showing outbound-only connections from customer infrastructure to Warp backend endpoints, Docker Hub, Google Cloud Storage, and GitHub](../../../../assets/agent-platform/self-hosted-network-egress.png)
+
 **Warp's backend (all architectures):**
 
 * `app.warp.dev` — port 443
@@ -111,6 +113,7 @@ LLM inference routes through Warp's backend. With Warp-managed inference, reques
 ## Related pages
 
 * [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and architecture decision guide.
+* [Data security and boundaries](/platform/architecture/#data-security-and-boundaries) — Diagrams of where each class of data lives and travels.
 * [Security overview](/enterprise/security-and-compliance/security-overview/) — Warp's broader security model, including ZDR.
 * [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) — Route inference through your own cloud provider accounts.
 * [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option.

src/sidebar.ts

@@ -623,6 +623,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 					// 'Warp-hosted agents' under its own opposite.
 					label: 'Deployment & hosting',
 					items: [
+						{ slug: 'platform/architecture', label: 'Architecture' },
 						{ slug: 'platform/deployment-patterns', label: 'Deployment patterns' },
 						{ slug: 'platform/warp-hosting', label: 'Warp-hosted agents' },
 						// Qualified: a bare 'Overview'/'Quickstart' would now read as the