opencode-skill/CREDENTIALS_SETUP_GUIDE.md

# 📋 SEO Skills - Credentials Setup Guide

**Purpose:** Set up all API credentials for testing all features

---

## 🔑 CREDENTIALS REQUIRED BY FEATURE

### **Core Features (No Credentials Needed)** ✅

These features work **without any API credentials**:
- ✅ Multi-channel content generation (Facebook, Google Ads, Blog, X)
- ✅ Thai keyword density analysis
- ✅ Thai readability scoring
- ✅ Content quality scoring (0-100)
- ✅ Context file creation

**You can test Groups 1-3 immediately without any credentials!**

---

### **Image Features (Needs Chutes AI)** 🎨

**Required for:** Tests 4.1, 4.3

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `CHUTES_API_TOKEN` | API token for image generation/editing | https://chutes.ai/ |

**Setup:**
1. Sign up at https://chutes.ai/
2. Get API token from dashboard
3. Add to `.env`:
   ```bash
   CHUTES_API_TOKEN=your_token_here
   ```

---

### **Analytics Features (Optional)** 📊

**Required for:** Tests 6.2-6.5

#### **Google Analytics 4**

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `GA4_PROPERTY_ID` | Your GA4 property ID (e.g., G-123456789) | GA4 Admin → Data Streams |
| `GA4_CREDENTIALS_PATH` | Path to service account JSON file | Google Cloud Console |

**Setup:**
1. Go to Google Cloud Console
2. Create service account
3. Download JSON credentials
4. Grant service account access to GA4 property
5. Add to `.env`:
   ```bash
   GA4_PROPERTY_ID=G-XXXXXXXXXX
   GA4_CREDENTIALS_PATH=/path/to/ga4-credentials.json
   ```

---

#### **Google Search Console**

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `GSC_SITE_URL` | Your verified site URL | GSC dashboard |
| `GSC_CREDENTIALS_PATH` | Path to service account JSON file | Google Cloud Console |

**Setup:**
1. Use same service account as GA4 (or create new)
2. Grant service account access to GSC property
3. Add to `.env`:
   ```bash
   GSC_SITE_URL=https://yoursite.com
   GSC_CREDENTIALS_PATH=/path/to/gsc-credentials.json
   ```

---

#### **DataForSEO**

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `DATAFORSEO_LOGIN` | API login | https://dataforseo.com/ dashboard |
| `DATAFORSEO_PASSWORD` | API password | https://dataforseo.com/ dashboard |

**Setup:**
1. Sign up at https://dataforseo.com/
2. Get API credentials from dashboard
3. Add to `.env`:
   ```bash
   DATAFORSEO_LOGIN=your_login
   DATAFORSEO_PASSWORD=your_password
   ```

---

#### **Umami Analytics**

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `UMAMI_API_URL` | Your Umami instance URL | Your Umami dashboard |
| `UMAMI_API_KEY` | API key from Umami | Umami dashboard → Settings |
| `UMAMI_WEBSITE_ID` | Website ID in Umami | Umami dashboard → Websites |

**Setup:**
1. Self-host Umami or use cloud version
2. Get API key from dashboard
3. Add to `.env`:
   ```bash
   UMAMI_API_URL=https://analytics.yoursite.com
   UMAMI_API_KEY=your_api_key
   UMAMI_WEBSITE_ID=your_website_id
   ```

---

### **Git/Auto-Publish Features (Optional)** 🚀

**Required for:** Test 5.1 (auto-publish)

| Variable | Description | Where to Get |
|----------|-------------|--------------|
| `GIT_USERNAME` | Your Git username | Gitea/GitHub profile |
| `GIT_EMAIL` | Your Git email | Gitea/GitHub profile |
| `GIT_TOKEN` | Personal access token | Gitea/GitHub settings |
| `GIT_URL` | Git server URL | Your Gitea/GitHub instance |

**Setup:**
1. Generate personal access token from Gitea/GitHub
2. Add to `.env`:
   ```bash
   GIT_USERNAME=your_username
   GIT_EMAIL=your@email.com
   GIT_TOKEN=your_token
   GIT_URL=https://git.moreminimore.com
   ```

---

## 📝 SETUP WORKFLOW

### **Step 1: Copy .env.example**

```bash
cd /Users/kunthawatgreethong/Gitea/opencode-skill

cp .env.example .env
```

### **Step 2: Edit .env**

```bash
nano .env  # or use your preferred editor
```

### **Step 3: Add Your Credentials**

**Minimum for testing core features (nothing required!):**
```bash
# Leave everything blank - core features still work!
```

**For full testing:**
```bash
# Images (for Tests 4.1, 4.3)
CHUTES_API_TOKEN=your_chutes_token

# Git (for Test 5.1)
GIT_USERNAME=your_username
GIT_EMAIL=your@email.com
GIT_TOKEN=your_git_token

# Analytics (for Tests 6.2-6.5, skip if you don't have)
GA4_PROPERTY_ID=G-XXXXXXXXXX
GA4_CREDENTIALS_PATH=/path/to/ga4.json
GSC_SITE_URL=https://yoursite.com
GSC_CREDENTIALS_PATH=/path/to/gsc.json
DATAFORSEO_LOGIN=your_login
DATAFORSEO_PASSWORD=your_password
UMAMI_API_URL=https://analytics.yoursite.com
UMAMI_API_KEY=your_key
UMAMI_WEBSITE_ID=your_id
```

### **Step 4: Verify Setup**

```bash
# Check .env exists
ls -la .env

# Check it has your credentials (first 5 chars only)
grep "^CHUTES_API_TOKEN=" .env | cut -c1-20
```

---

## ✅ CREDENTIAL CHECKLIST

Before testing, check which credentials you have:

### **Core Features (No credentials needed)**
- [ ] None required! Ready to test Groups 1-3

### **Image Features**
- [ ] `CHUTES_API_TOKEN` - Required for Tests 4.1, 4.3
- [ ] Skip if not available (image features are optional)

### **Git/Auto-Publish**
- [ ] `GIT_USERNAME`
- [ ] `GIT_EMAIL`
- [ ] `GIT_TOKEN`
- [ ] Required for Test 5.1

### **Analytics (All Optional)**
- [ ] `GA4_PROPERTY_ID` + `GA4_CREDENTIALS_PATH` - Test 6.2
- [ ] `GSC_SITE_URL` + `GSC_CREDENTIALS_PATH` - Test 6.3
- [ ] `DATAFORSEO_LOGIN` + `DATAFORSEO_PASSWORD` - Test 6.4
- [ ] `UMAMI_API_URL` + `UMAMI_API_KEY` + `UMAMI_WEBSITE_ID` - Test 6.5

---

## 🧪 TESTING STRATEGY

### **Phase 1: Test Without Credentials** (Recommended Start)

Test these features that don't need any credentials:
- ✅ Group 1: Content generation (all 5 channels)
- ✅ Group 2: Thai analysis (keyword, readability, quality)
- ✅ Group 3: Context management

**Time:** 1 hour  
**Credentials needed:** None!

---

### **Phase 2: Add Image Credentials**

Add `CHUTES_API_TOKEN` and test:
- ✅ Group 4: Image generation and editing

**Time:** 30 minutes  
**Credentials needed:** Chutes AI token only

---

### **Phase 3: Add Git Credentials**

Add Git credentials and test:
- ✅ Group 5: Auto-publish to Astro

**Time:** 20 minutes  
**Credentials needed:** Git token + Chutes (optional)

---

### **Phase 4: Add Analytics Credentials** (Optional)

Add analytics credentials if you have them:
- ✅ Group 6: Analytics integrations

**Time:** 30 minutes  
**Credentials needed:** GA4/GSC/DataForSEO/Umami (any you have)

---

## 🔒 SECURITY NOTES

1. **NEVER commit .env** - It's in .gitignore for a reason!
2. **Use separate service accounts** for each service when possible
3. **Limit service account permissions** to read-only where possible
4. **Rotate tokens regularly** for security
5. **Use environment variables** in production instead of .env file

---

## 📞 TROUBLESHOOTING

### **Issue: Credentials Not Being Read**

**Check:**
```bash
# Verify .env file exists
ls -la .env

# Check it's being loaded (add to your script)
python3 -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.getenv('CHUTES_API_TOKEN', 'Not set'))"
```

---

### **Issue: GA4/GSC Authentication Failed**

**Common causes:**
- Service account doesn't have access to GA4/GSC property
- Wrong credentials path
- JSON file corrupted

**Fix:**
1. In GA4 Admin → Add user with service account email
2. Grant "Viewer" or "Analyst" role
3. Verify credentials path is absolute path

---

### **Issue: Git Push Fails**

**Common causes:**
- Token doesn't have write permissions
- Wrong Git URL
- Repository doesn't exist

**Fix:**
1. Generate new token with `repo` or `write` scope
2. Verify Git URL is correct
3. Create repository first if it doesn't exist

---

## 📖 QUICK REFERENCE

| Feature | Credentials | Test | Status |
|---------|-------------|------|--------|
| Content Generation | None | 1.1-1.3 | ✅ Ready |
| Thai Analysis | None | 2.1-2.3 | ✅ Ready |
| Context Management | None | 3.1-3.2 | ✅ Ready |
| Image Generation | CHUTES_API_TOKEN | 4.1, 4.3 | ⏳ Optional |
| Image Editing | CHUTES_API_TOKEN | 4.2, 4.3 | ⏳ Optional |
| Auto-Publish | GIT_* | 5.1 | ⏳ Optional |
| GA4 | GA4_* | 6.2 | ⏳ Optional |
| GSC | GSC_* | 6.3 | ⏳ Optional |
| DataForSEO | DATAFORSEO_* | 6.4 | ⏳ Optional |
| Umami | UMAMI_* | 6.5 | ⏳ Optional |

---

**Ready to test! Start with Phase 1 (no credentials needed).** 🚀