docs(offload): move architectural rationale to user-facing documentation

.gemini/skills/offload/README.md

@@ -41,6 +41,17 @@ When you run `npm run offload <PR> fix`, the orchestrator provisions the remote
 environment and then launches a Gemini CLI session specifically powered by the
 `fix-pr` skill.
 
+## Architecture: The Hybrid Powerhouse
+
+The offload system uses a **Hybrid VM + Docker** architecture designed for maximum performance and reliability:
+
+1.  **The GCE VM (Raw Power)**: By running on high-performance Google Compute Engine instances, we offload heavy CPU and RAM tasks (like full project builds and massive test suites) from your local machine, keeping your primary workstation responsive.
+2.  **The Docker Container (Consistency & Resilience)**:
+    *   **Source of Truth**: The `.gcp/Dockerfile.maintainer` defines the exact environment. If a tool is added there, every maintainer gets it instantly.
+    *   **Zero Drift**: Containers are immutable. Every job starts in a fresh state, preventing the "OS rot" that typically affects persistent VMs.
+    *   **Local-to-Remote Parity**: The same image can be run locally on your Mac or remotely in GCP, ensuring that "it works on my machine" translates 100% to the remote worker.
+    *   **Safe Multi-tenancy**: Using Git Worktrees inside an isolated container environment allows multiple jobs to run in parallel without sharing state or polluting the host system.
+
 ## Playbooks
 
 -   **`review`** (default): Build, CI check, static analysis, and behavioral proofs.

.gemini/skills/offload/SKILL.md

@@ -2,7 +2,8 @@
 
 This skill provides a high-performance, parallelized workflow for offloading intensive developer tasks (PR reviews, fixing CI, preparing merges) to a remote workstation. It leverages a Node.js orchestration engine to run complex validation playbooks concurrently in a dedicated terminal window.
 
-## Playbooks
+## Performance Workflow
+
 
 The `offload` skill supports the following specialized playbooks:
 

MAINTAINER_ONBOARDING.md

@@ -10,7 +10,24 @@ preflight) to a dedicated GCP worker.
    `gemini-cli-team-quota` project.
 2. **GCloud CLI**: Authenticated locally (`gcloud auth login`).
 3. **GitHub CLI**: Authenticated locally (`gh auth login`).
-4. **iTerm2**: (Optional) For automated window popping on macOS.
+
+- **iTerm2**: (Optional) For automated window popping on macOS.
+
+## Architecture: Why this setup?
+
+The offload system uses a **Hybrid VM + Docker** architecture to balance raw
+power with environmental stability:
+
+1.  **GCE VM (Raw Power)**: High-performance machines handle the "heavy lifting"
+    (full project builds, exhaustive test suites), keeping your local primary
+    workstation responsive and cool.
+2.  **Docker (Consistency)**: All development tools (`node`, `gh`, `tsx`,
+    `vitest`) are managed via `.gcp/Dockerfile.maintainer`. This ensures every
+    maintainer works in an identical environment, eliminating "it works on my
+    machine" issues.
+3.  **Persistence + Isolation**: Tmux sessions on the host VM provide
+    persistence (surviving disconnects), while Git Worktrees and isolated Docker
+    runs ensure that multiple jobs don't interfere with each other.
 
 ## Setup Workflow