docs: add architecture for Gemini CLI Workspaces

docs/architecture/workspaces/overview.md

@@ -0,0 +1,44 @@
+# Gemini CLI Workspaces: High-Level Architecture Overview
+
+## 1. Introduction
+Gemini CLI Workspaces provides a distributed, persistent, and multi-device compute layer for `gemini-cli`. It enables developers to provision, manage, and "teleport" into remote execution environments hosted on GCP.
+
+## 2. Core Vision
+- **Persistence:** Sessions survive local device disconnects or terminal restarts.
+- **Portability:** Start a task on one device (e.g., Laptop) and seamlessly re-attach from another (e.g., Surface/Tablet).
+- **Scale:** Offload heavy compute (builds, tests, evals) to remote GCE instances.
+- **Consistency:** Pre-built container images ensure every workspace has the exact same tools and environment.
+
+## 3. High-Level Architecture
+The architecture is centered around a **Workspace Hub**, which acts as the fleet manager, and **Remote Workspaces**, which are containerized GCE VMs.
+
+```mermaid
+graph TD
+    A[Local Device: gemini-cli] -->|API Calls| B(Workspace Hub: Cloud Run)
+    A -->|SSH/IAP| C(Remote Workspace: GCE VM)
+    B -->|Provision/Monitor| C
+    B -->|State Persistence| D(Firestore)
+    C -->|Pull Image| E(Artifact Registry)
+```
+
+## 4. Multi-Tenancy Models
+The Workspace Hub is a self-service, deployable feature that supports several grains of multi-tenancy:
+
+### A. Per-User (Personal Cloud)
+- **Deployment:** Each developer deploys their own Workspace Hub in a personal GCP project.
+- **Isolation:** Absolute. All VMs and secrets belong to the individual.
+
+### B. Per-Team (Shared Infrastructure)
+- **Deployment:** A single Hub managed by a team/org.
+- **Tenancy:** Identity-based partitioning. The Hub filters instances based on the authenticated user's Google ID.
+- **Isolation:** Instances are tagged with `owner_id`. Users can only manage their own environments.
+
+### C. Per-Repository (Project Environments)
+- **Deployment:** Tied to a specific repo (e.g., for PR reviews or ephemeral test envs).
+- **Tenancy:** Project-context isolation. Users can connect to any workspace associated with the repository context.
+
+## 5. Multi-Device Portability
+Since the Workspace Hub stores the state centrally (Firestore), any device with the authenticated `gemini-cli` can:
+1.  Query the Hub for the list of active workspaces.
+2.  Initiate a connection to a remote VM started by *another* device.
+3.  Sync its local `~/.gemini` settings and GitHub PAT to ensure a consistent experience on the remote side.