Source: data_layer/docs/GOOGLE_DRIVE_SETUP.md

Google Drive Sync Setup Guide

Date: October 18, 2025 Purpose: Enable non-technical stakeholders to browse prompt documentation in Google Drive

🎯 Overview

The Google Drive sync system automatically uploads enriched prompt documentation to Google Drive, making it accessible to business teams, stakeholders, and non-technical users who need to understand available prompts, workflows, and contracts.

Benefits:

✅ Non-technical teams can browse prompts without command line access
✅ Comment and discuss prompts directly in Google Docs
✅ Search across all prompts using Google Drive search
✅ Access from mobile devices and web browsers
✅ Share specific prompts with external partners
✅ Track who's viewing which prompts

📋 Prerequisites

1. Google Cloud Project Setup

You need a Google Cloud project with Drive API enabled:

# 1. Go to Google Cloud Console
https://console.cloud.google.com/
 
# 2. Create a new project or select existing
# 3. Enable Google Drive API
https://console.cloud.google.com/apis/library/drive.googleapis.com
 
# 4. Create a service account
# Go to: IAM & Admin > Service Accounts > Create Service Account
# Name: "altsports-prompt-sync"
# Description: "Service account for syncing prompt docs to Drive"
 
# 5. Create and download JSON key
# Click on the service account > Keys > Add Key > Create New Key > JSON
# Save as: credentials/google-drive-service-account.json

2. Python Packages

Install required Google Drive packages:

pip install google-auth google-api-python-client

Or add to your requirements.txt:

google-auth>=2.23.0
google-api-python-client>=2.100.0

3. Environment Variables

Set up environment variables:

# Add to .env file
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials/google-drive-service-account.json"
 
# Optional: Specify existing Drive folder ID
export DRIVE_FOLDER_ID="your-folder-id-here"

🚀 Quick Start

First Time Setup

# 1. Set credentials path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
 
# 2. Run sync
python data_layer/scripts/sync_to_drive.py
 
# Output:
# ✅ Connected to Google Drive API
# 📁 Creating root folder: AltSports Prompt Library
# ✅ Created root folder: abc123xyz
# 📁 Creating folder structure...
#    ✅ Agent (created)
#    ✅ Workflow (created)
#    ✅ Contract Template (created)
#    ... etc
# ✅ Synced: specs.contracts.tier-1-partnership
# ... (116 files synced)
#
# ============================================================
# SYNC SUMMARY
# ============================================================
# ✅ Synced: 116
# ⏭️  Skipped: 0
# ❌ Errors: 0
# 📁 Total: 116
# ============================================================
#
# 📂 View in Google Drive:
#    https://drive.google.com/drive/folders/abc123xyz

Subsequent Syncs

The script automatically detects changes and only syncs modified files:

python data_layer/scripts/sync_to_drive.py
 
# Only changed files will be synced
# ⏭️  Skipped (up to date): specs.contracts.tier-1-partnership
# ✅ Synced: specs.contracts.tier-2-partnership  # (modified)

Force Re-sync All Files

python data_layer/scripts/sync_to_drive.py --force

Check Sync Status

python data_layer/scripts/sync_to_drive.py --stats
 
# Output:
# 📊 Sync Statistics
#
# Total Prompts: 116
# Synced Files: 116
# Folders: 6
# Last Sync: 2025-10-18T10:30:45.123456
#
# 📂 View in Drive:
#    https://drive.google.com/drive/folders/abc123xyz

📁 Drive Folder Structure

After sync, your Google Drive will have this structure:

📂 AltSports Prompt Library/
   ├── 📂 Agent/                    (25 files)
   │   ├── altsportsdata.1-email-handler.md
   │   ├── altsportsdata.10-email-classifier.md
   │   └── ... (23 more agent docs)
   │
   ├── 📂 Workflow/                 (22 files)
   │   ├── workflows.email-to-contract-pipeline.md
   │   ├── workflows.league-onboarding.md
   │   └── ... (20 more workflow docs)
   │
   ├── 📂 Contract Template/        (20 files)
   │   ├── specs.contracts.tier-1-partnership.md
   │   ├── specs.contracts.tier-2-partnership.md
   │   └── ... (18 more contract templates)
   │
   ├── 📂 Legal Template/           (3 files)
   │   ├── legal.confidentiality-agreement.md
   │   └── ... (2 more legal templates)
   │
   ├── 📂 Component/                (4 files)
   │   └── ... (component docs)
   │
   └── 📂 General/                  (42 files)
       └── ... (general prompt docs)

🔐 Sharing and Permissions

Share with Team Members

# Option 1: Share via Google Drive UI
# 1. Go to the Drive folder
# 2. Right-click > Share
# 3. Add team members' email addresses
# 4. Set permission level (Viewer, Commenter, Editor)
 
# Option 2: Make folder viewable by anyone with link
# (Good for internal company access)
# 1. Right-click folder > Share > Get link
# 2. Change to "Anyone with the link" > Viewer
# 3. Copy link and share with team

Recommended Permission Levels

Business Teams: Viewer (can read, search, comment)
Product Managers: Commenter (can suggest changes)
Tech Writers: Editor (can update docs if needed)
External Partners: Viewer on specific folders only

🔄 Sync State Management

Sync State File

The sync system maintains state in:

data_layer/storage/prompts/drive_sync/sync_registry.json

Contents:

{
  "root_folder_id": "abc123xyz",
  "folder_mapping": {
    "agent": "folder-id-1",
    "workflow": "folder-id-2",
    "contract_template": "folder-id-3",
    "legal_template": "folder-id-4",
    "component": "folder-id-5",
    "general": "folder-id-6"
  },
  "file_mapping": {
    "specs.contracts.tier-1-partnership": {
      "drive_id": "file-id-123",
      "local_path": "data_layer/storage/prompts/docs/contract_template/specs.contracts.tier-1-partnership.md",
      "last_synced": "2025-10-18T10:30:45.123456",
      "file_size": 12345
    }
  },
  "last_sync": "2025-10-18T10:30:45.123456",
  "total_synced": 116
}

Registry Updates

After sync, the prompt registry is updated with Drive IDs:

{
  "id": "specs.contracts.tier-1-partnership",
  "drive_id": "file-id-123",
  "last_synced": "2025-10-18T10:30:45.123456",
  ...
}

🛠️ Troubleshooting

Error: Credentials not found

❌ Google credentials not found
   Set GOOGLE_APPLICATION_CREDENTIALS environment variable

Solution:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"

Error: Permission denied

❌ Failed to initialize Drive service: insufficient permissions

Solution:

Ensure Drive API is enabled in Google Cloud Console
Verify service account has correct permissions
Re-download service account JSON key if needed

Error: Folder not found

⚠️  Previous root folder not found, creating new one

This is usually fine - The script will create a new folder. However, if you want to reuse an existing folder:

# Set the folder ID as environment variable
export DRIVE_FOLDER_ID="your-existing-folder-id"

Files not syncing

# Check sync state
python data_layer/scripts/sync_to_drive.py --stats
 
# Force re-sync
python data_layer/scripts/sync_to_drive.py --force

🔧 Advanced Configuration

Use Existing Drive Folder

Instead of creating a new folder, you can sync to an existing one:

# 1. Get the folder ID from the URL
# https://drive.google.com/drive/folders/ABC123XYZ
# Folder ID = ABC123XYZ
 
# 2. Set environment variable
export DRIVE_FOLDER_ID="ABC123XYZ"
 
# 3. Run sync
python data_layer/scripts/sync_to_drive.py

Custom Credentials Path

python data_layer/scripts/sync_to_drive.py --credentials /path/to/creds.json

Integration with CI/CD

Add to your deployment pipeline:

# .github/workflows/sync-prompts.yml
name: Sync Prompts to Drive
 
on:
  push:
    paths:
      - 'data_layer/prompts/**'
 
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
 
      - name: Install dependencies
        run: |
          pip install google-auth google-api-python-client
 
      - name: Sync to Drive
        env:
          GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.DRIVE_CREDENTIALS }}
        run: |
          python data_layer/scripts/sync_to_drive.py

📊 Usage Patterns

Daily Development Workflow

# 1. Edit prompt files
vim data_layer/prompts/specs/contracts/tier_1_partnership.md
 
# 2. Rebuild registry
python data_layer/scripts/scan_prompts.py
 
# 3. Regenerate docs
python data_layer/scripts/generate_prompt_docs.py
 
# 4. Sync to Drive
python data_layer/scripts/sync_to_drive.py
 
# Only changed files will be synced

Weekly Review Workflow

# 1. Check sync status
python data_layer/scripts/sync_to_drive.py --stats
 
# 2. Force full sync if needed
python data_layer/scripts/sync_to_drive.py --force
 
# 3. Share Drive link with team for review

Release Workflow

# Before major release
python data_layer/scripts/sync_to_drive.py --force
 
# This ensures all stakeholders have latest docs

🎉 What's Next?

After Google Drive sync is working:

Share with stakeholders - Give team members access to the Drive folder
Set up LangMem indexing - Enable semantic search for AI system
Update prompt builder - Integrate registry-based retrieval
Track usage metrics - Monitor which prompts are most viewed/used

Next Phase: LangMem Indexing

# Coming next: Phase 4
python data_layer/scripts/index_prompts.py

📚 Resources

Google Drive API Docs: https://developers.google.com/drive/api/v3/about-sdk (opens in a new tab)
Service Account Setup: https://cloud.google.com/iam/docs/creating-managing-service-accounts (opens in a new tab)
Python Client Library: https://github.com/googleapis/google-api-python-client (opens in a new tab)

Last Updated: October 18, 2025 System Version: 1.0.0 Status: ✅ Ready for Use

Few-Shot Examples Restructuring - Execution Plan GraphQL SDL Migration Analysis