@mytechtoday/augment-extensions 2.3.7 → 2.5.0

package/augment-extensions/writing-standards/screenplay/commercials/rules/commercials.md

@@ -0,0 +1,285 @@
+# Commercial Writing: Core Principles
+
+## Overview
+
+Commercial writing is the art of persuasive storytelling within strict time constraints. Whether creating a 15-second spot or a 60-second narrative, the goal is to capture attention, communicate value, and inspire action—all while maintaining brand integrity and legal compliance.
+
+## The Five Pillars of Effective Commercial Writing
+
+### 1. Clear Messaging
+
+**Principle:** One commercial, one message. Trying to communicate multiple ideas dilutes impact and confuses viewers.
+
+**Best Practices:**
+- Identify the single most important message before writing
+- Every element (visual, audio, dialogue) should support this message
+- Test your message: Can a viewer recall it 24 hours later?
+- Avoid jargon, complex terminology, or industry-speak
+- Use simple, direct language that resonates with your target audience
+
+**Example - Clear vs. Unclear:**
+
+```
+❌ UNCLEAR (30-second car commercial):
+"The new Apex sedan features advanced safety technology, 
+best-in-class fuel efficiency, premium leather interior, 
+cutting-edge infotainment system, and award-winning design."
+
+✅ CLEAR (30-second car commercial):
+"The new Apex sedan. The safest car we've ever built."
+(All visuals and copy support this single safety message)
+```
+
+### 2. Strong Call-to-Action (CTA)
+
+**Principle:** Every commercial must tell viewers exactly what to do next. A weak or missing CTA wastes the entire investment.
+
+**Best Practices:**
+- Place CTA in final 5-10 seconds (depending on length)
+- Use action verbs: "Visit," "Call," "Download," "Try," "Shop"
+- Make it specific: "Visit dealership.com/test-drive" not just "Visit our website"
+- Include urgency when appropriate: "Limited time offer," "While supplies last"
+- Ensure CTA is visually and audibly clear (on-screen text + voiceover)
+
+**CTA Strength Hierarchy:**
+1. **Strongest:** Specific action + deadline ("Order by midnight for 50% off")
+2. **Strong:** Specific action + incentive ("Visit today for free consultation")
+3. **Moderate:** Specific action ("Download the app now")
+4. **Weak:** Generic action ("Learn more online")
+5. **Weakest:** No action ("Brand X. We're here.")
+
+**Example - Strong CTA:**
+
+```
+VOICEOVER
+Visit TryApex.com slash safety to schedule 
+your test drive. That's TryApex.com slash safety.
+
+ON-SCREEN TEXT
+TryApex.com/safety
+```
+
+### 3. Memorable Hook
+
+**Principle:** You have 2-3 seconds to capture attention before viewers tune out. The hook is everything.
+
+**Hook Types:**
+- **Visual Hook:** Unexpected imagery, striking visuals, pattern interruption
+- **Audio Hook:** Distinctive sound, music sting, silence, unexpected noise
+- **Narrative Hook:** Question, conflict, relatable problem, surprising statement
+- **Emotional Hook:** Humor, nostalgia, fear, joy, surprise
+
+**Best Practices:**
+- Open with the hook—don't build up to it
+- Make it relevant to your message (not just attention-grabbing)
+- Test hooks with target audience before production
+- Avoid clichés: babies, puppies, explosions (unless truly original)
+
+**Example - Effective Hooks:**
+
+```
+VISUAL HOOK:
+[OPEN ON: A car driving normally, suddenly flips upside-down]
+[REVEAL: It's a toy car in a child's hand]
+VOICEOVER: "When you're a parent, everything feels like a crash test."
+
+AUDIO HOOK:
+[OPEN ON: Complete silence. No music, no sound]
+[5 seconds of silence]
+VOICEOVER (whisper): "Noise-canceling headphones that actually work."
+
+NARRATIVE HOOK:
+[OPEN ON: Woman at laptop, frustrated]
+WOMAN: "I've been on hold for 47 minutes."
+VOICEOVER: "There's a better way."
+```
+
+### 4. Emotional Connection
+
+**Principle:** People buy with emotion and justify with logic. Create an emotional response first, then support with rational benefits.
+
+**Emotional Triggers:**
+- **Joy/Happiness:** Celebrations, achievements, family moments
+- **Fear/Anxiety:** Loss prevention, security, safety
+- **Nostalgia:** "Remember when," throwback aesthetics, familiar music
+- **Aspiration:** "Be like this," lifestyle upgrade, status
+- **Belonging:** Community, shared values, "people like you"
+- **Relief:** Problem solved, stress removed, simplification
+
+**Best Practices:**
+- Choose ONE primary emotion per commercial
+- Show emotion through characters, not just tell through copy
+- Use music to amplify emotional tone
+- Authentic emotion beats manufactured sentiment
+- Test emotional resonance with focus groups
+
+**Example - Emotional Connection:**
+
+```
+[OPEN ON: Elderly man sitting alone at kitchen table]
+[He opens a video call on tablet]
+[Grandchildren appear on screen, waving]
+GRANDKIDS (V.O.): "Hi Grandpa!"
+[Man's face lights up with genuine joy]
+VOICEOVER: "Stay connected to what matters."
+[SUPER: FamilyConnect Video Calling]
+```
+
+### 5. Audience Targeting
+
+**Principle:** A commercial for everyone is a commercial for no one. Know exactly who you're talking to and speak their language.
+
+**Targeting Dimensions:**
+- **Demographics:** Age, gender, income, education, location
+- **Psychographics:** Values, interests, lifestyle, attitudes
+- **Behavioral:** Purchase history, brand loyalty, media consumption
+- **Situational:** Life stage, current needs, pain points
+
+**Best Practices:**
+- Create detailed audience personas before writing
+- Use language, references, and cultural touchpoints that resonate
+- Cast talent that reflects your target audience
+- Choose media placement that reaches your audience
+- Avoid alienating non-target audiences (unless intentional)
+
+**Example - Targeted Messaging:**
+
+```
+MILLENNIAL AUDIENCE (Streaming service):
+[OPEN ON: Young professional on couch, scrolling phone]
+VOICEOVER: "Another Friday night, another 45 minutes 
+deciding what to watch."
+[App interface appears]
+VOICEOVER: "StreamPick AI knows what you'll love. 
+No more scrolling. Just watching."
+
+BOOMER AUDIENCE (Same service):
+[OPEN ON: Couple in living room, confused by remote]
+VOICEOVER: "Remember when TV was simple?"
+[Simple interface appears]
+VOICEOVER: "StreamPick. All your favorites. 
+One button. No confusion."
+```
+
+## The Commercial Writing Formula
+
+### 3-Act Structure (Adapted for Commercials)
+
+**Act 1: Problem/Hook (First 20-30%)**
+- Establish relatable problem or capture attention
+- Introduce conflict or need
+- Create curiosity or concern
+
+**Act 2: Solution (Middle 40-50%)**
+- Introduce product/service as solution
+- Demonstrate key benefit
+- Show transformation or resolution
+
+**Act 3: Call-to-Action (Final 20-30%)**
+- Reinforce benefit
+- Clear, specific CTA
+- Brand reinforcement
+
+**Example - 30-Second Structure:**
+
+```
+ACT 1 (0:00-0:08) - PROBLEM
+[Woman at desk, surrounded by paperwork, stressed]
+WOMAN: "I spend more time doing paperwork than 
+seeing patients."
+
+ACT 2 (0:09-0:22) - SOLUTION
+[She opens laptop, uses software]
+VOICEOVER: "MediFlow automates your admin. 
+Charts, billing, scheduling—done."
+[She closes laptop, smiles]
+
+ACT 3 (0:23-0:30) - CTA
+VOICEOVER: "Try MediFlow free for 30 days. 
+Visit MediFlow.com."
+[SUPER: MediFlow.com - 30 Day Free Trial]
+```
+
+## Common Pitfalls to Avoid
+
+### 1. Feature Dumping
+**Problem:** Listing every product feature instead of focusing on benefits  
+**Solution:** Choose 1-2 key benefits that matter most to your audience
+
+### 2. Weak Opening
+**Problem:** Slow build-up, logo first, generic establishing shots  
+**Solution:** Hook in first 2-3 seconds, logo at end
+
+### 3. Unclear Brand
+**Problem:** Viewer can't remember who the commercial was for  
+**Solution:** Brand integration throughout, not just end card
+
+### 4. No Differentiation
+**Problem:** Could be any competitor's commercial  
+**Solution:** Unique selling proposition, distinctive creative approach
+
+### 5. Overproduction
+**Problem:** Style over substance, effects overshadow message  
+**Solution:** Serve the message, not the ego
+
+## Writing for Different Commercial Lengths
+
+### 15-Second Spots
+- **One idea only**
+- Hook + benefit + CTA
+- No time for storytelling
+- Every word counts
+- Often used for brand awareness or simple promotions
+
+### 30-Second Spots
+- **Industry standard**
+- Room for simple narrative
+- Problem-solution structure works well
+- 2-3 key points maximum
+- Most versatile length
+
+### 60-Second Spots
+- **Premium storytelling**
+- Full narrative arc possible
+- Emotional depth achievable
+- Multiple benefits can be shown
+- Higher production value expected
+
+## Integration with Brand Guidelines
+
+Every commercial must align with:
+- **Brand Voice:** Tone, personality, language style
+- **Brand Values:** What the company stands for
+- **Visual Identity:** Colors, fonts, logo usage
+- **Messaging Hierarchy:** Primary and secondary messages
+- **Legal Requirements:** Disclaimers, disclosures, compliance
+
+## Measurement and Optimization
+
+**Key Performance Indicators (KPIs):**
+- **Awareness:** Brand recall, message retention
+- **Engagement:** View-through rate, social shares
+- **Action:** Click-through rate, conversions, sales lift
+- **Efficiency:** Cost per acquisition, return on ad spend
+
+**A/B Testing Opportunities:**
+- Different hooks (first 3 seconds)
+- CTA variations (wording, placement, urgency)
+- Emotional tone (humor vs. serious)
+- Talent/casting choices
+- Music/audio approaches
+
+## Conclusion
+
+Effective commercial writing combines art and science: the art of storytelling and emotional connection, the science of persuasion and measurement. Master these five pillars—clear messaging, strong CTAs, memorable hooks, emotional connection, and precise targeting—and you'll create commercials that not only capture attention but drive real business results.
+
+Remember: In commercial writing, every second counts, every word matters, and every element must earn its place. Be ruthless in editing, relentless in testing, and always put your audience first.
+
+---
+
+**Next Steps:**
+- Review [Commercial Formats](./commercial-formats.md) for duration-specific guidelines
+- Explore [Commercial Types](./commercial-types.md) for category-specific best practices
+- Study [Persuasion Techniques](./commercial-persuasion.md) for advanced strategies
+- Consult [Legal Compliance](./commercial-laws.md) before production
+

package/augment-extensions/writing-standards/screenplay/commercials/scripts/validate-character-count.ts

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * Validate Character Count for Commercials Module
+ * Version: 3.0.0
+ * Last Updated: 2026-03-03
+ * 
+ * Validates that each individual content file is between 3,000 and 45,000 characters
+ * 
+ * Usage:
+ *   npx tsx validate-character-count.ts [--verbose] [--json]
+ *   npm run validate:commercials [-- --verbose] [-- --json]
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as process from 'process';
+
+// Configuration
+const FILE_MIN = 3000;
+const FILE_MAX = 45000;
+
+const EXCLUDED_FILES = [
+  'module.json',
+  'README.md',
+  'CONFIGURATION.md',
+  'REFERENCES.md',
+  'CHARACTER-COUNT-TRACKING.md',
+  'VALIDATION-REPORT.md'
+];
+
+// Color codes for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  gray: '\x1b[90m',
+  white: '\x1b[37m',
+  yellow: '\x1b[33m'
+};
+
+interface FileInfo {
+  file: string;
+  path: string;
+  characters: number;
+  status: string;
+  statusColor: keyof typeof colors;
+  isExcluded: boolean;
+  directory: string;
+}
+
+interface ValidationResult {
+  totalCharacters: number;
+  fileMin: number;
+  fileMax: number;
+  status: 'PASS' | 'FAIL';
+  message: string;
+  passedFiles: number;
+  failedFiles: number;
+  files: FileInfo[];
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const verbose = args.includes('--verbose') || args.includes('-v');
+const jsonOutput = args.includes('--json') || args.includes('-j');
+
+// Get module root (parent of scripts directory)
+const moduleRoot = path.resolve(__dirname, '..');
+
+/**
+ * Find all markdown files recursively
+ */
+function findMarkdownFiles(dir: string): string[] {
+  const files: string[] = [];
+  
+  function traverse(currentDir: string) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      
+      if (entry.isDirectory()) {
+        traverse(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(fullPath);
+      }
+    }
+  }
+  
+  traverse(dir);
+  return files;
+}
+
+/**
+ * Validate character counts
+ */
+function validateCharacterCounts(): ValidationResult {
+  const markdownFiles = findMarkdownFiles(moduleRoot);
+  const fileBreakdown: FileInfo[] = [];
+  let totalChars = 0;
+  let passedCount = 0;
+  let failedCount = 0;
+  
+  for (const filePath of markdownFiles) {
+    const fileName = path.basename(filePath);
+    const relativePath = path.relative(moduleRoot, filePath);
+    const directory = path.basename(path.dirname(filePath));
+    const isExcluded = EXCLUDED_FILES.includes(fileName);
+    
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const charCount = content.length;
+    totalChars += charCount;
+    
+    let status: string;
+    let statusColor: keyof typeof colors;
+    
+    if (isExcluded) {
+      status = 'EXCLUDED';
+      statusColor = 'gray';
+    } else if (charCount >= FILE_MIN && charCount <= FILE_MAX) {
+      status = 'PASS';
+      statusColor = 'green';
+      passedCount++;
+    } else if (charCount < FILE_MIN) {
+      const deficit = FILE_MIN - charCount;
+      status = `FAIL (too short by ${deficit} chars)`;
+      statusColor = 'red';
+      failedCount++;
+    } else {
+      const excess = charCount - FILE_MAX;
+      status = `FAIL (too long by ${excess} chars)`;
+      statusColor = 'red';
+      failedCount++;
+    }
+    
+    fileBreakdown.push({
+      file: fileName,
+      path: relativePath,
+      characters: charCount,
+      status,
+      statusColor,
+      isExcluded,
+      directory
+    });
+  }
+  
+  const overallStatus: 'PASS' | 'FAIL' = failedCount === 0 ? 'PASS' : 'FAIL';
+  const message = failedCount === 0
+    ? 'All content files within 3,000 - 45,000 character range'
+    : `${failedCount} file(s) outside target range`;
+  
+  return {
+    totalCharacters: totalChars,
+    fileMin: FILE_MIN,
+    fileMax: FILE_MAX,
+    status: overallStatus,
+    message,
+    passedFiles: passedCount,
+    failedFiles: failedCount,
+    files: fileBreakdown
+  };
+}
+
+/**
+ * Print colored text to console
+ */
+function printColor(text: string, color: keyof typeof colors) {
+  console.log(`${colors[color]}${text}${colors.reset}`);
+}
+
+/**
+ * Print validation results to console
+ */
+function printResults(result: ValidationResult) {
+  console.log('');
+  printColor('=== Commercial Writing Standards - Per-File Character Count Validation ===', 'cyan');
+  printColor(`Per-File Target Range: ${FILE_MIN} - ${FILE_MAX} characters`, 'gray');
+  printColor(`Total Module Characters: ${result.totalCharacters}`, 'white');
+  console.log('');
+
+  const symbol = result.status === 'PASS' ? '✓' : '✗';
+  printColor(`${symbol} ${result.status} : ${result.message}`, result.status === 'PASS' ? 'green' : 'red');
+
+  // Show failed files prominently
+  const failedFiles = result.files.filter(f => f.status.startsWith('FAIL'));
+  if (failedFiles.length > 0) {
+    console.log('');
+    printColor('=== Failed Files ===', 'red');
+    for (const file of failedFiles) {
+      printColor(`  ✗ ${file.file}: ${file.characters} chars - ${file.status}`, 'red');
+    }
+  }
+
+  // Verbose output
+  if (verbose) {
+    console.log('');
+    printColor('=== All Files ===', 'cyan');
+
+    const sortedFiles = [...result.files].sort((a, b) => {
+      if (a.isExcluded !== b.isExcluded) return a.isExcluded ? 1 : -1;
+      return b.characters - a.characters;
+    });
+
+    for (const file of sortedFiles) {
+      const symbol = file.status === 'PASS' ? '✓' : file.status === 'EXCLUDED' ? '○' : '✗';
+      printColor(`  ${symbol} ${file.file}: ${file.characters} chars - ${file.status}`, file.statusColor);
+    }
+
+    // Category totals
+    console.log('');
+    printColor('=== Category Totals ===', 'cyan');
+
+    const categories = {
+      'Foundational Rules': result.files.filter(f => /^commercial(s|-(formats|types))\.md$/.test(f.file)),
+      'Technique Rules': result.files.filter(f => /^commercial-(techniques|persuasion|audience|scripts|tips)\.md$/.test(f.file)),
+      'Legal/Ethical Rules': result.files.filter(f => /^commercial-(laws|ethics)\.md$/.test(f.file)),
+      'Supporting Rules': result.files.filter(f => /^commercial-(counter-principles-examples|templates|mistakes|history|glossary)\.md$/.test(f.file)),
+      'Example Files': result.files.filter(f => /^(effective|ineffective)-commercials\.md$/.test(f.file)),
+      'Infrastructure': result.files.filter(f => f.isExcluded)
+    };
+
+    for (const [category, files] of Object.entries(categories)) {
+      if (files.length > 0) {
+        const total = files.reduce((sum, f) => sum + f.characters, 0);
+        const passCount = files.filter(f => f.status === 'PASS' || f.status === 'EXCLUDED').length;
+        printColor(`${category} : ${total} chars - ${files.length} files (${passCount} passing)`, 'white');
+      } else {
+        printColor(`${category} : 0 chars - 0 files`, 'gray');
+      }
+    }
+
+    // Summary
+    console.log('');
+    printColor('=== Summary ===', 'cyan');
+    printColor(`Content Files: ${result.files.length - EXCLUDED_FILES.length}`, 'white');
+    printColor(`Passed: ${result.passedFiles}`, 'green');
+    printColor(`Failed: ${result.failedFiles}`, result.failedFiles === 0 ? 'green' : 'red');
+    printColor(`Excluded: ${EXCLUDED_FILES.length}`, 'gray');
+  }
+
+  console.log('');
+}
+
+/**
+ * Main execution
+ */
+function main() {
+  const result = validateCharacterCounts();
+
+  if (jsonOutput) {
+    // JSON output
+    const output = {
+      totalCharacters: result.totalCharacters,
+      fileMin: result.fileMin,
+      fileMax: result.fileMax,
+      status: result.status,
+      message: result.message,
+      passedFiles: result.passedFiles,
+      failedFiles: result.failedFiles,
+      files: result.files.map(f => ({
+        file: f.file,
+        path: f.path,
+        characters: f.characters,
+        status: f.status,
+        isExcluded: f.isExcluded
+      }))
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    // Console output
+    printResults(result);
+  }
+
+  // Exit with appropriate code
+  process.exit(result.status === 'PASS' ? 0 : 1);
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main();
+}
+

package/cli/dist/commands/generate-shot-list/generator/ai-blocking-extractor.d.ts

@@ -0,0 +1,58 @@
+/**
+ * AI-Powered Blocking Extractor
+ *
+ * Uses Claude Sonnet 4.6 to extract detailed character blocking and spatial positions
+ * from screenplay action lines. Infers stage positions, relative positions, and
+ * maintains spatial consistency across shots.
+ */
+export interface CharacterBlockingPosition {
+    character: string;
+    position: string;
+    stagePosition?: string;
+    relativePosition?: string;
+    action?: string;
+}
+export interface CharacterDescription {
+    character: string;
+    physicalAppearance: string;
+    wardrobe: string;
+    emotion?: string;
+}
+export interface BlockingExtractionResult {
+    characterPositions: CharacterBlockingPosition[];
+    characterDescriptions: CharacterDescription[];
+    setDescription: string;
+    characterActions: string[];
+    soundEffects: string[];
+}
+export declare class AIBlockingExtractor {
+    private client;
+    private characterDescriptionCache;
+    private styleGuidelines;
+    constructor(apiKey?: string, styleGuidelines?: any);
+    /**
+     * Clear the character description cache (call at start of new screenplay)
+     */
+    clearCache(): void;
+    /**
+     * Get cached character description
+     */
+    getCachedDescription(characterName: string): CharacterDescription | undefined;
+    /**
+     * Extract blocking, set description, and actions from action lines using AI
+     */
+    extractBlocking(actionLines: string[], characterNames: string[], previousPositions?: Map<string, CharacterBlockingPosition>): Promise<BlockingExtractionResult>;
+    /**
+     * Build prompt for AI blocking extraction
+     */
+    private buildBlockingPrompt;
+    /**
+     * Parse AI response into structured blocking data
+     */
+    private parseBlockingResponse;
+    /**
+     * Fallback extraction when AI fails
+     */
+    private fallbackExtraction;
+}
+//# sourceMappingURL=ai-blocking-extractor.d.ts.map

package/cli/dist/commands/generate-shot-list/generator/ai-blocking-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-blocking-extractor.d.ts","sourceRoot":"","sources":["../../../../src/commands/generate-shot-list/generator/ai-blocking-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,kBAAkB,EAAE,yBAAyB,EAAE,CAAC;IAChD,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,yBAAyB,CAAgD;IACjF,OAAO,CAAC,eAAe,CAAoB;gBAE/B,MAAM,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,GAAG;IAOlD;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAI7E;;OAEG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EAAE,EACrB,cAAc,EAAE,MAAM,EAAE,EACxB,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,GACzD,OAAO,CAAC,wBAAwB,CAAC;IAwDpC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgK3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAe3B"}