buttercut 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57b76c4460b6e40602877e8d9c3a31f0b9748b1447b2dbb5d7189a497a17ad87
-  data.tar.gz: 87b7a604c6f807171c463b5e3b49fef95d88796ebd3803b9ab6f495ebdc2e0e5
+  metadata.gz: 768b511af86ba148f459f7238a4e181755e9a8e034c1f826194b4b273fa7cb3f
+  data.tar.gz: a9a83cbe8000fa315f8716505fd0bc9e21cb2411b743446629296e413ff3fef9
 SHA512:
-  metadata.gz: bbce3378342cc2c11ae5644f215162f523e564206519873ad58f30fc38cbb61363db95a323dfbb0bf9e4df735f7ed7ea49d812bb9f49f826e0c773a7c33df5d4
-  data.tar.gz: 3c602e886a0d2597be5e960f0cd5202b8c4143ae8ab66dfa88e04ccc57a982f075ad0a61b489340bde86c13653e469fac472f146977c2b1d174747eb3d9edee9
+  metadata.gz: 0a70a6a73a80edea617161468519ec22ce8089b21dc95fb5689811eb7221f84c38e3b5b11b833b48dd5e33e712c8a8e12512f00de7cf12723820dbfebae31c6d
+  data.tar.gz: 464000a7106249b5a09fac805c97d60063934c745d6cd7efd9e6e06579d25587b71f4532338733f1ca9bf2f864c703dfa17a4c106e6e21adcad293ac4aa394c3

data/.claude/settings.local.json

@@ -28,7 +28,14 @@
       "Bash(gh api:*)",
       "Bash(gh pr:*)",
       "Bash(cp *)",
-      "Bash(chmod +x .claude/skills/export-video/export_video.rb)"
+      "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,308 +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`, `analyze-video`, and `summarize-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
-   - Then: `summarize-video` generates a short markdown summary from each visual transcript
-   - All videos must have audio transcripts, visual transcripts, AND summaries before proceeding to rough cut or sequence creation
-3. **Edit** → Use `cut-planner` then `roughcut` to plan and build a timeline from transcripts
-   - `cut-planner` reads all summaries in the main thread, proposes 2–3 narrative options, iterates with the user, and writes an approved plan markdown file
-   - `roughcut` consumes that plan, spins up a sub-agent that reads the library directly, builds the YAML iteratively, reviews against format conventions, exports the XML, and returns conversational editorial notes the parent uses to dialogue with the user
-   - **Rough cuts**: 3–15+ min edits. **Sequences**: 30–60s clips. Same pair of skills, different target duration.
-   - **PREREQUISITE:** Check library.yaml to verify all videos have `visual_transcript` and `summary` 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
-mkdir -p libraries/[library-name]/summaries
-mkdir -p libraries/[library-name]/plans
-```
-
-Note: A single `tmp/` directory inside the buttercut project 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`, `visual_transcript`, and `summary`
-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. Pass these values inline in each agent's prompt:
-   - `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. 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. After all visual transcripts complete, summarize each video using the `summarize-video` skill on the **Haiku model**:
-   - For each video, first pre-create a skeleton file in the parent: `ruby .claude/skills/summarize-video/summary_skeleton.rb <visual_transcript_path> <summary_output_path>`
-   - Then launch the agent passing inline: `visual_transcript_path`, `summary_output_path` (e.g., `libraries/[library-name]/summaries/summary_[videoname].md`)
-   - The agent fills the four placeholders via Edit. The skeleton + Edit pattern is required: without it, Haiku frequently refuses Write and dumps markdown into its reply instead.
-8. As each agent completes, update library.yaml with `summary` (filename only, not full path).
-9. Analyze ALL videos before offering to create rough cuts.
-10. **After all analysis completes, automatically create a backup** using the `backup-library` skill.
-
-**Contract: sub-agents receive `agent_prompt.md`, not `SKILL.md`.** For parallelizable skills (`transcribe-audio`, `analyze-video`, `summarize-video`), the parent reads `SKILL.md` for dispatch info (parallelism cap, required inputs) and inlines `agent_prompt.md` into the sub-agent's prompt. `SKILL.md` is parent-only.
-
-**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.
-
-   Each skill's `agent_prompt.md` documents its own IO contract — including whether the sub-agent reads or writes `library.yaml`.
-
-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 `summary` missing (added in [Unreleased]; missing means "todo", default to empty string)
-- 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 and summaries are mandatory.** Before creating any rough cut or sequence, verify ALL videos have audio transcripts, visual transcripts, AND summaries. Check `library.yaml` — every video entry must have `visual_transcript` and `summary` with filenames (not empty, null, or ""). Transcripts are stored in `libraries/[library-name]/transcripts/`; summaries in `libraries/[library-name]/summaries/`. Visual descriptions and summaries are essential for shot selection and pacing decisions.
-
-**Single-track timelines only.** ButterCut produces one sequential video track. Each clip's own audio plays during that clip — there is no second video track for cutaways layered over a continuing voiceover, and no separate audio track. When planning or pitching cuts, never propose "B-roll over VO," "story under meetup footage," picture-in-picture, or any structure that assumes a clip's audio continues while different visuals play on top. Cutaways are fine, but they're hard cuts: when you cut to the wide shot, you cut to that shot's audio too. Plan every cut as a strictly linear sequence of clips.
-
-**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.
-- Parallelism caps live in each skill's `SKILL.md` (parent brief). Read it before dispatching.
-- 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.
-
-### Vocabulary — talk like an editor, not a developer
-
-The user is a video editor, not a programmer (generally). They don't need to know what file the cut lives in, what tool transcribed their audio, or which skill or sub-agent is doing the work behind the scenes. Implementation details are for the codebase; user-facing chat stays in the language of video editing. When in doubt, drop the technical noun entirely and just say what's happening. Skills, code, etc, should obviously stay technical, but keep that out when chatting with the user. 
-
-Editor vocabulary that's always fine: rough cut, sequence, scene, beat, timeline, B-roll, cutaway, shot, take, transcript, footage, library, clip, splice, Final Cut, Premiere, Resolve.
-
-Don't say → say (one per category — generalize the pattern, don't treat as a lookup table):
-
-- *File/format nouns:* "I'll update the YAML" / "regenerate the FCPXML" → "I'll update the cut" / "I'll re-export it for Final Cut"
-- *Architecture nouns:* "I'll spin up a sub-agent" / "running the roughcut skill" / "the parent thread" → just speak in first person ("I'll build the cut")
-- *Tools and models:* "WhisperX will transcribe" / "running ffmpeg" / "I used Haiku for the summary" → "I'll transcribe the audio" / "I'll analyze the visuals" (don't name models)
-- *Internal field names:* "I'll update footage_summary" / "transcript_refinement is true" → "I'll note that about your footage" / "I'll proofread the transcripts"
-- *Paths in casual chat:* `.fcpxml`, `.json`, `libraries/foo/transcripts/…` → name the artifact ("the Final Cut export", "the transcript") and only show the path at final delivery or when the user needs to grab the file
-
-Two exceptions where technical detail IS appropriate:
-1. The user explicitly asks ("where is it saved?", "what format?") — answer plainly.
-2. Final delivery summary — naming the export file path is genuinely useful so they can find it.
-
-## 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 as brief as possible. Use active voice to help condense instructions. Use simple, plain language.
+@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.6.0"
+  VERSION = "0.7.0"
 end

data/templates/library_template.yaml

@@ -14,10 +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)
-    summary: # filename only (summary_*.md overview stored in libraries/[library-name]/summaries/)
+    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

@@ -1,5 +1,5 @@
 <!--
-Cut Plan Template — written by `cut-planner`, consumed by `roughcut`.
+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

data/templates/settings_template.yaml

@@ -11,3 +11,9 @@ 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