From 5f26de9eae2fd911477afc0fc400a82b79fb21a2 Mon Sep 17 00:00:00 2001
From: mkorwel <matt.korwel@gmail.com>
Date: Sun, 15 Mar 2026 09:54:27 -0700
Subject: [PATCH] docs(offload): implement maintainer onboarding guide and link
 from contributing

---
 CONTRIBUTING.md          | 18 ++++-----
 MAINTAINER_ONBOARDING.md | 84 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+), 10 deletions(-)
 create mode 100644 MAINTAINER_ONBOARDING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c71fbe2e22..a843f5d333 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,16 +43,14 @@ The process for contributing code is as follows:
 
 1.  **Find an issue** that you want to work on. If an issue is tagged as
     `🔒Maintainers only`, this means it is reserved for project maintainers. We
-    will not accept pull requests related to these issues. In the near future,
-    we will explicitly mark issues looking for contributions using the
-    `help-wanted` label. If you believe an issue is a good candidate for
-    community contribution, please leave a comment on the issue. A maintainer
-    will review it and apply the `help-wanted` label if appropriate. Only
-    maintainers should attempt to add the `help-wanted` label to an issue.
-2.  **Fork the repository** and create a new branch.
-3.  **Make your changes** in the `packages/` directory.
-4.  **Ensure all checks pass** by running `npm run preflight`.
-5.  **Open a pull request** with your changes.
+    will not accept pull requests related to these issues.
+2.  **Maintainer Setup**: If you are a team maintainer, please follow the
+    [Maintainer Onboarding Guide](./MAINTAINER_ONBOARDING.md) to set up your
+    high-performance remote offload environment.
+3.  **Fork the repository** and create a new branch.
+4.  **Make your changes** in the `packages/` directory.
+5.  **Ensure all checks pass** by running `npm run preflight`.
+6.  **Open a pull request** with your changes.
 
 ### Code reviews
 
diff --git a/MAINTAINER_ONBOARDING.md b/MAINTAINER_ONBOARDING.md
new file mode 100644
index 0000000000..89129f1880
--- /dev/null
+++ b/MAINTAINER_ONBOARDING.md
@@ -0,0 +1,84 @@
+# Maintainer Onboarding: High-Performance Offload System 🚀
+
+Welcome to the Gemini CLI maintainer team! This guide will help you set up your
+remote development environment, which offloads heavy tasks (reviews, fixes,
+preflight) to a dedicated GCP worker.
+
+## Prerequisites
+
+1. **Google Cloud Access**: Ensure you have access to the
+   `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.
+
+## Setup Workflow
+
+### 1. Fork & Clone
+
+Start by forking the repository and cloning it to your local machine.
+
+```bash
+gh repo fork google-gemini/gemini-cli --clone
+cd gemini-cli
+```
+
+### 2. Run the Offload Setup
+
+This interactive script will handle all the complex orchestration setup:
+
+- Configures your GCP project and compute zone.
+- Sets up a **Fast-Path SSH Alias** (`gcli-worker`) in `~/.ssh/config`.
+- Creates/Identifies your **Security Fork** for autonomous work.
+- Performs a **One-Shot Authentication** for Gemini and GitHub.
+- Pre-clones the repository to your remote worker.
+
+```bash
+npm run offload:setup
+```
+
+### 3. Provision Your Worker
+
+Once setup is configured, spin up your dedicated, high-performance VM:
+
+```bash
+npm run offload:fleet provision
+```
+
+## Daily Workflow
+
+### Offloading a PR Review
+
+To perform a deep behavioral review of a PR on your remote worker:
+
+```bash
+npm run offload <PR_NUMBER> review
+```
+
+_A new iTerm2 window will pop up, instantly connected to your worker, running
+the `review-pr` skill._
+
+### Monitoring Your Jobs
+
+View the real-time status of all your in-flight remote jobs:
+
+```bash
+npm run offload:status
+```
+
+### Stopping Your Worker
+
+To save costs, shut down your worker when you're done for the day. The
+orchestrator will automatically wake it up when you run a new task.
+
+```bash
+npm run offload:fleet stop
+```
+
+## Security Model
+
+- **Isolation**: Each maintainer has their own dedicated VM
+  (`gcli-offload-<user>`).
+- **Permissions**: The agent uses a scoped token that is read-only to the main
+  repo and read/write only to your personal fork.
+- **OS Login**: Access is managed via your Google corporate identity.