# Google Cloud Console Setup Guide

## Step 1: Create Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Sign in with your **consulting account** (this will own the OAuth app)
3. Click **Select a project** → **New Project**
4. Name: `Geoffrey Google Workspace`
5. Click **Create**

## Step 2: Enable APIs

Navigate to **APIs & Services → Library** and enable each:

### Required APIs
- [ ] Gmail API
- [ ] Google Calendar API
- [ ] Google Drive API
- [ ] Google Docs API
- [ ] Google Sheets API
- [ ] Google Slides API
- [ ] Google Forms API
- [ ] Google Chat API
- [ ] Tasks API
- [ ] People API (for user info)

### Optional APIs
- [ ] Google Keep API (limited availability)
- [ ] Gemini API (if using AI features)

**Tip:** Search for each API name and click **Enable**

## Step 3: Configure OAuth Consent Screen

1. Go to **APIs & Services → OAuth consent screen**
2. Select **External** (unless all accounts are in same org)
3. Click **Create**

### App Information
- App name: `Geoffrey`
- User support email: Your consulting email
- Developer contact: Your consulting email

### Scopes
Click **Add or Remove Scopes** and add:

```
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/presentations
https://www.googleapis.com/auth/forms.body
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/tasks
https://www.googleapis.com/auth/userinfo.email
```

### Test Users
Add all three email addresses:
- Your PSD email
- Your personal email
- Your consulting email

**Note:** While in "Testing" mode, only these users can authorize.

## Step 4: Create OAuth Credentials

1. Go to **APIs & Services → Credentials**
2. Click **Create Credentials → OAuth client ID**
3. Application type: **Desktop app**
4. Name: `Geoffrey CLI`
5. Click **Create**
6. Copy the **Client ID** and **Client Secret**
7. Add to your iCloud secrets `.env` file:
   ```
   ~/Library/Mobile Documents/com~apple~CloudDocs/Geoffrey/secrets/.env
   ```

   Add these lines:
   ```
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   ```

## Step 5: PSD Domain Allowlisting

Your PSD Google Workspace likely restricts third-party apps. To allow Geoffrey:

### If You're a Google Admin:

1. Go to [Google Admin Console](https://admin.google.com)
2. Navigate to **Security → Access and data control → API controls**
3. Click **Manage Third-Party App Access**
4. Click **Add app → OAuth App Name Or Client ID**
5. Enter your OAuth Client ID (from Step 4)
6. Select **Trusted** access

### If You Need IT Approval:

Send this to your IT team:

```
Subject: Request to Allow OAuth App for Personal Productivity Tool

I need to allowlist a personal productivity app that integrates with Google Workspace.

OAuth Client ID: [YOUR_CLIENT_ID_HERE]

Requested scopes:
- Gmail (read/send)
- Calendar (read/write)
- Drive (read/write)
- Docs/Sheets/Slides (read/write)
- Tasks (read/write)

This is a local CLI tool that runs only on my machine.
No data is sent to external servers.

Please add this client ID to the trusted apps list.
```

## Step 6: Authenticate Each Account

Once credentials are in your .env:

```bash
cd skills/google-workspace

# Install dependencies
bun install

# Authenticate each account
bun auth/oauth_setup.js psd    # Will open browser, sign in with PSD account
bun auth/oauth_setup.js kh     # Will open browser, sign in with personal account
bun auth/oauth_setup.js hrg    # Will open browser, sign in with consulting account

# After each auth, store the tokens (copy the JSON output from oauth_setup)
bun auth/token_manager.js store psd '<tokens-json-output>'
bun auth/token_manager.js store kh '<tokens-json-output>'
bun auth/token_manager.js store hrg '<tokens-json-output>'
```

## Step 7: Verify Setup

```bash
# List stored accounts
bun auth/token_manager.js list

# Test token retrieval
bun auth/token_manager.js get psd
```

## Troubleshooting

### "Access blocked: This app's request is invalid"
- Check that redirect URI matches: `http://localhost:3000/oauth2callback`
- Verify OAuth consent screen is configured

### "Access denied" for PSD account
- App needs to be allowlisted in PSD Google Admin
- Contact IT with the client ID

### "Refresh token is null"
- Delete the app from your Google account's connected apps
- Re-run oauth_setup.js with the account
- The `prompt: 'consent'` should force a new refresh token

### Token expires quickly
- Access tokens last 1 hour
- token_manager.js auto-refreshes using the refresh token
- Refresh tokens don't expire unless revoked

## Security Notes

- Credentials stored in iCloud secrets `.env` (synced, but local to your devices)
- Tokens stored in macOS Keychain (encrypted)
- Each account has its own isolated tokens
- Revoke access anytime from Google Account → Security → Third-party apps