docs/integration-guide.md

# CarouselForge — Integration Guide

Setup instructions for all external services. Fill in as each phase is completed.

---

## OpenRouter (Phase 4)
1. Sign up at openrouter.ai
2. Create API key → add to `.env.local` as `OPENROUTER_API_KEY`
3. Default model: `anthropic/claude-3-sonnet` (cost-effective for structuring)
4. Fallback: `meta-llama/llama-3-70b-instruct` (free tier)

---

## HF Inference (Phase 4)
1. Sign up at huggingface.co
2. Create access token (read) → add to `.env.local` as `HF_API_KEY`
3. Used as fallback when OpenRouter fails

---

## Apify (Phase 7)
1. Sign up at apify.com
2. Create API token → add to `.env.local` as `APIFY_API_KEY`
3. Actors used: `apify/instagram-scraper`, `apidojo/tweet-scraper`, `apify/website-content-crawler`
4. Free tier: 5$/month credit — sufficient for dev/testing

---

## Zernio (Phase 8)
1. Sign up at zernio.com (or equivalent)
2. Connect social accounts via OAuth
3. Get API key → add to `.env.local` as `ZERNIO_API_KEY`

---

## Postiz (Phase 8 — fallback)
1. Self-hosted or cloud: postiz.app
2. OAuth setup for social platforms
3. Get API key → add to `.env.local` as `POSTIZ_API_KEY`

---

## Telegram Bot (Phase 6)
1. Open Telegram → message @BotFather
2. `/newbot` → name: CarouselForge Bot
3. Copy token → add to `.env.local` as `TELEGRAM_BOT_TOKEN`
4. Set webhook URL: `{NEXT_PUBLIC_APP_URL}/api/telegram/webhook`
5. For local dev: use ngrok to expose localhost

---

## Docker + HF Spaces (Phase 14)
1. Create HF Space (Docker SDK, port 7860)
2. Add secrets in Space settings (all env vars from `.env.example`)
3. Push Dockerfile → Space auto-builds
4. SQLite DB: mount as HF Dataset for persistence

---

*Updated as each phase is completed.*