proofcut 0.29.0__tar.gz

proofcut-0.29.0/LICENSE

@@ -0,0 +1,166 @@
+Required Notice: Copyright 2026 tydude001 (https://github.com/tydude001/proofcut)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/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.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management
+System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+[Noncompete](#noncompete) for that product.
+
+## 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.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**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
+its affiliates.
+
+**Affiliates** means the other organizations than an
+organization has control over, is under the control of, or is
+under common control with.
+
+**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.

proofcut-0.29.0/PKG-INFO

@@ -0,0 +1,444 @@
+Metadata-Version: 2.4
+Name: proofcut
+Version: 0.29.0
+Summary: Source-available, local-first AI video editor and MCP server: recordings to a finished film, cut by transcript, then verified
+Author: tydude001
+Author-email: tydude001 <tylergrose321@gmail.com>
+License-Expression: LicenseRef-PolyForm-Shield-1.0.0
+License-File: LICENSE
+Requires-Dist: mcp>=2
+Requires-Dist: opentimelineio>=0.18.1
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.13, <3.14
+Project-URL: Homepage, https://github.com/tydude001/proofcut
+Project-URL: Documentation, https://github.com/tydude001/proofcut/blob/main/docs/MANUAL.md
+Project-URL: Issues, https://github.com/tydude001/proofcut/issues
+Description-Content-Type: text/markdown
+
+# proofcut
+
+**An AI video editor that proves its cuts.** Your recordings in, a finished,
+mastered film out: cut by transcript, with b-roll, cards, music and captions,
+and every step an agent can call. proofcut renders on your own machine, then
+transcribes the render and checks that it says what the edit says.
+
+https://github.com/user-attachments/assets/4153d180-3d7c-4c70-af5f-54d63d0a8bd5
+
+Above: an agent cutting a demo video, unattended. The two runs it was cut
+from, uncut (silent: the recorder took frames only, and the voice is in the
+film the agent cut): [the workspace](https://github.com/tydude001/proofcut/releases/download/v0.23.0/proofcut-v0.23.0-uncut-workspace-run.mp4)
+(2:26) and [Claude Code with the proofcut plugin](https://github.com/tydude001/proofcut/releases/download/v0.23.0/proofcut-v0.23.0-uncut-claude-code-run.mp4)
+(3:09).
+
+That is not a staged run. [TRIAL.md](https://github.com/tydude001/proofcut/blob/main/docs/TRIAL.md) scores three unattended
+ones, each handed a goal and no steps, and each passed every one of its checks.
+- **The demo cut**, the one above.
+- **Real footage:** 96 seconds of narration with its fluffed takes left in,
+  plus four clips of film footage. The agent cut it to 45 seconds, chose
+  footage by what each line was about, burned captions, and checked its own
+  render: all 123 expected words heard back.
+- **A whole film:** the demo material plus a score, briefed as a finished film
+  ready to upload. In 192 seconds and $2.27 the agent cut it, laid the music
+  under the voice, ended on a card, mastered it to −16 LUFS, and checked it.
+  The score, the level and the end card were each measured in the delivered
+  file, not taken from the project.
+
+> **Have a Mac or a Windows PC and half an hour?** Nobody has run proofcut on
+> a Mac yet, and on Windows only its author has. One script runs the whole
+> test and removes what it installed:
+> [Mac](#help-wanted-the-first-run-on-a-mac) or [Windows](#help-wanted-a-windows-run-by-someone-else).
+
+## From recordings to a finished film
+
+One project, and proofcut's own commands from the first import to the
+delivered file. No NLE finishes the film, and nothing else touches the render.
+Each stage is one command. The [manual](https://github.com/tydude001/proofcut/blob/main/docs/MANUAL.md) walks every one, and
+its [§ Music, holds, a cold open and the master](https://github.com/tydude001/proofcut/blob/main/docs/MANUAL.md#music-holds-a-cold-open-and-the-master)
+covers the sound:
+
+| Stage | Command |
+|---|---|
+| Bring in the voiceover and footage, and transcribe | `import`, `transcribe` |
+| Cut retakes and asides by naming their words | `cut vo 111:114` |
+| Hang b-roll and cards off the lines they belong to | `cue add`, `card new` |
+| Open cold on a scene, end on a card | `head`, `tail` |
+| Play the footage's own lines in a gap, or under the narration | `hold add`, `hold under` |
+| Score it: placed passages, crossfaded, levelled under the voice | `music` |
+| Pull breaths down without cutting them | `attenuate` |
+| Render and master to a loudness target | `export --render --loudness -16` |
+| Burn in captions | `captions --burn` |
+| Check the render says what the edit says | `verify`, `frames`, `hold check` |
+
+Two video essays of five to six minutes have been rebuilt this way and
+measured against their originals, which had been finished outside proofcut.
+One came out the same length to the frame. The other matched its original's
+63 voiceover ranges to the millisecond, with the voice aligned to the sample,
+starting from a retake pass made in Kdenlive. Both master at the original's
+−16 LUFS (HISTORY.md § The Lambs/Longlegs native rebuild, § The Scream native
+rebuild).
+
+proofcut makes no footage and writes no script. It takes what you recorded to
+a film, and proves the film matches the edit.
+
+## Why proofcut
+
+- **It checks its own work.** `verify` transcribes the finished file and
+  diffs it word by word against the timeline, so a retake left in the film is
+  caught before anyone watches it. Frame counts and the picture are measured
+  too, because ffmpeg, melt and auto-editor all exit 0 on some failures.
+- **Cuts stay addressable.** Every word in a recording keeps a fixed index
+  that never renumbers, so `cut vo 111:114` names the same words however many
+  cuts came before it. `--plan` prints what a range says before anything
+  changes, and `restore` and `undo` walk it back.
+- **Built for agents.** 93 MCP tools with typed inputs and structured
+  returns, so Claude Code, Codex or your own agent can drive it. Tools like
+  `shot-sheet` return an image of the edit, not a file path the agent can't
+  open.
+- **One engine, three ways in.** The MCP server, the `proofcut` command line
+  and a browser workspace all call the same operations. Every tool has a
+  matching command (the test suite enforces it), so anything an agent does,
+  you can script or re-run by hand.
+- **Local-first.** Commercial AI editors are apps around a metered cloud
+  service. proofcut transcribes, edits and renders on your machine, and calls
+  no cloud service of its own: no account, no per-minute billing. The only
+  thing that talks to a model provider is the agent you choose to run (the
+  optional footage-description and voice models download once, on first use).
+- **No lock-in.** The timeline is OpenTimelineIO. Export a `.kdenlive` or
+  OTIO file, finish in Resolve, Premiere or Kdenlive, and bring your trim back
+  with `import-edit`.
+
+![The proofcut workspace on the demo project: the transcript with a retake struck
+through, the preview drawing the shot under the playhead with its captions, the
+side rail on its agent tab reporting a finished render against the timeline,
+and the layered timeline below — picture, waveform and captions as three
+projections of one edit](https://raw.githubusercontent.com/tydude001/proofcut/main/docs/img/edit-mode.png)
+
+## How it works
+
+Every hard part of an editor already exists as mature open source. proofcut
+is the layer that lets an agent drive them, and check what they produced:
+
+| Job | Done by |
+|---|---|
+| Cutting, concatenating, captions, rendering | ffmpeg |
+| Word-timed transcription (30+ languages) | openai-whisper |
+| Silence and bad-take removal | auto-editor |
+| The timeline, and export to other editors | OpenTimelineIO |
+| Layered rendering (b-roll, cards, music) | MLT |
+| Title and end cards | SVG templates, rendered by ImageMagick |
+
+## Try it
+
+Check your machine first, before cloning anything. `proofcut doctor` probes
+every tool proofcut uses and prints the fix for anything missing
+([§ Requirements](#requirements) has the list). With
+[uv](https://docs.astral.sh/uv/) and git installed:
+
+```sh
+uvx --from git+https://github.com/tydude001/proofcut proofcut doctor
+```
+
+The first run downloads Python 3.13 if uv has none, plus proofcut's
+dependencies, about 230 MB together.
+
+On Linux, `proofcut setup` installs whatever doctor marked ✗, for you alone
+and with no sudo, and `proofcut setup --uninstall` removes exactly what it
+added. It says what it will download and asks first; whisper is about 1.9 GB
+of it. On a Mac or a Windows PC, follow the fix doctor prints under each ✗.
+
+```sh
+uvx --from git+https://github.com/tydude001/proofcut proofcut setup
+```
+
+The demo and your own recordings run from a checkout:
+
+```sh
+git clone https://github.com/tydude001/proofcut && cd proofcut
+uv sync
+```
+
+### The two-minute demo
+
+No footage needed. [docs/DEMO.md](https://github.com/tydude001/proofcut/blob/main/docs/DEMO.md) generates a voiceover with a
+real retake, b-roll and a score, then walks a whole small film: cut the retake
+by naming its words, hang b-roll off a phrase, lay the score under the voice,
+render and master it, end on a card, and check the render against the
+timeline.
+
+```sh
+uv run python scripts/make_demo.py ~/proofcut-demo
+```
+
+### In Claude Code
+
+The plugin registers proofcut's MCP server, so all 93 tools are available
+with no setup of your own:
+
+```
+/plugin marketplace add tydude001/proofcut
+/plugin install proofcut@proofcut
+```
+
+The first start downloads about 175 MB of Python dependencies, and Claude
+Code gives a server 30 seconds to connect. On a slow connection, start that
+first session as `MCP_TIMEOUT=300000 claude`. If `/mcp` already shows proofcut
+as failed, reconnect it there; the download keeps what it fetched.
+
+Any other MCP client runs the same server, from a checkout or with no
+checkout at all:
+
+```sh
+uv run --project /path/to/proofcut proofcut mcp
+uvx --from git+https://github.com/tydude001/proofcut proofcut mcp
+```
+
+### On your own recording
+
+```sh
+uv run proofcut init myproject
+uv run proofcut -C myproject import VO.wav --clip-id vo
+uv run proofcut -C myproject transcribe vo                  # whisper, word-timed
+uv run proofcut -C myproject seed vo                        # auto-editor strips silences
+uv run proofcut -C myproject transcript vo --search "here's the thing"
+uv run proofcut -C myproject cut vo 111:114 --plan          # what do those indices say?
+uv run proofcut -C myproject cut vo 111:114 --pad 0.1       # inclusive word range
+uv run proofcut -C myproject export final.mp4 --render      # or a .kdenlive to finish in an NLE
+uv run proofcut -C myproject verify final.mp4               # did the render say what you edited?
+```
+
+To watch the edit instead, open the workspace. It plays the source through
+the edit, so seeing a cut costs no render:
+
+```sh
+uv run proofcut -C myproject open        # server plus an app window
+uv run proofcut -C myproject web --open  # the same page in a browser tab
+```
+
+## What it does
+
+One line each. The [manual](https://github.com/tydude001/proofcut/blob/main/docs/MANUAL.md) covers every command and the
+reasoning behind it.
+
+**Editing**
+
+- **Cut by transcript.** Word ranges, phrases, or spans of timeline time, all
+  undoable.
+- **The workspace.** Edit (transcript, preview, drag-trim and razor), Frame
+  (review every crop in place) and Finish (presets, verify, and the finished
+  file). The truth strip warns while you edit if the film would ship wrong.
+- **Captions from the timeline.** They stay right after cuts, and the style
+  is saved with the project. Karaoke highlight, sidecar ASS, or burned in.
+- **Multi-mic recordings.** A file with two mics is refused until you say how
+  to use it (`--mix` or `--audio-stream k`), and `attribute-speakers` labels
+  each word with who said it.
+
+**Sound**
+
+- **A score, placed.** `music` lays a bed under the voiceover from a word,
+  as passages that crossfade into each other or assets that rotate. Its level
+  is measured against the voice, and it moves with every cut because it stores
+  words, not seconds.
+- **The footage's own lines.** `hold add` opens a gap in the narration and
+  plays a clip's line across it, with the picture pinned to it. `hold under`
+  plays it quietly beneath the voice instead, and `hold check` transcribes
+  each one off the render.
+- **A cold open.** `head` plays a scene before the first word, with its own
+  audio.
+- **Breaths and the master.** `attenuate` pulls short noises down rather than
+  cutting holes. `export --loudness` masters the render to a target, measures
+  it before and after, and refuses a master that misses.
+
+**Checking**
+
+- **Render verification.** `verify` diffs the render's words against the
+  timeline. `frames`, `film-check`, `black` and `spots` check the picture.
+- **Transcript self-checks.** Retake seams, invented words, swallowed repeats
+  and suspect durations are reported when a transcript is attached, and
+  `unspoken` lets the render itself testify to words nobody said.
+- **An agent that can look.** `shot-sheet` draws the whole picture track as
+  one labelled grid, and `footage-sheet` browses a clip you haven't cut yet.
+  Both return the image itself over MCP.
+
+**Picture**
+
+- **B-roll by description.** `describe` writes what is on screen in each
+  ~10-second window of footage, and a cue table lays clips and cards over the
+  voiceover by word index.
+- **Cards.** Six SVG title and end card templates, rendered at the project's
+  own frame size. Change the size and they are flagged stale, and `card
+  reauthor` redraws them at the new size instead of stretching them.
+- **Reframing.** Per-shot crop windows for aspect changes, face-aware
+  proposals (`reframe-detect`), a review sheet, and stacked splits for two
+  speakers.
+- **Layered rendering.** Timelines with b-roll, cards or music render through
+  MLT, and the output file is measured, not trusted.
+- **Derived reels.** `reel` cuts part of the film into a new project, such as
+  a vertical teaser. It reports every picture it dropped and pins the ones it
+  kept.
+- **NLE round-trip.** Export to Kdenlive or OTIO, finish elsewhere, and
+  `import-edit` the trim back.
+
+![Frame mode: a shot list beside the selected shot's windows — each crop
+drawn as a rect on three of the source's own frames, over a filmstrip of the
+whole shot with the sampled instants ticked on it, the window's rect quoted
+in source pixels, Approve/Re-frame beside it, and coverage chips for stale
+framing and unexplained steps](https://raw.githubusercontent.com/tydude001/proofcut/main/docs/img/frame-mode.png)
+
+proofcut is 0.x software. A project from an older version is refused rather
+than guessed at, and `proofcut migrate` brings it forward.
+
+## Help wanted: the first run on a Mac
+
+GitHub's macOS runner takes the demo to a checked render, but a runner never
+reads the instructions, and no person has run proofcut on a Mac. If you have
+one and half an hour, one script installs what proofcut needs, makes a short
+test video, has proofcut cut, score, master and check it, and puts a report on your
+Desktop. It asks before it starts.
+
+```sh
+git clone https://github.com/tydude001/proofcut
+bash proofcut/scripts/mac_trial.sh
+```
+
+It installs `uv`, `ffmpeg-full`, `espeak-ng` and `auto-editor` with Homebrew
+(and Homebrew itself if you have none), plus the Shotcut app for its renderer
+and whisper. It records what it added, and `bash
+proofcut/scripts/mac_trial.sh --uninstall` removes exactly that and nothing
+you already had. Then [file the report](https://github.com/tydude001/proofcut/issues/new?template=mac-test.yml).
+A run that stops at the first step is just as useful, because where it stops
+is the finding.
+
+<a id="help-wanted-the-first-run-on-windows"></a>
+
+## Help wanted: a Windows run by someone else
+
+The author's own Windows 11 laptop ran this test end to end on 2026-09-14
+([#3](https://github.com/tydude001/proofcut/issues/3)), once the one bug it
+found was fixed: the render finished its file and then never exited, which
+GitHub's runner could not show because it has no console. It ran again on
+2026-09-15 with the score and the master the demo now makes, and passed every
+check, including hearing the score in the render. That is one x64 PC,
+set up by the person who wrote the script, so a run by anyone else is still
+the missing report. Windows 10 and ARM64 PCs have not been tried at all. From
+PowerShell:
+
+```powershell
+git clone https://github.com/tydude001/proofcut
+powershell -ExecutionPolicy Bypass -File proofcut\scripts\windows_trial.ps1
+```
+
+It downloads `uv`, `ffmpeg`, `auto-editor`, `espeak-ng`, Shotcut's renderer
+and whisper into one folder under `%LOCALAPPDATA%`. Nothing is installed
+system-wide and it needs no administrator rights. The same command with
+`-Uninstall` deletes that folder. It puts `proofcut-windows-report.zip` on
+your Desktop with your home folder's name taken out; [file the report](https://github.com/tydude001/proofcut/issues/new?template=windows-test.yml).
+
+## Requirements
+
+proofcut is developed on Linux (a Fedora-based desktop). On macOS and
+Windows the test suite passes on CI and GitHub's runners take the demo to a
+checked render. On Windows one person's PC has too, the author's; no person
+has run it on a Mac yet. Where each OS stands is in
+[docs/plans/PORTABILITY.md](https://github.com/tydude001/proofcut/blob/main/docs/plans/PORTABILITY.md).
+
+Run `uv run proofcut doctor` to check everything below at once. On Linux,
+`uv run proofcut setup` installs any of the last four that doctor marks ✗:
+a static ffmpeg, whisper, auto-editor's release binary and Shotcut's
+portable melt, which renders with no display at all
+([docs/plans/INSTALL.md](https://github.com/tydude001/proofcut/blob/main/docs/plans/INSTALL.md)).
+
+| You need | For | Notes |
+|---|---|---|
+| **Python 3.13** and [uv](https://docs.astral.sh/uv/) | everything | `uv sync` installs the Python side. The only runtime dependencies are `mcp` and OpenTimelineIO. |
+| **ffmpeg / ffprobe** built with `libx264`, freetype and libass | every media operation, captions | Fedora's default `ffmpeg-free` has no `libx264`: use RPM Fusion's `ffmpeg`. On a Mac, Homebrew's `ffmpeg` lacks freetype and libass: install `ffmpeg-full` and put `$(brew --prefix ffmpeg-full)/bin` first on `PATH` (it is keg-only). |
+| **[auto-editor](https://github.com/WyattBlue/auto-editor) 31+** | silence removal, single-source renders | Install the upstream binary. The PyPI package is a stale 29.x. |
+| **whisper** | transcription, render verification | Any `openai-whisper` install. `uv tool install --python 3.12 openai-whisper` is the short route (3.12 because torch's Intel-Mac builds stop there); add `--torch-backend cpu` without an NVIDIA GPU (1.9 GB instead of 5.5 GB). Found via `PROOFCUT_WHISPER`, then `PATH`. The CPU build transcribed the demo's 19-second voiceover in 33 seconds. |
+| **MLT (`melt`)** | layered renders (b-roll, cards, music) | Your distribution's MLT package (`mlt` on Fedora, whose `melt` package is an unrelated compression tool), or Kdenlive, whose flatpak copy is found automatically. `PROOFCUT_MELT` overrides both. |
+
+Optional. Each unlocks one feature, `proofcut doctor` reports whether it is
+available, and everything else works without it:
+
+| Optional | Unlocks | Notes |
+|---|---|---|
+| **ImageMagick 7** (`magick`) | title and end cards | ImageMagick 6's `convert` is not used, so distributions that still ship 6 (Ubuntu 24.04) need ImageMagick's own build. |
+| **[Claude Code](https://docs.claude.com/en/docs/claude-code)** (`claude`, logged in) | the agent pane in the workspace | `proofcut mcp` works with any MCP client; only the pane runs `claude` itself. |
+| **`PROOFCUT_VLM`** | `describe` (b-roll search by what's on screen) | The python of a venv with torch, transformers, bitsandbytes and Pillow, on a CUDA GPU. The Qwen2.5-VL model downloads on first use. |
+| **`PROOFCUT_FACE`** | `reframe-detect` (face-aware crops) | The python of a venv with insightface, onnxruntime and opencv-python. |
+| **`PROOFCUT_TTS`**, **`PROOFCUT_TTS_MODEL`**, **`PROOFCUT_TTS_VOICE`** | `vo-synth` (a line in a cloned voice) | A python with qwen-tts and a CUDA torch, a local Qwen3-TTS snapshot, and a directory holding a reference clip of the voice. There is no default voice, on purpose. |
+
+## Working on proofcut
+
+Whether you're a person or a coding agent, start with
+[CLAUDE.md](https://github.com/tydude001/proofcut/blob/main/CLAUDE.md). It holds the rules and the traps this repo has
+already hit, and Claude Code loads it automatically.
+[CONTRIBUTING.md](https://github.com/tydude001/proofcut/blob/main/CONTRIBUTING.md) is the short version a pull request is
+checked against, and [SECURITY.md](https://github.com/tydude001/proofcut/blob/main/SECURITY.md) says how to report a
+vulnerability.
+
+Where things live:
+
+| Path | What it is |
+|---|---|
+| `src/proofcut/ops.py` | Every operation. The MCP tools, the CLI and the web UI all call these. |
+| `src/proofcut/server.py` | The MCP server. Register tools with `@_tool()`, never `@mcp.tool()`. |
+| `src/proofcut/cli.py` | The `proofcut` command: one subcommand per tool, printing JSON. |
+| `src/proofcut/webui.py`, `src/proofcut/web/` | The workspace. It posts to `ops` and renders what comes back; it never decides anything itself. |
+| `src/proofcut/project.py`, `timeline.py` | The project manifest (`proofcut.json`) and the OTIO timeline. |
+| `tests/` | `test_server_stdio.py` drives a real `proofcut mcp` subprocess; `test_webui_http.py` a real socket. |
+| `scripts/` | The demo maker, the Mac and Windows trial kits, screenshot capture. |
+| `docs/` | The manual, the demo, and the design record (below). |
+
+Run the checks:
+
+```sh
+uv sync
+uv run ruff check .      # never `ruff format`; see CONTRIBUTING.md
+uv run pytest
+```
+
+The suite talks to a real `proofcut mcp` subprocess, so it is slower than a
+pure unit suite. Tests that need whisper, auto-editor, melt or ImageMagick
+skip when the tool is missing. Tests that render through `melt` also need a
+display: on a headless machine use `QT_QPA_PLATFORM=offscreen` or `xvfb-run
+-a` (`proofcut doctor` tells you which your MLT needs). Without one they fail
+with "no display for MLT's Qt module to open", which is the environment, not a
+regression.
+
+## Documentation
+
+- [docs/MANUAL.md](https://github.com/tydude001/proofcut/blob/main/docs/MANUAL.md): every command, with the reasoning.
+- [docs/DEMO.md](https://github.com/tydude001/proofcut/blob/main/docs/DEMO.md): the whole loop in two minutes.
+
+proofcut's reasoning is part of what it ships, so the design record is public:
+
+- [PLAN.md](https://github.com/tydude001/proofcut/blob/main/docs/PLAN.md): architecture, stack decisions, open questions.
+- [HISTORY.md](https://github.com/tydude001/proofcut/blob/main/docs/HISTORY.md): the dated record of what shipped and what the
+  evidence said.
+- [PRIOR-ART.md](https://github.com/tydude001/proofcut/blob/main/docs/PRIOR-ART.md): what else exists in this space, and what
+  proofcut does that they don't.
+- [NEXT.md](https://github.com/tydude001/proofcut/blob/main/docs/NEXT.md): the directions after the queues closed, ranked.
+- [TRIAL.md](https://github.com/tydude001/proofcut/blob/main/docs/TRIAL.md): an agent cutting a video end to end, unattended
+  and scored.
+- [docs/plans/](https://github.com/tydude001/proofcut/tree/main/docs/plans): the plans. LAUNCH.md, PORTABILITY.md, NATIVE.md
+  and SHOWCASE.md are in progress, and RENAME.md is done. Three are finished and kept because the code
+  cites their reasoning: [DAYDREAM.md](https://github.com/tydude001/proofcut/blob/main/docs/plans/DAYDREAM.md), the
+  feature map from [Daydream](https://www.daydreamvideo.com), the closest
+  commercial product; [STUDIO.md](https://github.com/tydude001/proofcut/blob/main/docs/plans/STUDIO.md), the workspace
+  design; and [POLISH.md](https://github.com/tydude001/proofcut/blob/main/docs/plans/POLISH.md), the works-for-anyone pass.
+
+## License
+
+[PolyForm Shield 1.0.0](https://github.com/tydude001/proofcut/blob/main/LICENSE). proofcut is source-available, not open
+source: you can read, run, change and redistribute it for any purpose except
+building a product that competes with it. Cutting your own videos, running it
+for clients, building on it and forking it to fix a bug are all fine. For a
+commercial licence, ask.
+
+The bundled typefaces are not proofcut's to relicense. The caption face in
+`src/proofcut/fonts/` and the three browser faces in `src/proofcut/web/` are
+OFL-1.1, each with its licence text beside it and its source in that
+directory's `FONTS.md`.
+
+## Say thanks
+
+If proofcut cut a video for you, you can [buy me a coffee on Ko-fi](https://ko-fi.com/tydude001).