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.