Your IDE agent writes this:              FrameForge renders this:
──────────────────────────               ─────────────────────────
scenes: [                                final_video_1080p.mp4 ✓
  { narration: "...",                    short_1_vertical.mp4  ✓
    caption: "OVERLAY",                  video_meta.json       ✓
    visual_description: "..." }          → Telegram / YouTube
]

node --version    # need ≥ 18
ffmpeg -version   # need ≥ 5.0   (brew install ffmpeg / apt install ffmpeg)
npm install -g edge-tts   # free offline TTS — no account needed

git clone https://github.com/AMG555/FrameForge.git
cd FrameForge
npm run doctor        # pre-flight check — tells you what's missing
npm run setup         # interactive key wizard (~2 min)

GROQ_API_KEY=gsk_...         # free tier — console.groq.com
PROVIDER_LLM=groq
PROVIDER_TTS=edge-tts        # free, offline — no key needed
PROVIDER_IMAGE=pollinations  # free — no key needed

npm run make -- --topic "How does GPS actually work?"

final_video_<id>.mp4    1080p landscape master
short_1_<id>.mp4        auto-extracted 9:16 vertical Short
video_meta.json         title, description, tags, chapter markers
usage.ndjson            per-call cost log

cd cloudflare-mcp
npm install
wrangler secret put WORKER_API_URL      # https://your-render-app.onrender.com
wrangler secret put MCP_AUTH_TOKEN      # any 32-byte hex string
wrangler secret put INTERNAL_API_TOKEN  # different 32-byte hex string
wrangler deploy

{
  "mcpServers": {
    "frameforge": {
      "url": "https://video-mcp.YOUR_SUBDOMAIN.workers.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
    }
  }
}

{
  "mcpServers": {
    "frameforge": {
      "command": "node",
      "args": ["/absolute/path/to/FrameForge/src/mcp-server/stdio.js"],
      "env": {
        "GROQ_API_KEY": "gsk_...",
        "PROVIDER_LLM": "groq",
        "PROVIDER_TTS": "edge-tts",
        "PROVIDER_IMAGE": "pollinations"
      }
    }
  }
}

create_video_from_script({
  scenes: [
    {
      narration: "WiFi sends data as invisible radio waves at 2.4 or 5 GHz.",
      caption: "RADIO WAVES",
      visual_description: "router emitting concentric waves, flat design, bold colors"
    },
    {
      narration: "Your laptop picks up the signal and decodes the packets instantly.",
      caption: "YOUR DEVICE",
      visual_description: "laptop with signal bars, white background, minimal illustration"
    }
  ],
  imageStyle: "flat design, white background, bold primary colors"
})
→ { masterPath: "/files/final_video_abc123.mp4", passed: true, sceneCount: 2 }

1. research_topic({ topic: "How GPS works", style: "educational", format: "YouTube short" })
2. write_script({ ...claims, persona: "tech explainer", language: "en", targetDuration: 60 })
3. render_from_scenes({ productionId, skipImages: false })

{
  "narration": "Here is the sorting algorithm running step by step.",
  "caption": "ALGORITHM",
  "video_path": "/recordings/screen_capture.mp4",
  "audio_path": "/recordings/my_voice.mp3"
}

YOUR IDE (IBM Bob / Codex / opencode / Cursor / Windsurf / Claude Code)
         │
         │  HTTPS + SSE  (Cloudflare Remote MCP)
         ▼
[Cloudflare Workers]   ← caches schemas, proxies tool calls, keeps IDE context lean
         │
         │  HTTP + INTERNAL_API_TOKEN
         ▼
[FrameForge Node]  ← runs on Render free / VPS / Pi / your machine
         │
         ├─ src/pipeline/
         │   ├─ providers.js        10 LLM + 5 TTS + 5 Image providers
         │   ├─ state-machine.js    file + PostgreSQL production state
         │   ├─ retry-policy.js     exponential backoff, FATAL/NON_RETRYABLE/RETRYABLE
         │   ├─ telemetry.js        NDJSON cost tracking per provider
         │   ├─ artifact-manifest.js  content-addressed idempotency manifest
         │   └─ artifact-retention.js permanent / 30-day / temp sweep
         │
         ├─ src/workflows/
         │   ├─ research.js   research + fact extraction
         │   ├─ script.js     scene schema v2.0.0 generation + normalisation
         │   ├─ assets.js     parallel image gen + TTS (configurable concurrency)
         │   ├─ render.js     FFmpeg zoompan + captions + quality gate
         │   ├─ shorts.js     silence segmentation + focal-point 9:16 crop
         │   ├─ packaging.js  manifest + metadata JSON
         │   └─ publishing.js Telegram + YouTube OAuth2
         │
         ├─ src/mcp-server/
         │   ├─ server.js   HTTP MCP (port 3210) — 13 tools
         │   └─ stdio.js    stdio MCP — same 13 tools
         │
         └─ src/worker/
             ├─ server.js              full worker (local / VPS)
             └─ server-render-free.js  Render.com free tier (api_only mode)
                                       delegates FFmpeg to LOCAL_RENDER_URL

Render free tier  ← research, script, assets, packaging, publishing
Your local machine ← render, shorts (FFmpeg, ~800 MB RAM peak)

cp docs/env.template .env
# then edit .env — minimum:
GROQ_API_KEY=gsk_...
PROVIDER_LLM=groq
PROVIDER_TTS=edge-tts
PROVIDER_IMAGE=pollinations

[Unit]
Description=FrameForge MCP Server
After=network.target

[Service]
User=node
WorkingDirectory=/home/node/FrameForge
EnvironmentFile=/home/node/FrameForge/.env
ExecStart=/usr/bin/node src/mcp-server/server.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable frameforge
sudo systemctl start  frameforge
sudo journalctl -fu   frameforge

npm run make -- \
  --topic "How GPS works" \
  --style educational \       # educational | comedic | documentary | vlog | tutorial
  --format "YouTube short" \  # YouTube video | YouTube short | Instagram reel | explainer
  --language en \             # BCP-47 code
  --no-publish \              # render only, skip delivery
  --no-shorts \               # skip vertical crop
  --channels telegram,youtube

npm test