specweave 1.0.57 → 1.0.59

package/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- SW:META template="claude" version="1.0.58" sections="header,start,autodetect,metarule,rules,workflow,context,lsp,structure,taskformat,secrets,syncing,mapping,testing,api,limits,troubleshooting,principles,linking,mcp,autoexecute,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.62" sections="header,start,autodetect,metarule,rules,workflow,context,lsp,structure,taskformat,secrets,syncing,mapping,testing,api,limits,troubleshooting,principles,linking,mcp,autoexecute,auto,docs" -->
 
 <!-- SW:SECTION:header version="1.0.56" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
@@ -45,7 +45,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.56" -->
+<!-- SW:SECTION:workflow version="1.0.58" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -53,13 +53,16 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 | Cmd | Action |
 |-----|--------|
 | `/sw:increment` | Plan feature |
-| `/sw:do` | Execute |
+| `/sw:do` | Execute tasks |
+| `/sw:auto` | Autonomous execution |
+| `/sw:auto-status` | Check auto session |
+| `/sw:cancel-auto` | Cancel auto session |
 | `/sw:validate` | Quality check |
 | `/sw:done` | Close |
 | `/sw-github:sync` | GitHub sync |
 | `/sw-jira:sync` | Jira sync |
 
-**Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done`
+**Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done` | "Ship while sleeping" → `/sw:auto`
 <!-- SW:END:workflow -->
 
 <!-- SW:SECTION:context version="1.0.56" -->
@@ -147,7 +150,7 @@ rustup component add rust-analyzer
 - Combine with Explore agent for comprehensive codebase understanding
 <!-- SW:END:lsp -->
 
-<!-- SW:SECTION:structure version="1.0.56" -->
+<!-- SW:SECTION:structure version="1.0.59" -->
 ## Structure
 
 ```
@@ -160,7 +163,41 @@ rustup component add rust-analyzer
 └── config.json
 ```
 
-**Multi-repo**: Clone to `/repositories`, not root → `repositories/backend/src/...`
+### ⚠️ CRITICAL: Multi-Repo Project Paths (MANDATORY)
+
+**ALL multi-project repositories MUST be created in `repositories/` folder - NEVER in project root!**
+
+```
+❌ FORBIDDEN (pollutes root):
+my-project/
+├── frontend/        ← WRONG!
+├── backend/         ← WRONG!
+├── shared/          ← WRONG!
+└── .specweave/
+
+✅ REQUIRED (clean structure):
+my-project/
+├── repositories/
+│   ├── frontend/    ← CORRECT!
+│   ├── backend/     ← CORRECT!
+│   └── shared/      ← CORRECT!
+└── .specweave/
+```
+
+**This applies to ALL cases:**
+- GitHub multi-repo → `repositories/`
+- Azure DevOps multi-repo → `repositories/`
+- Bitbucket multi-repo → `repositories/`
+- **Local git multi-repo → `repositories/`** ← Same rule!
+- Monorepo with multiple packages → `repositories/` or `packages/`
+
+**When spec.md has `projects:` array:**
+```yaml
+projects:
+  - id: my-api
+    scope: "Backend API"
+```
+The implementation path is ALWAYS: `repositories/my-api/` (NOT `my-api/` in root!)
 
 **Multi-repo permissions**: In `.claude/settings.json`:
 ```json
@@ -240,12 +277,12 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:api version="1.0.58" -->
+<!-- SW:SECTION:api version="1.0.61" -->
 ## API Development (OpenAPI-First)
 
 **For API projects only.** Skip this section if your project has no REST/GraphQL endpoints.
 
-**Use OpenAPI as the source of truth for API documentation.** Postman collections are derived from OpenAPI.
+**Use OpenAPI as the source of truth for API documentation.** Postman collections and environments are derived from OpenAPI and .env.
 
 ### Configuration (`.specweave/config.json`)
 
@@ -256,12 +293,21 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
     "openApiPath": "openapi.yaml",
     "generatePostman": true,
     "postmanPath": "postman-collection.json",
+    "postmanEnvPath": "postman-environment.json",
     "generateOn": "on-increment-done",
     "baseUrl": "http://localhost:3000"
   }
 }
 ```
 
+### Generated Artifacts
+
+| File | Purpose | Source |
+|------|---------|--------|
+| `openapi.yaml` | API specification (source of truth) | Framework decorators/annotations |
+| `postman-collection.json` | API requests for testing | Derived from OpenAPI |
+| `postman-environment.json` | Variables (baseUrl, tokens, etc.) | Derived from .env |
+
 ### OpenAPI Generation by Framework
 
 | Framework | Auto-Generation | Setup |
@@ -281,28 +327,39 @@ Code (decorators/annotations)
 openapi.yaml (SOURCE OF TRUTH - version controlled)
         |
         v (derived on /sw:done or /sw:api-docs)
-postman-collection.json (for manual testing)
+├── postman-collection.json (requests with {{baseUrl}} variables)
+└── postman-environment.json (variables from .env, secrets marked)
 ```
 
 ### Commands
 
 ```bash
-# Generate/update API docs (OpenAPI + Postman)
-/sw:api-docs
+# Generate all API docs (OpenAPI + Postman collection + environment)
+/sw:api-docs --all
+
+# Generate only OpenAPI
+/sw:api-docs --openapi
+
+# Generate only Postman collection from existing OpenAPI
+/sw:api-docs --postman
+
+# Generate only environment file from .env
+/sw:api-docs --env
+
+# Validate existing OpenAPI spec
+/sw:api-docs --validate
 
 # Generate on increment close (automatic if enabled)
 /sw:done 0001  # -> triggers API doc generation
 ```
 
-### Manual Generation (if config disabled)
+### Postman Import
 
-```bash
-# Generate Postman from existing OpenAPI
-npx @postman/openapi-to-postmanv2 -s openapi.yaml -o postman-collection.json
-
-# Generate OpenAPI for Express
-npx swagger-jsdoc -d swagger-config.js -o openapi.yaml
-```
+After generation:
+1. Postman → Import → `postman-collection.json`
+2. Postman → Environments → Import → `postman-environment.json`
+3. Fill in secret values (marked as secret type, values empty)
+4. Select environment from dropdown
 
 ### When Docs Update
 
@@ -356,52 +413,366 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:mcp version="1.0.56" -->
-## MCP Servers (External Service Integration)
+<!-- SW:SECTION:mcp version="1.0.62" -->
+## External Service Connection (CLI-First, Smart Fallbacks)
+
+**Core principle: CLIs are LLM-native. Use them when authenticated.**
+
+### Connection Priority
 
-**MCP servers extend Claude Code's capabilities for external services.** Install them for autonomous operations.
+```
+Authenticated CLI → REST API → MCP Server → SDK/Client
+        ↑                                        ↓
+  MOST EFFICIENT                              FALLBACK
+```
 
-### Recommended MCP Servers
+**Why CLI-first?** LLMs can invoke CLIs directly, parse output, handle errors, and chain commands efficiently.
 
-| Service | Install | Purpose |
-|---------|---------|---------|
-| **Supabase** | `npx @anthropic/claude-code-mcp-setup add supabase` | Database, Auth, Edge Functions |
-| **GitHub** | Built-in via `gh` CLI | Issues, PRs, Repos |
-| **Postgres** | `npx @anthropic/claude-code-mcp-setup add postgres` | Direct DB access |
+### Pre-Flight Check (MANDATORY)
 
-### Supabase MCP Setup
+**Run this BEFORE any external service operation:**
 
 ```bash
-# Add to Claude Code MCP config
-npx @anthropic/claude-code-mcp-setup add supabase
+# Check all CLI auth at once
+supabase projects list 2>/dev/null && echo "✓ Supabase"
+wrangler whoami 2>/dev/null && echo "✓ Cloudflare"
+gh auth status 2>/dev/null && echo "✓ GitHub"
+vercel whoami 2>/dev/null && echo "✓ Vercel"
+aws sts get-caller-identity 2>/dev/null && echo "✓ AWS"
 
-# Or manual config in .claude/settings.local.json:
-{
-  "mcpServers": {
-    "supabase": {
-      "type": "http",
-      "url": "https://mcp.supabase.com/mcp"
-    }
-  }
-}
+# Check .env for API keys
+grep -E "(SUPABASE_|GITHUB_TOKEN|CF_|VERCEL_|AWS_)" .env 2>/dev/null
 ```
 
-### Auto-Install Rule
+---
+
+### Supabase
+
+**Credentials needed:**
 
-**If credentials exist for a service, Claude SHOULD auto-install the MCP server:**
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **Project Ref** | Dashboard → Settings → General → "Reference ID" | `abcdefghijkl` (12 chars) |
+| **Access Token** | Dashboard → Account (top-right) → Access Tokens → Generate | `sbp_xxxxxxxxxxxxxxxx` |
+| **Org ID** (optional) | Dashboard → Org Settings → General | `org-xxxxx` |
+| **Database Password** | Dashboard → Settings → Database → Connection string | In the URI |
+| **API URL** | Dashboard → Settings → API → "Project URL" | `https://xxx.supabase.co` |
+| **Anon Key** | Dashboard → Settings → API → "anon public" | `eyJhbGc...` (JWT) |
+| **Service Role Key** | Dashboard → Settings → API → "service_role" (secret!) | `eyJhbGc...` (JWT) |
 
+**CLI Setup (PREFERRED):**
 ```bash
-# If SUPABASE_URL exists → suggest/install Supabase MCP
-if grep -q "SUPABASE_URL" .env 2>/dev/null; then
-  npx @anthropic/claude-code-mcp-setup add supabase
-fi
+# 1. Login (one-time, opens browser)
+supabase login
+
+# 2. Link project (in your project directory)
+supabase link --project-ref <PROJECT_REF>
+# Optional: --password <DB_PASSWORD> to skip prompt
+
+# 3. Verify
+supabase projects list
+```
+
+**CLI Operations (once linked):**
+```bash
+supabase db push                      # Apply migrations
+supabase db pull                      # Pull remote schema
+supabase db reset                     # Reset to migrations
+supabase functions deploy <name>      # Deploy edge function
+supabase secrets set KEY=value        # Set secrets
+supabase gen types typescript         # Generate types
+supabase migration new <name>         # Create migration
+```
+
+**If CLI has network issues, use Access Token:**
+```bash
+SUPABASE_ACCESS_TOKEN=sbp_xxx supabase db push
+```
+
+**REST API Fallback (.env):**
+```bash
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_ANON_KEY=eyJhbGc...
+SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...  # For admin operations
+```
+
+**Direct DB (use pooler port 6543, NOT 5432):**
+```bash
+DATABASE_URL="postgresql://postgres.PROJECT_REF:PASSWORD@aws-0-REGION.pooler.supabase.com:6543/postgres"
+```
+
+---
+
+### Cloudflare (Wrangler)
+
+**Credentials needed:**
+
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **Account ID** | Dashboard → any domain → Overview → right sidebar | `32-char hex` |
+| **API Token** | Dashboard → My Profile → API Tokens → Create | `xxxxx` (40+ chars) |
+| **Zone ID** (per domain) | Dashboard → domain → Overview → right sidebar | `32-char hex` |
+
+**CLI Setup (PREFERRED - uses OAuth):**
+```bash
+# Login via browser (recommended)
+wrangler login
+
+# Verify
+wrangler whoami
+```
+
+**CLI Operations:**
+```bash
+wrangler deploy                           # Deploy worker
+wrangler dev                              # Local dev server
+wrangler kv namespace list                # List KV namespaces
+wrangler kv key put --binding=KV k "v"    # KV write
+wrangler d1 list                          # List D1 databases
+wrangler d1 execute DB --command "SQL"    # D1 query
+wrangler r2 bucket list                   # List R2 buckets
+echo "secret" | wrangler secret put NAME  # Set secret (non-interactive)
+wrangler tail                             # Live logs
+wrangler pages deploy ./dist              # Deploy Pages
+```
+
+**API Token Fallback (.env):**
+```bash
+CLOUDFLARE_API_TOKEN=xxxxx
+CLOUDFLARE_ACCOUNT_ID=xxxxx
+# Per-domain operations:
+CLOUDFLARE_ZONE_ID=xxxxx
+```
+
+**wrangler.toml (project config):**
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+account_id = "YOUR_ACCOUNT_ID"  # Optional if logged in
+
+[[kv_namespaces]]
+binding = "KV"
+id = "xxxxx"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "my-db"
+database_id = "xxxxx"
+```
+
+---
+
+### GitHub (gh CLI)
+
+**Credentials needed:**
+
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **Personal Access Token** | Settings → Developer settings → Personal access tokens → Fine-grained | `github_pat_xxx` |
+| **Classic Token** | Same location, "Tokens (classic)" | `ghp_xxxxx` |
+
+**CLI Setup (PREFERRED):**
+```bash
+# Interactive login (opens browser)
+gh auth login
+
+# Or with token
+gh auth login --with-token < token.txt
+# Or: export GITHUB_TOKEN=ghp_xxx && gh auth status
+
+# Verify
+gh auth status
+```
+
+**CLI Operations:**
+```bash
+gh repo clone owner/repo                  # Clone
+gh issue list                             # List issues
+gh issue create --title "X" --body "Y"    # Create issue
+gh pr create --fill                       # Create PR
+gh pr merge --auto --squash               # Auto-merge
+gh workflow list                          # List workflows
+gh workflow run deploy.yml                # Trigger workflow
+gh api repos/{owner}/{repo}/issues        # Raw API call
+gh release create v1.0.0                  # Create release
+```
+
+**Token Fallback (.env):**
+```bash
+GITHUB_TOKEN=ghp_xxxxx
+# Or for GitHub Apps:
+GITHUB_APP_ID=xxxxx
+GITHUB_PRIVATE_KEY="-----BEGIN RSA..."
+```
+
+---
+
+### Vercel
+
+**Credentials needed:**
+
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **Token** | Settings → Tokens → Create | `xxxxx` |
+| **Org ID** | Settings → General → "Vercel ID" | `team_xxxxx` |
+| **Project ID** | Project → Settings → General | `prj_xxxxx` |
+
+**CLI Setup (PREFERRED):**
+```bash
+# Login via browser
+vercel login
+
+# Or with token
+vercel login --token xxxxx
+
+# Verify
+vercel whoami
+```
+
+**CLI Operations:**
+```bash
+vercel                                    # Deploy (interactive)
+vercel --prod                             # Production deploy
+vercel env pull .env.local                # Pull env vars
+vercel env add SECRET production          # Add env var
+vercel logs                               # View logs
+vercel domains ls                         # List domains
+vercel link                               # Link to project
+```
+
+**Token Fallback (.env):**
+```bash
+VERCEL_TOKEN=xxxxx
+VERCEL_ORG_ID=team_xxxxx
+VERCEL_PROJECT_ID=prj_xxxxx
+```
+
+---
+
+### AWS
+
+**Credentials needed:**
+
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **Access Key ID** | IAM → Users → Security credentials → Create access key | `AKIA...` (20 chars) |
+| **Secret Access Key** | Same (shown once at creation) | `xxxxx` (40 chars) |
+| **Region** | Choose based on location | `us-east-1`, `eu-west-1`, etc. |
+| **SSO Start URL** | AWS SSO config (if using SSO) | `https://xxx.awsapps.com/start` |
+
+**CLI Setup:**
+```bash
+# Option 1: Configure with keys
+aws configure
+# Prompts for: Access Key, Secret Key, Region, Output format
+
+# Option 2: SSO (recommended for orgs)
+aws configure sso
+# Prompts for: SSO start URL, SSO region, account, role
+
+# Login (SSO)
+aws sso login --profile your-profile
+
+# Verify
+aws sts get-caller-identity
+```
+
+**CLI Operations:**
+```bash
+aws s3 ls                                 # List buckets
+aws s3 cp file.txt s3://bucket/           # Upload
+aws lambda list-functions                 # List Lambdas
+aws lambda invoke --function-name X out   # Invoke Lambda
+aws logs tail /aws/lambda/X --follow      # Tail logs
+aws secretsmanager get-secret-value --secret-id X  # Get secret
+aws ecr get-login-password | docker login # ECR login
+```
+
+**Credentials Fallback (.env):**
+```bash
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=xxxxx
+AWS_REGION=us-east-1
+# Or for assumed roles:
+AWS_ROLE_ARN=arn:aws:iam::xxx:role/xxx
+```
+
+---
+
+### MongoDB Atlas
+
+**Credentials needed:**
+
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **Connection String** | Cluster → Connect → Drivers | `mongodb+srv://user:pass@cluster.xxx.mongodb.net/` |
+| **Data API Key** | Data API → Create API Key | `xxxxx` |
+| **App ID** | Data API → App ID | `data-xxxxx` |
+
+**Data API (.env):**
+```bash
+MONGODB_DATA_API_KEY=xxxxx
+MONGODB_APP_ID=data-xxxxx
+MONGODB_CLUSTER=Cluster0
+MONGODB_DATABASE=mydb
+```
+
+---
+
+### Upstash Redis
+
+**Credentials needed:**
+
+| Credential | Where to find | Format |
+|------------|---------------|--------|
+| **REST URL** | Database → REST API → UPSTASH_REDIS_REST_URL | `https://xxx.upstash.io` |
+| **REST Token** | Same section → UPSTASH_REDIS_REST_TOKEN | `AXxx...` |
+
+**REST API (.env):**
+```bash
+UPSTASH_REDIS_REST_URL=https://xxx.upstash.io
+UPSTASH_REDIS_REST_TOKEN=AXxx...
+```
+
+---
+
+### When to Use MCP
+
+Use MCP servers when CLI is unavailable or you need structured responses:
+
+```bash
+npx @anthropic-ai/claude-code-mcp add supabase
+npx @anthropic-ai/claude-code-mcp add postgres
+# Restart Claude Code after adding
+```
+
+---
+
+### Smart Credential Request Template
+
+**When credentials are missing, ask specifically:**
+
+```markdown
+🔐 **[Service] Setup Needed**
+
+I need to connect to your [Service]. Please provide:
+
+| What I need | Where to find it |
+|-------------|------------------|
+| **[Credential 1]** | [Exact path in dashboard] |
+| **[Credential 2]** | [Exact path in dashboard] |
+
+**Or run:** `[cli login command]`
+
+[I'll configure and execute automatically]
 ```
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:autoexecute version="1.0.56" -->
+<!-- SW:SECTION:autoexecute version="1.0.60" -->
 ## Auto-Execute Rule (CRITICAL)
 
-**NEVER output "Manual Step Required" or "Next Steps" when credentials are available.**
+**NEVER output "Manual Step Required" or "Next Steps" when CLI tools are available.**
 
 ### The Golden Rule
 
@@ -409,64 +780,93 @@ fi
 ❌ FORBIDDEN: "Manual Step Required: Open Supabase SQL Editor..."
 ❌ FORBIDDEN: "Next Steps: 1. Run wrangler deploy..."
 ❌ FORBIDDEN: "Execute this SQL in your database console..."
+❌ FORBIDDEN: "Please run this command manually..."
 
-✅ REQUIRED: Execute commands directly using available credentials
+✅ REQUIRED: Use CLI tools directly when authenticated
+✅ REQUIRED: Ask for specific credentials if missing, then execute
 ```
 
 ### Decision Tree
 
 ```
-Credentials in .env? ──YES──→ EXECUTE IMMEDIATELY
+CLI authenticated? ──YES──→ EXECUTE via CLI
+         │
+         NO
+         │
+         ▼
+.env has credentials? ──YES──→ EXECUTE via API/CLI
          │
          NO
          │
          ▼
-ASK for credentials (don't show manual steps!)
+ASK for SPECIFIC credentials needed
          │
          ▼
-Save to .env → EXECUTE IMMEDIATELY → Continue
+User provides → Save if needed → EXECUTE IMMEDIATELY
 ```
 
-### Credential Lookup (MANDATORY before any external operation)
+### Pre-Flight Check (Run BEFORE any external operation)
 
 ```bash
-# 1. Check .env
-grep -E "(SUPABASE_|DATABASE_URL|CF_API_|GITHUB_TOKEN)" .env 2>/dev/null
+# Check ALL potentially relevant CLI tools at once
+echo "=== CLI Auth Status ===" && \
+supabase projects list 2>/dev/null && echo "✓ Supabase" || echo "✗ Supabase" && \
+wrangler whoami 2>/dev/null && echo "✓ Wrangler" || echo "✗ Wrangler" && \
+gh auth status 2>/dev/null && echo "✓ GitHub" || echo "✗ GitHub" && \
+vercel whoami 2>/dev/null && echo "✓ Vercel" || echo "✗ Vercel" && \
+aws sts get-caller-identity 2>/dev/null && echo "✓ AWS" || echo "✗ AWS"
 
-# 2. Check CLI auth
-supabase status 2>/dev/null     # Supabase
-wrangler whoami 2>/dev/null     # Cloudflare
-gh auth status 2>/dev/null      # GitHub
-aws sts get-caller-identity 2>/dev/null  # AWS
-
-# 3. Use MCP server if available
-# MCP servers provide direct API access
+# Check .env for API keys/tokens
+grep -E "(SUPABASE_|DATABASE_URL|GITHUB_TOKEN|OPENAI_|ANTHROPIC_)" .env 2>/dev/null
 ```
 
 ### Auto-Execute Examples
 
 ```bash
-# Supabase SQL execution
-if [ -n "$DATABASE_URL" ]; then
-  psql "$DATABASE_URL" -f schema.sql  # ✅ Execute directly
+# Supabase - prefer CLI when linked
+if supabase projects list 2>/dev/null; then
+  supabase db push  # ✅ CLI handles auth automatically
+else
+  # Fallback to REST API with tokens
+  curl "${SUPABASE_URL}/rest/v1/..." -H "apikey: ${SUPABASE_ANON_KEY}"
 fi
 
-# Wrangler secrets
+# Cloudflare - wrangler handles everything
 if wrangler whoami 2>/dev/null; then
-  echo "$SECRET" | wrangler secret put MY_SECRET  # ✅ Execute directly
-  wrangler deploy  # ✅ Deploy directly
+  wrangler deploy                          # ✅ Deploy
+  echo "$SECRET" | wrangler secret put KEY # ✅ Set secret
+  wrangler d1 execute DB --command "SQL"   # ✅ Database
+fi
+
+# GitHub - gh CLI is extremely capable
+if gh auth status 2>/dev/null; then
+  gh issue create --title "..." --body "..."
+  gh pr create --fill
+  gh api repos/{owner}/{repo}/actions/workflows
 fi
 ```
 
-### If Credentials Missing → ASK, Don't Show Manual Steps
+### If Credentials Missing → ASK Specifically
+
+**Don't ask vaguely. Ask for EXACTLY what you need:**
 
 ```markdown
-🔐 **Credential Required**
+🔐 **Supabase Connection Needed**
+
+To push migrations, I need your Supabase project linked. Either:
+
+**Option A** (Recommended): Run these commands:
+\`\`\`bash
+supabase login
+supabase link --project-ref YOUR_PROJECT_REF
+\`\`\`
+Your project ref is at: Dashboard → Settings → General
 
-I need your DATABASE_URL to execute the migration.
+**Option B**: Provide credentials for .env:
+- SUPABASE_URL: `____________`
+- SUPABASE_SERVICE_ROLE_KEY: `____________`
 
-**Paste your connection string:**
-[I will save to .env and execute automatically]
+Which would you prefer?
 ```
 <!-- SW:END:autoexecute -->
 
@@ -484,10 +884,11 @@ I need your DATABASE_URL to execute the migration.
 - Click buttons in UIs
 
 **If you need external access:**
-1. Check for credentials in `.env`
-2. Use CLI tools (`supabase`, `wrangler`, `gh`, `aws`)
-3. Use MCP servers for direct API access
-4. If credentials missing → ASK for them, save to `.env`, then EXECUTE
+1. Check CLI auth status FIRST (`supabase projects list`, `wrangler whoami`, `gh auth status`)
+2. Use authenticated CLI tools directly - they're most efficient for LLMs
+3. Fallback to `.env` credentials + REST API if CLI not available
+4. Use MCP servers only when CLI/API aren't options
+5. If credentials missing → ASK for them, save to `.env`, then EXECUTE
 
 ### 🧪 Test Execution Loop (MANDATORY)