@amg555/frameforge-mcp 2.3.0 → 2.3.1

package/.claude-plugin/marketplace.json

@@ -1,17 +1,45 @@
 {
   "name": "frameforge",
-  "owner": { "name": "AMG555" },
-  "metadata": {
-    "description": "FrameForge — Enterprise AI video production engine. Localhost-first, any agentic IDE (IBM Bob, Cursor, Windsurf, Kiro, Claude Code). Cloudflare Remote MCP for ~80% token savings.",
-    "version": "1.2.0"
-  },
+  "displayName": "FrameForge — AI Video Production",
+  "description": "Full AI video production engine. Produce short-form reels (1080×1920), YouTube videos (1920×1080), or code-driven animated explainers — directly from your IDE. Playwright + FFmpeg renders every frame. 17 MCP tools.",
+  "version": "2.3.1",
+  "homepage": "https://github.com/AMG555/FrameForge",
   "plugins": [
     {
       "name": "video-pipeline",
-      "source": "./plugins/video-pipeline",
-      "description": "End-to-end overnight video production: topic research with real fact-checking (Tavily/Brave/SearXNG), script writing, voice synthesis (ElevenLabs/edge-tts/Azure/OpenAI), FFmpeg animation, quality gates, file and webhook delivery.",
-      "version": "2.3.0",
-      "keywords": ["frameforge", "video", "automation", "mcp", "tts", "ffmpeg", "ibm-bob", "enterprise", "cloudflare"]
+      "path": "plugins/video-pipeline/.claude-plugin/plugin.json",
+      "skills": [
+        {
+          "name": "video-pipeline",
+          "displayName": "FrameForge Video Pipeline",
+          "description": "End-to-end video production: research → script → TTS → images → render → publish. Three paths: (1) IDE writes scenes (most common, no API key), (2) code-driven Playwright animation, (3) auto-research pipeline. 17 MCP tools.",
+          "triggerPhrases": [
+            "make a video about",
+            "produce a reel on",
+            "create a short",
+            "edit this into a reel",
+            "make an explainer",
+            "animated video",
+            "code-driven video",
+            "generate video",
+            "run the pipeline",
+            "publish video",
+            "overnight batch",
+            "queue videos"
+          ]
+        }
+      ]
     }
-  ]
+  ],
+  "mcpServer": {
+    "command": "npx",
+    "args": ["--yes", "--package=@amg555/frameforge-mcp", "frameforge-mcp"],
+    "description": "Runs the FrameForge MCP server via npx (no install needed). Requires ffmpeg and edge-tts on PATH."
+  },
+  "requirements": {
+    "node": ">=18.0.0",
+    "binaries": ["ffmpeg", "ffprobe"],
+    "optional": ["edge-tts", "python3"],
+    "notes": "edge-tts: pip install edge-tts. Playwright (for code-driven animation): npm install playwright && npx playwright install chromium (run once in project dir)."
+  }
 }

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.3.1] — 2026-11-04
+
+### Added
+
+- **`.claude-plugin/marketplace.json`** — Claude Code plugin marketplace registration. FrameForge is now discoverable via `claude plugin marketplace add AMG555/FrameForge`.
+- **`plugins/video-pipeline/.claude-plugin/plugin.json`** — per-plugin manifest for the video-pipeline skill.
+
+### Changed
+
+- **`src/cli/setup-keys.js`** — `skip` is now the **default** option in the LLM provider menu. Users who write their own scenes (the most common path) are no longer forced through an API key section.
+- **`CLAUDE.md`** — Path 2 expanded: transcript/`cuePhrase()` word-sync workflow, `video_job.py` spend-capped batch, golden stills regression test, hook variants (A/B testing opening shots), mobile crop check, still-review budget.
+- **`START_HERE.md`** — restructured into three named paths (A: IDE-scenes, B: code-driven animation, C: auto-research). Reel vs. YouTube format choice surfaced in opening questions. Path B includes transcription, hook variants, and storyboard gate.
+- Version bump: `2.3.0` → `2.3.1` across all version strings.
+
+---
+
 ## [2.3.0] — 2026-11-02
 
 ### Added

package/CLAUDE.md

@@ -94,10 +94,14 @@ Output files appear in `.frameforge-files/`:
 
 ### Path 2 — Code-driven animated video (Playwright + FFmpeg, no AI images)
 
-Use this when: the user wants motion graphics, Pollinations is unavailable, or they ask for "animated" or "code-rendered" video. Every frame is a pure function of time `t`.
+Use this when: the user wants motion graphics, Pollinations is unavailable, or they ask for "animated", "code-rendered", "explainer", "reel", or "YouTube-style" video. Every frame is a pure function of time `t`.
 
 > **Iron rule:** Never use `Math.random()`, `Date.now()`, `setTimeout`, or module-level mutable state in scene code. Use `hash(i)` from `reel/engine.js` for deterministic randomness.
 
+**Pick a format first:**
+- **Reel / Short / TikTok** → `width: 1080, height: 1920` (portrait 9:16)
+- **YouTube / Explainer** → `width: 1920, height: 1080` (landscape 16:9)
+
 **Step 0 — Beat sheet first. Always. No exceptions.**
 
 Before writing any scene code, reply to the user with:
@@ -106,17 +110,22 @@ Before writing any scene code, reply to the user with:
 
 **Stop and wait for approval before Step 1.** Fixing a beat sheet costs one message. Rewriting a finished scene costs everything.
 
-**Step 1 — Generate TTS first (exact timing is ground truth):**
+**Step 1 — Generate TTS and transcription (exact timing is ground truth):**
 ```
 multi_voice_tts({ text: "Full narration text.", outputPath: ".frameforge-files/voice_0.m4a" })
 ```
+Then transcribe for word-level timestamps (required for `cuePhrase()` sync):
+```
+// run in projectDir after scaffold: python scripts/transcribe.py .frameforge-files/voice_0.m4a
+// → produces voice_0.captions.json with per-word start/end times
+```
 
 **Step 2 — Scaffold the project:**
 ```
 scaffold_animation_project({
   outDir: ".frameforge-files/my-animation/",
   title: "My Video",
-  width: 1920, height: 1080,
+  width: 1920, height: 1080,   // or 1080×1920 for portrait reel
   scenes: [{ narration: "...", caption: "...", visual_description: "..." }],
   audioPath: ".frameforge-files/voice_0.m4a"
 })
@@ -138,16 +147,49 @@ validate_storyboard({ storyboardPath: ".frameforge-files/my-animation/STORYBOARD
 - Read `ANIMATION_GUIDE.md` in the project folder first
 - Every style must be a **pure function of `t`**
 - Use `layer('name').on(t => ({ ...styles }))` for each scene
+- Sync animation to narration using `cuePhrase('the exact words spoken')` — this reads `voice_0.captions.json` and returns the frame when those words start. **The build fails if the phrase isn't found**, so re-recording VO can never silently desync the animation.
 
 **Step 5 — Pre-flight, then stills, then full render:**
 ```
 render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "look" })       // fonts, assets, NaN checks
 render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "sheet" })      // contact sheet — inspect this
 render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "strip", timestamps: [2.1, 2.6] })  // motion check
+render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "crop", timestamps: ["9:16", 3.0] })  // mobile check
 render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "full",
                    audioPath: ".frameforge-files/voice_0.m4a" })                         // only after stills pass
 ```
 
+**Still review budget (minimum, before full render):**
+- At least one `sheet` per shot
+- One `strip` per key motion or transition
+- One `crop` per story-carrying face or detail
+
+**Step 6 — Optional: hook variants**
+
+For reels and Shorts, make 2–3 versions with different opening hooks:
+- Change only the first shot (0s–3s) in `edit.js`
+- `render_animation({ mode: "stills", timestamps: [0.0, 1.5, 3.0] })` to compare openings
+- Full render each variant, deliver as `hook_a.mp4`, `hook_b.mp4`, etc.
+
+**Step 7 — Optional: unattended / spend-capped batch**
+```
+// run from projectDir
+python scripts/video_job.py submit --spec spec.json --max-usd 2.00
+// → { jobId }  — detached process, survives your session closing
+python scripts/video_job.py status --id <jobId>
+python scripts/video_job.py result --id <jobId>
+```
+Each step only starts if the running cost won't exceed `--max-usd`. Receipts go to `jobs/receipts.jsonl`.
+
+**Step 8 — Golden stills regression test (before any refactor)**
+
+After the video passes QC, save the test stills:
+```
+render_animation({ projectDir, mode: "storyboard" })  // 4 keyframes, file to out/storyboard.jpg
+// → copy out/storyboard.jpg to test/golden/storyboard.jpg
+```
+Before future refactors, re-run and compare. If pixels shift, the refactor broke determinism.
+
 > Requires one-time setup in the project directory: `npm install playwright && npx playwright install chromium`
 
 ---

package/README.md

@@ -6,9 +6,10 @@
 
 **Any IDE. Any topic. Any style. 1080p videos from a single prompt.**
 
+[![npm](https://img.shields.io/npm/v/@amg555/frameforge-mcp.svg?label=npm)](https://www.npmjs.com/package/@amg555/frameforge-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.3.1-blue.svg)](CHANGELOG.md)
 [![MCP Spec](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io/)
 [![Tests](https://img.shields.io/badge/tests-512%20passing-brightgreen.svg)](#testing)
 
@@ -272,6 +273,16 @@ Every video passes 7 checks before delivery. Any failure blocks the output.
 
 ## CLI commands
 
+**Via npx (no clone needed):**
+
+| Command | What it does |
+|---------|-------------|
+| `npx --package=@amg555/frameforge-mcp frameforge-setup` | Interactive key wizard — saves to `~/.frameforge/config.json` |
+| `npx --package=@amg555/frameforge-mcp frameforge-doctor` | Check Node, FFmpeg, edge-tts, and env vars |
+| `npx --package=@amg555/frameforge-mcp frameforge --topic "..."` | Full pipeline: research → render → deliver |
+
+**Via cloned repo:**
+
 | Command | What it does |
 |---------|-------------|
 | `npm run doctor` | Check Node, FFmpeg, edge-tts, and env vars |
@@ -323,7 +334,14 @@ Report vulnerabilities: [SECURITY.md](SECURITY.md)
 
 ## Deployment
 
-**VPS / Pi / local machine:**
+**npx (no install — recommended for users):**
+
+```bash
+npx --package=@amg555/frameforge-mcp frameforge-setup
+# then add the IDE config from the quickstart above
+```
+
+**VPS / Pi / self-hosted (cloned repo):**
 
 ```bash
 git clone https://github.com/AMG555/FrameForge.git && cd FrameForge

package/START_HERE.md

@@ -17,18 +17,20 @@ produce it — from research through render to final MP4.
 
 ## Opening Message (say this verbatim to the user)
 
-> 👋 I'm your FrameForge video studio. I can make short-form reels, YouTube explainers,
-> documentary clips, tutorials, or any video you describe — using AI research, voiceover,
-> animated scenes, and a full render pipeline.
+> 👋 I'm your FrameForge video studio. I can make:
 >
-> Let's start with a few quick questions so I know exactly what to build:
+> - **Short-form reels** (Instagram, TikTok, YouTube Shorts — 15–60s, 9:16 portrait)
+> - **YouTube videos** (explainers, tutorials, long-form — 3–15 min, 16:9 landscape)
+> - **Code-driven animated explainers** (motion graphics, no stock images needed — any length)
+>
+> Let's start with a few quick questions:
 >
 > 1. **What's the topic or idea?** (e.g. "How black holes form", "5 tips for sourdough bread", "A travel reel about Tokyo")
-> 2. **What style?** Pick one: `educational` · `comedic` · `documentary` · `vlog` · `cinematic` · `tutorial` · or describe your own
-> 3. **How long?** `Short (15–60s)` · `Medium (1–3 min)` · `Long (5–10 min)`
-> 4. **Orientation?** `Landscape 16:9 (YouTube/desktop)` · `Portrait 9:16 (Reels/TikTok/Shorts)`
+> 2. **Format?** `Reel / Short / TikTok (9:16)` · `YouTube video (16:9)` · `Animated explainer (any)`
+> 3. **Style?** `educational` · `comedic` · `documentary` · `cinematic` · `tutorial` · or describe your own
+> 4. **How long?** `Short (15–60s)` · `Medium (1–3 min)` · `Long (5–10 min)`
 > 5. **Voice?** `Auto-select` · or name a style: `professional narrator`, `friendly teacher`, `energetic host`
-> 6. **Any images or clips you want included?** (paste file paths, or say "no — generate everything")
+> 6. **Any footage, images, or audio to include?** (paste file paths, or say "generate everything")
 >
 > Answer as many or as few as you like. I'll fill in the rest.
 
@@ -36,16 +38,24 @@ produce it — from research through render to final MP4.
 
 ## After the User Answers — Agent Instructions
 
-Once you have the user's answers, proceed as follows. Never skip the beat-sheet gate.
+Once you have the user's answers, choose the right render path and follow it precisely.
+
+---
+
+## Render Paths
 
-### Step 1 — Beat Sheet Gate (MANDATORY, no exceptions)
+### PATH A — IDE-written scenes (fastest, most common)
 
-Before calling any render tool, produce a **beat sheet** in this exact format and
-**stop** — wait for the user to approve it before continuing:
+Use for: any video where you (the IDE agent) write the narration and visual descriptions.
+No LLM key needed — FrameForge generates TTS + AI images and renders with FFmpeg.
+
+**Step A1 — Beat Sheet Gate (MANDATORY)**
+
+Before calling any render tool, produce a beat sheet and **stop** — wait for approval:
 
 ```
 BEAT SHEET — "<title>"
-Duration: Xs  |  Style: <style>  |  Format: <orientation>
+Duration: Xs  |  Style: <style>  |  Format: <landscape/portrait>
 
 Scene 1  [0:00–0:08]  <what happens + what the viewer learns>  →  TRANSITION
 Scene 2  [0:08–0:18]  <what happens + what the viewer learns>  →  TRANSITION
@@ -56,43 +66,89 @@ Voice: <voice description>
 Visual style: <1-sentence description>
 ```
 
-Gate rules — reject and revise the beat sheet if ANY of these are true:
+Gate rules — revise if ANY are true:
 - A scene has no event (action that changes something)
 - Two scenes share the same timestamp range
 - Any seam is missing a transition label
-- The total duration doesn't match the user's requested length ±10%
+- Total duration doesn't match requested length ±10%
 
-Only proceed to Step 2 after the user says **"looks good"**, **"go ahead"**, or equivalent.
+**Step A2 — Render**
 
-### Step 2 — Research (if the topic needs facts)
+```
+create_video_from_script({
+  scenes: [ { narration: "...", caption: "...", visual_description: "...", camera_hint: "zoom_in" } ],
+  title: "My Video",
+  orientation: "landscape",   // "portrait" for Reels/Shorts/TikTok
+  voice: "en-US-BrianNeural", // or use language: "en"
+  withMusic: true
+})
+```
 
-Use `research_topic` to gather verified claims. Skip this for pure creative/style videos.
+**Step A3 — Publish**
 
-### Step 3 — Script
+Ask: "Save locally, or deliver somewhere?" Then call `publish_video`.
 
-Use `write_script` with the beat sheet as the outline. Pass `style`, `format`, and
-`voice` from the user's answers. The script must match the beat sheet scene-for-scene.
+---
 
-### Step 4 — Assets
+### PATH B — Code-driven animated video (motion graphics, explainers, reels)
 
-For each scene, call `generate_scene_image` with a prompt that matches the scene's
-visual description. If the user supplied their own files, use `ingest_media` instead.
+Use for: motion graphics, animated explainers, reels that must look high-quality without stock images.
+Requires one-time: `npm install playwright && npx playwright install chromium` (run in the project dir).
 
-Call `render_tts` for each scene's narration line.
+**Step B1 — Beat sheet first (same gate as Path A — MANDATORY)**
 
-### Step 5 — Render
+**Step B2 — TTS and transcription**
 
-Call `create_video_from_script` (IDE-driven path) or `assemble_video` (pipeline path)
-to produce the final MP4.
+```
+multi_voice_tts({ text: "Full narration.", outputPath: ".frameforge-files/voice_0.m4a" })
+// After scaffolding: python scripts/transcribe.py .frameforge-files/voice_0.m4a
+// → voice_0.captions.json — word timestamps for cuePhrase() sync
+```
 
-After render, call `render_animation` with `mode: "sheet"` to produce a contact-sheet
-preview. Show the user the sheet path and ask if they want any changes.
+**Step B3 — Scaffold**
 
-### Step 6 — Publish (optional)
+```
+scaffold_animation_project({
+  outDir: ".frameforge-files/my-animation/",
+  title: "My Video",
+  width: 1920, height: 1080,   // 1080×1920 for portrait reels
+  scenes: [...],
+  audioPath: ".frameforge-files/voice_0.m4a"
+})
+```
 
-Ask the user: "Do you want to publish this anywhere, or just save the file locally?"
+**Step B4 — Validate STORYBOARD.md**
 
-If they want to publish, call `publish_video` with their chosen channel.
+```
+validate_storyboard({ storyboardPath: ".frameforge-files/my-animation/STORYBOARD.md" })
+```
+
+**Step B5 — Write `edit.js`, then stills, then full render**
+
+```
+render_animation({ projectDir: "...", mode: "look" })           // pre-flight
+render_animation({ projectDir: "...", mode: "sheet" })          // one sheet per shot
+render_animation({ projectDir: "...", mode: "strip", timestamps: [2.1, 2.6] })  // motion check
+render_animation({ projectDir: "...", mode: "full", audioPath: ".frameforge-files/voice_0.m4a" })
+```
+
+**For reels: make 2–3 hook variants** (change only the first 3s of `edit.js`, full-render each):
+```
+render_animation({ projectDir: "...", mode: "stills", timestamps: [0.0, 1.5, 3.0] })
+// deliver hook_a.mp4, hook_b.mp4 so the user can A/B test
+```
+
+---
+
+### PATH C — Auto-research (needs `PROVIDER_LLM` + key in `.env`)
+
+Use for: overnight batch, topics where you want FrameForge to research and script everything.
+
+```
+queue_full_pipeline({ topic: "How GPS works", style: "educational" })
+→ { jobId }
+get_job_status({ jobId })   // poll every 30s
+```
 
 ---
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 17 MCP tools.",
   "publishConfig": {
     "access": "public"
   },
   "main": "src/mcp-server/server.js",
   "bin": {
-    "frameforge":        "src/cli/make.js",
-    "frameforge-mcp":    "src/mcp-server/stdio.js",
-    "frameforge-setup":  "src/cli/setup-keys.js",
+    "frameforge": "src/cli/make.js",
+    "frameforge-mcp": "src/mcp-server/stdio.js",
+    "frameforge-setup": "src/cli/setup-keys.js",
     "frameforge-doctor": "src/cli/doctor.js"
   },
   "scripts": {
@@ -55,6 +55,6 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AMG555/FrameForge"
+    "url": "git+https://github.com/AMG555/FrameForge.git"
   }
 }

package/src/cli/setup-keys.js

@@ -171,6 +171,15 @@ async function main() {
 This wizard writes your provider API keys to: ${path.resolve(outFile)}
 Keys are never sent anywhere — they stay on your machine.
 Press Enter to accept a default. Ctrl+C to cancel.
+
+  ✅  No keys are required to make videos.
+      Your IDE writes the scenes — FrameForge uses free providers by default:
+        • edge-tts  — free voice (no account)
+        • pollinations — free images (no account)
+        • FFmpeg — free local render (already on your machine)
+
+      You only need keys for the auto-research pipeline (FrameForge writes the
+      script itself). Skip those sections if you plan to write scenes yourself.
 `);
 
   const cfg = {};
@@ -178,22 +187,27 @@ Press Enter to accept a default. Ctrl+C to cancel.
   // ── LLM ──────────────────────────────────────────────────────────────────
   section('1 / 5  —  LLM Provider  (research + script generation)');
   console.log('  Used for: researching topics, writing scripts, fact-checking.');
+  console.log('  ⚡ SKIP THIS if your IDE agent writes the scenes (most common path).');
   console.log('  Free option: Groq (no credit card needed for free tier).\n');
 
   cfg.PROVIDER_LLM = await menu('Choose LLM provider', [
+    ['skip',       '⏭  Skip — I write my own scenes (most common, no key needed)'],
     ['groq',       'Groq — free, fast (llama-3.3-70b). Get key: console.groq.com'],
     ['cerebras',   'Cerebras — fastest inference (2000+ tok/s). Get key: cloud.cerebras.ai'],
+    ['gemini',     'Google Gemini 2.0 Flash — free tier. Get key: aistudio.google.com'],
     ['openrouter', 'OpenRouter — all models with one key. Get key: openrouter.ai'],
     ['anthropic',  'Anthropic Claude Sonnet 4.5. Get key: console.anthropic.com'],
-    ['gemini',     'Google Gemini 2.0 Flash. Get key: aistudio.google.com'],
     ['mistral',    'Mistral Large. Get key: console.mistral.ai'],
     ['together',   'Together AI Llama-3.3-70B-Turbo. Get key: api.together.ai'],
     ['openai',     'OpenAI GPT-4o. Get key: platform.openai.com'],
     ['ollama',     'Ollama — fully local, no key needed. Install: ollama.com'],
     ['webhook',    'Custom/VoxForge/any OpenAI-compatible endpoint'],
-  ], 'groq');
+  ], 'skip');
 
-  if (cfg.PROVIDER_LLM === 'groq') {
+  if (cfg.PROVIDER_LLM === 'skip') {
+    console.log('  ✅  LLM skipped — your IDE will write scenes via create_video_from_script.\n');
+    cfg.PROVIDER_LLM = undefined; // don't write to config
+  } else if (cfg.PROVIDER_LLM === 'groq') {
     cfg.GROQ_API_KEY = await askSecret('  Groq API key (starts with gsk_)');
   } else if (cfg.PROVIDER_LLM === 'cerebras') {
     cfg.CEREBRAS_API_KEY = await askSecret('  Cerebras API key');

package/src/mcp-server/server.js

@@ -1120,7 +1120,7 @@ Requires: npm install playwright && npx playwright install chromium (one-time se
 
 const SERVER_INFO = {
   name:    'video-pipeline',
-  version: '2.3.0',
+  version: '2.3.1',
 };
 
 const CAPABILITIES = {