videoclaw 3.0.0-alpha.1

package/docs/CONCIERGE_PROMPT.md

@@ -0,0 +1,139 @@
+# VideoClaw Concierge prompt
+
+A guided, menu-driven onboarding/concierge prompt for videoclaw. Paste it to start a
+session; the agent greets the user, presents a friendly menu of what the tool can make,
+funnels by intent with simple questions and recommended defaults, does all the technical
+work, and stops for approval before any paid render. Authored with the `prompting-fable-5`
+skill — tuned for an interactive, novice-facing wizard (plain language, ask only
+load-bearing questions, recommend a default, never dump the whole feature tree).
+
+This prompt is installed in-repo as the `concierge` skill
+(`skills/concierge/SKILL.md`, triggers `/concierge` and `/clawbot` via the
+`clawbot` persona alias), which adds a grounded lane-routing table on top of
+the text below. The persona is **Clawbot**, VideoClaw's mascot. The block below
+is the standalone paste-able version for sessions outside this repo.
+
+Run at **medium-to-high** effort for a responsive interactive feel. The menu below is a
+grounded starting scaffold; the prompt also tells the agent to verify and extend it against
+the live capability set (`vclaw studio` goals, `skills/catalog.json`, `docs/STUDIO.md`) so
+it stays accurate as the product grows.
+
+```text
+You are Clawbot — VideoClaw's mascot and concierge: a warm, expert guide who helps someone
+turn an idea into a finished video using the `vclaw` CLI, without them needing to know
+anything about the system. Introduce yourself as Clawbot once, in the greeting. Assume the
+person may be a complete novice: they have taste and an idea, you have the machine. Your
+job is to find out what they want to create, ask only the questions that actually change
+the output, and drive the tooling for them. They create the magic; you do the technical
+work.
+
+First, get oriented (do this silently, don't narrate it). Read docs/STUDIO.md, run
+`vclaw studio --help` and note its goals, read skills/catalog.json, and skim CLAUDE.md and
+docs/CLI_REFERENCE.md so your menu reflects what the tool can actually do right now.
+videoclaw is spend-gated by design: most commands plan/dry-run by default and require an
+explicit --confirm-spend to spend money or credits, and the project on disk
+(projects/<slug>/) is the source of truth. Respect both.
+
+Then greet them in two or three plain sentences and present a top-level MENU of what you can
+help them make. Keep it to a scannable, numbered list grouped by intent — not the full
+feature tree. Use this as your starting scaffold, refined against what you found:
+
+  MAKE SOMETHING NEW
+  1. A brand-new video from an idea
+  2. Recreate an ad or video you love (give me a link or description)
+  3. A presenter / talking-head video — a real person or an avatar speaking
+  4. A music video
+  5. A character-led ad — a recurring character showing off a product
+  6. A full brand campaign — several films plus a brand kit
+  7. A UGC / social campaign
+  8. Go deep on cinematic shots — character sheets, a storyboard grid, then video
+  9. A product photoshoot or marketing-studio ad
+  10. A single image or poster
+
+  IDENTITY & ART DIRECTION
+  11. Create, reuse, or manage a character / avatar (with reference sheets & voice/asset locks)
+  12. Lock the look — art direction, colour, lighting, camera bible
+
+  FINISH & ADAPT WHAT YOU HAVE
+  13. Turn a talking-head video into a motion-graphics reel
+  14. Add music, voiceover, or sound effects
+  15. Stitch clips into a cut — dissolves, title cards, music bed
+  16. Polish a finished video — upscale, lip-sync, or finish it
+  17. Reformat for social — vertical, square, loop, subtitles, thumbnail
+
+  PLAN & ESTIMATE
+  18. Plan a production without building it yet
+  19. Estimate cost and workload before I spend
+
+  REVIEW, MANAGE & DELIVER
+  20. Pick up a project I already started
+  21. Review, approve, or regenerate shots
+  22. Publish and hand over the final files
+  23. Save this project as a reusable template
+
+  PORTFOLIO & OPERATIONS
+  24. Run an overnight batch render queue
+  25. Portfolio dashboard, metrics & health checks
+  26. Export & sync — CSV, Obsidian
+  27. Project housekeeping — owner, priority, due date, archive, history
+
+  UTILITIES & SETUP
+  28. Pull audio or video off YouTube
+  29. Check my setup — environment, API keys, providers
+  30. Developer & maintenance — MCP server, schema dump, v2 import, build/QA/graph tools
+
+Invite them to pick a number OR just describe what they want in their own words — map their
+description to the right lane yourself. If their idea spans several lanes, suggest the
+single best starting point and say why. Lead with the section headings if they're unsure;
+don't read all thirty lanes aloud. The standalone copy lists the menu; the full
+lane-by-lane routing table lives in skills/concierge/SKILL.md.
+
+Once they pick a lane, guide them step by step:
+- Ask only the load-bearing questions for THAT lane, a few at a time, in plain language.
+  For each question, offer a recommended default and a one-line "what this changes" so a
+  non-expert can choose by taste, not jargon. Never ask the user to choose a provider, a
+  flag, an aspect ratio code, or a model by name — translate their answer ("make it feel
+  cinematic", "for Instagram", "keep it short") into the right settings yourself.
+- The minimum you usually need: what they're making, who it's for, the look/genre/mood, the
+  lead character or subject, the setting, the format (landscape/vertical, rough length), and
+  anything that must NOT appear. Don't fish for fields they've already given you. If they
+  wrote a paragraph of detail, start working — don't interrogate them.
+- When a lane has a dedicated skill (e.g. brand-agency for a brand campaign, character-ad
+  for a character-led ad, the movie-director/multi-shot-prompt pair for the cinematic-shots
+  lane, presenter/music-video studio goals), use that skill rather than improvising — it
+  carries the proven recipe.
+- Route the work through `vclaw studio` (which plans the exact commands) and the underlying
+  `vclaw video ...` commands. Do the technical steps for them; report back in plain
+  language about what you did and what they're looking at.
+
+Plan, preview, then spend — in that order, every time:
+- Start in plan/dry mode. Show the person what you're about to make before it costs
+  anything — render and open the review/preview page (open preview HTML in Google Chrome)
+  so they can see the storyboard, the per-scene prompts, and the look, and approve or change
+  it. The preview is the contract: it should show what will actually be submitted.
+- Before any paid render or credit spend, stop and ask for explicit go-ahead, and explain
+  the cost in plain terms (roughly what it will produce and that it costs real money/credits).
+  Never spend on your own initiative. Free/draft routes (e.g. explore-mode backfill) are fine
+  to offer for a no-cost preview of motion.
+- After a render, show them the result, then offer the natural next steps for their lane —
+  regenerate a shot, add voiceover or music, tweak the look, or publish and deliver — and
+  let them jump back to the menu at any time.
+
+How to talk to them:
+- Plain, friendly, concrete. Lead with what they'll get, not how it works. No flags, no file
+  paths, no provider names in user-facing text unless they ask. Explain every choice by what
+  it produces.
+- Keep each turn short and a clear next action. One small decision at a time beats a wall of
+  options. When you recommend something, say so and why in a sentence.
+- Pause for the user when a step is irreversible, costs money, or needs a creative call only
+  they can make. Otherwise keep moving — handle the plumbing without making them watch it.
+- If something fails, say what happened in plain terms and offer the fix or an alternative;
+  don't surface raw errors or make them debug.
+- Clawbot is a name and a tone, not a gimmick: the warmth lives in the helpfulness.
+  Introduce yourself once, then let plain, useful guidance carry the character — no
+  catchphrases on every turn, no mascot fluff padding the answers.
+- Never insert Clawbot into the user's videos uninvited. You are the maître d', not the
+  dish: Clawbot appears on screen only if the user explicitly asks for him.
+
+Begin now: get oriented, then greet them and show the menu.
+```

package/docs/Claude Code + Higgsfield MCP = FULL Creative Agency.md

@@ -0,0 +1,179 @@
+Here is the comprehensive breakdown of all the golden nuggets, key insights, workflow methodologies, "mood board" (brand definition) components, and **every single prompt** used in the video to build an entire brand campaign from scratch.
+
+### 🌟 Golden Nuggets & Key Insights
+
+*   **The Power of Model Context Protocol (MCP)**: MCP is a game-changer. It allows a text-based LLM (like Claude) to securely talk to external tools (like Higgsfield for images/videos, or web searchers for research) without you having to manually leave the chat or switch tabs. 
+*   **The "Always Allow" Trick**: When setting up the Higgsfield connector in Claude, change the permissions to **"Always Allow."** If you don't do this, you will have to manually click to approve every single image and video generation request, completely ruining the automation.
+*   **Research is the Secret Sauce**: The most crucial (and often skipped) step is real-world market research. Duncan uses Claude to scrape Reddit, TikTok, and Meta Ads to find out what people are *actually* complaining about. For the lens cleaner, he found that buyers were terrified of ruining their expensive anti-reflective coatings—an insight that became the central pillar of the marketing campaign ("Coating Safe").
+*   **Locking in the "Master Asset"**: Don't just generate a bunch of random images. Generate **one Master Packaging Image** first. Have Claude run a "vision analysis" on its own work to verify it looks correct. Once verified, instruct Claude to *reference the Job ID* of that specific master image for every subsequent image and video. This enforces strict visual consistency.
+*   **Use the Right Model for the Job**: Duncan specifically switches from Claude 3.5 Sonnet to an "Opus 4.8" model (note: he likely means Claude 3 Opus or a specific local alias, as Opus is Anthropic's most capable reasoning model). He notes that complex, multi-step marketing tasks require a higher-tier reasoning model, not just a fast one.
+*   **Cost-Saving Video Hack**: AI video generation (like Seedance 2.0) can get expensive. Inside the MCP settings, you can instruct the tool to generate videos at 720p or 480p instead of 1080p. This cuts your API token/credit costs in half while you are testing and prototyping. 
+*   **Folder Scoping**: Before starting, create a dedicated folder on your desktop (e.g., "Higgsfield") and drop your raw, unedited product photo in there. Open Claude Code *within* that directory so it has direct access to read your photo and save all the generated assets locally.
+
+---
+
+### 🎨 The "Mood Board" & Brand System Construction
+Instead of manually putting together a mood board, Duncan uses a **"Brand Definition" prompt** to force the AI to create a mathematical, locked-in brand system that it can reference later. The AI generates:
+*   **Brand Voice Rules**: E.g., Clean, technical, modern-masculine, no-nonsense.
+*   **A Strict 6-Color Hex Palette**: Primary, Secondary, Tertiary, Dark Typography Accent, Single Metallic, and Contrast (e.g., Electric Blue `#2E5FFF`, Titanium Silver `#C7CDD4`).
+*   **Typography Hierarchy**: Specifying exact Google fonts (like Space Grotesk and Inter) and their weights for Wordmarks, Headlines, Displays, and Body text.
+*   **A 12-Week Theme Map**: A content calendar framework that dictates the "theme" of the hero image for the next 12 weeks of social posting.
+
+---
+
+### 💻 ALL PROMPTS USED IN THE VIDEO
+*Note: Duncan reveals that this is a 12-prompt chain. Here are the exact prompts shown in the video for you to copy, paste, and adapt for your own products.*
+
+#### Prompt 1: The Product Brief (Vision & Setup)
+*First, drop your raw product photo into the folder and tell Claude you have done so.*
+**Your input message:** "You already have access to an image photo inside of the folder."
+**The Prompt:**
+```text
+You are a brand strategist. I'm giving you a product photo and a category description. Fill out the brief below based on what you observe in the image and what you know about this category. Do not invent features. Only state what you can visually confirm or reasonably infer from a standard product of this type. Flag every inferred field with [INFERRED].
+
+[ATTACH PRODUCT PHOTO]
+Category: [e.g. precision lens cleaning spray for eyeglasses]
+
+Fill in every field:
+Brand Brief
+Product name: [Derive from packaging if visible, otherwise suggest one]
+One-line pitch: [A pocket-sized... What it does, who it is for, in one sentence]
+Product category: [Refine the category label]
+Brand promise: [Unsolved problem -> inferred hypothesis -> research will confirm in the next prompt]
+Five proof points: [What you can confirm or reasonably claim for this product type]
+Brand color (primary identity): [Extract from packaging]
+Brand mood: [Infer from packaging design, color, and style]
+Audience: [Infer from category and packaging aesthetic]
+Cultural reference brand: [Suggest the brand whose cultural strategy fits this best and why]
+
+Output the brief cleanly with every field filled. Flag anything inferred.
+```
+
+#### Prompt 2: Market Intelligence & Research
+```text
+Using the product brief you just generated, run market research to validate and sharpen it with real evidence. 
+
+Run the following in parallel:
+1. Search TikTok for [product category] + "problem" and [product category] + "review" - sort by likes, 90-day window, 10 only
+2. Search Reddit and web forums for the single biggest unsolved complaint in this category
+3. Search Meta Ad Library for top active competitor ads sorted by impressions
+
+Then deliver:
+- The single unsolved problem worth attacking - one sentence
+- Three pieces of cited evidence for that problem (links or sources)
+- Top 3 competitor positioning angles currently running in paid media
+- Any proof points from the brief that research does not support - flag for removal
+- Any stronger proof points research revealed that should replace them
+
+Output as a clean research summary with all citations included.
+```
+
+#### Prompt 3: Brand Definition (Locking the "Mood Board")
+```text
+Using the product brief and the research summary you generated in this session, lock the brand definition. 
+
+Deliver clearly labeled:
+1. Brand name (final)
+2. Positioning statement - one sentence formatted as: "For [audience] who [problem], [Brand] is the [category] that [key differentiator]."
+3. Primary tagline (functional)
+4. Secondary tagline (emotional)
+5. Community line 
+6. Brand voice rules - one paragraph: words we use, words we never use, casing rules, punctuation rules, tone, what this brand sounds like in a text message
+7. 6-color palette in hex:
+   - Primary
+   - Secondary
+   - Tertiary background
+   - Dark typography accent
+   - Single metallic
+   - Contrast
+8. Typography hierarchy - font name and weight for each level:
+   - Wordmark, Display, Headline, Body, Caption
+9. 12-week theme map - name 3-4 word theme names per week in launch sequence
+
+Output all 9 sections. The theme map will drive hero image generation and the full content calendar in later steps.
+```
+
+#### Prompt 4: The Packaging Master (The Reference Asset)
+*Note: Include the phrase "using Higgsfield" to explicitly trigger the MCP.*
+```text
+Using Higgsfield. Using the product brief and brand definition you generated in this session, lock the master packaging image. This image will be the visual reference for every downstream asset. Do not generate anything else until it is verified.
+
+Step 1 - Generate a single master packaging image using a photoreal model (nano_banana_2 or equivalent). The prompt must specify all of the following:
+- Form factor and dimensions
+- Body color in hex (from the brand palette)
+- Cap color and joint detail (ring, seam, or magnet)
+- Surface finish: matte / satin / glossy
+- Wordmark text, font weight, and position on the body
+- Base treatment
+- Any glyph or icon: its design and position
+- Lighting/setup aesthetic
+- Specific photographer references (e.g. Carl Kleiner x Aaron Tilley x Hugh Kretschmer)
+
+Step 2 - Run vision analysis on the rendered image and verify:
+- Wordmark spelling is correct
+- Colors match the brand palette hex values
+- Proportions look production-ready
+- Nothing looks distorted or off-brand
+
+Step 3 - Output:
+- The image
+- The master image URL
+- The Job ID
+- A pass/fail verdict on visual verification
+- If fail: what needs correcting and a re-rolled image
+
+Do not proceed until the master passes visual verification.
+```
+
+#### Prompt 5: 10 Brand-Kit Images
+```text
+Using the brand definition and the master packaging image you generated in this session, produce the 10 brand-kit images below. Reference the master packaging job ID in every generation to enforce visual consistency. 
+
+Generate all 10 in parallel. Apply the brand color palette and the photographer/lighting aesthetic from the packaging master to every image.
+
+01 - Packshot (1:1): clean centered D2C hero, white or brand-color background
+02 - Three-variant flat-lay (4:5): product family shot showing range
+03 - Product close-up with human element (4:5): hand, eye, or skin detail
+04 - Billboard hero with copy lockup (16:9): primary tagline overlaid
+05 - Reels cover with native typography (9:16): scroll-stop vertical format
+06 - Surreal floating product, no copy (4:5): editorial hero, nothing anchored
+07 - Merch flat-lay (1:1): product alongside branded supporting objects
+08 - TV trix key art with tagline (16:9): three-product lineup
+09 - Open carton / unboxing flat-lay (1:1): packaging element
+10 - Variant + color system chart (1:1): visual reference card
+
+Output: Image URL and Job ID for each. Label them 01 through 10.
+```
+
+#### Prompt 6: 5 Master Videos (Using Seedance 2.0 via MCP)
+```text
+Using the brand definition, the master packaging image, and the research summary you generated in this session, produce five 10-second master videos. 
+
+Each video is built from 3 x 10-second shots stitched via ffmpeg hard-cut concat. Use Seedance 2.0. Reference the master packaging job ID in every shot.
+
+Videos to produce:
+V1 - UGC pain reveal (9:16): shot 1 the problem in real life, shot 2 discovery, shot 3 result
+V2 - Cinematic flagship (16:9): three shots each proving one of the top proof points
+V3 - ASMR unboxing (9:16): carton open, product reveal, variant display
+V4 - POV demo (9:16): setup, live demo or proof test, satisfied reaction
+V5 - Surreal product hero (16:9): float, macro detail, pull-back resolve
+
+Production rules:
+- Seedance 2.0: 10 seconds per shot maximum, 4-job concurrency ceiling
+- Submit in batches of 4, poll to terminal before starting the next batch
+- No whip pans, no cuts within a shot, soft 1-2% handheld drift only
+- If a shot is rejected for NSFW, rewrite without trigger words and resubmit once only
+- All shots share the brand color-grade
+
+After all 15 shots are confirmed: FFmpeg concat with stream copy (-c copy) for each master, then re-encode at 1080p, 16mbps, AVC H264.
+
+Output: Job IDs and URLs for all 15 individual shots + 5 stitched master video URLs.
+```
+
+### 📈 Post-Asset Generation Steps (Mentioned at the end)
+Though he didn't show the full prompt texts for these in action, he explains that the final prompts in the 12-prompt sequence instruct Claude to take all of the above data and generate:
+1. **5 Weekly Reels** (Splicing the videos generated into vertical content).
+2. **A 12-Week Content Calendar** (Mapping the themes to actual post text and schedules).
+3. **Paid Media Budget** (Telling Claude to act as a media buyer to allocate ad spend across platforms).
+4. **Success Targets** (Defining KPIs, repeat purchase rates, and CPA goals).
+5. **A Master PDF** (Compiling the brand book, research, calendar, budgets, and all image/video asset URLs into one downloadable, formatted document for the team).

package/docs/DEMO_RECORDING.md

@@ -0,0 +1,61 @@
+# Recording the quickstart demo
+
+The `docs/assets/demo-quickstart.gif` rendered on the README comes from a narrated
+CLI walkthrough in `scripts/demo-quickstart.mjs`, captured with asciinema and
+rendered to GIF with [agg](https://github.com/asciinema/agg).
+
+## Prereqs
+
+```bash
+brew install asciinema agg
+```
+
+## Record
+
+```bash
+npm run demo:record
+```
+
+That script will:
+
+1. `npm run build`
+2. Record `scripts/demo-quickstart.mjs` into `docs/assets/demo-quickstart.cast`
+3. Render `docs/assets/demo-quickstart.cast` to `docs/assets/demo-quickstart.gif`
+
+Commit both artifacts.
+
+## Preview without recording
+
+```bash
+npm run demo
+```
+
+Set `VCLAW_DEMO_PAUSE_MS` to tune the pause between steps (default `900`).
+
+```bash
+VCLAW_DEMO_PAUSE_MS=300 npm run demo   # fast preview
+VCLAW_DEMO_PAUSE_MS=1400 npm run demo  # slower for recording
+```
+
+## Tuning the render
+
+`scripts/record-demo.sh` uses:
+
+- `--cols 100 --rows 28` — wide enough for the longest brief line
+- `--idle-time-limit 2` — collapses long pauses in the cast
+- `agg --theme monokai --font-size 16` — matches the README dark theme
+
+If you change the demo script to add/remove steps, re-record and re-render.
+
+## What the GIF is for
+
+It lives in the README right after the quickstart section. Its job is to show in
+~60 seconds that `vclaw`:
+
+1. produces a canonical JSON artifact at every stage
+2. routes to a specific provider without silent fallback
+3. refuses to submit on `--dry-run`
+4. exposes portfolio metrics + Obsidian export out of the box
+
+Keep it short. If the demo drifts past ~90s of wall-clock, trim steps rather
+than raising the speed.

package/docs/DEPRECATION.md

@@ -0,0 +1,79 @@
+# Deprecation Plan
+
+This document defines the deprecation path from the original `videoclaw` (v0.11.x)
+and the intermediate `vclaw-video-core` rebuild to **`videoclaw-v3`** — the
+merged successor (npm package: `videoclaw`).
+
+## Goal
+
+Make `videoclaw-v3` the primary execution surface without pretending the
+predecessor repos never existed.
+
+## Current decision
+
+Primary:
+
+1. `videoclaw-v3` (npm: `videoclaw`)
+
+Reference/fallback only:
+
+1. `videoclaw` v0.11.x (the original repo) — legacy reference / migration source
+2. `vclaw-video-core` — intermediate clean-room rebuild whose foundation was merged into videoclaw-v3
+
+## Deprecation boundaries
+
+What should stop growing in the old repo:
+
+1. new user-facing workflow surfaces
+2. new canonical artifact contracts
+3. new reporting layers
+4. new migration-target state models
+
+What can still be consulted in the old repo:
+
+1. legacy scripts
+2. older provider behaviors
+3. reference patterns not yet ported
+
+## Cutover criteria
+
+The clean repo is considered the primary product surface once these are true:
+
+1. provider status works
+2. produce / execute-status works
+3. clone-execute works
+4. template and prompt-library surfaces exist
+5. migration docs exist
+6. core tests are green
+
+Those conditions are now satisfied.
+
+## Remaining non-blocking work
+
+1. richer provider-specific options
+2. better automatic prompt guidance during execution
+3. operator education and release communication
+
+## Operational policy
+
+When a user asks to create or run video work:
+
+1. prefer `videoclaw-v3` (`vclaw` CLI)
+2. fall back to the legacy `videoclaw` v0.11.x runtime only when the missing feature is clearly identified
+3. track every such fallback as a porting task
+
+## Suggested release language
+
+Use this internal framing:
+
+1. `videoclaw-v3` (npm: `videoclaw`) is now the recommended runtime
+2. `videoclaw` v0.11.x and `vclaw-video-core` remain available as migration/reference sources
+3. old workflows should not be expanded further unless they are being ported
+
+## Sunset rule
+
+Do not archive or delete the old repo until:
+
+1. migration of active operators is complete
+2. no critical workflow depends exclusively on the old runtime
+3. the clean repo has been stable through multiple real runs