buttercut 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78b845e8b54d03aee93f00bdbaa96f140d0f10c94910a117352b7401cf30bf63
-  data.tar.gz: 0eb609100a9e2f367b493d6aef9f45d08e784ad573c4d033733009be40ccc525
+  metadata.gz: 768b511af86ba148f459f7238a4e181755e9a8e034c1f826194b4b273fa7cb3f
+  data.tar.gz: a9a83cbe8000fa315f8716505fd0bc9e21cb2411b743446629296e413ff3fef9
 SHA512:
-  metadata.gz: 33eb34693818323f40900bcea272781391c372fc5bf9adb71f11632da83aa3de5936538150c69a9d5407f5e5a6059342eed23eed5683e6b1fec36d9a55b37d2a
-  data.tar.gz: f022d15eb198cb32dde550d0120598cf5d8eb7f95145e21bfb70401df1c762bcd4474f4836966601aa46ce232e2bd364a25cc8d1187ad2c1e7edf02164ca1789
+  metadata.gz: 0a70a6a73a80edea617161468519ec22ce8089b21dc95fb5689811eb7221f84c38e3b5b11b833b48dd5e33e712c8a8e12512f00de7cf12723820dbfebae31c6d
+  data.tar.gz: 464000a7106249b5a09fac805c97d60063934c745d6cd7efd9e6e06579d25587b71f4532338733f1ca9bf2f864c703dfa17a4c106e6e21adcad293ac4aa394c3

data/.claude/settings.local.json

@@ -27,7 +27,15 @@
       "Bash(python3:*)",
       "Bash(gh api:*)",
       "Bash(gh pr:*)",
-      "Bash(cp *)"
+      "Bash(cp *)",
+      "Bash(chmod +x .claude/skills/export-video/export_video.rb)",
+      "Bash(bundle exec *)",
+      "Bash(cp libraries/programmer-story-vlog/roughcuts/backstory-aroll_20260507_155307.fcpxml ~/Desktop/)",
+      "Bash(grep -v \"^--$\")",
+      "Bash(grep -v \"^$\")",
+      "Bash(ls ~/code/buttercut-evals/library-processing/)",
+      "Bash(caffeinate -dimsu)",
+      "Bash(echo \"caffeinate PID: $!\")"
     ],
     "deny": [],
     "ask": []

data/.claude/skills

@@ -0,0 +1 @@
+../skills

data/CLAUDE.md

@@ -1,278 +1 @@
-# ButterCut - Video Rough Cut Generator
-**ButterCut** is a Ruby gem for generating Final Cut Pro XML from video files with AI-powered rough cut creation. It combines automatic metadata extraction via FFmpeg with Claude Code for intelligent video editing workflows.
-
-The project has two main components:
-1. **Ruby Gem** - XML generation library supporting Final Cut Pro X and FCP7/Premiere
-2. **Claude Code Integration** - AI-powered video editing workflow with transcription and rough cut creation
-
-## Supported Editors
-
-Currently supports:
-- **Final Cut Pro X** (FCPXML 1.8 format)
-- **Adobe Premiere Pro** (xmeml version 5)
-- **DaVinci Resolve** (xmeml version 5)
-
-## Core Workflow
-
-You are an AI video editor assistant working with a software engineer. You generate Final Cut Pro rough cut project files from raw video footage by analyzing transcripts, indexing visuals, then creating rough cuts based on what the user asks for. Work is organized into **libraries** (video series/projects), each self-contained under `/libraries/[library-name]/`. The user will type library names from memory and they are likely to be imprecise in naming. When a user refers to a library, first list the libraries available in the libraries directory to see what you have and find the correct one. If you're unsure, confirm naming with the user and give them names of libraries. If it's clear what library they're referring to, just start working with that library.
-
-### Workflow Steps
-
-1. **Setup** → Initialize a new library or work with an existing library
-   - Check for existing library in `/libraries/[library-name]/`
-   - If new: gather project information (library name, video file locations, language)
-   - Create directory structure and library.yaml from template
-   - Automatically start footage analysis after setup
-2. **Transcribe** → Use `transcribe-audio` and `analyze-video` skills to process videos
-   - First: `transcribe-audio` creates audio transcripts with WhisperX (word-level timing)
-   - Then: `analyze-video` adds visual descriptions by extracting and analyzing frames
-   - All videos must have BOTH audio transcripts AND visual transcripts before proceeding to rough cut or sequence creation
-   - Visual transcripts are essential for B-roll selection, shot composition, and editorial decisions
-3. **Edit** → Use `roughcut` skill to create timeline scripts from transcripts
-   - **Rough cuts**: Multi-minute edits for full videos (typically 3-15+ minutes)
-   - **Sequences**: 30-60 second clips that user will build to be imported into a larger video (created using the same roughcut skill with shorter target duration)
-   - **PREREQUISITE:** Check library.yaml to verify all videos have visual_transcript populated
-4. **Backup** → Use `backup-library` skill to create compressed archives of all libraries
-   - Creates timestamped ZIP backup of entire libraries directory
-   - Backups are stored in `/backups/` and excluded from git
-
-## Library Setup and Management
-
-Libraries are the primary abstraction in ButterCut - each library represents a video series or project and is self-contained under `/libraries/[library-name]/`. A library is conceptually similar to a Final Cut Pro library, but uses a simple file structure (YAML, JSON transcripts) optimized for AI analysis rather than FCP's proprietary format.
-
-### Initialize Settings
-
-Before any library setup, check if `libraries/settings.yaml` exists. If not, copy from template:
-
-```bash
-cp templates/settings_template.yaml libraries/settings.yaml
-```
-
-If no previous settings.yaml was present, use the ask user question tool to ask the user to confirm or change their defaults (editor and whisper_model).
-
-Editor Options:
-- Final Cut Pro X
-- Adobe Premiere Pro
-- DaVinci Resolve
-
-Model Options:
-- Small (recommended — pairs well with per-library transcript_refinement)
-- Medium
-- Turbo (Large)
-
-Save these options into libraries/settings.yaml.
-
-Note: `transcript_refinement` is a **per-library** setting (not global). Ask about it during library setup (see "Gather Project Information" below), not during initial settings setup.
-
-
-When creating a new library, read `libraries/settings.yaml` and use the `editor` value to pre-populate the library's `editor` field.
-
-### Check for Existing Library
-
-**ALWAYS** check if a library already exists before starting setup:
-
-```bash
-ls libraries/[library-name]/library.yaml
-```
-
-**If library.yaml exists:**
-- Skip setup entirely - the library is already configured
-- Read the existing library.yaml to understand project status
-- User is returning to existing work
-
-**If library directory exists but library.yaml is missing:**
-- Check what files are present (`/transcripts/`, `/roughcuts/`, etc.)
-- Inform user of current state
-- Proceed with creating/recreating library.yaml to restore consistency
-
-**If no library directory exists:**
-- Proceed to gather project information and create new library
-
-### Gather Project Information
-
-Ask the user these questions for new libraries one at a time (never all at once):
-
-1. **What do you want to call this project library?**
-   - Examples: "bike-locking-video-series", "raiders-2025-highlights", "yo-yo-techniques"
-   - Normalize the name:
-     - Replace spaces with dashes
-     - Convert to lowercase
-     - Remove special characters (keep alphanumeric and dashes)
-
-2. **Where are the video files located?**
-   - Ask: "Where are your video files? You can drag folders or individual files directly into the chat."
-   - Verify all files exist before proceeding
-   - Inform user of what was found: "Found 5 video files totaling 2.3GB"
-
-3. **What language is spoken in these videos?**
-   - Ask using AskUserQuestion with options: "English", "Spanish" and a free-text fallback for other languages
-   - Save the language name (e.g., "English") to library.yaml
-   - Map to language code (e.g., `en`, `es`, `fr`) behind the scenes when needed for transcription
-
-4. **Can I proofread the transcripts after they're generated?**
-   - Ask using AskUserQuestion with this exact question: "Can I proofread the transcripts after they're generated? I'll use the video's context to fix mistakes."
-   - Options: "Yes - Recommended (Use Claude to refine video understanding)" and "No"
-   - Save the boolean to `transcript_refinement` in library.yaml (true for Yes, false for No)
-   - Default to `true` if the user skips
-
-### Create Directory Structure
-
-```bash
-mkdir -p libraries/[library-name]
-mkdir -p libraries/[library-name]/transcripts
-mkdir -p libraries/[library-name]/roughcuts
-```
-
-Note: A single `/tmp/` directory at the root is used for all temporary files. Create subdirectories as needed and delete after use.
-
-### Create Library File
-
-Duplicate `templates/library_template.yaml` to create `libraries/[library-name]/library.yaml`:
-
-For each video file:
-1. Use `ffprobe` to get duration
-2. Add entry to library.yaml with empty `transcript` and `visual_transcript`
-3. Empty fields mean "todo", valid filenames mean "done"
-
-The `language` field stores the language code for all videos in this library.
-
-Progressively update the `footage_summary` field after each video is transcribed with 1-3 sentences covering subjects, locations, activities, visual style, etc.
-
-### Start Footage Analysis
-
-After library setup completes, **automatically start analyzing all footage**:
-
-1. Inform user: "Library setup complete. Found [N] videos ([total size]). Starting footage analysis..."
-2. Read `libraries/settings.yaml` (for `whisper_model`) and the library's `library.yaml` (for `language`, `transcript_refinement`, `user_context`, `footage_summary`) ONCE in the parent thread. If any expected field is missing, run the appropriate migration first (see Critical Principles below).
-3. Launch `transcribe-audio` agents (can run in parallel for multiple videos). Pass these values inline in each agent's prompt — the sub-agent never reads `library.yaml` or `settings.yaml`:
-   - `video_path`, `transcript_output_dir`, `language_code`, `whisper_model`
-   - `transcript_refinement` (boolean). If `true`, also pass the current `user_context` and `footage_summary` strings (empty strings are fine — refinement still catches nonsense-token and self-witness fixes).
-4. As each agent completes, update library.yaml with `transcript` (filename only, not full path).
-5. After all audio transcripts complete, launch `analyze-video` agents (can run in parallel) following the same "parent passes context inline" contract. Pass inline: `video_path`, `audio_transcript_path`, `visual_transcript_path`.
-6. As each agent completes, update library.yaml with `visual_transcript` (filename only, not full path).
-7. Analyze ALL videos before offering to create rough cuts.
-8. **After all analysis completes, automatically create a backup** using the `backup-library` skill.
-
-**Contract: sub-agents don't read `library.yaml`.** The parent owns `library.yaml` (and `settings.yaml`) — it reads once, passes values inline, and writes results once per agent completion. Sub-agents should not even know those files exist. This keeps the context boundary clean and avoids race conditions when many agents run in parallel.
-
-**Note on refinement:** When `transcript_refinement: true`, each `transcribe-audio` agent reviews and corrects its transcript in place before returning, using the `user_context` and `footage_summary` the parent passed in. Empty context strings are fine — the agent still runs and catches nonsense-token and self-witness fixes. The parent still only writes `transcript: <filename>.json` to `library.yaml` after the agent completes.
-
-**Terminology:**
-- User-facing: Call it "footage analysis" or "analyzing footage"
-- Internal/file names: Use "transcription" (library.yaml, transcript, etc.)
-
-**If user requests rough cut before analysis completes:**
-- Warn: "I can create a rough cut now, but I'll do a better job after analyzing all the footage. Continue anyway?"
-- If user confirms, proceed with rough cut creation
-- Otherwise, wait for analysis to complete
-
-## Parallel Transcription Pattern
-
-When processing multiple videos, use parallel agents for maximum throughput:
-
-1. **Parent agent responsibilities:**
-   - Read `library.yaml` and `settings.yaml` once to gather: videos needing work, `language_code`, `whisper_model`, `transcript_refinement`, `user_context`, `footage_summary`.
-   - Launch Task agents with transcribe-audio or analyze-video skills, passing all needed values **inline in the prompt**.
-   - Update library.yaml sequentially as agents complete.
-   - Handle errors and retries.
-
-2. **Child agent (transcribe-audio/analyze-video) responsibilities:**
-   - Process ONE video file using only the inputs passed inline by the parent.
-   - Run WhisperX or frame extraction.
-   - Prepare and clean transcript JSON.
-   - Return structured response with file paths.
-   - DO NOT read `library.yaml` or `settings.yaml`, and DO NOT update `library.yaml` (parent handles all yaml I/O).
-
-3. **Benefits:**
-   - Multiple videos process simultaneously
-   - No race conditions on shared YAML file
-   - Clear separation of concerns
-   - Easy to retry individual failed videos
-
-## Critical Principles
-
-Each library has a `library.yaml` file that serves as your persistent memory and the SOURCE OF TRUTH. This file contains all library metadata, footage descriptions, transcription status, and key learnings. Always read this file when working on a library and you need guidance for how/where to save files.
-
-**Migrate legacy library.yaml files before doing anything else.** Every time you read a library.yaml, check it against the canonical field list in `templates/library_template.yaml`. If any expected field is missing, or any field appears under an old name, the library predates a feature and MUST be migrated before you do any further work on it — no rough cuts, sequences, transcription, exports, or anything else until the schema is current. The migrations are fast, idempotent, and safe; don't ask the user for permission and don't describe them as optional "tidying." Just run them.
-
-Known migration triggers (match each to a `scripts/NNN_migrate_*.rb` script via CHANGELOG.md):
-
-- `editor` missing (added in 0.4.0)
-- `transcript_refinement` missing (added in [Unreleased]; missing means "predates the feature, default to `false`" — NOT the template default of `true`)
-- `footage_summary` missing OR old name `footage_description` present (renamed in [Unreleased])
-- video entries with `transcript_path` / `visual_transcript_path` (renamed to `transcript` / `visual_transcript` in 0.3.0)
-- video entries with `file_size_mb` (removed in 0.3.0)
-
-A missing field is not the same as a field set to the template default — the template default only applies to freshly created libraries. If you see a schema issue not on this list, still check CHANGELOG.md; the list may be behind. After running migrations, re-read the library.yaml and continue with whatever the user asked for.
-
-**Keep main-thread context minimal.** The main thread orchestrates; sub-agents do the heavy work and return concise summaries. Don't read full transcript JSON, visual transcript JSON, or extracted frames into the main thread as part of routine workflow — across a large library this bloats context fast. Trust sub-agent return messages when updating library.yaml. Direct user requests ("show me transcript X") are fine; the rule is about automatic workflow behavior.
-
-**Use actual filenames.** Never use generic labels like "Video 1" or "Clip A" - always reference actual filenames like "DJI_20250423171212_0210_D.mov" for clear traceability.
-
-**Visual transcripts are mandatory.** Before creating any rough cut or sequence, verify ALL videos have both audio and visual transcripts. Check `library.yaml` - every video entry must have a `visual_transcript` with a filename (not empty or null or ""). Transcripts are stored in `libraries/[library-name]/transcripts/`. Visual descriptions are essential for shot selection, pacing decisions, and B-roll placement.
-
-**Be curious and ask questions.** Occasionally ask users questions about their libraries and footage to better understand context, creative intent, and preferences. When you receive answers, add this information to the `user_context` key in the library.yaml file. This builds institutional knowledge that improves future rough cut and sequence decisions and helps maintain continuity across editing sessions.
-
-## Key Reminders
-
-- Never modify source video files - always preserve originals
-- Flag areas needing human judgment rather than making assumptions
-- When you have lots of videos to process (dozens or hundreds isn't out of the ordinary), create a reasonable task list with 5 tasks and then a final task that says to check the yaml processing file to see if you need to then generate more tasks. This way users can see progress and the agent doesn't get overwhelmed.
-- Generally avoid writing one-off scripts, but if you do need to write one, write it in Ruby unless you have a very strong reason to write in another language.
-- Only run 4 parallel tasks at a time.
-- Whenever you export XML files, include a datetime timestamp in the filename so it's clear when they were generated.
-
-## Programming Style
-
-When you add a Ruby script under `.claude/scripts/` or similar, follow these conventions:
-
-- **One class per script; file name matches the class name.** `ScriptExtractor` lives in `script_extractor.rb`.
-- **Single high-level entry point.** Expose a class method (`Klass.extract`, `Klass.run`, etc.) that calls `new(...).extract` internally — callers shouldn't need to know about instantiation.
-- **Break the work into small private methods with clear names** (`load_transcript`, `format_script`, `write_output`, `report`). The public entry point should read like a short outline of the workflow.
-- **Required arguments are required.** Don't silently default `nil`/missing args — raise `ArgumentError` in `initialize` if a required value is missing or empty. No hidden fallback paths.
-- **Keep CLI arg parsing out of the class.** Use a bottom-of-file `if __FILE__ == $PROGRAM_NAME` block to parse `ARGV`, validate file paths, print a usage line, and delegate to the class.
-
-## Project Structure
-
-- `lib/buttercut.rb` - Factory class that creates editor-specific generators
-- `lib/buttercut/editor_base.rb` - Shared validation, metadata extraction, and timeline math
-- `lib/buttercut/fcpx.rb` - Final Cut Pro X implementation (FCPXML 1.8)
-- `lib/buttercut/fcp7.rb` - Final Cut Pro 7 / Premiere / DaVinci Resolve implementation (xmeml v5)
-- `.claude/skills/` - Claude Code skills for AI-powered workflow
-- `spec/` - RSpec test suite
-- `templates/` - Library and project templates
-- `libraries/` - Working directory for user's video projects (gitignored)
-- `libraries/settings.yaml` - User settings (editor, whisper_model) — created from template on first library setup
-- `backups/` - Compressed library backups (transcriptions, roughcuts, etc) (gitignored)
-
-## Design Philosophy
-
-ButterCut is designed to be simple, automatic and geared toward working with non technical people using ButterCut via a client, Claude Cowork or Claude Code.
-
-- **Input**: Array of full file paths to video files
-- **Output**: Working XML file ready to import into the non-technical user's video editor (Final Cut, Premiere, Resolve)
-- **Automatic Metadata Extraction**: Uses FFmpeg internally to extract video properties (duration, resolution, frame rate, audio rate, etc.)
-
-The user should not need to understand video codecs, frame rates, or FCPXML structure - just provide file paths and get working XML. We should talk to the user from a video editing perspective, not a technical software engineer perspective.
-
-## Development Commands
-
-### Testing
-RSpec tests for the XML generation library. This doesn't include agent or end to end testing.
-```bash
-# Install dependencies
-bundle install
-
-# Run all tests
-bundle exec rspec
-
-# Run specific test file
-bundle exec rspec spec/buttercut_spec.rb
-
-# Run specific test
-bundle exec rspec spec/buttercut_spec.rb:10
-```
-
-## Claude Skills
-
-When creating new Claude skills, aim to keep them to 50 lines. Only very complicated skills (ie transcription and roughcuts) should be larger than that. If the skill is complicated and seems like it can't be explained in 50 lines, consider if they should be broken up across multiple skills or if the complexity can be contained inside a ruby script saved adjacent to the skill.
+@AGENTS.md

data/LICENSE

@@ -1,21 +1,106 @@
-MIT License
-
-Copyright (c) 2025 Andrew Ford
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Required Notice: Copyright 2025 TubeSalt LLC
+
+## Additional Permission: Commercial Output
+
+The licensor grants the following permission in addition to the rights
+granted by the PolyForm Noncommercial License 1.0.0 below.
+
+You may use the software to produce video files, project files, edits,
+exports, and other creative works ("Outputs") for any purpose, including
+commercial purposes. You retain all rights to your Outputs, and the
+licensor claims no ownership of them. Producing or distributing your
+Outputs, including for monetary compensation, is not by itself a
+commercial use of the software.
+
+This Additional Permission covers using the software as a tool to make
+videos. It does **not** permit any of the following, which remain
+restricted to noncommercial purposes under the license below:
+
+- Distributing, sublicensing, or selling the software (in original or
+  modified form), whether on its own or as part of another product;
+- Offering the software (in original or modified form) as a hosted,
+  managed, or Software-as-a-Service product;
+- Incorporating the software into a commercial software product,
+  plugin, extension, or service.
+
+Plainly: you may use ButterCut to make commercial videos. You may not
+use ButterCut to make commercial software.
+
+If any term of this Additional Permission conflicts with the PolyForm
+Noncommercial License 1.0.0 below, this Additional Permission controls.
+
+---
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

data/README.md

@@ -44,7 +44,7 @@ For manual installation, see [docs/installation.md](docs/installation.md).
 
 ## Usage
 
-First tell Claude to create a **Library**. A library organizes your video footage along with audio and visual transcripts. Then tell Claude you want to create a **rough cut** or **sequence**.
+First tell Claude to create a **Library**. A library organizes your video footage along with the transcripts, contact sheets, and summaries Claude needs to edit it. Then tell Claude you want to create a **rough cut** or **sequence**.
 
 ### Creating a Video Library
 
@@ -60,14 +60,14 @@ You:
 
 Claude: [Automatically processes all videos]
   ✓ Creates library structure
-  ✓ Transcribes audio with WhisperX
-  ✓ Analyzes video frames
-  ✓ Generates visual transcripts
+  ✓ Transcribes audio
+  ✓ Builds a contact sheet for every clip
+  ✓ Writes a short summary of each clip
 
 Result: Full footage analysis ready for rough cut creation
 ```
 
-Claude handles the parallel processing, metadata extraction, and transcript generation. See the [full walkthrough](docs/example-library-setup.md) for a detailed example of me setting up a library from my wedding footage.
+Claude handles the parallel processing, metadata extraction, and analysis. See the [full walkthrough](docs/example-library-setup.md) for a detailed example of me setting up a library from my wedding footage.
 
 ### Creating a Roughcut or Sequence
 
@@ -76,7 +76,7 @@ Once your library is analyzed, Claude can create rough cuts through an interacti
 ```plaintext
 You: "Let's create a new roughcut"
 
-Claude: [Loads roughcut skill and analyzes footage]
+Claude: [Loads cut skill and analyzes footage]
         What should this roughcut focus on?
         - Full story
         - Just the meetup coverage
@@ -100,7 +100,7 @@ Claude: [Asks which video editor you want to use]
 You: "Final Cut Pro X"
 
 Claude: [Creates roughcut with editorial decisions]
-        ✓ Combined visual transcripts
+        ✓ Reviewed contact sheets and transcripts
         ✓ Selected 29 clips (4:32 total)
         ✓ Exported to FCPXML
 
@@ -120,7 +120,12 @@ ButterCut was inspired by ambitious open source work from [Chris Hocking](https:
 
 ## License
 
-MIT
+ButterCut is open source under the [PolyForm Noncommercial License 1.0.0 with a Commercial Output exception](LICENSE).
+
+- **You can use ButterCut to make videos commercially.** Cut a YouTube video for ad revenue, edit a paid client project, deliver a sponsored brand piece — all fine. The videos are yours, and the licensor claims no rights to them.
+- **You can't repackage ButterCut as commercial software.** Selling, hosting, or bundling the tool itself (or a fork of it) into a commercial product, plugin, or SaaS requires a separate commercial license from TubeSalt LLC.
+
+Personal, hobby, research, and educational use of the software is also free under the underlying license. If you'd like a commercial software license, reach out.
 
 ## Contributing
 

data/lib/buttercut/version.rb

@@ -1,3 +1,3 @@
 class ButterCut
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/templates/library_template.yaml

@@ -14,9 +14,21 @@ footage_summary: "No footage analyzed yet."
 # "This footage appears to be wedding footage. It includes the bride and groom getting dressed, preparing for the wedding ceremomy, the ceremony, and the post ceremony dinner and party."
 # "This footage appears to be a vlog. The footage starts in The Richmond District in San Francisco, includes a bus ride on the 38R, and concludes at a Ruby Meetup in downtown San Francisco."
 
-# Video files and transcription status
+# Video files and analysis status
+#
+# Per clip, analysis fills three fields:
+#   transcript     — audio transcript JSON (word-level timing, in transcripts/);
+#                    also the source for on-demand dialogue extraction via
+#                    skills/analyze-video/script_extractor.rb
+#   contact_sheet  — _full.jpg visual overview (in contact_sheets/); per-segment
+#                    sheets for clips >10 min live alongside on disk
+#   summary        — markdown overview (in summaries/)
+#
+# Note: visual_transcript is deprecated. Older libraries may still carry the
+# field; new libraries use the contact_sheet field instead.
 videos:
   - path: /full/path/to/video_file.mp4
     duration: "00:05:32"
     transcript: # filename only (stored in libraries/[library-name]/transcripts/)
-    visual_transcript: # filename only (visual_*.json with frame descriptions)
+    contact_sheet: # filename only (_full.jpg in libraries/[library-name]/contact_sheets/)
+    summary: # filename only (summary_*.md in libraries/[library-name]/summaries/)

data/templates/plan_template.md

@@ -0,0 +1,53 @@
+<!--
+Cut Plan Template — written and consumed by the `cut` skill's Roughcut path (see `skills/cut/roughcut_planning.md`).
+
+Fill in every section. Delete this comment block before saving.
+The plan is editorial direction; the build agent picks the exact clips
+and timestamps inside each beat.
+-->
+
+# [Working title]
+
+## Concept
+<!-- 1–2 sentences on the angle, tone, or arc. What story is this cut telling? -->
+
+## Format
+<!-- Vlog, YouTube Short, long-form, documentary, talking-head, montage, etc.
+Include any pacing or tonal cues that flow from the format. -->
+
+## Target Duration
+<!-- Approximate runtime, e.g. "4–6 min" or "45–60s sequence". -->
+
+## Beats
+<!--
+Ordered list. Each beat is one editorial unit with intent and footage suggestions. Beats are direction, not paper-cut timestamps.
+
+For an 8 minute vlog, you might aim for something like 60 seconds per beat, with both good footage for a-roll and b-roll.
+
+For other types of videos use your best editorial judgement, thinking about what is common in the genre you're working with. You can also talk to the user directly to determine what they want.
+-->
+
+### 1. [Beat name]
+- **Intent:** what this beat does for the story (open, escalate, turn, payoff, etc.)
+- **Approx. share:** rough fraction of runtime (e.g. "~30s", "~2 min", "~15% of total")
+- **Footage suggestions:** filenames likely to feed this beat (e.g. `DJI_56738.mov`, `panasonic_1234.mov`). The build agent may swap in stronger moments from elsewhere.
+
+### 2. [Beat name]
+- **Intent:**
+- **Approx. share:**
+- **Footage suggestions:**
+
+<!-- Add more beats as needed. A 6 minute video might have 4-6 beats. You'll need to use your judgement about the footage availability, target duration and cut you're making. -->
+
+## Required Dialogue
+<!--
+Lines the user specifically wants in. Two flavors are both fine:
+
+- **Exact quote:** "Here's how I learned to juggle." (`source_file_if_known.mov`)
+- **Lossy reference:** "Include the bit about Kailey's uncle the magician teaching her to juggle before he died." (`file_1.mov, file_2.mov, file_5.mov`)
+
+Leave this section empty if no specific lines are required.
+-->
+
+## Notes for the Build
+<!-- Any constraints, things to avoid, or judgment calls the build agent should know — single-track timeline assumptions, must-not-include footage, tone preferences, etc. Include decisions or direction from the user. -->

data/templates/roughcut_template.yaml

@@ -1,25 +1,8 @@
 # Rough Cut Template
 # This template defines the structure for video rough cuts
 
-# User-facing description of what this rough cut contains
-description: "Brief description of the rough cut - what story it tells, target duration, and editorial approach"
-
-# Working notes for the agent during rough cut creation
-notes: |
-  Working notes area for editorial decisions, narrative structure planning,
-  pacing considerations, and any issues or concerns identified during editing.
-
-  Consider:
-  - Story arc and key narrative beats
-  - Pacing and rhythm
-  - Transitions between segments
-  - B-roll placement opportunities
-  - Audio/dialogue clarity
-
-# Coverage summary of available footage
-footage_coverage: |
-  Overview of what footage is available and how it could be used.
-  Include notes about strongest segments, potential issues, and creative opportunities.
+# One-line summary of what this cut is — useful when scanning a folder of cuts
+description: "Brief one-line summary of this cut — what it is and roughly how long"
 
 # The actual rough cut - ordered list of clips to use
 clips:
@@ -39,4 +22,4 @@ clips:
 # Rough cut metadata
 metadata:
   created_date: ""  # Will be populated when rough cut is created
-  total_duration: ""  # Calculated from all clip durations
+  total_duration: ""  # Calculated from all clip durations

data/templates/settings_template.yaml

@@ -8,3 +8,12 @@ editor: fcpx
 # turbo is nearly as accurate as large-v3 but significantly faster
 # Recommended: `small` paired with transcript_refinement (set per-library in library.yaml)
 whisper_model: small
+
+# After exporting a roughcut, also drop a copy of the XML on the Desktop for easy import
+save_to_desktop_after_export: true
+
+# Where to write library backup archives.
+# Defaults to ~/Documents/buttercut-video-editor-backups so backups live outside
+# the project directory and survive a fresh clone or `update-buttercut` run.
+# Set to a different absolute path (or one starting with ~) to redirect.
+# backups_dir: ~/Documents/buttercut-video-editor-backups