================================================================================
ADVANCED VOICE BUTLER: GOOGLE ECOSYSTEM INTEGRATION GUIDE
================================================================================
Developed by ShaneAllen
Software Developer & Smart Home Specialist

This document outlines the technical steps to bridge the Advanced Voice Butler 
with Google Workspace and Google Cloud for real-time calendar sync, email 
routing, and travel intelligence.

--------------------------------------------------------------------------------
PHASE 1: HUBITAT CLOUD AUTHORIZATION
--------------------------------------------------------------------------------
1. Navigate to 'Apps Code' in your Hubitat web interface.
2. Select the 'Advanced Voice Butler' application.
3. Click the 'OAuth' button at the top.
4. Click 'Enable OAuth' and then 'Update'.
5. Open your app instance and go to the 'Live System Dashboard'.
6. Copy the 'Cloud Webhook URL' base (everything BEFORE /email or /calendar).

--------------------------------------------------------------------------------
PHASE 2: GENERATIVE AI (GEMINI)
--------------------------------------------------------------------------------
1. Visit Google AI Studio (aistudio.google.com) and sign in.
2. Click 'Get API key' in the left sidebar.
3. Click 'Create API key in a new project'.
4. Copy the generated key.
5. In your Butler App on Hubitat, find 'Generative AI Integration'.
6. Paste your Gemini API Key and click 'Done'.

--------------------------------------------------------------------------------
PHASE 3: MAPS PLATFORM (TRAVEL INTELLIGENCE)
--------------------------------------------------------------------------------
1. Access the Google Cloud Console (console.cloud.google.com).
2. Create a project named "Butler Intelligence."
3. Go to 'Billing' and link a payment method (to unlock the $200/mo free credit).
4. Go to the 'API Library' and enable the following:
   - Distance Matrix API
   - Places API
5. Go to 'APIs & Services' > 'Credentials' and click '+ Create Credentials'.
6. Select 'API Key', copy it, and paste it into the 'Travel & Mapping' section 
   of the Butler app on Hubitat.

--------------------------------------------------------------------------------
PHASE 4: THE INBOUND SYNC BRIDGE (GMAIL & CALENDAR)
--------------------------------------------------------------------------------
1. Go to script.google.com and click 'New Project'.
2. Replace the default code with the "Master Bridge" script.
3. IMPORTANT: Update the 'HUBITAT_BASE_URL' constant with your URL from Phase 1.
4. Click the 'Triggers' (Clock Icon) in the sidebar.
5. Click '+ Add Trigger'.
6. Set function to 'checkImportantEmails' and timer to 'Every 5 minutes'.
7. Click 'Save' and authorize the script when prompted.

--------------------------------------------------------------------------------
PHASE 5: THE OUTBOUND CALENDAR BRIDGE (WRITE ACCESS)
--------------------------------------------------------------------------------
1. Go to script.google.com and click 'New Project'.
2. Paste the 'function doPost(e)' script from the Calendar Event Creation guide.
3. Click 'Deploy' > 'New deployment'.
4. Choose 'Web app'. Set 'Execute as' to 'Me' and 'Who has access' to 'Anyone'.
5. Click 'Deploy' and copy the 'Web App URL'.
6. Paste this URL into the 'Google Apps Script Webhook URL' field in the 
   Butler's Calendar settings in Hubitat.

--------------------------------------------------------------------------------
VERIFICATION CHECKLIST
--------------------------------------------------------------------------------
[ ] API Test: Click 'Test Google API Connection' in Hubitat.
[ ] Sync Test: Add an event to Google Calendar; verify it appears on 
    the Butler Dashboard within 5 minutes.
[ ] Chat Test: Test the 'Ask the Butler' widget in the Portal Chat.
================================================================================