davinci-resolve-mcp 2.68.1 → 2.69.0

package/CHANGELOG.md

@@ -2,6 +2,219 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.69.0
+
+The free edition is documented as reachable, silence ripple stops clipping
+speech at the cut, and the editorial surface grows a set of review-first
+planners: dead-space markers, craft-aware cut points, conform QC, colour
+pre-balance, beat detection, turnover manifests, and a project journal.
+
+Two themes run through the additions. **Nothing new executes** — every planner
+proposes and reports, and the existing plan → confirm → execute path is
+unchanged. And **unverified is never reported as clean**: an item that could not
+be analysed, a check that could not run, a handle that could not be measured and
+a take with no transcript are each reported as such rather than folded into a
+passing result.
+
+### Changed
+
+- **`plan_silence_ripple` guard bands are now 2 pre-head / 4 post-tail frames**
+  (previously 0 and 1 — effectively none). This changes default output for any
+  caller that does not pass explicit handles.
+
+  The old defaults cut exactly on `silencedetect`'s gate crossings, which are not
+  word boundaries. `s` is marked when amplitude falls below the gate, but a
+  word's decay and the room reverb after it stay audible below it, so cutting
+  from `s` clipped the release. `e` is marked when amplitude rises back above the
+  gate, and a soft attack (s, f, th, or any unstressed syllable) crosses later
+  than the word actually begins, so `e` sat *inside* the next word and cutting up
+  to it ate the onset.
+
+  The onset guard is the larger of the two because that is the asymmetry users
+  hear: reviewers of the first public tutorial for this project independently
+  reported that "the first split seconds of your clips are trimmed so the audio
+  is a bit cut off". At 24 fps the new guards are 83 ms and 167 ms; at 30 fps,
+  67 ms and 133 ms — both inside the range dialogue editors use by hand.
+
+  Pass `pre_head_frames` / `post_tail_frames` explicitly to restore the previous
+  behaviour.
+
+### Fixed
+
+- **The docs told free-edition users the door was closed.** v2.68.0 shipped the
+  in-app bridge, which reaches the free edition through the ungated
+  **Workspace > Scripts** menu, but README's Requirements section still said "the
+  free edition does not support external scripting" 195 lines below the section
+  documenting the bridge, and `docs/install.md` said the same with no mention of
+  the bridge at all. The claim is true about *external* scripting and false as
+  users read it — the first large public tutorial for this project pinned a
+  correction telling viewers the method "REQUIRES the Studio Version".
+
+  README, `docs/install.md`, `install.py` and the MCP server's own `instructions`
+  now state the limit and the remedy together. `install.py` also grew the branch
+  it was missing: Resolve running, healthy interpreter, no connection is the
+  free-edition signature, and it used to print "Not running — start Resolve".
+
+### Added
+
+**Editorial**
+
+- `edit_engine.plan_dead_space_markers` — **the review gate.** Finds dead space
+  with the same calibrated detection as `plan_silence_ripple`, but proposes
+  Resolve markers instead of assembling a variant, so an editor can see every
+  gap before agreeing to lose it. Red = confident; yellow = the gate only just
+  cleared its separation floor. Items that could not be analysed are reported
+  and are explicitly **not** certified clean.
+- `tightness` (`generous` default | `balanced` | `tight`) on the dead-space
+  planner. The default is deliberately the loosest: a first assembly is meant to
+  run long, because trimming is fast and visible while recovering material the
+  machine discarded is slow and invisible. Guard bands are floored regardless of
+  preset — `tight` removes more *gaps*, never more *speech*.
+- Syntactic pause classification in `plan_transcript_tighten`. A pause after a
+  full stop must be markedly longer before it is proposed for removal than the
+  acoustically identical pause mid-phrase; the first is usually breathing room
+  and the second usually is not. Unpunctuated transcripts are flagged low
+  confidence rather than treated as all-removable.
+- `edit_engine.rank_takes` — ranks takes on **measurable fluency** (fillers,
+  restarts, script coverage) and states in every response that fluency is not
+  quality. It never names a best take.
+- `edit_engine.plan_beat_cuts` — beat, bar and phrase cut points for
+  music-driven cutting, frame-snapped. Requires the optional `librosa` extra and
+  honest-refuses without it.
+- `edit_engine.plan_string_out` / `propose_structure` — assembly for footage
+  with no speech, from shots and motion rather than silence; and a no-script
+  mode that proposes a structure and requires approval.
+- `edit_engine.plan_broll` — places B-roll against A-roll beats. Placement only:
+  relevance is the caller's and is never re-scored, protected beats are never
+  covered, and an explicit beat choice is honoured or refused, never moved.
+- `edit_engine.rule_of_six_audit` and `split_edit_audit` — audits against the
+  classical weighted cut criteria, and J/L-cut classification. The audit is
+  explicit that the two heaviest criteria are not measurable and reports its own
+  coverage; there is deliberately no composite score.
+
+**Finishing and colour**
+
+- `edit_engine.conform_lint` — the online editor's pre-turnover checklist:
+  frame-rate mismatch, offline media, duplicate source timecode, buried layers,
+  fragile effects, missing reel names, duplicate usage. Checks that could not run
+  are listed in `not_checked`.
+- `edit_engine.plan_prebalance` and `plan_reference_match` — neutral technical
+  pre-balance, and matching to a graded reference still. Curves, vignettes,
+  saturation, qualifiers and windows are refused **in code**; midtones are left
+  warm by design. Reference matching is end-points-only and says so.
+- `edit_engine.plan_turnover` — sound / VFX / colour turnover manifests with
+  per-destination handle floors and a timecode-burned picture reference required
+  in all three. Manifests, not exports.
+- Plans now carry a `handle_report`: keep ranges that leave too little source
+  media at a join for a dissolve, a slip or an audio crossfade.
+
+**Reporting**
+
+- `edit_engine.plan_report` and `include_report` on every audit — Markdown
+  renderings covering what would change (in timecode, with a reason per cut),
+  what was deliberately left alone, what could not be verified, and what needs a
+  human. Off by default for token cost; every audit advertises it.
+- `journal` — ingest log, append-only known issues, session-prep summary with
+  value figures, technical handoff document, status summary, and a picture-lock
+  fingerprint with drift detection.
+- `first_impression` — timestamped capture of a first viewing, sealed once
+  locked. There is deliberately no unlock.
+
+**Documentation**
+
+- **Optional extras are now documented up front** — README and `docs/install.md`
+  list what each extra unlocks and under which licence, and `scripts/doctor.py`
+  reports which are present. Four of the features added in this release need
+  `numpy` or `librosa`; they refuse honestly with the install line, but a user
+  reading the README previously had no way to know before hitting the refusal.
+  "Setup too hard" was one of the loudest complaints this release answers, and
+  shipping features behind an undocumented `pip install` is the same failure.
+
+**Guards**
+
+- `tests/test_free_edition_docs_drift.py` — a guard that does not forbid stating
+  the free-edition limitation, but requires that any file stating it also names
+  the bridge. Broad enough to catch a new phrasing rather than only the sentences
+  fixed here, and it asserts the remedy exists (the README anchor and the
+  installer script the docs promise).
+- `tests/test_attribution_drift.py` — keeps named third parties out of the
+  committed tree entirely. Stores SHA-256 digests rather than the names it
+  forbids, so the guard is not itself the one file containing them.
+- `resolve-advanced` now carries an MIT `LICENSE` in its published tarball, and
+  the three vendored workspaces declare `"license": "MIT"`.
+
+## What's New in v2.68.2
+
+Bug fixes. The server no longer opens a second DaVinci Resolve, and a failed
+connection now tells the caller what is actually wrong.
+
+### Fixed
+
+- **The server launched Resolve when one was already running — usually the wrong
+  one.** The free edition refuses external scripting by design, so on a machine
+  where only it is running `scriptapp("Resolve")` always returns None.
+  `get_resolve()` read that as *"Resolve is not running"* and ran `open` on the
+  application; with both editions installed that started **Studio**, a second and
+  different application, on every tool call.
+
+  `resolve_is_running()` now answers the question that was being assumed. It
+  returns None when it cannot tell, deliberately — "cannot tell" must never decay
+  into "nothing is running", because that is the answer that leads to launching
+  something. A genuinely absent Resolve is still launched, as documented, and the
+  macOS candidate list now contains **both** editions rather than only the
+  installer path.
+- **The error a caller received described something that had not happened.**
+  Eleven sites asserted that Resolve was not running, that starting it had been
+  tried and failed, and that the reader should check their Studio install. After
+  the fix above none of that was true, and the accurate guidance was only reaching
+  the log. `_not_connected_error()` derives the message from the situation and
+  names the applicable remedy — external scripting on Studio, or the in-app bridge
+  on the free edition, including the framework-Python prerequisite. Three codes:
+  `SCRIPTING_UNAVAILABLE`, `BRIDGE_UNAVAILABLE`, `RESOLVE_NOT_RUNNING`.
+- **Those two are marked `retryable: false`.** The `not_connected` category
+  defaults to retryable because auto-launch may succeed next time; neither of
+  these can — one needs a preference changed, the other a script started inside
+  Resolve — and reporting them as retryable sends an agent into a loop it cannot
+  win.
+- **The offline test suite opened Resolve, and connected to whatever was running.**
+  A stub-based audio test reached for `AUDIO_SYNC_*`, which are attributes on the
+  *live* object, so it called `get_resolve()`, found nothing, and started Resolve;
+  when Resolve *was* open it connected instead, making the test's result depend on
+  the state of the machine. `tests/conftest.py` closes both suite-wide and names
+  any launch attempt in the terminal summary.
+- **`src/server.py` reported the wrong tool count to every agent.** Its module
+  docstring said "34 compound tools" while the agent-facing workflow prompt and
+  the startup log line said 32. The drift guard only required the correct number
+  to appear *somewhere* in the file, so the wrong one shipped. It now rejects any
+  other count in front of that phrase, and counts decorators from the parsed
+  syntax tree rather than by matching text — a docstring mentioning
+  `@mcp.tool()` had been counted as a 35th tool.
+- **The bridge harness graded the wrong clip and reported a known trap as a
+  finding.** It took the first video item, which is often a generator or title
+  that has no MediaPoolItem and answers None to every node query, so the grading
+  surface read as unreachable; it now takes the first gradeable item. And it
+  passed the codec *description* `"H.264"` to `SetCurrentRenderFormatAndCodec`,
+  which only accepts the id `"H264"`, making that observation permanently false
+  for a documented reason.
+
+### Changed
+
+- `scripts/install_resolve_bridge.py` no longer claims Resolve ignores Fusion's
+  standalone script tree. Measured on free 21.0.3.7: markers left in two
+  undocumented container paths both appeared under Workspace ▸ Scripts, so Lite
+  scans more locations than the README documents. Install behaviour is unchanged —
+  the documented paths work, and each extra target is another chance for the macOS
+  App Management prompt to stall the copy — but the stated reason is now the true
+  one.
+
+### Validated
+
+Free edition alone (21.0.3.7, App Store), Studio never launched at any point,
+confirmed by process check after every stage: 165/165 read-shaped MCP actions
+clean with Blackmagic's module blocked; 109/112 API read methods exercised; render
+to a non-empty file with `set_format` true; AAF/DRT/EDL/FCPXML all written;
+SetLUT clears and reads back. Suite 1913 passing.
+
 ## What's New in v2.68.1
 
 Bug fix. A missing tool argument now returns the structured error envelope the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.68.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.69.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)
@@ -185,6 +185,47 @@ The open-source servers are complete and fully functional on their own.
 | Render and deliver | Format/codec matrix probing, render settings validation, queued job lifecycle checks, guarded Quick Export |
 | Extension authoring | Fuse, DCTL, ACES DCTL, and Resolve-page Lua/Python script lifecycle helpers with safe MCP-marked install/remove |
 
+## Optional Extras
+
+The core install is deliberately small: Python, ffmpeg, and the Resolve scripting
+API. Some features need more, and **each one refuses honestly with its own
+install line rather than degrading into a guess** — a fabricated tempo or an
+invented level produces confident, wrong output, which is worse than no feature.
+
+Run `python scripts/doctor.py` to see which of these you have.
+
+| Extra | Unlocks | Licence |
+|---|---|---|
+| **ffmpeg** on PATH | Silence detection, dead-space markers, level measurement, audio analysis. The single most useful thing to install. | LGPL/GPL — invoked as a subprocess, never bundled |
+| `pip install numpy` | Colour pre-balance, reference-still matching, sound-density audit | BSD |
+| `pip install librosa` | Beat, bar and phrase detection for music-driven cutting | ISC |
+| `pip install -U openai-whisper` | Transcription, and everything word-level built on it | MIT |
+| `pip install open_clip_torch` | Visual similarity and `find_similar` | MIT |
+| `pip install transformers` | CLAP audio embeddings | Apache-2.0 |
+| `pip install opencv-python` | Additional frame analysis | Apache-2.0 |
+
+`media_analysis` action `capabilities` reports the analysis stack in detail and
+tells you what each missing piece would enable.
+
+**Nothing here is bundled.** Model weights carry their own licences separate from
+the code that loads them; check them before commercial use.
+
+## What This Does Not Do
+
+Knowing where a tool stops is worth as much as knowing what it does, and it is
+cheaper to read it here than to discover it mid-project.
+
+| Not supported | Why, and what you get instead |
+|---|---|
+| **Choosing the best take** | Performance is most of what makes a take right, and none of it is measurable from a waveform or a transcript. `rank_takes` ranks *fluency* — fillers, restarts, script coverage — and says so in every response. The take that plays is regularly the least fluent one, because the hesitation is often the acting. Use it to find the clean safety take, not to choose the read. |
+| **Cutting to music** | No beat or downbeat detection yet. Speech-driven tools will read a music bed as one long region and are the wrong instrument for it. |
+| **Judging a cut** | Nothing here has an opinion about whether an edit is good. Every destructive action is plan → review → confirm for that reason. |
+| **Replacing an editor** | The output is a first-pass assembly, in the assistant-editor sense: ingest, sync, organize, string out, flag problems. It is a starting point you cut, not a finished cut. Defaults are deliberately **generous** — a first assembly is supposed to run long, because trimming is fast and visible while recovering discarded material is slow and invisible. |
+| **Modifying your source media** | By design and without exception — see below. |
+
+Anything analyzed but unverifiable is reported as unverified, never folded into
+"fine". An empty result means "nothing found", never "nothing to find".
+
 ## Source Media Safety
 
 This project treats camera originals and source media as immutable. Analysis tools read source files and write reports only to sidecar, scratch, or project analysis directories; confirmed metadata publishing writes only to Resolve's project database. The server must not modify, transcode, proxy, or create derivatives of source media unless the user explicitly asks for that. See [Media Analysis Guide](docs/guides/media-analysis-guide.md) for the detailed source-safe workflow.
@@ -231,9 +272,11 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
 
 ## Requirements
 
-- DaVinci Resolve Studio 18.5+ on macOS, Windows, or Linux. The free edition does not support external scripting.
+- DaVinci Resolve 18.5+ on macOS, Windows, or Linux. **Studio** supports external scripting directly. The **free edition** does not — Blackmagic gates external scripting to Studio — but it is still reachable through the [in-app bridge](#free-edition-in-app-bridge), which runs inside Resolve from the ungated **Workspace ▸ Scripts** menu.
 - Python 3.10+ (3.10-3.12 is the lowest-risk range). Python 3.13/3.14 also work on recent Resolve builds (verified on Studio 20.3.2); older builds may fail to connect on 3.13+, in which case use 3.10-3.12.
-- Resolve external scripting set to **Local**.
+- Resolve external scripting set to **Local** (Studio). On the free edition this
+  preference has no effect — use the [in-app bridge](#free-edition-in-app-bridge)
+  instead.
 
 Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+.
 

package/docs/SKILL.md

@@ -850,11 +850,191 @@ clip-count readback plus `brain_edits` rationale rows.
   min_strip_frames?, pre_head_frames?, post_tail_frames?, include_audio?)` —
   waveform silence strips via ffmpeg `silencedetect`, mirroring Resolve's
   *Clip → Audio Operations → Ripple Delete Silence* (defaults: −30 dB,
-  10-frame minimum strip, 0 pre-head, 1 post-tail frame). Items without
+  10-frame minimum strip, 2 pre-head, 4 post-tail frames — guard bands that
+  keep the cut off the outgoing word's decay and the incoming word's attack).
+  Items without
   readable file paths ride along whole (reported in `skipped`), so the
   variant never silently loses content. `execute_silence_ripple(plan_id)`
   assembles a tightened VARIANT timeline from keep ranges — same safety model
   as `execute_tighten` (original untouched, confirm token, audio mirroring).
+- `plan_dead_space_markers(timeline_name?, track_index?, threshold_db?,
+  tightness?, min_strip_frames?, pre_head_frames?, post_tail_frames?)` —
+  **review before you cut.** Finds dead space with the *same* calibrated gate as
+  `plan_silence_ripple` but proposes Resolve **markers** instead of an edit, so
+  an editor can look at every gap, delete the markers they disagree with, and
+  only then tighten. Reach for this whenever the ask is "show me the gaps
+  first" — it is the review gate, and without it an agent will invent its own
+  detection and mark the wrong spots. Red = confident; **Yellow = the gate only
+  just cleared its separation floor, so speech and room are close together and
+  the call deserves a second look.** Nothing is written: pair the returned
+  marker specs with `timeline_markers`. Items in `skipped` were *not* analyzed
+  and are explicitly **not** certified clean.
+  `tightness` (`generous` default | `balanced` | `tight`) scales the guard bands
+  and the minimum gap length — see below.
+- `plan_report(plan_id, max_detail_rows?)` — **render any plan as a reviewable
+  Markdown report.** A 340-entry `keep_ranges` array is not reviewable, and the
+  rational response to a machine you cannot audit is to re-check it by hand,
+  which is the cost the tool was meant to remove. The report states: what would
+  change (in **timecode**, with a reason per cut), what was **deliberately left
+  alone** (invisible in the output, and the half people distrust most), what
+  could **not** be verified (never folded into "fine"), and what **needs a
+  human**. Returns both `report_markdown` and a one-line `summary` for chat.
+  Every plan kind renders, including ones this renderer does not know about.
+- `rank_takes(clip_refs[], script?)` — rank several clips of the same material by
+  **measurable fluency**: filler density, stammered restarts, longest clean run,
+  and (with a `script`) how much of the intended line got said. **It ranks
+  fluency, not quality, and says so in every response.** Performance is most of
+  what makes a take right and none of it is measurable here — the take that
+  plays is regularly the least fluent one, because the hesitation is often the
+  acting. Use it to find the clean safety take or skip the warm-ups, never to
+  choose the read. Clips without transcripts are listed in `unavailable`
+  (**absent from the ranking, not last in it**), and takes too short to score
+  are flagged rather than dropped.
+- `plan_beat_cuts(clip_ref | media_path, mode?, beats_per_bar?, bars_per_phrase?,
+  beat_offset?, min_shot_seconds?, timeline_fps?)` — **cut points from the music's
+  own pulse**, for footage with no speech. The speech tools find edit points in
+  words and pauses; music has neither, and pointing a silence gate at it makes
+  engine noise read as content and quiet read as dead space. `mode`: `beat` (every
+  beat — relentless), `bar` (downbeats), **`phrase` (default)** — music resolves at
+  phrase boundaries, which is what makes a cut feel inevitable rather than merely
+  synchronised. Frame-snapped. **Downbeats are inferred, not detected** (the first
+  beat is assumed to start a bar) — a track with a pickup needs `beat_offset`, and
+  that is the first thing to check if cuts feel consistently one beat early.
+  Reports its own tracking confidence. Requires the optional `librosa` extra
+  (`pip install librosa`, ISC) and **honest-refuses without it** rather than
+  inventing a tempo. Returns cut POINTS, not an assembly.
+- `plan_prebalance(timeline_name?, track_index?, max_items?)` — **neutral technical
+  pre-balance**, the assistant colorist's highest-leverage pass. Measures black and
+  white points per channel off a mid-shot frame, groups by setup, picks a hero, and
+  proposes one bypassable **`ASST: Balance`** node per clip. Black balance on the
+  parade first, then white point. **Midtones are deliberately left warm** — skin
+  belongs near 11 o'clock on the vectorscope, and neutralizing midtones is the
+  fastest way to make everyone grey. Curves, vignettes, saturation, qualifiers and
+  windows are **refused in code**, not merely discouraged. Clipped highlights and
+  crushed shadows are flagged as `ASST: TECH/CREATIVE` markers, never silently
+  fixed. It has scopes and no eyes: numeric balance is defensible, look development
+  is not, and it cannot know the dim shot was dim on purpose.
+- `rule_of_six_audit(timeline_name?, track_index?)` — audits a timeline against
+  the **Rule of Six** — the classical weighted cut criteria — and is loud about
+  what it cannot see. Those weights
+  are inverted against measurability: **everything computable is the bottom 26%**.
+  So **emotion (51%) and story (23%) appear in every response as `NOT_ASSESSED`
+  and cannot be suppressed**, criteria this build does not compute report
+  `NOT_IMPLEMENTED` (never a pass), and coverage is stated outright — *"1 of 6
+  criteria assessed, covering 10% of the decision."* **There is deliberately no
+  composite score**; averaging 26% into one number implies it describes the cut.
+  Findings order by scope ("movie first, scene second, moment third")
+  then by criterion weight — never by volume, so a rhythm problem (10%) always
+  outranks a screen-geography one (5%). Rhythm is implemented: metronomic runs
+  are flagged, and a pattern break landing on a marker is reported as **craft,
+  not a finding** — the break is where meaning lives. Cuts/min is compared to
+  the 14–16 commonly observed in dialogue, explicitly **descriptive not
+  prescriptive**.
+- `split_edit_audit(timeline_name?, track_index?)` — **sound leads picture**.
+  The ear is faster than the eye, so the classical advice is to treat the cut as
+  a sound event first. Classifies every join: **L-cut** (audio edit later — outgoing
+  sound lingers), **J-cut** (audio earlier — incoming sound pulls forward), or
+  straight. A picture cut with no nearby audio edit is reported as **unpaired,
+  not straight** — sound running continuously across a join is a *stronger* form
+  of sound carrying picture. Flags a timeline where every join is straight: that
+  is where the NLE puts audio edits by default, and a dialogue sequence with no
+  split edits anywhere is usually one nobody has listened to yet. **No correct
+  ratio is suggested and none exists** — a montage, a two-hander and an
+  interview all want different distributions.
+- `sound_density_audit(track_media, stream_limit?, duration_seconds?)` — the
+  **two-and-a-half rule**: an audience follows roughly 2.5 simultaneous sound
+  streams before the rest becomes texture. The distinction that makes this usable
+  is **competing vs. layered** — a music bed under dialogue is one stream plus
+  texture, not two competitors, and a version that counted active tracks would
+  flag every mixed timeline ever made. A stream within 12 dB of the loudest
+  counts as competing; further under counts as a bed. **2.5 is a long-standing
+  observation in sound editing, not a measured constant** — it is a parameter and its provenance
+  travels with every result. Pass rendered stems for a true reading; source clips
+  give a reading of the sources, and the response says which it got.
+- `setup_sheet(timeline_name?, track_index?)` — **the wall of stills**: one
+  representative frame per *setup*, not per shot, so twenty images stand for the
+  whole film instead of two hundred reproducing the timeline at higher
+  resolution. Frame taken from the middle of that setup's longest usage (heads
+  and tails catch fades, slates and handles); ordered by **first appearance** so
+  the sheet reads in the direction the film does. Grouping is reel-name-else-
+  folder — a stated proxy for lighting setup, which Resolve does not expose.
+- `first_impression(op=start|record|lock|get|list|diff, …)` — the editor is the
+  only person who gets to be a first-time audience, and that perception is
+  destroyed by the second viewing. Captures timestamped reactions during a first
+  pass and then **seals them**. `record` on a locked log raises; **there is
+  deliberately no unlock** — an impression that can be revised later is
+  worthless, because by then what changed is the viewer, not the film. Free text,
+  **no schema and no sentiment scoring** — the words are the artifact. `diff`
+  reports whether a later pass **revisited** each reaction and explicitly refuses
+  to claim anything was *fixed*.
+- `plan_reference_match(reference_media, reference_at_seconds?, timeline_name?, max_items?)`
+  — match clips to a **graded reference still**, the way a colorist actually
+  communicates ("make it look like this one"). Reuses `prebalance.validate_plan`
+  rather than reimplementing the guardrails, so this path cannot permit what the
+  neutral path forbids. **END POINTS ONLY, stated in every response** — it puts
+  a shot in the reference's tonal neighbourhood and does **not** transfer the
+  reference's grade; curves, vignettes and secondaries stay where they are.
+  Matching across dissimilar subject matter (night exterior vs white cyc) is
+  reported as **low confidence** rather than delivered with a straight face.
+- `plan_string_out(shots, order?)` — assembly for footage that does not talk.
+  Speechless material is cut from **shots and motion**, not silence: point a
+  speech gate at motorsport and engine noise reads as content while a quiet
+  straight reads as dead space. `order`: `chronological` (default) or
+  `activity`. **Unmeasured motion is never treated as static**, a locked-off
+  shot is described rather than penalised, and ranking by movement is a
+  measurement not an edit — the most important shot may rank last. Returns a
+  string-out, never a cut.
+- `propose_structure(topics)` — **no-script mode**. Orders topics by coverage,
+  which measures what was *shot* and not what matters, and says so.
+  `requires_approval` is always true: a structure inferred from clustering is a
+  hypothesis about what the piece is, and the decision least safe to take
+  silently.
+- `plan_broll(beats, candidates, allow_reuse?)` — place B-roll against A-roll
+  beats. **Placement only: relevance is whatever your matcher said and is never
+  re-scored here**, because whether a shot illustrates a line is not something
+  this can see. Cutaways sit *inside* a beat rather than straddling one; a beat
+  marked `protected` is never covered; an explicit `beat_index` is honoured
+  there or not at all, never silently moved somewhere it fits better.
+- `plan_turnover(destinations, contents, version?, handle_frames?)` — validate
+  **sound / VFX / colour turnover manifests** against spec. Per-destination
+  handle floors (sound 48 frames, picture 8 — crossfades and room tone reach
+  past the picture cut), and a **timecode-burned picture reference is required
+  in all three**, its absence a blocker: without one the receiving editor cannot
+  verify anything against your intent. Includes the burn-in spec (both source
+  *and* record timecode). **Manifests, not exports** — an export that runs
+  perfectly and omits the textless is still a failed turnover, and rendering
+  needs a live Resolve.
+- `journal(op=append|read|known_issues|ingest_log|session_prep|handoff|status|
+  picture_lock|check_lock, …)` — the paperwork every craft role keeps and every
+  tool skips. **Append-only:** resolving an issue appends a resolution and never
+  deletes the issue, so the one nobody got round to is still there when someone
+  asks why a shot shipped soft. `session_prep` carries open issues plus the value
+  figures (prep hours, hours saved, rate) because the prep has to justify itself
+  in the next budget round. `handoff` prints missing fields as **NOT STATED**
+  rather than omitting them — a handoff that silently drops the frame rate reads
+  as complete and the gap surfaces after work has started. `picture_lock` records
+  a fingerprint of the cut and `check_lock` reports drift; the fingerprint hashes
+  the **edit points**, not just counts and totals, so shots redistributed inside
+  an unchanged runtime — exactly what a trim pass produces — still trip it.
+- **All audits accept `include_report=true`** for a Markdown rendering (what
+  changed, what was deliberately left alone, what could not be verified, what
+  needs a human). Off by default because rendering costs tokens on every call;
+  every audit advertises it in `report_available`.
+- `conform_lint(timeline_name?, track_index?)` — **the online editor's checklist,
+  run before turnover** instead of discovered after picture lock in someone else's
+  suite. Blockers: frame-rate mismatch, offline media, two sources claiming one
+  source timecode (misnamed cards — the most common reason a relink fails).
+  Warnings: items buried under opaque layers, track overlaps, missing reel names,
+  and effects that will not survive interchange (Premiere's *Scale to Frame Size*
+  is the classic — its sizing data does not reach Resolve at all). It reports, it
+  does not fix, and **checks that could not run for want of data are listed in
+  `not_checked`** rather than counted as passes.
+- Plans now carry a **`handle_report`**: keep ranges that leave too little source
+  media at a join for a dissolve, a slip or an audio crossfade. Picture floor 8
+  frames, audio 48 — audio is far larger because crossfades and room tone reach
+  past the picture cut. It reports rather than blocks (cutting to the head of a
+  clip is often unavoidable), but **an unverified handle is never reported as a
+  passing one**.
 - `plan_swap(timeline_start_frame | item_name, kind="visual"|"text",
   limit?)` — alternates for one timeline item via the similarity index,
   filtered to shots long enough to fill the slot exactly.

package/docs/install.md

@@ -4,13 +4,39 @@ This guide covers Resolve requirements, the universal installer, supported MCP c
 
 ## Requirements
 
-- **DaVinci Resolve Studio** 18.5+ (macOS, Windows, or Linux) — the free edition does not support external scripting
+- **DaVinci Resolve** 18.5+ (macOS, Windows, or Linux). **Studio** supports
+  external scripting directly. The **free edition** does not — Blackmagic gates
+  external scripting to Studio — but it is still reachable through the
+  [free-edition in-app bridge](../README.md#free-edition-in-app-bridge), which
+  runs inside Resolve from the ungated **Workspace ▸ Scripts** menu. Everything
+  below assumes Studio unless the bridge is in use
 - **Python 3.10+** (the MCP SDK requires 3.10). **3.10–3.12 is the lowest-risk
   choice**; 3.13/3.14 also work on recent Resolve builds — see below
 - DaVinci Resolve running with **Preferences > General > "External scripting using"**
   set to **Local**, or **Network** with `RESOLVE_SCRIPT_HOST` set to the Resolve
   host IP (`127.0.0.1` when Resolve and the MCP run on the same machine)
 
+### Optional extras
+
+The core install needs only Python, ffmpeg and the Resolve scripting API.
+Several features need an additional package and **refuse with the install line
+rather than guessing** if it is absent:
+
+| Extra | Unlocks | Licence |
+|---|---|---|
+| **ffmpeg** on PATH | silence detection, dead-space markers, level measurement | LGPL/GPL, subprocess only |
+| `numpy` | `plan_prebalance`, `plan_reference_match`, `sound_density_audit` | BSD |
+| `librosa` | `plan_beat_cuts` (beat / bar / phrase detection) | ISC |
+| `openai-whisper` | transcription and the word-level tools built on it | MIT |
+| `open_clip_torch` | visual similarity, `find_similar` | MIT |
+| `transformers` | CLAP audio embeddings | Apache-2.0 |
+| `opencv-python` | additional frame analysis | Apache-2.0 |
+
+`python scripts/doctor.py` reports which are present. `media_analysis`
+`capabilities` covers the analysis stack in more detail.
+
+Model weights carry their own licences, separate from the code that loads them.
+
 > **Python 3.13 / 3.14:** these are **allowed** — setup will use them and warn.
 > Python 3.14 is verified working against DaVinci Resolve Studio 20.3.2. On
 > *older* Resolve builds the scripting bridge may fail to load on 3.13+

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.68.1"
+VERSION = "2.69.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -1721,6 +1721,31 @@ def main():
                         f"             This can happen on Python 3.13+ with older Resolve builds. "
                         f"If MCP tools fail, recreate the venv with Python 3.10-3.12."
                     )
+                elif resolve_running:
+                    # Running, healthy interpreter, still no connection. Reporting
+                    # "Not running — start Resolve" here (as this branch used to)
+                    # is both wrong and a dead end: Resolve *is* running. This is
+                    # the free-edition signature — external scripting is gated to
+                    # Studio — and the bridge is the way through, so say so
+                    # rather than sending the user to restart an app that is up.
+                    print(
+                        f"  Resolve:   {yellow('Running, but external scripting returned no connection')}"
+                    )
+                    print(
+                        "             On Studio: Preferences > General > "
+                        "'External scripting using' = Local."
+                    )
+                    print(
+                        "             On the free edition: external scripting is gated to Studio, "
+                        "but the in-app bridge works —"
+                    )
+                    print(
+                        "               python scripts/install_resolve_bridge.py"
+                    )
+                    print(
+                        "               then Workspace > Scripts > resolve_bridge, "
+                        "and set DAVINCI_RESOLVE_BRIDGE=1"
+                    )
                 else:
                     print(f"  Resolve:   {yellow('Not running')} — start Resolve to use MCP tools")
             else:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.68.1",
+  "version": "2.69.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 DaVinci Resolve MCP Contributors and Bradford Operations LLC
+
+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.

package/resolve-advanced/package.json

@@ -15,7 +15,8 @@
   "files": [
     "server/**/*.mjs",
     "vendor/**",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/resolve-advanced/vendor/conform-qc/package.json

@@ -4,6 +4,7 @@
   "description": "Conform QC & repair engine: parse a turnover, derive the frame the target tool actually shows (the Oracle), frame-compare to a reference (brightness-robust), repair resourcefully, and deliver a verified package. Pure core + injected adapters. See docs/design/conform-qc-repair-engine-2026-06-16.md.",
   "main": "./index.js",
   "private": true,
+  "license": "MIT",
   "scripts": {
     "test": "node --test test/"
   },

package/resolve-advanced/vendor/drp-format/package.json

@@ -4,6 +4,7 @@
   "description": "DaVinci Resolve DRP (Project) format \u2014 XML/binary serialization, asset packaging, grade node encoders/decoders, validation. Layer 2 (drp-validator + grade-node-extractor read from fs / zip archives).",
   "main": "./index.js",
   "private": true,
+  "license": "MIT",
   "scripts": {
     "test": "echo 'see grade-encoder.test.js \u2014 runs via root jest config' && exit 0"
   },

package/resolve-advanced/vendor/drt-format/package.json

@@ -4,6 +4,7 @@
   "description": "DaVinci Resolve DRT (Timeline-only) format — same SeqContainer/MpFolder schema as DRP, no project shell. Parser + builder + validator delegate to drp-format primitives.",
   "main": "./index.js",
   "private": true,
+  "license": "MIT",
   "scripts": {
     "test": "node --test __tests__/"
   },