@farazirfan/costar-server-executor 1.7.37 → 1.7.39

package/skills/docx/scripts/pack.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Pack a directory into a DOCX file.
+
+Validates with auto-repair, condenses XML formatting, and creates the DOCX.
+"""
+
+import argparse
+import shutil
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+import defusedxml.minidom
+
+from helpers.simplify_redlines import infer_author
+from ooxml.scripts.validation import DOCXSchemaValidator, RedliningValidator
+
+
+def pack(
+    input_directory: str,
+    output_file: str,
+    original_file: str | None = None,
+    validate: bool = True,
+) -> tuple[None, str]:
+    """Pack a directory into a DOCX file.
+
+    Args:
+        input_directory: Path to unpacked DOCX directory
+        output_file: Path to output DOCX file
+        original_file: Path to original DOCX for validation comparison
+        validate: If True, run validation with auto-repair before packing
+
+    Returns:
+        (None, message) - message indicates success or failure
+    """
+    input_dir = Path(input_directory)
+    output_path = Path(output_file)
+
+    if not input_dir.is_dir():
+        return None, f"Error: {input_dir} is not a directory"
+
+    if output_path.suffix.lower() != ".docx":
+        return None, f"Error: {output_file} must be a .docx file"
+
+    # Validate with auto-repair if requested and original file provided
+    if validate and original_file:
+        original_path = Path(original_file)
+        if original_path.exists():
+            success, output = _run_validation(input_dir, original_path)
+            if output:
+                print(output)
+            if not success:
+                return None, f"Error: Validation failed for {input_dir}"
+
+    # Work in temporary directory to avoid modifying original
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_content_dir = Path(temp_dir) / "content"
+        shutil.copytree(input_dir, temp_content_dir)
+
+        # Process XML files to remove pretty-printing whitespace
+        for pattern in ["*.xml", "*.rels"]:
+            for xml_file in temp_content_dir.rglob(pattern):
+                _condense_xml(xml_file)
+
+        # Create final DOCX file as zip archive
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for f in temp_content_dir.rglob("*"):
+                if f.is_file():
+                    zf.write(f, f.relative_to(temp_content_dir))
+
+    return None, f"Successfully packed {input_dir} to {output_file}"
+
+
+def _run_validation(unpacked_dir: Path, original_file: Path) -> tuple[bool, str | None]:
+    """Run validation with auto-repair.
+
+    Returns:
+        (success, output) - success is True if all validations pass
+    """
+    output_lines = []
+
+    # Infer author for redlining validation
+    try:
+        author = infer_author(unpacked_dir, original_file)
+    except ValueError as e:
+        print(f"Warning: {e} Using default author 'Costar'.", file=sys.stderr)
+        author = "Costar"
+
+    # Create validators
+    validators = [
+        DOCXSchemaValidator(unpacked_dir, original_file),
+        RedliningValidator(unpacked_dir, original_file, author=author),
+    ]
+
+    # Run auto-repair
+    total_repairs = sum(v.repair() for v in validators)
+    if total_repairs:
+        output_lines.append(f"Auto-repaired {total_repairs} issue(s)")
+
+    # Run validation
+    success = all(v.validate() for v in validators)
+
+    if success:
+        output_lines.append("All validations PASSED!")
+
+    return success, "\n".join(output_lines) if output_lines else None
+
+
+def _condense_xml(xml_file: Path) -> None:
+    """Strip unnecessary whitespace and remove comments from XML."""
+    try:
+        with open(xml_file, encoding="utf-8") as f:
+            dom = defusedxml.minidom.parse(f)
+
+        # Process each element to remove whitespace and comments
+        for element in dom.getElementsByTagName("*"):
+            # Skip text elements (w:t, a:t, etc.) - preserve their content
+            if element.tagName.endswith(":t"):
+                continue
+
+            # Remove whitespace-only text nodes and comment nodes
+            for child in list(element.childNodes):
+                if (
+                    child.nodeType == child.TEXT_NODE
+                    and child.nodeValue
+                    and child.nodeValue.strip() == ""
+                ) or child.nodeType == child.COMMENT_NODE:
+                    element.removeChild(child)
+
+        # Write back the condensed XML
+        with open(xml_file, "wb") as f:
+            f.write(dom.toxml(encoding="UTF-8"))
+    except Exception as e:
+        print(f"ERROR: Failed to parse {xml_file.name}: {e}", file=sys.stderr)
+        raise
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Pack a directory into a DOCX file")
+    parser.add_argument("input_directory", help="Unpacked DOCX directory")
+    parser.add_argument("output_file", help="Output DOCX file")
+    parser.add_argument(
+        "--original",
+        help="Original DOCX file for validation comparison",
+    )
+    parser.add_argument(
+        "--validate",
+        type=lambda x: x.lower() == "true",
+        default=True,
+        metavar="true|false",
+        help="Run validation with auto-repair (default: true)",
+    )
+    args = parser.parse_args()
+
+    _, message = pack(
+        args.input_directory,
+        args.output_file,
+        original_file=args.original,
+        validate=args.validate,
+    )
+    print(message)
+
+    if "Error" in message:
+        sys.exit(1)

package/skills/docx/scripts/templates/comments.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" ?>
+<w:comments xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl w16du wp14">
+</w:comments>

package/skills/docx/scripts/templates/commentsExtended.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" ?>
+<w15:commentsEx xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl w16du wp14">
+</w15:commentsEx>

package/skills/docx/scripts/templates/commentsExtensible.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" ?>
+<w16cex:commentsExtensible xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" xmlns:cr="http://schemas.microsoft.com/office/comments/2020/reactions" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl cr w16du wp14">
+</w16cex:commentsExtensible>

package/skills/docx/scripts/templates/commentsIds.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" ?>
+<w16cid:commentsIds xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas" xmlns:cx="http://schemas.microsoft.com/office/drawing/2014/chartex" xmlns:cx1="http://schemas.microsoft.com/office/drawing/2015/9/8/chartex" xmlns:cx2="http://schemas.microsoft.com/office/drawing/2015/10/21/chartex" xmlns:cx3="http://schemas.microsoft.com/office/drawing/2016/5/9/chartex" xmlns:cx4="http://schemas.microsoft.com/office/drawing/2016/5/10/chartex" xmlns:cx5="http://schemas.microsoft.com/office/drawing/2016/5/11/chartex" xmlns:cx6="http://schemas.microsoft.com/office/drawing/2016/5/12/chartex" xmlns:cx7="http://schemas.microsoft.com/office/drawing/2016/5/13/chartex" xmlns:cx8="http://schemas.microsoft.com/office/drawing/2016/5/14/chartex" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:aink="http://schemas.microsoft.com/office/drawing/2016/ink" xmlns:am3d="http://schemas.microsoft.com/office/drawing/2017/model3d" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:oel="http://schemas.microsoft.com/office/2019/extlst" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml" xmlns:w16cex="http://schemas.microsoft.com/office/word/2018/wordml/cex" xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid" xmlns:w16="http://schemas.microsoft.com/office/word/2018/wordml" xmlns:w16du="http://schemas.microsoft.com/office/word/2023/wordml/word16du" xmlns:w16sdtdh="http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash" xmlns:w16sdtfl="http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock" xmlns:w16se="http://schemas.microsoft.com/office/word/2015/wordml/symex" xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup" xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk" xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16sdtfl w16du wp14">
+</w16cid:commentsIds>

package/skills/docx/scripts/templates/people.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" ?>
+<w15:people xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml">
+</w15:people>

package/skills/docx/scripts/unpack.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Unpack DOCX files for editing.
+
+Extracts the ZIP archive, pretty-prints XML files, and merges adjacent runs
+with identical formatting (enabled by default).
+"""
+
+import argparse
+import sys
+import zipfile
+from pathlib import Path
+
+import defusedxml.minidom
+from helpers.merge_runs import merge_runs as do_merge_runs
+from helpers.simplify_redlines import simplify_redlines as do_simplify_redlines
+
+# Smart quotes that get mangled by the tokenizer - convert to XML entities
+# Using hex escapes since we can't type the actual characters
+SMART_QUOTE_REPLACEMENTS = {
+    "\u201c": "“",  # Left double quote
+    "\u201d": "”",  # Right double quote
+    "\u2018": "‘",  # Left single quote
+    "\u2019": "’",  # Right single quote
+}
+
+
+def unpack(
+    input_file: str,
+    output_directory: str,
+    merge_runs: bool = True,
+    simplify_redlines: bool = True,
+) -> tuple[None, str]:
+    """Unpack a DOCX file and prepare for editing.
+
+    Args:
+        input_file: Path to DOCX file
+        output_directory: Path to output directory
+        merge_runs: If True, merge adjacent runs with identical formatting
+        simplify_redlines: If True, merge adjacent tracked changes from same author
+
+    Returns:
+        (None, message) - message indicates success or failure
+    """
+    input_path = Path(input_file)
+    output_path = Path(output_directory)
+
+    if not input_path.exists():
+        return None, f"Error: {input_file} does not exist"
+
+    if input_path.suffix.lower() != ".docx":
+        return None, f"Error: {input_file} must be a .docx file"
+
+    try:
+        # Create output directory
+        output_path.mkdir(parents=True, exist_ok=True)
+
+        # Extract ZIP contents
+        with zipfile.ZipFile(input_path, "r") as zf:
+            zf.extractall(output_path)
+
+        # Pretty print all XML files
+        xml_files = list(output_path.rglob("*.xml")) + list(output_path.rglob("*.rels"))
+        for xml_file in xml_files:
+            _pretty_print_xml(xml_file)
+
+        message = f"Unpacked {input_file} ({len(xml_files)} XML files)"
+
+        # Simplify tracked changes if requested (before merge_runs so more runs can merge)
+        if simplify_redlines:
+            simplify_count, _ = do_simplify_redlines(str(output_path))
+            message += f", simplified {simplify_count} tracked changes"
+
+        # Merge runs if requested
+        if merge_runs:
+            merge_count, _ = do_merge_runs(str(output_path))
+            message += f", merged {merge_count} runs"
+
+        # Escape smart quotes AFTER transformations (which rewrite files)
+        for xml_file in xml_files:
+            _escape_smart_quotes(xml_file)
+
+        return None, message
+
+    except zipfile.BadZipFile:
+        return None, f"Error: {input_file} is not a valid DOCX file"
+    except Exception as e:
+        return None, f"Error unpacking: {e}"
+
+
+def _pretty_print_xml(xml_file: Path) -> None:
+    """Pretty print an XML file with indentation."""
+    content = xml_file.read_text(encoding="utf-8")
+    dom = defusedxml.minidom.parseString(content)
+    xml_file.write_bytes(dom.toprettyxml(indent="  ", encoding="utf-8"))
+
+
+def _escape_smart_quotes(xml_file: Path) -> None:
+    """Replace smart quotes with XML entities so they survive tokenization."""
+    content = xml_file.read_text(encoding="utf-8")
+    for char, entity in SMART_QUOTE_REPLACEMENTS.items():
+        content = content.replace(char, entity)
+    xml_file.write_text(content, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Unpack a DOCX file for editing")
+    parser.add_argument("input_file", help="DOCX file to unpack")
+    parser.add_argument("output_directory", help="Output directory")
+    parser.add_argument(
+        "--merge-runs",
+        type=lambda x: x.lower() == "true",
+        default=True,
+        metavar="true|false",
+        help="Merge adjacent runs with identical formatting (default: true)",
+    )
+    parser.add_argument(
+        "--simplify-redlines",
+        type=lambda x: x.lower() == "true",
+        default=True,
+        metavar="true|false",
+        help="Merge adjacent tracked changes from same author (default: true)",
+    )
+    args = parser.parse_args()
+
+    _, message = unpack(
+        args.input_file,
+        args.output_directory,
+        merge_runs=args.merge_runs,
+        simplify_redlines=args.simplify_redlines,
+    )
+    print(message)
+
+    if "Error" in message:
+        sys.exit(1)

package/skills/longform-video-generation/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: longform-video-generator
+description: Generate videos longer than 8 seconds using Google Veo 3.1 API. Creates seamless multi-scene videos by chaining 8-second clips with frame-to-video references and smooth crossfade transitions. Supports enhanced mode with Nano Banana Pro for higher quality reference images. Use for creating multi-scene videos, cinematic narratives, product demos, marketing content, or any video requiring multiple consecutive scenes.
+---
+
+# Long-Form Video Generator
+
+Generate videos longer than 8 seconds using Google Veo 3.1 API by chaining multiple clips with frame-to-video references and smooth transitions.
+
+## Core Concept
+
+Veo 3.1 generates maximum 8-second clips. To create longer videos:
+
+1. Generate first 8-second clip from text prompt (or enhanced reference image)
+2. Extract last frame from generated video
+3. Use extracted frame as reference for next clip
+4. Maintain consistent character/style descriptions across scenes
+5. Repeat for N scenes
+6. Concatenate with smooth crossfade transitions
+
+Optional: Use Nano Banana Pro (gemini-3-pro-image-preview) for first frame to achieve higher quality.
+
+## Quick Start
+
+Run the video generation command from the skill directory:
+
+## Command Format
+
+Always run from the skill directory:
+
+```bash
+cd /home/user/skills/longform-video-generation && python scripts/video_generator.py [OPTIONS] SCENE1 SCENE2 SCENE3...
+```
+
+## Parameters
+
+Required:
+  SCENES                Scene descriptions (at least one)
+
+Optional:
+  -o, --output FILE               Output filename (default: longform_video.mp4)
+  --enhanced                      Use Nano Banana Pro for first frame
+  --resolution {1K,2K,4K}         Enhanced resolution (default: 2K)
+  --no-smooth                     Disable smooth transitions
+  --transition-duration FLOAT     Transition length in seconds (default: 0.5)
+  --no-frame-chaining             Disable frame chaining
+
+## Enhanced Mode
+
+Enable enhanced mode to use Nano Banana Pro for generating the first reference frame:
+
+```bash
+python scripts/video_generator.py --enhanced --resolution 2K \
+  "Scene 1" "Scene 2" "Scene 3"
+```
+
+Benefits: 30-50% better visual quality, higher resolution reference (up to 4K), improved composition.
+Cost: +$0.036 (2K) or +$0.06 (4K) per video.
+
+## Veo Prompt Writing Guide
+
+### Essential Elements
+
+Include these elements in every video prompt:
+
+**Subject**: The main focus (person, animal, object, scenery)
+- Examples: cityscape, nature, vehicles, puppies, woman in red jacket
+
+**Action**: What the subject is doing
+- Examples: walking, running, turning head, looking around
+
+**Style**: Creative direction and aesthetic
+- Examples: cinematic, sci-fi, horror film, film noir, cartoon, photorealistic
+
+**Camera Positioning** (optional): Camera location and movement
+- Examples: aerial view, eye-level, top-down shot, dolly shot, POV shot, tracking drone view
+
+**Composition** (optional): How the shot is framed
+- Examples: wide shot, close-up, medium shot, single-shot, two-shot
+
+**Focus and Lens** (optional): Visual effects
+- Examples: shallow focus, deep focus, soft focus, macro lens, wide-angle lens
+
+**Ambiance** (optional): Color and lighting
+- Examples: blue tones, night, warm tones, natural light, sunrise, cool blue tones
+
+### Example Prompts
+
+**Simple**:
+```
+A cute creature with snow leopard fur walking in winter forest, 3D cartoon style
+```
+
+**Detailed**:
+```
+Close-up cinematic shot follows a desperate man in weathered green trench coat as he dials 
+rotary phone mounted on gritty brick wall, bathed in eerie glow of green neon sign. Camera 
+dollies in, revealing tension in his jaw and desperation etched on face. Shallow depth of 
+field focuses on furrowed brow and black rotary phone, blurring background into sea of neon 
+colors and indistinct shadows, creating sense of urgency and isolation.
+```
+
+### Audio Prompting
+
+Veo 3.1 generates audio natively. Include audio cues for best results:
+
+**Dialogue**: Use quotes for specific speech
+```
+Man murmurs, "This must be it. That's the secret code."
+```
+
+**Sound Effects**: Explicitly describe sounds
+```
+Tires screeching loudly, engine roaring, glass shattering
+```
+
+**Ambient Noise**: Describe environment soundscape
+```
+A faint eerie hum resonates in background, wind rustling through leaves
+```
+
+### Character Consistency
+
+Repeat character descriptions in every scene:
+
+```python
+character = "Woman in red jacket, brown hair, professional attire"
+scenes = [
+    f"{character}, walking through modern office, natural lighting",
+    f"{character}, presenting to colleagues, conference room",
+    f"{character}, shaking hands, successful meeting conclusion"
+]
+```
+
+### Visual Continuity
+
+Maintain style and atmosphere:
+
+```python
+style = "Cinematic action movie, dramatic lighting, high contrast"
+scenes = [
+    f"{style}. Agent running through alley, motion blur, neon lights",
+    f"{style}. Agent sliding across car hood, sparks flying",
+    f"{style}. Agent leaping through window, glass shattering"
+]
+```
+
+### Scene Transitions
+
+Design endings that lead to next scene:
+
+```python
+scenes = [
+    "Person walking toward door, hand reaching for handle",
+    "Person opening door, stepping through threshold",
+    "Person entering room, looking around new space"
+]
+```
+
+### Negative Prompts
+
+Specify what NOT to include (use descriptive terms, not instructions):
+
+**Incorrect**: "No walls", "Don't show buildings"
+**Correct**: "wall, frame, urban background, man-made structures"
+
+```python
+operation = client.models.generate_videos(
+    model="veo-3.1-generate-preview",
+    prompt="Solitary oak tree with leaves blowing in wind",
+    config=types.GenerateVideosConfig(
+        negative_prompt="urban background, man-made structures, dark, stormy"
+    )
+)
+```
+
+## Nano Banana Pro Prompt Writing Guide
+
+When using enhanced mode, the first frame is generated using Nano Banana Pro (gemini-3-pro-image-preview).
+
+### Image Generation Best Practices
+
+**Be Specific**: Include detailed visual descriptions
+```
+Professional woman in navy blue business suit, confident posture, modern glass office 
+building background, natural daylight, warm professional atmosphere, high resolution, 
+photorealistic
+```
+
+**Specify Style**: Photography type and quality
+```
+Cinematic still frame, high-resolution professional photography, dramatic lighting, 
+ultra detailed, 16:9 aspect ratio, photorealistic
+```
+
+**Camera Details**: Perspective and composition
+```
+Medium shot, eye-level camera angle, rule of thirds composition, shallow depth of field
+```
+
+**Lighting**: Describe light sources and mood
+```
+Soft natural window light from left, warm golden hour glow, subtle rim lighting on subject
+```
+
+### Enhanced Reference Image Template
+
+```python
+image_prompt = f"""
+Cinematic still frame for video scene.
+{your_scene_description}
+High-resolution, professional photography, dramatic lighting.
+This will be starting frame of video sequence.
+16:9 aspect ratio, photorealistic, ultra detailed.
+"""
+
+reference = generator.generate_reference_image(
+    prompt=image_prompt,
+    model="gemini-3-pro-image-preview",
+    resolution="2K"  # or "4K" for maximum quality
+)
+```
+
+### Resolution Options
+
+**1K** (1376×768): $0.024 - Good quality, fast
+**2K** (2752×1536): $0.036 - Professional quality (recommended)
+**4K** (5504×3072): $0.06 - Maximum quality
+
+## Cost Analysis
+
+### Standard Mode (3 scenes, 24 seconds)
+- 3x Veo 3.1 generations: $0.45
+- Smooth transitions: Included
+- Quality: Good
+
+### Enhanced Mode (3 scenes, 24 seconds)
+- 1x Nano Banana Pro (2K): $0.036
+- 3x Veo 3.1 generations: $0.45
+- Total: $0.486 (+8%)
+- Quality: Excellent (+30-50%)
+
+Use enhanced mode for: Production videos, client deliverables, marketing content, high-quality requirements
+Use standard mode for: Prototypes, testing, quick iterations, budget projects
+
+## Complete Example
+
+```bash
+# Define scenes as bash variables for clarity
+STYLE="Cinematic corporate video, professional lighting, modern aesthetic"
+CHARACTER="Professional woman in navy blue suit, confident demeanor"
+
+# Generate with enhanced quality
+python scripts/video_generator.py --enhanced --resolution 2K \
+  -o corporate_video.mp4 \
+  --transition-duration 0.5 \
+  "$STYLE. $CHARACTER walking through modern glass office lobby. Wide shot transitions to medium shot. Natural daylight through windows. Sound of heels clicking on marble floor." \
+  "$STYLE. $CHARACTER enters conference room, greeting team with smile. Medium shot, eye-level camera. Colleagues visible in background. Sound of door opening, greetings." \
+  "$STYLE. $CHARACTER presenting at whiteboard, gesturing confidently. Close-up capturing engaged expression. Sound of marker on whiteboard, voice presenting ideas."
+```
+
+## Technical Details
+
+**Processing Time**: 2-3 minutes per scene, +30 seconds for enhanced first frame, +10-15 seconds for concatenation
+
+**Output**: Generated video saved to `/home/user/task/` directory. Default filename: `longform_video.mp4` (customize with `-o` option).
+
+**Specifications**: 720p or 1080p (1080p only for 8s clips), 24fps, native audio with crossfade, SynthID watermark.
+
+**Duration**: Approximately 2-3 minutes per scene.
+
+## Troubleshooting
+
+**Character Drift**: Use enhanced mode with consistent character descriptions to minimize drift across scenes
+
+**Jerky Transitions**: Adjust transition duration:
+```bash
+python scripts/video_generator.py --transition-duration 0.7 "scene 1" "scene 2"
+```
+
+**Inconsistent Results**: Disable frame chaining if causing issues:
+```bash
+python scripts/video_generator.py --no-frame-chaining "scene 1" "scene 2"
+```
+
+## Reference Documentation
+
+**API Details**: See [references/google_api_guide.md](references/google_api_guide.md) for complete API documentation including all parameters, model versions, and advanced features.
+
+**Advanced Techniques**: See [references/advanced_techniques.md](references/advanced_techniques.md) for optimization strategies, complex workflows, and troubleshooting tips.
+
+## Limitations
+
+- Maximum clip length: 8 seconds per scene
+- API rate limits: Pause 5 seconds between generations recommended
+- SynthID watermark: Applied automatically, cannot be removed
+- Video retention: 2 days on server, download promptly
+- Regional limitations: Some regions restrict person generation settings