# Setup & maintenance guide

## 1. Server prerequisites (cPanel / Linux)

- Python **3.9+** (`python3 --version`)  
  On cPanel: *Software → Setup Python App* is optional; CLI + venv is enough.  
- `ffmpeg` on `$PATH` (for short videos). Ask host support if missing.  
- Outbound HTTPS allowed (Anthropic, Google, Telegram, RSS).

```bash
ffmpeg -version
python3 -m venv --help
```

## 2. Install the project

```bash
cd ~/content_generation   # or your deploy path
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
cp .env.example .env
chmod +x cron/run.sh bin/run_pipeline.py
```

## 3. Configure `.env`

| Variable | Required | Notes |
|---|---|---|
| `ANTHROPIC_API_KEY` | yes | Claude API key |
| `CLAUDE_MODEL` | no | Default Sonnet; adjust if your account uses another ID |
| `TELEGRAM_BOT_TOKEN` | prod | From [@BotFather](https://t.me/BotFather) |
| `TELEGRAM_CHAT_ID` | prod | Group or user id (use `@userinfobot` / getUpdates) |
| `GOOGLE_SERVICE_ACCOUNT_FILE` | prod | Path to JSON key |
| `GOOGLE_DRIVE_FOLDER_ID` | prod | Folder ID from Drive URL |
| `BRAND_NAME` / colors | recommended | Visual identity |
| `BATCH_SIZE` | no | Ideas per run (default 3) |
| `ENABLE_VIDEO` | no | `true`/`false` |
| `DRY_RUN` | no | Skip Drive + Telegram |

### Telegram
1. Create a bot with BotFather → copy token.  
2. Add the bot to your team group.  
3. Send a message in the group, then open  
   `https://api.telegram.org/bot<TOKEN>/getUpdates`  
   and copy `chat.id` (often negative for groups).

### Google Drive (personal My Drive — recommended)

Google **service accounts cannot upload into normal My Drive folders** (no storage quota).
Use a one-time OAuth login instead:

1. Google Cloud Console → enable **Google Drive API**
2. **APIs & Services → OAuth consent screen** (External is fine for yourself; add your email as test user)
3. **Credentials → Create credentials → OAuth client ID → Desktop app**
4. Download the JSON → save as `config/google_oauth_client.json`
5. Run once:
   ```bash
   source .venv/bin/activate
   pip install -r requirements.txt
   python bin/google_auth.py
   ```
6. Browser opens → sign in with the Google account that owns the folder  
7. Token is saved to `config/google_token.json` (gitignored)

Keep `GOOGLE_DRIVE_FOLDER_ID` pointing at your output folder.

### Google Drive (Workspace Shared Drive alternative)

If you have Google Workspace Shared Drives, you can keep the service account:
1. Create a Shared Drive → add the service-account email as **Content manager**
2. Set `GOOGLE_USE_SHARED_DRIVE=true` in `.env`
3. Point `GOOGLE_DRIVE_FOLDER_ID` at a folder inside that Shared Drive

## 4. Add your knowledge base

```bash
data/profiles/   # markdown notes on creator benchmarks
data/erp/        # proprietary ERP docs (.md / .txt / .pdf)
```

Remove or replace the sample `omniflow_overview.md` and `example_creator.md` with real material.

Optional: drop `.ttf` brand fonts into `data/fonts/`.

## 5. Test

```bash
source .venv/bin/activate

# No keys needed — verifies Pillow + ffmpeg path
python bin/run_pipeline.py --demo

# Calls Claude; writes local files only
python bin/run_pipeline.py --dry-run --batch-size 2

# Full production path
python bin/run_pipeline.py
```

Check `storage/runs/` and Telegram / Drive.

## 6. Schedule (cPanel Cron)

cPanel → **Cron Jobs** → add:

```
0 8 * * * /home/USERNAME/content_generation/cron/run.sh >> /home/USERNAME/content_generation/storage/logs/cron.log 2>&1
```

Adjust path and schedule (daily 08:00 shown).  
For twice weekly: `0 8 * * 1,4`.

## 7. Day-2 maintenance

| Task | How |
|---|---|
| Change brand colors | Edit `.env` `BRAND_*` |
| Tune idea count | `BATCH_SIZE` |
| Disable video | `ENABLE_VIDEO=false` |
| Refresh ERP messaging | Update files in `data/erp/` |
| Add competitor/creator refs | New files in `data/profiles/` |
| Change news sources | Edit `DEFAULT_FEEDS` in `src/services/news.py` |
| Rotate secrets | New values in `.env` / new SA JSON; restart not needed (cron reads each run) |
| Inspect failures | `storage/logs/pipeline.log` and `cron.log` |

### Prompt / tone adjustments
Edit `IDEATION_SYSTEM` in `src/services/ideation.py`. Keep the JSON schema intact so renderers stay compatible.

### Disk hygiene
Batches accumulate under `storage/runs/`. Monthly:

```bash
find storage/runs -maxdepth 1 -type d -name 'batch_*' -mtime +30 -exec rm -rf {} +
```

Drive remains the system of record if uploads succeed.

## 8. Troubleshooting

| Symptom | Likely fix |
|---|---|
| `Missing required env var: ANTHROPIC_API_KEY` | Create `.env` from example |
| Claude JSON parse errors | Rare; pipeline retries; check model ID / truncated output → lower `BATCH_SIZE` |
| No news in prompts | Host blocking RSS; check outbound HTTP; feeds degrade gracefully |
| Drive 403 | Folder not shared with SA email; Drive API not enabled |
| Telegram 401/400 | Bad token or chat id; bot not in group |
| Video missing / `.png` fallback | Install `ffmpeg` |
| Fonts look ugly | Add TTF to `data/fonts/` |

## 9. Handoff checklist

- [ ] `.env` filled on server (not in git)  
- [ ] SA JSON on server; Drive folder shared  
- [ ] Telegram bot posts test message  
- [ ] `--demo` and `--dry-run` succeed  
- [ ] Cron entry documented  
- [ ] Real ERP + profile docs loaded  
- [ ] Team knows who can edit prompts / brand colors