diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..5c44913
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,81 @@
+# BoringOS environment variables. Copy to `.env.local` for local
+# development (`.env.local` is git-ignored). The framework reads
+# the same names in `pnpm dev` and in production.
+
+# ─────────────────────────────────────────────────────────────────
+# Core
+# ─────────────────────────────────────────────────────────────────
+
+# Dev-server HTTP port. The shell SPA on 5174 proxies /api/* here.
+# PORT=3030
+
+# Embedded Postgres port. Only used when `database.embedded = true`.
+# PG_PORT=5436
+
+# External Postgres URL. When set, `database.embedded` is ignored
+# and the framework connects to this DB instead.
+# DATABASE_URL=postgres://user:pass@host:5432/boringos
+
+# Auth signing secret for the callback JWT and OAuth state. A random
+# secret is generated per boot when unset; set this in production
+# so issued tokens survive restarts.
+# AUTH_SECRET=
+
+# Shell SPA origin used for OAuth redirect-allowlisting and shell
+# links inside emails. Defaults to http://localhost:5174 in dev.
+# BORINGOS_SHELL_URL=http://localhost:5174
+
+# ─────────────────────────────────────────────────────────────────
+# Connectors — each one is OPTIONAL. The connector module no-ops
+# when its env vars are absent.
+# ─────────────────────────────────────────────────────────────────
+
+# Google OAuth client (Gmail + Calendar).
+# Setup walkthrough: docs/setup/google.md
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# Slack signing secret (Events API).
+SLACK_SIGNING_SECRET=
+# SLACK_BOT_TOKEN=
+
+# ─────────────────────────────────────────────────────────────────
+# Memory & infra (optional)
+# ─────────────────────────────────────────────────────────────────
+
+# Hebbs long-term memory provider. When unset the framework uses
+# the file-based Drive memory (sufficient for local dev).
+# HEBBS_ENDPOINT=
+# HEBBS_API_KEY=
+# HEBBS_WORKSPACE=
+
+# Resend API key for transactional email (invitations, alerts).
+# Email notifications are silently disabled when unset.
+# RESEND_API_KEY=
+# NOTIFICATION_FROM_EMAIL=noreply@boringos.dev
+
+# Redis URL for the BullMQ queue. When unset the framework uses
+# the in-process queue (fine for single-node dev).
+# REDIS_URL=redis://localhost:6379
+
+# ─────────────────────────────────────────────────────────────────
+# Module signing (production hosts)
+# ─────────────────────────────────────────────────────────────────
+
+# Allowlisted module publisher keys (JSON array of {keyId, publicKey}).
+# Dev hosts can set HEBBS_DEV_MODULES=true to accept unsigned uploads.
+# HEBBS_MODULE_PUBLISHERS=[]
+# HEBBS_DEV_MODULES=true
+
+# Override the on-disk module store directory. Defaults to
+# `<cwd>/.data/module-store/`.
+# MODULES_STORE_DIR=
+
+# ─────────────────────────────────────────────────────────────────
+# Demo / testing
+# ─────────────────────────────────────────────────────────────────
+
+# Replace every Claude run with a deterministic canned reply. Useful
+# for CI runs, screenshots, and local development without API keys.
+# BORINGOS_DEMO_FAKE_AI=1
+# BORINGOS_DEMO_FAKE_AI_REPLY="Hello from demo mode."
diff --git a/.gitignore b/.gitignore
index ac685e8..4ae2106 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@ dist/
 .env
 .env.local
 .env.*
+!.env.example
 *.log
 .DS_Store
 .turbo/
diff --git a/README.md b/README.md
index 9a7ba67..634aab4 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,7 @@ embedded Postgres, and start the shell on `http://localhost:3000`.
 ```bash
 git clone https://github.com/BoringOS-dev/boringos.git
 cd boringos
+cp .env.example .env.local   # fill in any connectors you want to use
 pnpm install
 pnpm -r build
 pnpm dev
@@ -208,6 +209,12 @@ pnpm dev
 
 Then open `http://localhost:3000`.
 
+`.env.example` documents every env var the framework reads. Most
+are optional — Google + Slack connectors no-op when their secrets
+are absent, embedded Postgres boots when `DATABASE_URL` is unset.
+See [`docs/setup/google.md`](docs/setup/google.md) for the
+Gmail + Calendar setup walkthrough.
+
 ### Scaffold your own host
 
 ```bash
@@ -256,48 +263,13 @@ For the step-by-step guide, see
 ## Connecting Google (Gmail + Calendar)
 
 The `@boringos/connector-google` Module needs an OAuth client.
-Two minutes in Google Cloud Console, then two env vars.
-
-### 1. Google Cloud Console
-
-[`console.cloud.google.com`](https://console.cloud.google.com)
-
-1. **Create a project** (or pick an existing one).
-2. **Enable APIs** — `APIs & Services` → `Library`:
-   - Gmail API
-   - Google Calendar API
-3. **OAuth consent screen** — `APIs & Services` → `OAuth consent screen`:
-   - User type: `External` (or `Internal` if you're on Workspace)
-   - Add your email as a test user while in `Testing` status
-   - Add these scopes:
-     - `https://www.googleapis.com/auth/gmail.modify`
-     - `https://www.googleapis.com/auth/gmail.send`
-     - `https://www.googleapis.com/auth/calendar`
-     - `https://www.googleapis.com/auth/calendar.events`
-4. **Create OAuth 2.0 Client** — `APIs & Services` → `Credentials`
-   → `Create credentials` → `OAuth client ID`:
-   - Application type: `Web application`
-   - Authorized JavaScript origins: `http://localhost:3000`
-   - Authorized redirect URIs:
-     `http://localhost:3000/api/connectors/oauth/google/callback`
-5. Copy the **Client ID** and **Client secret**.
-
-### 2. Environment variables
-
-Drop these in `.env.local` at the repo root:
-
-```bash
-GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
-GOOGLE_CLIENT_SECRET=your-client-secret
-```
-
-Restart `pnpm dev`, head to the shell's **Connectors** screen,
-click **Connect Google**, and finish the OAuth flow. Gmail and
-Calendar tools are now available to every agent in that tenant.
+Two minutes in Google Cloud Console, then two env vars in
+`.env.local` (`GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`).
 
-> For production hosts, swap `http://localhost:3000` for your
-> public origin everywhere above and publish your OAuth consent
-> screen.
+See [`docs/setup/google.md`](docs/setup/google.md) for the
+step-by-step Cloud Console walkthrough, the exact OAuth scopes
+to request, and the production-host notes. [`.env.example`](.env.example)
+lists every env var the framework reads alongside Google's.
 
 ---
 
diff --git a/docs/INDEX.md b/docs/INDEX.md
index c04643b..507fc9f 100644
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -11,6 +11,8 @@ want them.
   Module in 60 seconds.
 - [`CLAUDE.md`](../CLAUDE.md) — orientation for contributors
   (humans + AI). Mental model, monorepo layout, non-obvious behavior.
+- [`docs/setup/google.md`](setup/google.md) — Gmail + Calendar
+  OAuth setup (Cloud Console + env vars).
 
 ## Build a Module
 
diff --git a/docs/setup/google.md b/docs/setup/google.md
new file mode 100644
index 0000000..df14899
--- /dev/null
+++ b/docs/setup/google.md
@@ -0,0 +1,78 @@
+# Connecting Google (Gmail + Calendar)
+
+The `@boringos/connector-google` Module needs an OAuth client.
+Two minutes in Google Cloud Console, then two env vars.
+
+> If you got here from the [README](../../README.md) quickstart,
+> you should already have `pnpm dev` running on
+> `http://localhost:3000`. Come back to this doc once those steps
+> are done — the OAuth callback won't resolve otherwise.
+
+---
+
+## 1. Google Cloud Console
+
+[`console.cloud.google.com`](https://console.cloud.google.com)
+
+1. **Create a project** (or pick an existing one).
+2. **Enable APIs** — `APIs & Services` → `Library`:
+   - Gmail API
+   - Google Calendar API
+3. **OAuth consent screen** — `APIs & Services` → `OAuth consent screen`:
+   - User type: `External` (or `Internal` if you're on Workspace)
+   - Add your email as a test user while in `Testing` status
+   - Add these scopes:
+     - `https://www.googleapis.com/auth/gmail.modify`
+     - `https://www.googleapis.com/auth/gmail.send`
+     - `https://www.googleapis.com/auth/calendar`
+     - `https://www.googleapis.com/auth/calendar.events`
+4. **Create OAuth 2.0 Client** — `APIs & Services` → `Credentials`
+   → `Create credentials` → `OAuth client ID`:
+   - Application type: `Web application`
+   - Authorized JavaScript origins: `http://localhost:3000`
+   - Authorized redirect URIs:
+     `http://localhost:3000/api/connectors/oauth/google/callback`
+5. Copy the **Client ID** and **Client secret**.
+
+## 2. Environment variables
+
+Drop these in `.env.local` at the repo root (copy
+[`.env.example`](../../.env.example) if you haven't already):
+
+```bash
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+Restart `pnpm dev`, head to the shell's **Connectors** screen,
+click **Connect Google**, and finish the OAuth flow. Gmail and
+Calendar tools are now available to every agent in that tenant.
+
+## 3. Production hosts
+
+Swap `http://localhost:3000` for your public origin everywhere
+in step 1 (both JavaScript origins and the redirect URI), publish
+the OAuth consent screen, and set the same two env vars in your
+deployment environment.
+
+---
+
+## Troubleshooting
+
+**`redirect_uri_mismatch` after clicking Connect.** The redirect
+URI in your OAuth client must match the framework's callback
+exactly: `<BORINGOS_SHELL_URL or http://localhost:3000>/api/connectors/oauth/google/callback`.
+If you run the shell on a different host (e.g. behind a reverse
+proxy), update both the Cloud Console entry **and** the
+`BORINGOS_SHELL_URL` env var so the redirect resolves.
+
+**`access_denied` mid-flow.** While the consent screen is in
+`Testing` status, only emails you added under "Test users" can
+finish the flow. Either add your address there or move the
+consent screen to `In production`.
+
+**Gmail returns `403 insufficientPermissions` when the agent runs.**
+The OAuth scopes were not requested at consent time. Disconnect
+the connector in the shell, re-add the missing scopes in the
+Cloud Console under `OAuth consent screen → Scopes`, then
+reconnect.
diff --git a/packages/@boringos/connector-google/README.md b/packages/@boringos/connector-google/README.md
index f5c919e..4f22226 100644
--- a/packages/@boringos/connector-google/README.md
+++ b/packages/@boringos/connector-google/README.md
@@ -8,6 +8,16 @@ Google Workspace connector for BoringOS -- Gmail and Calendar integration with O
 npm install @boringos/connector-google
 ```
 
+## Setup
+
+The connector needs an OAuth 2.0 client from the Google Cloud
+Console. The full walkthrough -- which scopes to request, the
+exact callback URI, and the production-host checklist -- lives
+at [`docs/setup/google.md`](../../../docs/setup/google.md) in the
+framework repo. Two env vars on the host (`GOOGLE_CLIENT_ID` and
+`GOOGLE_CLIENT_SECRET`) and the `Connect Google` button in the
+shell's Connectors screen does the rest.
+
 ## Usage
 
 ```typescript