docs(platform): add architecture page with diagrams

.claude/settings.json

@@ -6,9 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "if": "Bash(gh pr create *)",
-            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"Read .github/pull_request_template.md and use its exact structure as the PR body before continuing.\"}}'",
-            "statusMessage": "Checking PR template..."
+            "command": "cmd=$(jq -r '.tool_input.command // \"\"'); case \"$cmd\" in \"gh pr create \"*) echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"Read .github/pull_request_template.md and use its exact structure as the PR body before continuing.\"}}';;  esac"
           }
         ]
       }

.claude/skills/vcluster-docs-writer/SKILL.md

@@ -281,7 +281,29 @@ import Partial from '@site/docs/_partials/example.mdx';
 
 See `references/partials-guide.md` for complete patterns and troubleshooting.
 
-## Critical Rules
+## Concept and Explanation Pages
+
+Explanation pages (architecture, overview, "what is X") should build the reader's mental model from the outside in. Each section should answer the question a reader would naturally ask next, given what they just learned.
+
+**The progressive disclosure sequence:**
+
+1. What it IS — plain-language definition before any technical framing
+2. What it contains — structural components and their roles
+3. How the parts connect — topology, agents, registrations
+4. How you interact with it — entry points, access patterns
+5. How work flows through it — lifecycle, reconciliation, request paths
+6. Operational detail — network paths, failure behavior, edge cases
+
+**Rules:**
+
+- Do not introduce a term before the concept behind it is established. Glossary links help but do not substitute for a clear conceptual foundation.
+- Add a plain-language "why this matters" sentence before technical component lists. Readers need to know what the list is for before they can absorb its items.
+- Place diagrams immediately after the content they illustrate — not after examples that build on the pattern. A diagram should reinforce what was just described, not summarize what follows.
+- Do not open explanation pages with defensive disclaimers ("X does not replace Y"). Put the relationship between products where it naturally belongs in the flow — usually at the handoff point between sections.
+- Merge sections with confusingly similar names. Adjacent sections covering the same concept from slightly different angles (e.g. "Project lifecycle" and "Project resource lifecycle") signal a structural problem, not a content problem.
+- Separate "what it is" sections from "how it works" sections. A section covering both structure and behavior is usually two sections collapsed into one.
+
+**Check the flow by asking:** can a reader who skims only the section headings reconstruct the mental model? If the heading sequence reads like a component inventory rather than a conceptual arc, restructure.
 
 ### Never-Do
 - ⚠️ **NEVER modify versioned docs** unless explicitly requested

platform/introduction/architecture.mdx

@@ -0,0 +1,75 @@
+---
+title: Architecture
+sidebar_label: Architecture
+sidebar_position: 3
+description: The structural components of vCluster Platform and how they fit together.
+---
+
+import GlossaryTerm from '@site/src/components/GlossaryTerm';
+import PlatformIntroOverview from '@site/static/media/platform/diagrams/platform-intro-overview.svg';
+import PlatformArchitectureOverview from '@site/static/media/platform/diagrams/platform-architecture-overview.svg';
+import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg';
+
+vCluster Platform is the management plane for your <GlossaryTerm term="tenant-cluster">tenant cluster</GlossaryTerm> fleet. It runs in Kubernetes and exposes UI, CLI, and API entry points. It reconciles Platform resources into connected <GlossaryTerm term="control-plane-cluster">control plane clusters</GlossaryTerm>.
+
+Platform is where admins define projects, specify who can create tenant clusters, and set which templates and policies apply. Platform controllers reconcile those decisions into connected clusters, where vCluster runs each tenant cluster control plane.
+
+<figure>
+  <PlatformIntroOverview style={{width: '100%', height: 'auto'}} role="img" aria-label="vCluster Platform connects admins and automation to projects, policies, connected clusters, and tenant clusters" />
+  <figcaption>Platform connects admins and automation to connected clusters and tenant clusters</figcaption>
+</figure>
+
+## Management plane
+
+The management plane runs as the `vcluster-platform` Helm chart, deployed into the `vcluster-platform` namespace. It is the source of truth for all Platform decisions.
+
+- **API gateway.** Authenticates all inbound requests and routes them to the right backend.
+- **Web UI.** Browser interface for the Platform API, running as part of the management API process.
+- **Management API.** Serves Platform resources: projects, clusters, VirtualClusterInstances, templates, users, and access keys.
+- **Platform manager.** Controllers that reconcile Platform resources into connected clusters.
+- **Operational services.** Audit, metrics, cost data, sleep and wake behavior, snapshots, and integrations.
+
+Platform uses Kubernetes custom resources for all management state. The default single-replica deployment uses an embedded database. High-availability deployments can connect to an [external relational database](../administer/clusters/advanced/external-database/external-database.mdx) through Kine, which provides an etcd-compatible API over MySQL or PostgreSQL.
+
+## Connected clusters and agents
+
+A connected cluster is a Kubernetes cluster registered with Platform. Tenant cluster control planes and project workloads run there. Connecting a cluster installs the Platform agent, which maintains an outbound connection to Platform and keeps cluster-side state in sync.
+
+Platform automatically registers the cluster where it is installed as the local cluster. Smaller deployments can use it for both the management plane and tenant workloads.
+
+<figure>
+  <PlatformArchitectureOverview style={{width: '100%', height: 'auto'}} role="img" aria-label="vCluster Platform management plane connected to two connected clusters" />
+  <figcaption>Platform management plane and connected clusters</figcaption>
+</figure>
+
+[Dive deeper into connected clusters →](../understand/what-are-clusters.mdx)
+
+## Projects
+
+A project is the primary policy boundary in Platform. It groups tenant clusters, spaces, templates, secrets, quotas, and integrations, and defines the users and teams who can access them. Each project specifies which connected clusters its members can deploy into, and which templates they can use.
+
+[Dive deeper into projects →](../understand/what-are-projects.mdx)
+
+## Access
+
+Most users enter through the UI or CLI. All requests pass through the API gateway, which authenticates each request and routes it to the right backend.
+
+- **Web UI.** Browser interface for managing projects, tenant clusters, users, templates, and connected clusters.
+- **CLI.** Calls the Platform API for login, create, connect, inspect, and lifecycle commands.
+- **Automation.** Integrations, GitOps workflows, and scripts call the Platform API directly.
+
+The gateway uses Kubernetes impersonation to forward requests. It presents the caller's verified identity to the target API without issuing direct cluster credentials.
+
+<figure>
+  <PlatformEntryPoints style={{width: '100%', height: 'auto'}} role="img" aria-label="Platform API gateway routing requests to management, connected cluster, and tenant cluster APIs" />
+  <figcaption>Platform API gateway request paths</figcaption>
+</figure>
+
+[Dive deeper into entry points and proxy paths →](./how-platform-works.mdx#entry-points)
+
+## Further reading
+
+- [How Platform works](./how-platform-works.mdx)
+- [Connected clusters](../understand/what-are-clusters.mdx)
+- [Projects](../understand/what-are-projects.mdx)
+- [vCluster architecture](/docs/vcluster/introduction/architecture)

platform/introduction/how-platform-works.mdx

@@ -0,0 +1,103 @@
+---
+title: How Platform works
+sidebar_label: How Platform works
+sidebar_position: 4
+description: How vCluster Platform reconciles resources, routes traffic, and behaves when components are unavailable.
+---
+
+import GlossaryTerm from '@site/src/components/GlossaryTerm';
+import PlatformEntryPoints from '@site/static/media/platform/diagrams/platform-entry-points.svg';
+import PlatformTenantLifecycle from '@site/static/media/platform/diagrams/platform-tenant-lifecycle.svg';
+import PlatformNetworkPaths from '@site/static/media/platform/diagrams/platform-network-paths.svg';
+
+Platform follows the Kubernetes controller model. Users and automation create or update API resources expressing desired state. Controllers in the management plane compare that state against connected clusters and reconcile the difference. The connected cluster agent applies changes locally and reports status back to Platform. vCluster then runs the <GlossaryTerm term="tenant-cluster">tenant cluster</GlossaryTerm> control plane within the connected cluster.
+
+For the structural components, see [Platform architecture](./architecture.mdx).
+
+## Entry points
+
+All requests enter through the API gateway, which authenticates each request, checks access, applies impersonation, and forwards to the appropriate backend. Users do not receive credentials for connected clusters directly.
+
+| Entry point | Used by | Purpose |
+|---|---|---|
+| Web UI | Browser users | Manage projects, tenant clusters, users, templates, connected clusters, and settings. |
+| Platform API | UI, CLI, integrations, automation | Manage Platform resources such as projects, clusters, templates, users, and tenant cluster instances. |
+| CLI | Operators and automation | Calls the Platform API for login, create, connect, inspect, and lifecycle commands. |
+| Management Kubernetes API | CLI and Kubernetes clients | Proxies authenticated requests to Platform management resources under `/kubernetes/management`. |
+| Connected cluster proxy | CLI and UI workflows | Proxies authenticated requests to a connected cluster under `/kubernetes/cluster/<cluster>`. |
+| Project resource proxy | Tenant cluster and space access | Proxies project-scoped requests under `/kubernetes/project/<project>/virtualcluster/<name>` or `/kubernetes/project/<project>/space/<name>`. |
+
+<figure>
+  <PlatformEntryPoints style={{width: '100%', height: 'auto'}} role="img" aria-label="Platform API gateway routing requests to management, connected cluster, and tenant cluster APIs" />
+  <figcaption>Platform API gateway request paths</figcaption>
+</figure>
+
+## Resource lifecycle
+
+When a user or automation creates or updates a Platform resource, it moves through a consistent path from request to deployed state:
+
+1. A user, CLI command, integration, or GitOps workflow submits a request. Platform creates or updates the API resource expressing desired state.
+2. Platform validates the resource against project policy, allowed clusters, allowed templates, and quotas.
+3. Platform controllers reconcile the desired state. The connected cluster agent applies changes locally, including namespaces, RBAC, and Helm releases.
+4. The connected cluster reports status back to Platform. The resource status is updated and reflected in the UI and API.
+
+<figure>
+  <PlatformTenantLifecycle style={{width: '100%', height: 'auto'}} role="img" aria-label="Tenant resource lifecycle from request through policy, reconciliation, vCluster runtime, and status" />
+  <figcaption>Tenant resource lifecycle</figcaption>
+</figure>
+
+For tenant clusters, the central resource is VirtualClusterInstance. A Platform-managed tenant cluster uses this resource as its desired state. It covers provisioning, configuration updates, upgrades, access, sleep behavior, wake behavior, Argo CD registration, and cleanup. An [externally deployed tenant cluster](../understand/externally-vs-platform-deployed.mdx) can be registered with Platform without transferring lifecycle ownership to Platform.
+
+Platform manages supporting resources within a project. NodeProvider and NodeClaim resources handle private node provisioning and lifecycle. These resources follow the same lifecycle pattern as other project resources.
+
+## Tenant cluster runtime
+
+Platform decides where and how a tenant cluster should be deployed, but vCluster runs the tenant cluster itself. During creation, Platform combines project policy, the selected VirtualClusterTemplate, user-provided parameters, and the selected connected cluster. It then installs or updates the vCluster Helm release in the target namespace. After that point, the vCluster runtime owns the Kubernetes control plane behavior.
+
+For the API server, syncer, data store, CoreDNS, networking, and worker node models, see the [vCluster architecture](/docs/vcluster/introduction/architecture).
+
+## Network paths
+
+Platform supports multiple network paths depending on what is being accessed and how your environment is connected.
+
+<figure>
+  <PlatformNetworkPaths style={{width: '100%', height: 'auto'}} role="img" aria-label="Network paths for regional and direct access endpoints, Platform proxy, and Tailscale connectivity" />
+  <figcaption>Network paths to connected cluster and tenant cluster APIs</figcaption>
+</figure>
+
+### Regional and direct access endpoints
+
+Platform supports two approaches for bypassing the central API gateway. **Regional cluster endpoints** route requests through the agent installed on the connected cluster, avoiding the central Platform gateway while still applying authentication, authorization, and audit locally. **Direct access points** expose the tenant cluster API server endpoint directly in the user's kubeconfig. Platform still controls identity, access, and lifecycle in both cases.
+
+Use these paths when round-trip latency through the central gateway is a concern, or when users need a kubeconfig that points directly to their tenant cluster. See [regional cluster endpoints](../administer/clusters/advanced/regional-cluster-endpoints.mdx) for setup.
+
+### Platform proxy
+
+Platform can proxy Kubernetes API requests through its API gateway. Users authenticate to Platform. Platform checks project and tenant cluster access. The gateway forwards the request to the connected cluster or tenant cluster API server.
+
+Use the proxy path when users should not receive connected cluster credentials or when the target cluster is only reachable from Platform or the agent. It centralizes access checks and audit records.
+
+### Tailscale network path
+
+Platform uses a Tailscale network path for environments where direct connectivity is unavailable or unreliable. Platform coordinates network peers and can relay traffic through DERP when peers cannot connect directly.
+
+This path is useful when connected clusters, tenant clusters, or users are behind NAT, firewall rules, or private networks. The agent and Platform establish the network relationship. DERP provides a relay path when peer-to-peer traffic cannot be established.
+
+For troubleshooting this path, see [tsnet connectivity](../troubleshoot/tsnet-connectivity.mdx).
+
+## Failure behavior
+
+Platform, connected cluster agents, and tenant cluster control planes fail independently of each other. Existing workloads continue running in connected clusters even when management connectivity is lost.
+
+| Condition | What continues | What is affected |
+|---|---|---|
+| Platform is unavailable | Existing tenant workloads and tenant cluster API servers continue running in connected clusters. | UI, Platform API, proxy access, lifecycle operations, and status updates are unavailable until Platform returns. |
+| Agent connection is interrupted | Existing tenant clusters and workloads continue running in the connected cluster. | Platform cannot reconcile new changes for that connected cluster until the agent reconnects. |
+| Tenant cluster API is unreachable | Platform and other tenant clusters continue operating. | Access, status, and lifecycle operations for that tenant cluster may fail until connectivity returns. |
+
+## Further reading
+
+- [Platform architecture](./architecture.mdx)
+- [Connected clusters](../understand/what-are-clusters.mdx)
+- [Projects](../understand/what-are-projects.mdx)
+- [vCluster architecture](/docs/vcluster/introduction/architecture)

platform/introduction/platform_intro.mdx

@@ -38,6 +38,8 @@ vCluster creates and runs tenant clusters. Platform manages the fleet. The relat
 
 Platform installs into a Kubernetes cluster and connects to other clusters in your environment. Those connected clusters become the Control Plane Clusters where tenant cluster control planes run. Platform doesn't replace those clusters. It manages what runs inside them.
 
+[Understand the Platform architecture →](./architecture.mdx)
+
 ## Projects
 
 Projects are the primary organizational unit in Platform. Each project is a policy boundary that groups tenant clusters and the users or teams who access them.

platform/understand/platform_communication.mdx

@@ -8,6 +8,8 @@ sidebar_label: What is vCluster-Platform Communication
 
 Several background processes run when creating a vCluster that enable communication with the platform. 
 
+For the full management plane, connected cluster, lifecycle, and network path overview, see [Platform architecture](../introduction/architecture.mdx).
+
 ## Components in vCluster-platform communication
 
 ### The platform
@@ -42,4 +44,3 @@ A bi-directional VPN tunnel then establishes secure communication between the pl
 ## Platform configuration
 
 Administrators can configure the endpoint and access key for the platform using Helm values.
-

platform/understand/what-are-clusters.mdx

@@ -2,6 +2,7 @@
 title: What are Connected Clusters
 sidebar_label: What Are Connected Clusters
 sidebar_position: 3
+description: Connected clusters are Kubernetes clusters registered with vCluster Platform, serving as the control plane clusters where tenant cluster control planes run.
 ---
 
 import ConnectedClustersDashboard from '@site/static/media/platform/screenshots/connected-clusters-agent-status.png';
@@ -10,7 +11,7 @@ A connected cluster is a Kubernetes cluster linked to vCluster Platform. It serv
 
 ## How connection works
 
-Connecting a cluster installs the vCluster Platform agent on it. The agent provides the communication layer between Platform and that cluster: tenant cluster provisioning, access control enforcement, lifecycle operations, and health monitoring. It uses an outbound connection to Platform, so no inbound firewall rules are required on the cluster.
+Connecting a cluster installs the vCluster Platform agent on it. The agent provides the communication layer between Platform and that cluster. It handles tenant cluster provisioning, access control enforcement, lifecycle operations, health monitoring, and proxy path forwarding when Platform routes requests to connected cluster or tenant cluster APIs. It uses an outbound connection to Platform, so no inbound firewall rules are required on the cluster.
 
 Once connected, the cluster appears in the Platform UI and can be assigned to projects. Members of those projects can then create tenant clusters and spaces within the cluster, scoped to their access level.
 
@@ -38,3 +39,5 @@ Platform itself runs on a Kubernetes cluster. That cluster is automatically conn
 The agent maintains a persistent outbound connection to the Platform API server. If connectivity is lost, existing tenant clusters continue running without interruption. Platform resumes full management once the connection is restored.
 
 [Connect a cluster →](../administer/clusters/connect-cluster.mdx)
+
+[Platform architecture →](../introduction/architecture.mdx)