@conceptcraft/mindframes 0.1.13 → 0.1.14

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from 'module'; const require = createRequire(import.meta.url);
 
 // src/index.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 import chalk13 from "chalk";
 
 // src/lib/brand.ts
@@ -1109,6 +1109,12 @@ async function pollForCompletion(checkFn, maxAttempts = 60, intervalMs = 2e3) {
   }
   throw new ApiError("Operation timed out", 408, 1);
 }
+async function scrapeUrl(url) {
+  return request("/api/cli/scrape", {
+    method: "POST",
+    body: { url }
+  });
+}
 
 // src/lib/feature-cache.ts
 var cache = new Conf2({
@@ -1164,7 +1170,7 @@ function getCachePath() {
 }
 
 // src/commands/login.ts
-var CLI_CLIENT_NAME = "ConceptCraft CLI";
+var CLI_CLIENT_NAME = `${brand.displayName} CLI`;
 var CALLBACK_PORT_START = 8765;
 var CALLBACK_PORT_END = 8775;
 function generateCodeVerifier() {
@@ -1414,11 +1420,11 @@ async function runLoginFlow(options) {
     throw err;
   }
 }
-var loginCommand = new Command("login").description("Authenticate with ConceptCraft (opens browser)").option("--no-browser", "Print URL instead of opening browser").action(async (options) => {
+var loginCommand = new Command("login").description(`Authenticate with ${brand.displayName} (opens browser)`).option("--no-browser", "Print URL instead of opening browser").action(async (options) => {
   console.log();
   if (hasOAuthTokens()) {
     warn("You are already logged in.");
-    info("Run 'conceptcraft logout' to log out first, or continue to re-authenticate.");
+    info(`Run '${brand.commands[0]} logout' to log out first, or continue to re-authenticate.`);
     console.log();
   }
   try {
@@ -1476,7 +1482,7 @@ import ora2 from "ora";
 var configCommand = new Command3("config").description("Manage CLI configuration").addCommand(
   new Command3("init").description("Initialize configuration interactively").action(async () => {
     console.log();
-    console.log(chalk4.bold("ConceptCraft CLI Configuration"));
+    console.log(chalk4.bold(`${brand.displayName} CLI Configuration`));
     console.log(chalk4.gray("\u2500".repeat(35)));
     console.log();
     try {
@@ -1495,7 +1501,7 @@ var configCommand = new Command3("config").description("Manage CLI configuration
       });
       setApiKey(apiKey.trim());
       const useCustomUrl = await confirm2({
-        message: "Use a custom API URL? (default: www.mindframes.app)",
+        message: `Use a custom API URL? (default: ${brand.apiUrl.replace("https://", "")})`,
         default: false
       });
       if (useCustomUrl) {
@@ -1550,7 +1556,7 @@ var configCommand = new Command3("config").description("Manage CLI configuration
         warn(
           `Could not verify API key: ${apiErr instanceof Error ? apiErr.message : String(apiErr)}`
         );
-        warn("You may need to set the team ID manually: mindframes config set team-id <id>");
+        warn(`You may need to set the team ID manually: ${brand.commands[0]} config set team-id <id>`);
       }
       console.log();
       success("Configuration saved!");
@@ -1654,7 +1660,7 @@ var configCommand = new Command3("config").description("Manage CLI configuration
     try {
       await fetchAndCache();
       spinner.succeed("Feature flags refreshed");
-      info("Run 'conceptcraft --help' to see updated commands");
+      info(`Run '${brand.commands[0]} --help' to see updated commands`);
     } catch (err) {
       spinner.fail("Failed to refresh");
       error(err instanceof Error ? err.message : String(err));
@@ -2002,29 +2008,29 @@ ${chalk6.bold("Recommended Usage:")}
 
 ${chalk6.bold("Examples:")}
   ${chalk6.gray("# Content from PDF + style from image reference")}
-  $ conceptcraft create "Quarterly Report" \\
+  $ ${brand.commands[0]} create "Quarterly Report" \\
       --file ./report.pdf \\
       --reference-url https://example.com/style-template.png \\
       -n 12 -m best --audience "Executive team"
 
   ${chalk6.gray("# Upload content files (PDF, PPTX, DOCX)")}
-  $ conceptcraft create "Product Demo" \\
+  $ ${brand.commands[0]} create "Product Demo" \\
       --file ./existing-deck.pptx --file ./specs.pdf \\
       --goal persuade --audience "Enterprise buyers"
 
   ${chalk6.gray("# Inline context with custom styling")}
-  $ conceptcraft create "Q4 Business Review" \\
+  $ ${brand.commands[0]} create "Q4 Business Review" \\
       -n 12 -m best --goal inform \\
       --context "Revenue: $50M (+25% YoY), EBITDA: $8M" \\
       --reference-url https://example.com/brand-style.jpg
 
   ${chalk6.gray("# Research presentation from URLs")}
-  $ conceptcraft create "AI Industry Trends" \\
+  $ ${brand.commands[0]} create "AI Industry Trends" \\
       -n 10 -m best -t educational \\
       --sources https://example.com/ai-report.pdf
 
   ${chalk6.gray("# Pipe content from another command")}
-  $ cat meeting-notes.md | conceptcraft create "Meeting Summary" \\
+  $ cat meeting-notes.md | ${brand.commands[0]} create "Meeting Summary" \\
       -n 6 -m balanced --goal inform
 
 ${chalk6.bold("Content Options (what to include in slides):")}
@@ -2053,7 +2059,7 @@ ${chalk6.bold("Theme Options:")}
   --decorations <style>      Background style (none, waves-bottom-left, waves-top-right, blob-corners, minimal)
 
   ${chalk6.gray("Example: Apply corporate colors")}
-  $ conceptcraft create "Brand Deck" \\
+  $ ${brand.commands[0]} create "Brand Deck" \\
       --theme blue --primary-color "#1E40AF" --decorations waves-bottom-left
 
 ${chalk6.bold("Mode Reference:")}
@@ -2288,11 +2294,11 @@ Uploading ${options.file.length} file(s)...`));
     console.log(chalk6.gray("  -c, --context <text>      Direct text context"));
     console.log(chalk6.gray("  --context-file <path>     Read from a file"));
     console.log(chalk6.gray("  --sources <urls...>       URLs to scrape"));
-    console.log(chalk6.gray("  cat file | conceptcraft   Pipe content"));
+    console.log(chalk6.gray(`  cat file | ${brand.commands[0]}   Pipe content`));
     console.log();
     console.log(chalk6.gray("Example:"));
-    console.log(chalk6.cyan('  conceptcraft create "Q4 Report" --file ./report.pdf'));
-    console.log(chalk6.cyan('  conceptcraft create "Q4 Report" --context "Revenue: $10M, Growth: 25%"'));
+    console.log(chalk6.cyan(`  ${brand.commands[0]} create "Q4 Report" --file ./report.pdf`));
+    console.log(chalk6.cyan(`  ${brand.commands[0]} create "Q4 Report" --context "Revenue: $10M, Growth: 25%"`));
     process.exit(6);
   }
   try {
@@ -2433,7 +2439,7 @@ var listCommand = new Command5("list").description("List presentations").option(
   const teamId = options.teamId ?? getDefaultTeamId();
   if (!teamId) {
     error(
-      "Team ID required. Set a default with 'mindframes config set team-id <id>' or use --team-id"
+      "`Team ID required. Set a default with '${brand.commands[0]} config set team-id <id>' or use --team-id`"
     );
     process.exit(6);
   }
@@ -2704,7 +2710,7 @@ var brandingCommand = new Command10("branding").description("Manage brand profil
           console.log();
           console.log(
             chalk8.gray(
-              "Create one with: conceptcraft branding extract <url>"
+              "`Create one with: ${brand.commands[0]} branding extract <url>`"
             )
           );
         }
@@ -2837,7 +2843,7 @@ var brandingCommand = new Command10("branding").description("Manage brand profil
         console.log(`    Confidence: ${Math.round(brand2.confidence * 100)}%`);
         console.log();
       }
-      info(`Create a presentation with this brand: conceptcraft create "Your Topic" -b ${result.id}`);
+      info(`Create a presentation with this brand: ${brand2.commands[0]} create "Your Topic" -b ${result.id}`);
       console.log();
     } catch (err) {
       spinner.fail("Extraction failed");
@@ -3000,7 +3006,7 @@ var ideasCommand = new Command12("ideas").description("Generate presentation top
   console.log("For now, try these approaches:");
   console.log(
     chalk10.gray(
-      "  1. Visit the ConceptCraft dashboard and use the idea generator"
+      "`  1. Visit the ${brand.displayName} dashboard and use the idea generator`"
     )
   );
   console.log(
@@ -3073,8 +3079,8 @@ function generateMainSkillContent(context) {
   const { name, cmd: cmd2 } = context;
   const envPrefix = name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
   return `---
-name: ${cmd2}
-description: ${name} CLI for AI-powered content creation. Use when user needs to create presentations, generate video assets (voiceover, music, images, stock videos), use text-to-speech, mix audio, search stock media, or manage branding. This is the main entry point - load specialized skills (${cmd2}-video, ${cmd2}-presentation) for detailed workflows.
+name: ${name}
+description: ${name} CLI for AI-powered content creation. Use when user needs to create presentations, generate video assets (voiceover, music, images, stock videos), use text-to-speech, mix audio, search stock media, or manage branding. This is the main entry point - load specialized skills (${name}-video, ${name}-presentation) for detailed workflows.
 ---
 
 # ${name} CLI
@@ -3096,6 +3102,7 @@ A comprehensive CLI for AI-powered content creation. Generate presentations, vid
 | Search images | \`${cmd2} image search -q "mountain landscape"\` |
 | Search videos | \`${cmd2} video search "ocean waves"\` |
 | Mix audio tracks | \`${cmd2} mix create --video v.mp4 --music m.mp3\` |
+| Scrape URL content | \`${cmd2} scrape https://example.com\` |
 
 ---
 
@@ -3152,7 +3159,7 @@ ${cmd2} create "Pitch Deck" \\
 - \`--mode <instant|ultrafast|fast|balanced|best>\` - Quality/speed tradeoff
 - \`--tone <creative|professional|educational|formal|casual>\`
 - \`--file <paths...>\` - Extract content from files
-- \`--sources <urls...>\` - Scrape URLs for context
+- \`--sources <urls...>\` - Scrape URLs for context (auto-routes YouTube, Twitter/X)
 - \`--brand <id|url>\` - Apply branding
 - \`--open\` - Open in browser when done
 
@@ -3193,6 +3200,7 @@ cat <<'EOF' | ${cmd2} video create --output ./public
       "imageQuery": "call to action button"
     }
   ],
+  "voiceId": "21m00Tcm4TlvDq8ikWAM",
   "voiceSettings": {
     "speed": 0.95,
     "stability": 0.4,
@@ -3231,10 +3239,10 @@ ${cmd2} tts generate -t "Hello world" -o output.mp3
 # With voice selection
 ${cmd2} tts generate -t "Welcome to the demo" -v Rachel -o welcome.mp3
 
-# With provider and settings (Gemini)
+# With provider and settings
 ${cmd2} tts generate \\
   -t "Professional narration" \\
-  -v Puck \\
+  -v Kore \\
   -p gemini \\
   -s 0.9 \\
   -o narration.mp3
@@ -3244,11 +3252,8 @@ ${cmd2} tts voices
 ${cmd2} tts voices --provider elevenlabs
 \`\`\`
 
-**Providers:** \`elevenlabs\` (default), \`gemini\`, \`openai\`
-**Voices by provider:**
-- ElevenLabs: \`Rachel\`, \`Josh\`, \`Adam\`, \`Bella\` (or voice IDs)
-- Gemini: \`Kore\`, \`Puck\`, \`Charon\`, \`Aoede\`
-- OpenAI: \`alloy\`, \`nova\`, \`echo\`, \`onyx\`
+**Providers:** \`gemini\`, \`elevenlabs\`, \`openai\`
+**Popular voices:** \`Kore\`, \`Puck\`, \`Rachel\`, \`alloy\`
 **Speed range:** 0.25 - 4.0 (default: 1.0)
 
 ---
@@ -3341,7 +3346,35 @@ Music automatically loops to match video duration.
 
 ---
 
-## 8. Branding
+## 8. URL Scraping
+
+Extract content from URLs for analysis, context gathering, or research.
+
+\`\`\`bash
+# Basic scrape
+${cmd2} scrape https://example.com
+
+# Save to file
+${cmd2} scrape https://company.com/about -o about.md
+
+# JSON output (for programmatic use)
+${cmd2} scrape https://docs.example.com --format json
+
+# Quiet mode (content only)
+${cmd2} scrape https://blog.example.com --format quiet > content.txt
+\`\`\`
+
+**Use cases:**
+- Gather context for presentation creation
+- Research competitor features
+- Extract documentation for analysis
+- Feed content into other workflows
+
+**Output includes:** title, description, full content (markdown), token count, cost
+
+---
+
+## 9. Branding
 
 Manage brand profiles for consistent styling.
 
@@ -3364,7 +3397,7 @@ ${cmd2} create "Topic" --brand my-company
 
 ---
 
-## 9. Configuration
+## 10. Configuration
 
 \`\`\`bash
 # Interactive setup
@@ -3432,7 +3465,7 @@ cat scenes.json | ${cmd2} video create -o product-demo/public
 
 # 4. Render and add thumbnail (version files: v1, v2, v3...)
 cd product-demo
-npx remotion render FullVideo out/FullVideo-v1.mp4
+pnpm exec remotion render FullVideo out/FullVideo-v1.mp4
 ${cmd2} video thumbnail out/FullVideo-v1.mp4 --frame 60
 \`\`\`
 
@@ -3491,236 +3524,636 @@ ${cmd2} --version           # Version info
 `;
 }
 
-// src/commands/skill/rules/video/content.ts
-var MOTION_DESIGN_GUIDELINES = `# Motion Design Principles
+// src/commands/skill/generate-video-skill.ts
+function generateVideoSkillContent(context) {
+  const { name, cmd: cmd2 } = context;
+  return `---
+name: ${name}-video
+description: Orchestrates video asset assembly for marketing videos, product demos, explainers, and promo content. Analyzes projects to extract branding (logos, colors, fonts), identifies reusable UI components, generates voiceovers and music via CLI, searches stock media, and produces a video-manifest.json. Use when user says "create a video", "make a promo", "product demo", "explainer video", "marketing video", "gather video assets", "video for my project", or "TikTok/Reels content".
+---
 
-**Core Philosophy:** "Atomic, Kinetic Construction" - nothing is static. Elements arrive and leave via physics-based transitions.
+# Video Asset Assembler (Phase 1)
 
-## Design System Approach
+You are an expert video producer who prepares all assets needed for Remotion video rendering. Your job is to analyze the project, gather resources, generate audio, and create a complete manifest\u2014NOT to render the final video.
 
-**Separate content from logic:**
-- Theme object: colors (primary, accent, background, text), fonts, corner radiuses in config
-- Scene object: define by duration in frames and content type, not timecodes
-- Avoid hardcoding: colors, text, data values can be passed via props or config file
+## When to Use This Skill
 
-## Animation Physics (Spring-Based)
+\u2705 **USE for:**
+- Marketing videos, product demos, launch videos
+- News/trending topic videos
+- Explainer videos from any source
+- Social content (TikTok, Reels, YouTube Shorts)
+- Any video that needs voiceover + visuals + music
 
-**Spring Pop:**
-- UI cards, bubbles, logos "pop" with bounce
-- \`spring()\` function works well: low mass (0.5), moderate damping (10-12), high stiffness (100-200)
-- Spring value can map to scale (0 to 1) and opacity (0 to 1)
-- Consider \`transform-origin\` placement (center for bubbles, top for dropdowns)
+\u274C **DO NOT use for:**
+- Editing existing video files (use ffmpeg directly)
+- Live streaming setup
+- Video format conversion
+- Simple image slideshows without voiceover
 
-**Kinetic Typography:**
-- Text entering line-by-line or word-by-word (not all at once)
-- Can split text into arrays, stagger with delays (index * 5 frames)
-- \`interpolate()\` works for opacity [0,1] and translateY [20px, 0px] - slide up
-- Cubic easing works well for slide-up motion
+## Critical Rules
 
-**Constructed UI:**
-- Building UI from HTML/CSS divs works better than screenshots
-- If user shares project: study actual UI components (buttons, cards, modals) and implement pixel-perfect recreations - match colors, fonts, shadows, border-radius
-- Bar charts: can animate height/width from 0% to target
-- Line charts: can animate SVG path \`stroke-dashoffset\`
-- Donut charts: can animate \`stroke-dasharray\` of SVG circle
-- Numbers: counter component interpolating from 0 to target over 30-60 frames
+1. **NEVER hallucinate file paths.** Before referencing any file, VERIFY it exists with \`ls\` or \`find\`.
+2. **NEVER skip the discovery phase.** Always analyze source material before scripting.
+3. **ALWAYS use the CLI** for audio generation\u2014don't simulate or skip it.
+4. **ALWAYS produce a valid video-manifest.json** at the end.
+5. **ALWAYS ask clarifying questions** if video type, duration, or tone is unclear.
 
-## Visual Composition
+## Video Types & Source Detection
 
-**Background Ambience:**
-- Static backgrounds feel flat - consider faint dots/patterns
-- Slow oscillation works well: \`Math.sin(frame / 100)\` applied to position/rotation for "floating" effect
-- Parallax adds depth: background moves slower than foreground
+Detect the video type and source material FIRST. This determines your asset strategy.
 
-**SVG Handling:**
-- Inline SVGs allow control of fill color via theme (better than img tags)
-- Chat bubbles can be constructed with SVG paths or heavy border-radius
-- Animating bubble "tail" separately adds polish
+| Video Type | Source | Asset Strategy |
+|------------|--------|----------------|
+| **Project Launch** | Local codebase | Extract components, branding, screenshots from code |
+| **Website Promo** | Live URL | Screenshot pages, extract colors/logos via browser |
+| **News/Trending** | External articles, URLs | Summarize content, use 100% stock media |
+| **Explainer/Tutorial** | Topic or concept | Research topic, use diagrams + stock |
+| **Product Announcement** | Press release, changelog | Extract key points, mix branded + stock |
 
-**Scene Transitions:**
-- Scenes can slide or camera can "pan" to new area
-- Slide-out approach: Scene A \`translateX\` 0% to -100%, Scene B 100% to 0%
-- Spatial pan approach: place scenes on giant canvas, animate parent container transform
+### Source Detection Logic
 
-## Suggested Component Architecture
+Check what the user provides or what's available:
 
-Consider these reusable patterns:
-- KineticText: text, delay, style props - handles word-splitting and stagger
-- SmartCard: container with Spring Pop entry and glassmorphism styles
-- AnimatedCounter: from, to, duration props - number ticking
-- ProgressBar/ChartElement: percentage, color props - growth animation from 0
+| User Provides | Action |
+|---------------|--------|
+| **Local codebase** (package.json, src/) | Extract components, branding, screenshots |
+| **URL to website** | Screenshot pages, extract colors/logos |
+| **URL to article/news** | Fetch content, summarize key points |
+| **Document** (PDF, markdown, .txt) | Parse and extract key messages |
+| **Raw text/script** | Use directly for voiceover |
+| **Images/videos** | Use as-is for scenes |
+| **Topic/concept** | Research + generate stock queries |
 
-**Motion Blur (optional):** Can simulate by stretching element in direction of movement on fast transitions.
-`;
-var SVG_ANIMATION_GUIDELINES = `# SVG Line Animation (Write-On Effect)
+**Sources can combine.** Examples:
+- "Launch video for my project + our blog post" = codebase + URL
+- "News video about X with our branding" = article + local logo
+- "Explainer using these screenshots" = user images + generated VO
 
-**Core Concept:** "Invisible Ink Rule" - lines draw in (don't fade in), as if hand-drawn in real-time.
+---
 
-**Animation approach:**
-- Setting \`pathLength="1"\` on SVG path elements normalizes length
-- Animating \`strokeDashoffset\` from 1 (hidden) to 0 (drawn) creates write-on effect
-- \`strokeDasharray: 1\` with interpolate \`[1, 0]\` over 20-30 frames works well
-- \`stroke-linecap="round"\` creates friendly hand-drawn look
+## Phase 1: Discovery & Analysis
 
-**Draw & vanish sequence:**
-- Draw in: 20 frames (offset 1\u21920)
-- Hold: 10 frames
-- Draw out: fade opacity or continue offset
+Run the relevant discovery based on detected source type.
 
-**Reusable component pattern:**
-- Props: path data (d), color, width, delay, type (underline/spark/circle/arrow)
-- Pre-defined path dictionaries work better than generating random coordinates
-- Positioning with top/left/scale/rotation props for text accents
-`;
-var ASSET_USAGE_GUIDELINES = `# Asset Usage & Optimization
+### 1.1 Codebase Analysis (if local project)
 
-**For project-specific videos:** Study the project first - extract logos, colors, fonts, actual UI components. Recreate components pixel-perfect in Remotion (match exact colors, shadows, border-radius, fonts). Use project's actual branding and design system for authentic look.
+\`\`\`bash
+# Find branding assets
+find . -type f \\( -name "logo*" -o -name "favicon*" -o -name "brand*" \\) 2>/dev/null | head -20
 
-**CLI provides flexible asset search** - images and videos can be used creatively throughout compositions.
+# Find color configuration
+find . -type f \\( -name "tailwind.config.*" -o -name "theme.*" -o -name "colors.*" \\) 2>/dev/null
 
-**Video assets (from CLI video search):**
-- Full-screen backgrounds (with overlays/text)
-- Embedded in UI cards or windows alongside text
-- Picture-in-picture style elements
-- Background layers with reduced opacity
-- Transitional footage between scenes
+# Find impressive UI components (prioritize pages/containers over atoms)
+find . -path "*/components/*" -name "*.tsx" 2>/dev/null | head -30
+\`\`\`
 
-**Image assets (from CLI image search):**
-- Scene backgrounds (static or with animation)
-- Embedded elements within compositions
-- UI component content (cards, panels)
-- Layered for depth and parallax effects
+**Extract:**
+- [ ] Logo path (verify exists)
+- [ ] Primary/accent colors from config
+- [ ] 2-4 "hero" components worth showcasing
 
-**Dynamic backgrounds (Three.js/WebGL):**
-- Three.js/React Three Fiber for performance-optimized animated backgrounds
-- Particle systems, procedural gradients, geometric patterns
-- SVG animations for abstract shapes and patterns
-- WebGL shaders for dynamic effects
-- Combines well with static assets for depth
+### 1.2 Website Analysis (if URL provided)
 
-**Best approach:** Mix CLI assets (images/videos) with generated elements (Three.js, SVG) for rich, performant compositions.
-`;
+\`\`\`bash
+# Scrape website content for analysis
+${cmd2} scrape "https://example.com" --format json
 
-// src/commands/skill/generate-video-skill.ts
-function generateVideoSkillContent(context) {
-  const { name, cmd: cmd2 } = context;
-  return `---
-name: ${cmd2}-video
-description: Use when user asks to create videos (product demos, explainers, social content, promos). Handles video asset generation, Remotion implementation, and thumbnail embedding.
----
+# Save content to file for reference
+${cmd2} scrape "https://example.com" -o ./content/homepage.md
 
-# ${name} Video Creation CLI
+# Scrape multiple pages
+${cmd2} scrape "https://example.com/features" -o ./content/features.md
+${cmd2} scrape "https://example.com/pricing" -o ./content/pricing.md
+\`\`\`
 
-Generate video assets (voiceover, music, images, stock videos) and render with Remotion.
+**Extract from scraped content:**
+- [ ] Main value proposition / headline
+- [ ] Key features and benefits
+- [ ] Brand name and tagline
+- [ ] Color mentions (if in content) or use stock visuals
 
----
+### 1.3 Content Analysis (if document/article)
 
-## Prerequisites
+For news articles, blog posts, press releases, changelogs:
 
-**Authenticate:**
 \`\`\`bash
-${cmd2} login
+# Scrape and parse article
+${cmd2} scrape "https://example.com/article" -o ./content.md
+
+# Or read local document
+cat ./CHANGELOG.md | head -100
 \`\`\`
 
+**Extract:**
+- [ ] Main headline / title
+- [ ] 3-5 key points for scenes
+- [ ] Quotes or stats to highlight
+- [ ] Related images (if embedded)
+
+### 1.4 User-Provided Content
+
+If user provides text, script, or topic directly:
+
+**Raw script provided:**
+- Use as-is for voiceover
+- Plan visuals based on content
+
+**Topic/concept provided:**
+- Research topic using your web search capabilities
+- Or scrape relevant URLs: \`${cmd2} scrape "https://relevant-article.com"\`
+
+**Images/videos provided:**
+- Verify files exist
+- Note dimensions and quality
+- Plan scenes around provided assets
+
+**Extract:**
+- [ ] Key messages (3-5 per video)
+- [ ] Visual concepts for each message
+- [ ] Any specific assets user wants included
+
+### 1.5 Content Brief & User Clarification
+
+**Goal:** Align on video purpose before scripting.
+
+**Use AskUserQuestion tool:** If your AI environment provides an \`AskUserQuestion\` tool (Claude Code, Agent SDK, etc.), use it to gather user preferences about duration, tone, focus, and CTA before proceeding. This provides a better UX than plain text questions.
+
+**When to ask vs. proceed:**
+- **Vague request** ("make a video for my project") \u2192 ASK clarifying questions
+- **Partial details** ("30-second TikTok for my app") \u2192 ASK remaining questions
+- **Detailed brief** (duration, tone, CTA specified) \u2192 PROCEED directly
+- **User says "just do it" or "use defaults"** \u2192 USE defaults below
+
+**Reasonable defaults (if user opts out of questions):**
+- Duration: 30-45 seconds
+- Tone: Professional
+- Focus: Balanced (show problem + solution)
+- CTA: "Try it free" or "Learn more"
+- Structure: Hook \u2192 Main Point \u2192 CTA
+
+**Validation Gate:** Do NOT proceed to asset generation until you have:
+- [ ] Clear video type identified
+- [ ] Source material gathered (screenshots, content, or stock queries planned)
+- [ ] Duration and tone (confirmed OR defaulted)
+
 ---
 
-## Video Creation Workflow
+## Phase 2: Script & Scene Planning
+
+### 2.1 Narrative Structure
+
+Follow this arc for maximum engagement:
+
+| Scene | Duration | Purpose | Example |
+|-------|----------|---------|---------|
+| **Hook** | 3-5s | Stop the scroll, create curiosity | "What if your dashboard updated itself?" |
+| **Problem** | 5-8s | Relatable pain point | "Tired of manual data entry?" |
+| **Solution** | 10-20s | Show the product/concept | Demo of key features |
+| **Proof** | 5-10s | Social proof, stats, benefits | "10x faster than competitors" |
+| **CTA** | 3-5s | Clear next step | "Try free at example.com" |
 
-### 1. Generate Assets
+**For Short Videos (15-30s):** Hook \u2192 Solution \u2192 CTA (skip Problem/Proof)
 
-Generate voiceover, music, images, and thumbnail:
+### 2.2 Scene Definition
+
+For each scene, define:
+
+\`\`\`json
+{
+  "name": "SceneName",
+  "script": "Voiceover text (conversational, 2-3 sentences max)",
+  "imageQuery": "Stock search query if needed",
+  "videoQuery": "Stock video search query if preferred over image",
+  "componentPath": "src/components/Feature.tsx (Project Mode only, VERIFIED path)"
+}
+\`\`\`
+
+**Script Writing Tips:**
+- Keep sentences SHORT (8-12 words ideal for voiceover)
+- Use active voice: "Build faster" not "Faster building is possible"
+- Include natural pauses with periods, not commas
+- Match script length to desired scene duration (~150 words/minute)
+
+---
+
+## Phase 3: Asset Generation
+
+### 3.1 Generate Voiceovers & Music
+
+**CRITICAL:** Run this command with your scenes JSON. Music is generated LAST to match total duration.
 
 \`\`\`bash
-cat <<SCENES | ${cmd2} video create --output ./public
+cat <<'SCENES_JSON' | ${cmd2} video create --output ./public
 {
   "scenes": [
     {
       "name": "Hook",
-      "script": "Watch how we transformed this complex workflow into a single click.",
-      "imageQuery": "modern dashboard interface dark theme"
+      "script": "Your hook script here.",
+      "imageQuery": "abstract tech gradient particles"
     },
     {
-      "name": "Demo",
-      "script": "Our AI analyzes your data in real-time, surfacing insights that matter."
+      "name": "Solution",
+      "script": "Your solution script here.",
+      "videoQuery": "modern dashboard interface animation"
+    },
+    {
+      "name": "CTA",
+      "script": "Your call to action here.",
+      "imageQuery": "gradient background call to action"
     }
-  ]
+  ],
+  "voiceId": "21m00Tcm4TlvDq8ikWAM",
+  "voiceSettings": {
+    "speed": 1.0,
+    "stability": 0.5,
+    "similarity": 0.75,
+    "style": 0.3
+  },
+  "musicPrompt": "upbeat corporate, modern synth, positive energy"
 }
-SCENES
+SCENES_JSON
 \`\`\`
 
-**Output:**
-- \`public/audio/*.wav\` - scene voiceovers
-- \`public/audio/music.mp3\` - background music
-- \`public/images/*.jpg\` - scene images (if imageQuery provided)
-- \`public/thumbnail.jpg\` - auto-generated thumbnail
-- \`public/video-manifest.json\` - **complete timeline ready to use**
+**Voice ID:** Use ElevenLabs voice IDs. Get available voices with \`${cmd2} tts voices\`.
+Common voice IDs:
+- \`21m00Tcm4TlvDq8ikWAM\` - Rachel (default, calm female)
+- \`EXAVITQu4vr4xnSDxMaL\` - Bella (young female)
+- \`ErXwobaYiN019PkySvjV\` - Antoni (male)
+
+**Voice Settings Tuning:**
+| Setting | Low (0.2-0.4) | Medium (0.5) | High (0.6-0.8) |
+|---------|---------------|--------------|----------------|
+| stability | More expressive/variable | Balanced | Consistent/monotone |
+| similarity | Creative interpretation | Balanced | Strict voice match |
+| style | Subtle emotion | Moderate | Dramatic/animated |
+| speed | Slower, dramatic | Normal | Faster, energetic |
 
-### 2. Initialize Remotion (MANDATORY)
+### 3.2 Search Additional Stock Media (Optional)
 
-Scaffold the template and copy assets:
+If scenes need more visuals:
 
 \`\`\`bash
-cd .. && ${cmd2} video init my-video
-cd my-video
-# Assets are now in public/ directory
+# Search stock images
+${cmd2} image search "modern SaaS dashboard dark theme" --count 5
+
+# Search stock videos
+${cmd2} video search "tech particles animation blue" --license free
 \`\`\`
 
-### 3. Render Video
+### 3.3 Verify Generated Assets
 
-**IMPORTANT:**
-- The \`video-manifest.json\` already contains the complete \`timeline\` - **no need to build or transform anything**
-- Just pass \`timeline\` directly to the composition
-- Always version output files: \`out/video-v1.mp4\`, \`out/video-v2.mp4\`, etc.
+After CLI completes, verify all files exist:
 
-**YouTube (landscape 16:9, NO captions):**
 \`\`\`bash
-npx remotion render YouTubeVideo out/youtube-v1.mp4 \\
-  --props='{"timeline":'$(cat public/video-manifest.json | jq -c .timeline)',"showCaptions":false}'
+ls -la ./public/audio/
+ls -la ./public/images/
+ls -la ./public/videos/
+cat ./public/video-manifest.json
 \`\`\`
 
-**TikTok/Reels/Shorts (vertical 9:16, WITH captions):**
-\`\`\`bash
-npx remotion render TikTokVideo out/tiktok-v1.mp4 \\
-  --props='{"timeline":'$(cat public/video-manifest.json | jq -c .timeline)',"showCaptions":true}'
+**Validation Gate:** Ensure:
+- [ ] Each scene has an audio file (\`.wav\` or \`.mp3\`)
+- [ ] Music file exists (\`audio/music.mp3\`)
+- [ ] video-manifest.json is valid JSON
+- [ ] Total duration looks reasonable for content
+
+---
+
+## Phase 4: Manifest Enrichment
+
+After CLI generates base manifest, enhance it with metadata based on your source type.
+
+**Add these fields as relevant:**
+
+\`\`\`json
+{
+  "source": "codebase|website|article|topic",
+  "sourceUrl": "https://... (if external)",
+
+  "scenes": [
+    {
+      "componentPath": "src/components/X.tsx",
+      "screenshotPath": "screenshots/home.png",
+      "textOverlay": "Key message here"
+    }
+  ],
+
+  "theme": {
+    "primary": "#3b82f6",
+    "accent": "#10b981"
+  },
+
+  "branding": {
+    "logoPath": "public/logo.svg",
+    "companyName": "Name"
+  },
+
+  "attribution": {
+    "source": "SourceName",
+    "date": "2024-01-15"
+  }
+}
+\`\`\`
+
+**Key rules:**
+- Only add \`componentPath\` for VERIFIED files
+- Only add \`screenshotPath\` if you captured screenshots
+- Only add \`attribution\` for news/article sources
+- \`theme\` and \`branding\` only if extracted from actual source
+
+---
+
+## Output Checklist
+
+Before completing Phase 1, verify:
+
+**Required for ALL videos:**
+- [ ] \`./public/audio/\` contains voiceover for each scene
+- [ ] \`./public/audio/music.mp3\` exists (or user opted out)
+- [ ] \`./public/video-manifest.json\` is valid JSON
+- [ ] Each scene has visual source (image, video, screenshot, or componentPath)
+
+**If using local codebase:**
+- [ ] All \`componentPath\` references VERIFIED to exist
+- [ ] Theme colors extracted from actual config
+- [ ] Logo path verified
+
+**If using website URL:**
+- [ ] Screenshots captured for key pages
+- [ ] Colors/branding extracted or noted
+
+**If news/content video:**
+- [ ] Source attribution included
+- [ ] Key points extracted for scenes
+
+**Success Message:**
+\`\`\`
+\u2705 Phase 1 Complete: Video assets assembled
+   - Video type: [project/website/news/explainer]
+   - Scenes: X
+   - Total duration: ~Xs
+   - Audio files: X
+   - Visuals: X images, X videos, X screenshots
+   - Components to adapt: X (if any)
+
+Ready for Phase 2: Remotion implementation
 \`\`\`
 
-### Video Compositions
+---
+
+## Handoff to Phase 2: Remotion Setup
 
-| Composition | Dimensions | Captions | Use Case |
-|-------------|------------|----------|----------|
-| \`YouTubeVideo\` | 1920x1080 (16:9) | No | YouTube, Vimeo, traditional video |
-| \`TikTokVideo\` | 1080x1920 (9:16) | Yes (word-by-word) | TikTok, Reels, Shorts |
+After Phase 1 is complete, prepare the Remotion project:
 
-**Same timeline, different output formats.** Both use the exact same \`timeline\` from \`video-manifest.json\`.
+### Step 1: Initialize Remotion Project
 
-### 4. Embed Thumbnail
+\`\`\`bash
+# Create Remotion project in current directory
+${cmd2} video init my-video
 
-Thumbnail is auto-generated during \`video create\`. Inject into final video:
+# For TikTok/Reels format (9:16)
+${cmd2} video init my-video --type tiktok
+\`\`\`
+
+This creates \`./my-video/\` with the Remotion template.
+
+### Step 2: Copy Assets to Remotion Project
 
 \`\`\`bash
-${cmd2} video thumbnail out/youtube-v1.mp4 --image public/thumbnail.jpg
+# Copy all generated assets to Remotion public folder
+cp -r ./public/audio ./my-video/public/
+cp -r ./public/images ./my-video/public/
+cp -r ./public/videos ./my-video/public/
+cp ./public/video-manifest.json ./my-video/public/
 \`\`\`
 
-**High-CTR thumbnail principles:**
-- Expressive faces boost CTR 20-30%
-- High contrast, bold colors (yellow, orange)
-- Simple: 3 elements max
-- Mobile-first: readable at 320px
-- Specs: 1280x720, <2MB
+### Step 3: Verify Transfer
+
+\`\`\`bash
+# Confirm all assets are in place
+ls -la ./my-video/public/
+cat ./my-video/public/video-manifest.json | jq '.scenes | length'
+\`\`\`
+
+**Expected structure in Remotion project:**
+\`\`\`
+my-video/
+\u251C\u2500\u2500 public/
+\u2502   \u251C\u2500\u2500 audio/
+\u2502   \u2502   \u251C\u2500\u2500 hook.wav
+\u2502   \u2502   \u251C\u2500\u2500 solution.wav
+\u2502   \u2502   \u251C\u2500\u2500 cta.wav
+\u2502   \u2502   \u2514\u2500\u2500 music.mp3
+\u2502   \u251C\u2500\u2500 images/
+\u2502   \u2502   \u2514\u2500\u2500 *.jpg, *.png
+\u2502   \u251C\u2500\u2500 videos/
+\u2502   \u2502   \u2514\u2500\u2500 *.mp4
+\u2502   \u2514\u2500\u2500 video-manifest.json
+\u251C\u2500\u2500 src/
+\u2502   \u2514\u2500\u2500 ... (Remotion components)
+\u2514\u2500\u2500 package.json
+\`\`\`
+
+### Step 4: Hand Off to Phase 2
+
+\`\`\`
+\u{1F4E6} Assets transferred to Remotion project: ./my-video/
+   
+Next steps (Phase 2 - Remotion Implementation):
+   cd my-video
+   pnpm dev              # Preview in Remotion Studio
+   # Then implement scenes using video-manifest.json
+\`\`\`
+
+**Note:** Phase 2 (Remotion implementation) is handled by a separate skill.
+
+---
+
+## Examples
+
+### Example 1: News Video
+**User says:** "Make a video about the latest AI news"
+
+**Actions:**
+1. Ask: "Any specific article or topic? What duration (30s or 60s)?"
+2. User provides article URL or topic
+3. Fetch/research content, extract 3-4 key points
+4. Write script with Hook \u2192 Key Points \u2192 Takeaway
+5. Run CLI with stock video queries for each point
+6. Generate manifest with source attribution
+
+**Result:** 45-second news video with stock footage, voiceover, and music
+
+---
+
+### Example 2: Product Launch (with codebase)
+**User says:** "Create a promo video for my app"
+
+**Actions:**
+1. Scan project: find logo, colors, impressive components
+2. Ask: "Which features to highlight? Duration preference?"
+3. Write script: Hook \u2192 Problem \u2192 Feature Demo \u2192 CTA
+4. Run CLI with scenes, use componentPath for demo scenes
+5. Enrich manifest with theme colors and branding
+
+**Result:** 60-second promo with branded visuals and component references
+
+---
+
+### Example 3: Website Promo (URL only)
+**User says:** "Make a video for https://example.com"
+
+**Actions:**
+1. Scrape website content: \`${cmd2} scrape "https://example.com" -o content.md\`
+2. Extract key messages, features, and value props from content
+3. Write script based on scraped content
+4. Run CLI with stock media queries matching the product/service
+5. Use text overlays for key messages
+
+**Result:** 30-second website promo with stock visuals and key messaging from site
+
+---
+
+### Example 4: Explainer (topic only)
+**User says:** "Explain how blockchain works in 30 seconds"
+
+**Actions:**
+1. Research topic briefly if needed
+2. Write simple script: Concept \u2192 How it works \u2192 Why it matters
+3. Run CLI with visual metaphor queries ("digital ledger", "chain links")
+4. Use 100% stock media
+
+**Result:** 30-second explainer with abstract visualizations
 
 ---
 
-${MOTION_DESIGN_GUIDELINES}
+## Error Recovery
+
+Use standalone CLI commands if \`video create\` fails partially.
+
+### If TTS Fails for One Scene
+
+\`\`\`bash
+# Retry single scene with standalone tts command
+${cmd2} tts "Your script text here" --voice Kore --output ./public/audio/scene-name.wav
+\`\`\`
+
+If still fails: try different voice, or skip scene.
+
+### If Music Generation Fails
+
+\`\`\`bash
+# Retry music separately
+${cmd2} music generate "upbeat corporate synth" --duration 30 --output ./public/audio/music.mp3
+\`\`\`
+
+If still fails: continue without music, notify user.
+
+### If Stock Search Returns Nothing
+
+\`\`\`bash
+# Try standalone image search with simpler query
+${cmd2} image search "dashboard" --count 10
+
+# Or try video search
+${cmd2} video search "tech animation" --license free
+\`\`\`
+
+Fallback: use solid color background with text overlay.
+
+### If Component Not Found
+1. DO NOT guess or hallucinate path
+2. Fall back to stock media for that scene
+3. Add to manifest: \`"componentPath": null, "fallbackReason": "not found"\`
 
 ---
 
-${SVG_ANIMATION_GUIDELINES}
+## Troubleshooting
+
+### CLI Command Fails
+
+**Error:** \`command not found: ${cmd2}\`
+**Fix:** Install CLI globally: \`npm install -g @anthropic/${name}\` or use npx: \`npx ${cmd2} video create\`
+
+**Error:** \`Authentication required\`
+**Fix:** Run \`${cmd2} login\` to authenticate with API key
+
+### Audio Generation Issues
+
+**Error:** \`Voice not found\`
+**Fix:** Use one of: Kore, Puck, Rachel, alloy (case-sensitive)
+
+**Error:** \`Music duration too short\`
+**Cause:** ElevenLabs requires minimum 3 seconds
+**Fix:** Ensure total script duration is at least 5 seconds
+
+### Stock Search Returns Nothing
+
+**Cause:** Query too specific or API limit reached
+**Fix:**
+1. Simplify query: "dashboard" instead of "modern SaaS dashboard with dark theme"
+2. Try alternative terms: "interface" instead of "UI"
+3. Check API quota: \`${cmd2} account\`
+
+### Component Path Not Found
+
+**Cause:** Guessed path without verification
+**Fix:**
+1. ALWAYS run \`ls\` or \`find\` before referencing
+2. Use stock media as fallback
+3. Add to manifest: \`"componentPath": null, "fallback": "stock"\`
+
+### Manifest JSON Invalid
+
+**Cause:** Syntax error in manual edits
+**Fix:** Validate JSON before saving: \`cat video-manifest.json | jq .\`
 
 ---
 
-${ASSET_USAGE_GUIDELINES}
+## Quick Reference
+
+### Minimum Viable Command
+\`\`\`bash
+cat <<'EOF' | ${cmd2} video create --output ./public
+{"scenes":[{"name":"Main","script":"Your script here."}],"musicPrompt":"ambient background"}
+EOF
+\`\`\`
+
+### Full Command with All Options
+\`\`\`bash
+cat <<'EOF' | ${cmd2} video create --output ./public
+{
+  "scenes": [
+    {"name": "Hook", "script": "...", "imageQuery": "..."},
+    {"name": "Demo", "script": "...", "videoQuery": "..."},
+    {"name": "CTA", "script": "...", "imageQuery": "..."}
+  ],
+  "voiceId": "21m00Tcm4TlvDq8ikWAM",
+  "voiceSettings": {"speed": 1.0, "stability": 0.5, "similarity": 0.75, "style": 0.3},
+  "musicPrompt": "genre, mood, instruments"
+}
+EOF
+\`\`\`
+
+### Voice Settings Presets
+| Preset | speed | stability | similarity | style | Best For |
+|--------|-------|-----------|------------|-------|----------|
+| Professional | 1.0 | 0.6 | 0.8 | 0.2 | Corporate, B2B |
+| Energetic | 1.1 | 0.4 | 0.7 | 0.5 | Startups, Apps |
+| Calm | 0.9 | 0.7 | 0.8 | 0.2 | Tutorial, Explainer |
+| Dramatic | 0.85 | 0.3 | 0.6 | 0.7 | Announcements |
 
 ---
+
+## References
+
+For advanced techniques, consult these files after Phase 1:
+- \`rules/video/motion-design.md\` - Animation principles
+- \`rules/video/thumbnails.md\` - CTR optimization
+- \`rules/video/svg-animations.md\` - Write-on effects
+- \`rules/video/asset-usage.md\` - Creative asset usage
 `;
 }
 
@@ -3766,8 +4199,12 @@ ${cmd2} create --file product-brief.md
 
 ### From URL
 
+Supports websites, YouTube videos, and Twitter/X posts:
+
 \`\`\`bash
 ${cmd2} create --url https://company.com/product
+${cmd2} create --url https://youtube.com/watch?v=abc123
+${cmd2} create --url https://x.com/user/status/123456
 \`\`\`
 
 ### From Piped Content
@@ -4784,6 +5221,7 @@ var createCommand3 = new Command19("create").description("Create video assets (v
       }
     }
     const voice = scenesInput?.voice || options.voice;
+    const voiceId = scenesInput?.voiceId;
     const musicPrompt = scenesInput?.musicPrompt || options.musicPrompt || "uplifting background music, positive energy";
     const audioDir = join2(options.output, "audio");
     const imagesDir = join2(options.output, "images");
@@ -4812,6 +5250,8 @@ var createCommand3 = new Command19("create").description("Create video assets (v
         texts: ttsRequests,
         options: {
           voice,
+          voiceId,
+          // ElevenLabs voice ID takes priority on backend
           voiceSettings: scenesInput.voiceSettings
         }
       });
@@ -5426,9 +5866,65 @@ var thumbnailCommand = new Command19("thumbnail").description("Embed a thumbnail
 });
 var videoCommand = new Command19("video").description("Video asset generation commands").addCommand(initCommand).addCommand(createCommand3).addCommand(searchCommand2).addCommand(thumbnailCommand);
 
+// src/commands/scrape.ts
+import { Command as Command20 } from "commander";
+import ora13 from "ora";
+import { writeFile as writeFile6 } from "fs/promises";
+var scrapeCommand = new Command20("scrape").description("Extract content from a URL").argument("<url>", "URL to scrape").option("-o, --output <path>", "Save content to file").option("-f, --format <format>", "Output format: human, json, quiet", "human").action(async (url, options) => {
+  const format = options.format;
+  const spinner = format === "human" ? ora13("Scraping URL...").start() : null;
+  try {
+    const result = await scrapeUrl(url);
+    spinner?.stop();
+    if (!result.success) {
+      error(result.error || "Failed to scrape URL");
+      process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+    const data = result.data;
+    if (options.output) {
+      await writeFile6(options.output, data.content, "utf-8");
+      if (format === "human") {
+        success(`Content saved to: ${options.output}`);
+      }
+    }
+    if (format === "json") {
+      printJson(data);
+      return;
+    }
+    if (format === "quiet") {
+      console.log(data.content);
+      return;
+    }
+    if (data.title) {
+      console.log();
+      console.log(`Title: ${data.title}`);
+    }
+    if (data.metadata?.description) {
+      console.log(`Description: ${data.metadata.description}`);
+    }
+    console.log(`URL: ${data.url}`);
+    console.log(`Tokens: ~${data.metadata?.tokenUsage?.toLocaleString() || "unknown"}`);
+    if (data.warning) {
+      warn(data.warning);
+    }
+    if (!options.output) {
+      console.log();
+      console.log("--- Content ---");
+      console.log(data.content);
+    }
+    if (data.cost && data.cost > 0) {
+      info(`Cost: $${data.cost.toFixed(6)}`);
+    }
+  } catch (err) {
+    spinner?.stop();
+    error(err instanceof Error ? err.message : "Unknown error");
+    process.exit(EXIT_CODES.GENERAL_ERROR);
+  }
+});
+
 // src/index.ts
-var VERSION = "0.1.13";
-var program = new Command20();
+var VERSION = "0.1.14";
+var program = new Command21();
 var cmdName = brand.commands[0];
 program.name(cmdName).description(brand.description).version(VERSION, "-v, --version", "Show version number").option("--debug", "Enable debug logging").option("--no-color", "Disable colored output").configureOutput({
   outputError: (str, write) => {
@@ -5453,6 +5949,7 @@ program.addCommand(musicCommand);
 program.addCommand(mixAudioCommand);
 program.addCommand(imageCommand);
 program.addCommand(videoCommand);
+program.addCommand(scrapeCommand);
 var deriveCommand = buildDeriveCommand();
 if (deriveCommand.commands.length > 0) {
   program.addCommand(deriveCommand);