aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/db-supabase-setup.md

@@ -1,712 +1,712 @@
-# Task: Supabase Setup Guide
-
-**Purpose**: Interactive guide to set up Supabase project with best practices
-
-**Elicit**: true
-
----
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: dbSupabaseSetup()
-responsável: Dara (Sage)
-responsavel_type: Agente
-atomic_layer: Organism
-
-**Entrada:**
-- campo: query
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Valid SQL query
-
-- campo: params
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Query parameters
-
-- campo: connection
-  tipo: object
-  origem: config
-  obrigatório: true
-  validação: Valid PostgreSQL connection via Supabase
-
-**Saída:**
-- campo: query_result
-  tipo: array
-  destino: Memory
-  persistido: false
-
-- campo: records_affected
-  tipo: number
-  destino: Return value
-  persistido: false
-
-- campo: execution_time
-  tipo: number
-  destino: Memory
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Database connection established; query syntax valid
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check database connection established; query syntax valid
-    error_message: "Pre-condition failed: Database connection established; query syntax valid"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Query executed; results returned; transaction committed
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify query executed; results returned; transaction committed
-    error_message: "Post-condition failed: Query executed; results returned; transaction committed"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Data persisted correctly; constraints respected; no orphaned data
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert data persisted correctly; constraints respected; no orphaned data
-    error_message: "Acceptance criterion not met: Data persisted correctly; constraints respected; no orphaned data"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** neo4j-driver
-  - **Purpose:** Neo4j database connection and query execution
-  - **Source:** npm: neo4j-driver
-
-- **Tool:** query-validator
-  - **Purpose:** Cypher query syntax validation
-  - **Source:** .aios-core/utils/db-query-validator.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** db-query.js
-  - **Purpose:** Execute Neo4j queries with error handling
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/db-query.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Connection Failed
-   - **Cause:** Unable to connect to Neo4j database
-   - **Resolution:** Check connection string, credentials, network
-   - **Recovery:** Retry with exponential backoff (max 3 attempts)
-
-2. **Error:** Query Syntax Error
-   - **Cause:** Invalid Cypher query syntax
-   - **Resolution:** Validate query syntax before execution
-   - **Recovery:** Return detailed syntax error, suggest fix
-
-3. **Error:** Transaction Rollback
-   - **Cause:** Query violates constraints or timeout
-   - **Resolution:** Review query logic and constraints
-   - **Recovery:** Automatic rollback, preserve data integrity
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-15 min (estimated)
-cost_estimated: $0.003-0.010
-token_usage: ~3,000-10,000 tokens
-```
-
-**Optimization Notes:**
-- Break into smaller workflows; implement checkpointing; use async processing where possible
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - database
-  - infrastructure
-updated_at: 2025-11-17
-```
-
----
-
-
-## Overview
-
-This task guides you through setting up a new Supabase project with optimal configuration and DB Sage integration.
-
----
-
-## Process
-
-### 1. Prerequisites Check
-
-Verify required tools:
-
-```bash
-echo "Checking prerequisites..."
-
-# Check Supabase CLI
-if command -v supabase >/dev/null 2>&1; then
-  echo "✓ Supabase CLI: $(supabase --version)"
-else
-  echo "❌ Supabase CLI not installed"
-  echo "   Install: https://supabase.com/docs/guides/cli"
-  exit 1
-fi
-
-# Check psql
-if command -v psql >/dev/null 2>&1; then
-  echo "✓ psql: $(psql --version)"
-else
-  echo "⚠️  psql not found (optional but recommended)"
-fi
-
-# Check git
-if command -v git >/dev/null 2>&1; then
-  echo "✓ git: $(git --version)"
-else
-  echo "⚠️  git not found (recommended for version control)"
-fi
-
-echo ""
-```
-
-### 2. Choose Setup Path
-
-Present options:
-
-```
-Supabase Setup Options:
-
-1. NEW PROJECT - Create new Supabase project from scratch
-2. EXISTING PROJECT - Link to existing Supabase project
-3. LOCAL ONLY - Set up local development environment only
-
-Select option (1/2/3):
-```
-
-### 3a. New Project Path
-
-If option 1 selected:
-
-```bash
-echo "Creating new Supabase project..."
-
-# Login to Supabase
-echo "Step 1: Login to Supabase"
-supabase login
-
-# Create project
-echo ""
-echo "Step 2: Create project on Supabase dashboard"
-echo "  → Go to: https://supabase.com/dashboard"
-echo "  → Click 'New Project'"
-echo "  → Enter details:"
-read -p "    Project name: " PROJECT_NAME
-read -p "    Organization: " ORG_NAME
-read -p "    Region (default: us-east-1): " REGION
-REGION=${REGION:-us-east-1}
-read -sp "    Database password (strong!): " DB_PASSWORD
-echo ""
-
-echo ""
-echo "✓ Project created on dashboard"
-echo "  Wait 2-3 minutes for provisioning..."
-read -p "  Press Enter when ready..."
-```
-
-### 3b. Existing Project Path
-
-If option 2 selected:
-
-```bash
-echo "Linking existing Supabase project..."
-
-# List projects
-echo "Your Supabase projects:"
-supabase projects list
-
-read -p "Enter project reference ID: " PROJECT_REF
-
-# Link project
-supabase link --project-ref "$PROJECT_REF"
-
-echo "✓ Project linked"
-```
-
-### 3c. Local Only Path
-
-If option 3 selected:
-
-```bash
-echo "Setting up local Supabase environment..."
-
-# Initialize local setup
-supabase init
-
-# Start local Supabase
-echo "Starting local Supabase (Docker required)..."
-supabase start
-
-echo "✓ Local Supabase running"
-echo "  Studio: http://localhost:54323"
-echo "  API: http://localhost:54321"
-```
-
-### 4. Initialize DB Sage Structure
-
-Create recommended folder structure:
-
-```bash
-echo "Initializing DB Sage project structure..."
-
-# Run db-bootstrap task internally
-mkdir -p supabase/{migrations,seeds,tests,rollback,docs,snapshots}
-
-# Create .env.local (gitignored)
-cat > .env.local << 'EOF'
-# Supabase Configuration
-# DO NOT COMMIT THIS FILE
-
-# Project Details
-SUPABASE_PROJECT_ID={project_ref}
-SUPABASE_PROJECT_NAME={project_name}
-
-# Database URLs
-# Connection pooler (port 6543) for serverless/edge functions
-SUPABASE_DB_URL_POOLER=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:6543/postgres
-
-# Direct connection (port 5432) for migrations
-SUPABASE_DB_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:5432/postgres
-
-# API Keys
-SUPABASE_URL=https://[PROJECT_REF].supabase.co
-SUPABASE_ANON_KEY=[ANON_KEY]
-SUPABASE_SERVICE_ROLE_KEY=[SERVICE_ROLE_KEY]
-EOF
-
-echo "✓ DB Sage structure created"
-echo "✓ .env.local template created (UPDATE WITH YOUR KEYS!)"
-```
-
-### 5. Configure .gitignore
-
-Ensure sensitive files are not committed:
-
-```bash
-echo "Configuring .gitignore..."
-
-cat >> .gitignore << 'EOF'
-
-# Supabase
-.env.local
-.env.production
-supabase/.branches
-supabase/.temp
-supabase/snapshots/*.sql
-supabase/rollback/*.sql
-
-# DB Sage
-/tmp/dbsage_*
-*.dump
-*.backup
-EOF
-
-echo "✓ .gitignore updated"
-```
-
-### 6. Set Up Environment Variables
-
-Guide user through configuration:
-
-```
-Setting up environment variables...
-
-1. Get your project keys from Supabase Dashboard:
-   → https://supabase.com/dashboard/project/{project_ref}/settings/api
-
-2. Update .env.local with:
-   - Database password
-   - Project reference ID
-   - Anon key
-   - Service role key (keep secret!)
-
-3. Source the file:
-   source .env.local
-
-4. Verify connection:
-   psql "$SUPABASE_DB_URL" -c "SELECT version();"
-
-Press Enter when complete...
-```
-
-### 7. Apply Initial Schema
-
-Create baseline schema:
-
-```bash
-echo "Setting up initial schema..."
-
-# Check if migrations exist
-if [ -z "$(ls -A supabase/migrations 2>/dev/null)" ]; then
-  echo "No migrations found."
-  echo "Options:"
-  echo "  1. Generate schema from design document"
-  echo "  2. Import existing schema"
-  echo "  3. Skip (will create later)"
-  read -p "Select option (1/2/3): " SCHEMA_OPTION
-
-  if [ "$SCHEMA_OPTION" = "1" ]; then
-    # Use domain modeling task
-    echo "→ Run: *model-domain to create schema"
-  elif [ "$SCHEMA_OPTION" = "2" ]; then
-    read -p "Path to existing schema SQL file: " SCHEMA_FILE
-    cp "$SCHEMA_FILE" "supabase/migrations/$(date +%Y%m%d%H%M%S)_initial_schema.sql"
-    echo "✓ Migration file created"
-  fi
-else
-  echo "✓ Migrations directory already has files"
-fi
-```
-
-### 8. Enable Recommended Extensions
-
-Install useful PostgreSQL extensions:
-
-```bash
-echo "Enabling recommended extensions..."
-
-psql "$SUPABASE_DB_URL" << 'EOF'
--- Core extensions
-CREATE EXTENSION IF NOT EXISTS "uuid-ossp";      -- UUID generation
-CREATE EXTENSION IF NOT EXISTS "pgcrypto";       -- Encryption functions
-CREATE EXTENSION IF NOT EXISTS "pg_stat_statements";  -- Query performance tracking
-
--- Supabase extensions
-CREATE EXTENSION IF NOT EXISTS "pgjwt";          -- JWT functions
-CREATE EXTENSION IF NOT EXISTS "pg_net";         -- HTTP client
-
--- Optional: Full-text search
-CREATE EXTENSION IF NOT EXISTS "pg_trgm";        -- Trigram matching
-
--- Optional: PostGIS (if using geospatial data)
--- CREATE EXTENSION IF NOT EXISTS "postgis";
-
-SELECT 'Extensions enabled' AS status;
-EOF
-
-echo "✓ Extensions enabled"
-```
-
-### 9. Configure Database Settings
-
-Apply recommended settings:
-
-```bash
-echo "Applying recommended database settings..."
-
-psql "$SUPABASE_DB_URL" << 'EOF'
--- Performance settings (adjust based on your tier)
--- These are set at session level - for permanent changes, use Supabase dashboard
-
--- Enable auto_explain for slow queries (dev only)
--- ALTER SYSTEM SET auto_explain.log_min_duration = 1000;  -- Log queries > 1s
--- ALTER SYSTEM SET auto_explain.log_analyze = on;
-
--- Work memory for complex queries
-SET work_mem = '16MB';
-
--- Statement timeout to prevent runaway queries
-SET statement_timeout = '30s';
-
--- Lock timeout to prevent long lock waits
-SET lock_timeout = '10s';
-
-SELECT 'Settings configured' AS status;
-EOF
-
-echo "✓ Database settings configured"
-echo "  (For permanent settings, use Supabase Dashboard → Database → Settings)"
-```
-
-### 10. Set Up Development Workflow
-
-Configure recommended workflow:
-
-```bash
-echo "Setting up development workflow..."
-
-# Create helpful scripts
-mkdir -p scripts
-
-cat > scripts/db-connect.sh << 'EOF'
-#!/bin/bash
-# Connect to Supabase database
-source .env.local
-psql "$SUPABASE_DB_URL"
-EOF
-
-cat > scripts/db-reset-local.sh << 'EOF'
-#!/bin/bash
-# Reset local Supabase database
-supabase db reset
-EOF
-
-chmod +x scripts/*.sh
-
-echo "✓ Helper scripts created in scripts/"
-```
-
----
-
-## Output
-
-Display setup summary:
-
-```
-✅ SUPABASE SETUP COMPLETE
-
-Project: {project_name}
-Region: {region}
-Status: Ready for development
-
-Environment:
-✓ Supabase CLI configured
-✓ Project linked/created
-✓ DB Sage structure initialized
-✓ Extensions enabled
-✓ .env.local created (REMEMBER TO UPDATE!)
-
-Folder Structure:
-supabase/
-├── migrations/    # Database migrations
-├── seeds/         # Seed data
-├── tests/         # SQL tests
-├── docs/          # Documentation
-└── snapshots/     # Backup snapshots
-
-Next Steps:
-1. Update .env.local with your keys
-2. Test connection: psql "$SUPABASE_DB_URL"
-3. Design your schema: *model-domain
-4. Create first migration: *create-migration
-5. Set up RLS policies: *create-rls-policies
-
-Useful Commands:
-- Connect to DB: ./scripts/db-connect.sh
-- Create migration: supabase migration new {name}
-- Push changes: supabase db push
-- Pull remote: supabase db pull
-
-Documentation:
-- Supabase Docs: https://supabase.com/docs
-- DB Sage Guide: docs/architecture/db-sage/README.md
-```
-
----
-
-## Common Next Steps
-
-### 1. Create Initial Schema
-
-```bash
-# Option A: Interactive modeling
-*model-domain
-
-# Option B: Create migration manually
-supabase migration new initial_schema
-# Edit: supabase/migrations/{timestamp}_initial_schema.sql
-```
-
-### 2. Set Up Row Level Security
-
-```bash
-# Create RLS policies
-*create-rls-policies
-
-# Or manually:
-ALTER TABLE users ENABLE ROW LEVEL SECURITY;
-CREATE POLICY "users_own_data" ON users
-  FOR ALL TO authenticated
-  USING (auth.uid() = id);
-```
-
-### 3. Add Seed Data
-
-```bash
-# Create seed file
-supabase migration new seed_initial_data
-
-# Or use DB Sage:
-*seed supabase/migrations/{timestamp}_seed.sql
-```
-
-### 4. Test Migration Workflow
-
-```bash
-# Create snapshot
-*snapshot baseline
-
-# Test migration
-*dry-run supabase/migrations/{file}.sql
-
-# Apply
-*apply-migration supabase/migrations/{file}.sql
-
-# Verify
-*smoke-test v1.0
-```
-
----
-
-## Supabase CLI Cheat Sheet
-
-```bash
-# Project Management
-supabase projects list              # List all projects
-supabase link --project-ref {ref}  # Link to project
-supabase status                     # Show project status
-
-# Local Development
-supabase init                       # Initialize local setup
-supabase start                      # Start local Supabase
-supabase stop                       # Stop local Supabase
-supabase db reset                   # Reset local database
-
-# Migrations
-supabase migration new {name}       # Create new migration
-supabase db push                    # Push migrations to remote
-supabase db pull                    # Pull remote schema
-supabase db diff                    # Compare local vs remote
-
-# Functions (Edge Functions)
-supabase functions new {name}       # Create new function
-supabase functions serve            # Run functions locally
-supabase functions deploy {name}    # Deploy function
-
-# Secrets
-supabase secrets set {name}={value} # Set secret
-supabase secrets list               # List secrets
-```
-
----
-
-## Troubleshooting
-
-### Issue 1: Connection Refused
-
-**Error:** `could not connect to server`
-
-**Fix:**
-1. Check database is running (Dashboard → Database → Connection info)
-2. Verify password in .env.local
-3. Check firewall allows port 5432/6543
-4. Try connection pooler (port 6543) instead
-
-### Issue 2: SSL Error
-
-**Error:** `SSL connection has been closed unexpectedly`
-
-**Fix:**
-Add `?sslmode=require` to connection string:
-```bash
-postgresql://postgres:password@db.ref.supabase.co:5432/postgres?sslmode=require
-```
-
-### Issue 3: Permission Denied
-
-**Error:** `permission denied for schema public`
-
-**Fix:**
-Use service_role key for admin operations, or grant permissions:
-```sql
-GRANT ALL ON SCHEMA public TO postgres;
-GRANT ALL ON ALL TABLES IN SCHEMA public TO postgres;
-```
-
----
-
-## References
-
-- [Supabase CLI Documentation](https://supabase.com/docs/guides/cli)
-- [Supabase Local Development](https://supabase.com/docs/guides/cli/local-development)
-- [PostgreSQL Connection Strings](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING)
-- [DB Sage Documentation](docs/architecture/db-sage/README.md)
+# Task: Supabase Setup Guide
+
+**Purpose**: Interactive guide to set up Supabase project with best practices
+
+**Elicit**: true
+
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: dbSupabaseSetup()
+responsável: Dara (Sage)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: query
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid SQL query
+
+- campo: params
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Query parameters
+
+- campo: connection
+  tipo: object
+  origem: config
+  obrigatório: true
+  validação: Valid PostgreSQL connection via Supabase
+
+**Saída:**
+- campo: query_result
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: records_affected
+  tipo: number
+  destino: Return value
+  persistido: false
+
+- campo: execution_time
+  tipo: number
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Database connection established; query syntax valid
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check database connection established; query syntax valid
+    error_message: "Pre-condition failed: Database connection established; query syntax valid"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Query executed; results returned; transaction committed
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify query executed; results returned; transaction committed
+    error_message: "Post-condition failed: Query executed; results returned; transaction committed"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Data persisted correctly; constraints respected; no orphaned data
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert data persisted correctly; constraints respected; no orphaned data
+    error_message: "Acceptance criterion not met: Data persisted correctly; constraints respected; no orphaned data"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** neo4j-driver
+  - **Purpose:** Neo4j database connection and query execution
+  - **Source:** npm: neo4j-driver
+
+- **Tool:** query-validator
+  - **Purpose:** Cypher query syntax validation
+  - **Source:** .aios-core/utils/db-query-validator.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** db-query.js
+  - **Purpose:** Execute Neo4j queries with error handling
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/db-query.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Connection Failed
+   - **Cause:** Unable to connect to Neo4j database
+   - **Resolution:** Check connection string, credentials, network
+   - **Recovery:** Retry with exponential backoff (max 3 attempts)
+
+2. **Error:** Query Syntax Error
+   - **Cause:** Invalid Cypher query syntax
+   - **Resolution:** Validate query syntax before execution
+   - **Recovery:** Return detailed syntax error, suggest fix
+
+3. **Error:** Transaction Rollback
+   - **Cause:** Query violates constraints or timeout
+   - **Resolution:** Review query logic and constraints
+   - **Recovery:** Automatic rollback, preserve data integrity
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - database
+  - infrastructure
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Overview
+
+This task guides you through setting up a new Supabase project with optimal configuration and DB Sage integration.
+
+---
+
+## Process
+
+### 1. Prerequisites Check
+
+Verify required tools:
+
+```bash
+echo "Checking prerequisites..."
+
+# Check Supabase CLI
+if command -v supabase >/dev/null 2>&1; then
+  echo "✓ Supabase CLI: $(supabase --version)"
+else
+  echo "❌ Supabase CLI not installed"
+  echo "   Install: https://supabase.com/docs/guides/cli"
+  exit 1
+fi
+
+# Check psql
+if command -v psql >/dev/null 2>&1; then
+  echo "✓ psql: $(psql --version)"
+else
+  echo "⚠️  psql not found (optional but recommended)"
+fi
+
+# Check git
+if command -v git >/dev/null 2>&1; then
+  echo "✓ git: $(git --version)"
+else
+  echo "⚠️  git not found (recommended for version control)"
+fi
+
+echo ""
+```
+
+### 2. Choose Setup Path
+
+Present options:
+
+```
+Supabase Setup Options:
+
+1. NEW PROJECT - Create new Supabase project from scratch
+2. EXISTING PROJECT - Link to existing Supabase project
+3. LOCAL ONLY - Set up local development environment only
+
+Select option (1/2/3):
+```
+
+### 3a. New Project Path
+
+If option 1 selected:
+
+```bash
+echo "Creating new Supabase project..."
+
+# Login to Supabase
+echo "Step 1: Login to Supabase"
+supabase login
+
+# Create project
+echo ""
+echo "Step 2: Create project on Supabase dashboard"
+echo "  → Go to: https://supabase.com/dashboard"
+echo "  → Click 'New Project'"
+echo "  → Enter details:"
+read -p "    Project name: " PROJECT_NAME
+read -p "    Organization: " ORG_NAME
+read -p "    Region (default: us-east-1): " REGION
+REGION=${REGION:-us-east-1}
+read -sp "    Database password (strong!): " DB_PASSWORD
+echo ""
+
+echo ""
+echo "✓ Project created on dashboard"
+echo "  Wait 2-3 minutes for provisioning..."
+read -p "  Press Enter when ready..."
+```
+
+### 3b. Existing Project Path
+
+If option 2 selected:
+
+```bash
+echo "Linking existing Supabase project..."
+
+# List projects
+echo "Your Supabase projects:"
+supabase projects list
+
+read -p "Enter project reference ID: " PROJECT_REF
+
+# Link project
+supabase link --project-ref "$PROJECT_REF"
+
+echo "✓ Project linked"
+```
+
+### 3c. Local Only Path
+
+If option 3 selected:
+
+```bash
+echo "Setting up local Supabase environment..."
+
+# Initialize local setup
+supabase init
+
+# Start local Supabase
+echo "Starting local Supabase (Docker required)..."
+supabase start
+
+echo "✓ Local Supabase running"
+echo "  Studio: http://localhost:54323"
+echo "  API: http://localhost:54321"
+```
+
+### 4. Initialize DB Sage Structure
+
+Create recommended folder structure:
+
+```bash
+echo "Initializing DB Sage project structure..."
+
+# Run db-bootstrap task internally
+mkdir -p supabase/{migrations,seeds,tests,rollback,docs,snapshots}
+
+# Create .env.local (gitignored)
+cat > .env.local << 'EOF'
+# Supabase Configuration
+# DO NOT COMMIT THIS FILE
+
+# Project Details
+SUPABASE_PROJECT_ID={project_ref}
+SUPABASE_PROJECT_NAME={project_name}
+
+# Database URLs
+# Connection pooler (port 6543) for serverless/edge functions
+SUPABASE_DB_URL_POOLER=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:6543/postgres
+
+# Direct connection (port 5432) for migrations
+SUPABASE_DB_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:5432/postgres
+
+# API Keys
+SUPABASE_URL=https://[PROJECT_REF].supabase.co
+SUPABASE_ANON_KEY=[ANON_KEY]
+SUPABASE_SERVICE_ROLE_KEY=[SERVICE_ROLE_KEY]
+EOF
+
+echo "✓ DB Sage structure created"
+echo "✓ .env.local template created (UPDATE WITH YOUR KEYS!)"
+```
+
+### 5. Configure .gitignore
+
+Ensure sensitive files are not committed:
+
+```bash
+echo "Configuring .gitignore..."
+
+cat >> .gitignore << 'EOF'
+
+# Supabase
+.env.local
+.env.production
+supabase/.branches
+supabase/.temp
+supabase/snapshots/*.sql
+supabase/rollback/*.sql
+
+# DB Sage
+/tmp/dbsage_*
+*.dump
+*.backup
+EOF
+
+echo "✓ .gitignore updated"
+```
+
+### 6. Set Up Environment Variables
+
+Guide user through configuration:
+
+```
+Setting up environment variables...
+
+1. Get your project keys from Supabase Dashboard:
+   → https://supabase.com/dashboard/project/{project_ref}/settings/api
+
+2. Update .env.local with:
+   - Database password
+   - Project reference ID
+   - Anon key
+   - Service role key (keep secret!)
+
+3. Source the file:
+   source .env.local
+
+4. Verify connection:
+   psql "$SUPABASE_DB_URL" -c "SELECT version();"
+
+Press Enter when complete...
+```
+
+### 7. Apply Initial Schema
+
+Create baseline schema:
+
+```bash
+echo "Setting up initial schema..."
+
+# Check if migrations exist
+if [ -z "$(ls -A supabase/migrations 2>/dev/null)" ]; then
+  echo "No migrations found."
+  echo "Options:"
+  echo "  1. Generate schema from design document"
+  echo "  2. Import existing schema"
+  echo "  3. Skip (will create later)"
+  read -p "Select option (1/2/3): " SCHEMA_OPTION
+
+  if [ "$SCHEMA_OPTION" = "1" ]; then
+    # Use domain modeling task
+    echo "→ Run: *model-domain to create schema"
+  elif [ "$SCHEMA_OPTION" = "2" ]; then
+    read -p "Path to existing schema SQL file: " SCHEMA_FILE
+    cp "$SCHEMA_FILE" "supabase/migrations/$(date +%Y%m%d%H%M%S)_initial_schema.sql"
+    echo "✓ Migration file created"
+  fi
+else
+  echo "✓ Migrations directory already has files"
+fi
+```
+
+### 8. Enable Recommended Extensions
+
+Install useful PostgreSQL extensions:
+
+```bash
+echo "Enabling recommended extensions..."
+
+psql "$SUPABASE_DB_URL" << 'EOF'
+-- Core extensions
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";      -- UUID generation
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";       -- Encryption functions
+CREATE EXTENSION IF NOT EXISTS "pg_stat_statements";  -- Query performance tracking
+
+-- Supabase extensions
+CREATE EXTENSION IF NOT EXISTS "pgjwt";          -- JWT functions
+CREATE EXTENSION IF NOT EXISTS "pg_net";         -- HTTP client
+
+-- Optional: Full-text search
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";        -- Trigram matching
+
+-- Optional: PostGIS (if using geospatial data)
+-- CREATE EXTENSION IF NOT EXISTS "postgis";
+
+SELECT 'Extensions enabled' AS status;
+EOF
+
+echo "✓ Extensions enabled"
+```
+
+### 9. Configure Database Settings
+
+Apply recommended settings:
+
+```bash
+echo "Applying recommended database settings..."
+
+psql "$SUPABASE_DB_URL" << 'EOF'
+-- Performance settings (adjust based on your tier)
+-- These are set at session level - for permanent changes, use Supabase dashboard
+
+-- Enable auto_explain for slow queries (dev only)
+-- ALTER SYSTEM SET auto_explain.log_min_duration = 1000;  -- Log queries > 1s
+-- ALTER SYSTEM SET auto_explain.log_analyze = on;
+
+-- Work memory for complex queries
+SET work_mem = '16MB';
+
+-- Statement timeout to prevent runaway queries
+SET statement_timeout = '30s';
+
+-- Lock timeout to prevent long lock waits
+SET lock_timeout = '10s';
+
+SELECT 'Settings configured' AS status;
+EOF
+
+echo "✓ Database settings configured"
+echo "  (For permanent settings, use Supabase Dashboard → Database → Settings)"
+```
+
+### 10. Set Up Development Workflow
+
+Configure recommended workflow:
+
+```bash
+echo "Setting up development workflow..."
+
+# Create helpful scripts
+mkdir -p scripts
+
+cat > scripts/db-connect.sh << 'EOF'
+#!/bin/bash
+# Connect to Supabase database
+source .env.local
+psql "$SUPABASE_DB_URL"
+EOF
+
+cat > scripts/db-reset-local.sh << 'EOF'
+#!/bin/bash
+# Reset local Supabase database
+supabase db reset
+EOF
+
+chmod +x scripts/*.sh
+
+echo "✓ Helper scripts created in scripts/"
+```
+
+---
+
+## Output
+
+Display setup summary:
+
+```
+✅ SUPABASE SETUP COMPLETE
+
+Project: {project_name}
+Region: {region}
+Status: Ready for development
+
+Environment:
+✓ Supabase CLI configured
+✓ Project linked/created
+✓ DB Sage structure initialized
+✓ Extensions enabled
+✓ .env.local created (REMEMBER TO UPDATE!)
+
+Folder Structure:
+supabase/
+├── migrations/    # Database migrations
+├── seeds/         # Seed data
+├── tests/         # SQL tests
+├── docs/          # Documentation
+└── snapshots/     # Backup snapshots
+
+Next Steps:
+1. Update .env.local with your keys
+2. Test connection: psql "$SUPABASE_DB_URL"
+3. Design your schema: *model-domain
+4. Create first migration: *create-migration
+5. Set up RLS policies: *create-rls-policies
+
+Useful Commands:
+- Connect to DB: ./scripts/db-connect.sh
+- Create migration: supabase migration new {name}
+- Push changes: supabase db push
+- Pull remote: supabase db pull
+
+Documentation:
+- Supabase Docs: https://supabase.com/docs
+- DB Sage Guide: docs/architecture/db-sage/README.md
+```
+
+---
+
+## Common Next Steps
+
+### 1. Create Initial Schema
+
+```bash
+# Option A: Interactive modeling
+*model-domain
+
+# Option B: Create migration manually
+supabase migration new initial_schema
+# Edit: supabase/migrations/{timestamp}_initial_schema.sql
+```
+
+### 2. Set Up Row Level Security
+
+```bash
+# Create RLS policies
+*create-rls-policies
+
+# Or manually:
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "users_own_data" ON users
+  FOR ALL TO authenticated
+  USING (auth.uid() = id);
+```
+
+### 3. Add Seed Data
+
+```bash
+# Create seed file
+supabase migration new seed_initial_data
+
+# Or use DB Sage:
+*seed supabase/migrations/{timestamp}_seed.sql
+```
+
+### 4. Test Migration Workflow
+
+```bash
+# Create snapshot
+*snapshot baseline
+
+# Test migration
+*dry-run supabase/migrations/{file}.sql
+
+# Apply
+*apply-migration supabase/migrations/{file}.sql
+
+# Verify
+*smoke-test v1.0
+```
+
+---
+
+## Supabase CLI Cheat Sheet
+
+```bash
+# Project Management
+supabase projects list              # List all projects
+supabase link --project-ref {ref}  # Link to project
+supabase status                     # Show project status
+
+# Local Development
+supabase init                       # Initialize local setup
+supabase start                      # Start local Supabase
+supabase stop                       # Stop local Supabase
+supabase db reset                   # Reset local database
+
+# Migrations
+supabase migration new {name}       # Create new migration
+supabase db push                    # Push migrations to remote
+supabase db pull                    # Pull remote schema
+supabase db diff                    # Compare local vs remote
+
+# Functions (Edge Functions)
+supabase functions new {name}       # Create new function
+supabase functions serve            # Run functions locally
+supabase functions deploy {name}    # Deploy function
+
+# Secrets
+supabase secrets set {name}={value} # Set secret
+supabase secrets list               # List secrets
+```
+
+---
+
+## Troubleshooting
+
+### Issue 1: Connection Refused
+
+**Error:** `could not connect to server`
+
+**Fix:**
+1. Check database is running (Dashboard → Database → Connection info)
+2. Verify password in .env.local
+3. Check firewall allows port 5432/6543
+4. Try connection pooler (port 6543) instead
+
+### Issue 2: SSL Error
+
+**Error:** `SSL connection has been closed unexpectedly`
+
+**Fix:**
+Add `?sslmode=require` to connection string:
+```bash
+postgresql://postgres:password@db.ref.supabase.co:5432/postgres?sslmode=require
+```
+
+### Issue 3: Permission Denied
+
+**Error:** `permission denied for schema public`
+
+**Fix:**
+Use service_role key for admin operations, or grant permissions:
+```sql
+GRANT ALL ON SCHEMA public TO postgres;
+GRANT ALL ON ALL TABLES IN SCHEMA public TO postgres;
+```
+
+---
+
+## References
+
+- [Supabase CLI Documentation](https://supabase.com/docs/guides/cli)
+- [Supabase Local Development](https://supabase.com/docs/guides/cli/local-development)
+- [PostgreSQL Connection Strings](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING)
+- [DB Sage Documentation](docs/architecture/db-sage/README.md)