# Changelog 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.57.5 Fixes a silent data-loss bug on Reel Name writes (issue #77) and bundles the community-contributed API-limitation entries from PR #76 (issue #75). - **Fixed** (#77) `set_clip_property` / `set_metadata` reporting `success: true` when writing the `Reel Name` clip property even though Resolve silently dropped the value. Resolve gates `Reel Name` behind the project setting *General Options > Assist using reel names from the:* — when that derives reel names automatically, scripted writes are ignored but still return `True`. On a batch ingest this meant hundreds of clips believed to have reel names assigned when none actually stuck. The server now reads the value back after writing known-unreliable keys and refuses to report success on mismatch, surfacing the project-setting gate as a `hint`. Wired into `set_clip_property`, `set_metadata` (both forms), and the bulk `normalize_metadata` path. Adds an `api_truth` bug entry (report now lists 18 missing + 11 bugs) and 10 unit tests. - **Added** (PR #76, thanks @swayll) four `submit: missing` API-limitation entries verified on Resolve 21.0.0: per-subtitle text/timing editing, subtitle track styling/presets, speech-recognition engine selection + SRT import, and Media Pool folder rename. These document the API ceiling behind the subtitle feature request in #75 — direct subtitle text editing and SRT round-trip are not exposed by the Blackmagic scripting API. ### Validation - Offline: full unit suite green; new `tests/test_reel_name_writeback.py` (10 tests) plus the api_truth/limitations drift guards. Live Resolve validation of the Reel Name read-back is recommended but not performed here — forcing the gate would require writing reel names into a live project's media metadata. ## What's New in v2.57.4 Live mutating verification of the catalogued API gaps. - **Added** `tests/live_api_gap_verification.py` — attempts each catalogued "missing capability" against a disposable project built from synthetic ffmpeg media, recording the failing call alongside a positive control that succeeds. All 8 surface-audited gaps confirmed missing on Resolve Studio 21.0.0: `SetProperty('Speed', …)` / audio-level keys return False while `RetimeProcess` / video-transform keys succeed; trim/move/split/proxy/node- graph/Smart-Bin methods are absent (by `dir()`), while append/CDL/AddSubFolder controls work. - **Added** a new bug entry: `hasattr()`/`getattr()` are unusable on Resolve objects — the Python bridge fabricates a callable for ANY attribute name, so capability detection must use `dir()`. (Discovered when the first harness pass reported nonexistent methods as present.) Report now lists 14 missing + 10 bugs. - **Changed** the report's Scope note to record the live mutating-harness methodology and the `hasattr` caveat. Strengthened the clip-speed and Fairlight-audio entries with the live `SetProperty` rejection evidence (and noted that `'Pan'` is the video-transform key, not audio pan). ## What's New in v2.57.3 Expanded the API-limitations catalogue with a live surface audit. - **Added** 8 newly-catalogued **missing capabilities** to `docs/reference/api-limitations.md`, found by a `dir()` audit of the live Resolve 21.0.0 API objects diffed against the UI feature set: timeline-item trim/move/re-time (getters only, no setters), razor/blade/split, clip speed/retime ratio & ramps, color node-graph editing + primary grade values, Fairlight audio levels/pan/EQ/automation/FairlightFX, proxy/optimized-media generation, insert/overwrite/replace/fit-to-fill edit modes, and Smart/Power Bin creation. The report now lists 14 missing capabilities + 9 bugs. - **Verified** the four previously-doc-derived entries (per-clip audio stereo↔mono, native multicam creation, transitions, cloud list/export/user) against the live API surface; all confirmed absent. - **Changed** the generated report to carry an explicit **Scope & completeness** note — it is not guaranteed exhaustive (surface audit + incident log; misses parameters that exist-but-misbehave and untested capabilities). ## What's New in v2.57.2 Consolidated, submittable list of Resolve scripting-API limitations. - **Added** `docs/reference/api-limitations.md` — a curated, behaviorally-verified catalogue of Resolve scripting-API gaps and bugs, split into **Missing Capabilities** (please add) and **Bugs / Unreliable Behavior** (please fix), formatted for submission to Blackmagic Design's developer feedback. First cut: 6 missing capabilities (Source Track Selector / insert `trackIndex`, per-clip audio stereo↔mono, native multicam-clip creation, transition create/copy, `GetTimelineByName`, cloud project list/export/user management) and 9 bugs/unreliable behaviors (enum-key silent failures in `AutoSyncAudio`, `CreateSubtitlesFromAudio`, CloudProject family, and `Timeline.Export`; flaky `DeleteProject`; `Composition.Paste` bridge failure; `FlowView` unreliable returns; truncated `Transcription` property; automation-blocking `CreateProject` modal). - **Added** `scripts/gen_api_limitations.py` — the report is generated from the `submit`-tagged entries in the `api_truth` ledger (single source of truth, also queryable at runtime via `resolve_control api_truth`), so it never drifts. - **Changed** the release process and CI to keep it current: a new `tests.test_api_limitations_doc` drift guard (added to the publish workflow) fails if the doc is stale, and `docs/process/release-process.md` now requires regenerating it whenever a `submit`-tagged entry changes. ## What's New in v2.57.1 Investigation outcome for community feature request #74 — no behavior change. - **Note** (issue #74) the DaVinci Resolve scripting API does not expose the Source/Auto Track Selector, so there is no way to choose the destination track when inserting Text+/titles/generators. Verified live on Resolve Studio 21.0.0: no get/set for the selector exists; the `Insert*IntoTimeline` family takes no `trackIndex` and always lands on V1; locking lower tracks makes the insert fail rather than redirect; and titles/generators can't be relocated afterward (no `MediaPoolItem`). Closed as won't-fix (API limitation). - **Documentation** recorded the limitation in the verified `api_truth` ledger (query at runtime with `resolve_control api_truth "track"`) and in `docs/reference/api-coverage.md`, with the supported alternative for media-backed clips (`MediaPool.AppendToTimeline` clipInfo `trackIndex`, exposed as `media_pool.append_to_timeline` `clip_infos`). Added a regression test. ## What's New in v2.57.0 Community feature requests #72 and #73. - **Added** OpenCode to the installer's supported MCP clients (issue #72). The installer now writes/merges `~/.config/opencode/opencode.json` using OpenCode's own schema (`type`/`enabled`, a combined `command` array, and an `environment` block), and `--manual` prints a ready-to-paste OpenCode snippet. - **Added** `fusion_comp(action="add_fusion_mask", ...)` (issue #73): a one-call Rectangle/Ellipse mask — adds the mask tool, sets its params (`corner_radius`, `width`, `height`, `center`/`center_x`/`center_y`, etc., all 0..1), and optionally wires it into a tool's mask input (`EffectMask` by default). Each input is applied independently so one unsupported parameter never aborts the rest. - **Added** `fusion_comp(action="set_text_plus" / "get_text_plus", ...)` (issue #73): read/write the text of a Fusion `Text+` tool or Fusion title template (e.g. a "Deep" title), auto-finding the `Text+` tool when `tool_name` is omitted. Complements `timeline(action="set_title_text")` for generator titles. - **Note** (issue #73) per-clip audio Stereo↔Mono conversion is not in Blackmagic's scripting API and was not added. The supported surface is already exposed: `timeline get_track_sub_type` (query channel format), `add_track` with `audioType` (create mono/stereo tracks), `convert_to_stereo` (timeline-wide), and `timeline_item get_source_audio_channel_mapping`. ## What's New in v2.56.1 Final reliability batch from the exhaustive audit (Wave B + P2/P3 selections). - **Fixed** (EX11) `audio_track_probe` reported `available: true` for track index 0 (and negatives); audio tracks are 1-indexed, so it now requires `1 <= index <= track_count`. - **Fixed** (EX10) `_find_timeline_item_by_id` no longer silently skips a whole track type when `GetTrackCount` errors — it logs the failure so a real API error isn't mistaken for "item not found". - **Fixed** (P3) the raw `timeline_item_color.set_cdl` now validates the ASC-CDL payload (shape/ranges) before `SetCDL`, matching its safe twin — malformed CDL returns a structured error instead of being silently rejected by Resolve. - **Fixed** (P2) `media_pool.delete_timelines` is read-back verified: it reports `verified` from the project's timeline count dropping, not the unreliable boolean. `import_folder` now validates its required `path`. ## What's New in v2.56.0 Destructive-action registry audit (EX-REG) — a systemic version of the EX2 bug. Many destructive actions were registered under the **wrong tool key**, so `is_destructive()` returned False and **version-on-mutate archiving / change logging silently never fired** for them. Examples: `create_timeline`, `auto_sync_audio`, `create_stereo_clip`, `append_to_timeline` were filed under `timeline` though `media_pool` dispatches them; `set_cdl`, `copy_grades`, `export_lut`, the version ops were under `timeline_item` though `timeline_item_color` dispatches them; the Fusion-comp and take actions used stale names (`add_fusion_comp`, `delete_take`) that matched no real handler. - **Fixed** rebuilt `DESTRUCTIVE_ACTIONS_BY_TOOL` so every action is keyed under the tool that actually dispatches it (stale names mapped to real ones: `*_fusion_comp` → `*_comp`, `*_take` → `add`/`delete`/`select`/`finalize`, `import_into` → `import_into_timeline`, `create_subtitles_from_audio` → `create_subtitles`). Inert entries whose tool isn't governed (media_pool_item `replace_clip`/`link_*`) were dropped. Catastrophic take/Fusion-comp deletes and the media-pool create/sync ops are now archived as intended. - **Added** the registry-drift guard now asserts *every* registry action is a real handler of its tool (broad check enabled), so this class can't regress. ## What's New in v2.55.2 Deep-QC P1 1b — required-param validation. Mutating/destructive actions that hard-indexed required params (`p["name"]`, `p["index"]`, `p["color"]`, …) now return a structured error instead of crashing with an unhandled `KeyError` (or, for `set_clip_enabled`/`set_current`, coercing the value). Guarded actions: - `timeline`: `set_current`, `set_name`, `set_start_timecode`, `add_track` - `timeline_item`: `set_property`, `set_clip_enabled` - `project_manager`: `create`, `load`, `import_project`, `export_project`, `archive`, `restore` - marker `delete_by_color` (clip / timeline / item — destructive) - `layout_presets`: `save`, `export`; `project_settings`: `set_name`, `set_setting` ## What's New in v2.55.1 Deep-QC P1 — settings/options whitelisting + DeleteProject reliability. - **Fixed** options/settings dicts passed to several Resolve APIs are now whitelisted to their documented keys, so a typo'd key is reported instead of silently dropped (`_filter_to_keys` → `ignored_options`/`ignored_settings`): `media_pool.import_timeline` (ImportTimelineFromFile), `timeline.import_into_timeline` (ImportIntoTimeline), raw `render.set_settings` (SetRenderSettings) and `render.quick_export`, and `set_voice_isolation_state` (track + item). - **Fixed** `ProjectManager.DeleteProject` is flaky — it silently returns False when the target is/was the current project. All callers (the safe and raw `project_manager.delete` actions and the granular `delete_project`) now route through `delete_project_safely` (switch-away + retry) and report `delete_detail`. Added an `api_truth` entry. - **Added** a destructive-registry drift guard (`tests/test_destructive_registry_drift.py`) that asserts token-gated actions map to real handlers and locks in the media-pool delete governance from v2.55.0. (It also surfaced a pre-existing registry mis-keying issue now tracked for a dedicated audit.) ## What's New in v2.55.0 Governance for catastrophic Media Pool deletes (exhaustive audit EX2/EX3). **Behavior change:** `media_pool` `delete_clips`, `delete_folders`, and `delete_timelines` now require a confirm token, the same two-step handshake `timeline.delete_track` already uses — the first call returns `status: "confirmation_required"` with a `confirm_token` and a preview (count + names); re-call with `params.confirm_token` to execute. Callers that disable gating via the `destructive.require_confirm_token=false` preference are unaffected. - **Fixed** the destructive-action registry listed granular function names (`delete_media_pool_clips`, `move_media_pool_folders`, …) that the compound `media_pool` tool never dispatches, so `is_destructive()` returned False and these catastrophic deletes silently skipped version-on-mutate archiving and change logging. The registry now uses the real compound action strings, so the deletes are archived/logged as intended. - **Added** confirm-token gating + previews to the three deletes (EX3). The registry fix also re-enables the existing media-pool change log for them. - Live-validated against DaVinci Resolve Studio 21.0.0 (non-destructively): the no-token call returns `confirmation_required` and deletes nothing. ## What's New in v2.54.5 Reliability + security hardening from the exhaustive reliability audit (Wave A). - **Security** `apply_spec` hooks no longer run with `shell=True`. A spec's hook command is now `shlex`-split and executed without a shell, so a hook string can't inject arbitrary shell (`; rm -rf …`, pipes, expansion). Hooks needing shell features must invoke an interpreter explicitly (e.g. `bash -c "…"`). - **Fixed** the confirm-token table (`_CONFIRM_TOKENS`) is now guarded by a lock. The control panel is threaded, so issue/consume/GC ran concurrently; validate- then-pop is now atomic and GC can't race a write. - **Fixed** negative item indices are rejected instead of silently returning the wrong item (Python reverse-indexing): `_get_item`, the audio item resolver, and the two timeline-matte helpers now require `0 <= index < len`. - **Fixed** history queries clamp `limit` to `[1, 1000]`. SQLite treats a negative `LIMIT` as "no limit", so a negative value could silently fetch the entire table (`get_brain_edit_history`, `list_runs`, `get_media_pool_change_history`). `timeline_versioning` version/limit/keep_n params are now validated (no unhandled `ValueError`; `rollback` rejects negative versions before archiving). `max_files` /`max_seconds` in the relink file search are clamped positive. - **Fixed** the server-reachable ffmpeg probes (render, audio, review) now pass `timeout=120` so a hung ffmpeg can't block the server indefinitely. (Deferred to a live-validated follow-up: confirm-token gating + archiving for catastrophic media-pool/take/fusion deletes, and temp-directory lifecycle cleanup.) ## What's New in v2.54.4 Persistence-safety hardening (generalizes issue #71 to the analysis state stores). A multi-agent audit found several state files whose **readers** swallow a `JSONDecodeError` and reset to an empty default — so a later read-modify-write writes back only the new field, silently wiping prior data. Atomic writes don't help, because the loss happens at *read* time. - **Fixed** read-modify-write paths now read strictly and **refuse to overwrite** a corrupt existing file (via a shared `ConfigParseError` + `_read_json_strict`), rather than clobbering it: - media-analysis **preferences** — 5 write paths (set-defaults, timed-marker default, sampling-mode default, AI governance, caps preset) - **update-state** — configure/clear update settings (3 paths), now also written atomically (temp + `os.replace`) - per-clip **corrections** (human edit history — the highest-value store) — update and revert paths - **Fixed** non-atomic writes that a crash mid-write could truncate: the bin summary markdown and Fusion `.setting` files now write to a temp file and `os.replace`. - **Fixed** a read-modify-write race on `analysis.json` under the threaded control panel: transcript regeneration is now serialized under the existing state lock, so a concurrent regen/batch write can't drop the other's updates. - Read-only callers keep their forgiving behavior (they fall back to defaults and never write). New tests in `tests/test_persistence_safety.py`. ## What's New in v2.54.3 Follow-up to the v2.54.2 config-merge fix (#71): the JSONC sanitizer's trailing-comma step was not string-aware. - **Fixed** `_strip_jsonc` removed trailing commas with a regex applied to the whole document, so a comma inside a string value followed by whitespace and a closing brace/bracket — e.g. `"greeting": "hello, } world"` — had the comma silently stripped *from inside the string* when merging a commented (JSONC) client config. The trailing-comma pass is now string-aware (mirroring the comment stripper), so string contents are never altered while real trailing commas are still removed. Added regression tests covering string values that contain `, }` / `, ]`. (Dropped the now-unused `re` import.) ## What's New in v2.54.2 A destructive-overwrite bug in the installer (issue #71): the MCP client setup step could wipe a user's entire editor settings file instead of merging into it. - **Fixed** `install.py` silently destroyed existing client config files whose contents weren't strict JSON. `read_json` swallowed `JSONDecodeError` and returned `{}`, so the subsequent "merge" wrote a file containing *only* the `davinci-resolve` server entry — wiping themes, terminal env vars, LSP settings, keybindings, everything else. Zed was the reported victim because its `settings.json` ships with `//` comments (JSONC), but the same latent risk existed for **every** supported client — VS Code and Continue also accept JSONC. The fix is centralized in the single read/merge path so all clients are covered: - `read_json` now best-effort strips JSONC `//` and `/* */` comments and trailing commas (string-aware, so comment markers inside string values are preserved), letting commented configs merge cleanly instead of being lost. - When a config file exists but still can't be parsed after that, the installer **refuses to overwrite it** and tells the user to add the entry manually — rather than silently replacing their settings. - **Added** regression tests covering JSONC merge, plain-JSON merge, refuse-to-overwrite on unparseable files, fresh-file creation, and string-aware comment stripping. ## What's New in v2.54.1 One more instance of the enum-keyed silent-failure class (issue #70), plus a guard so the next one can't ship unnoticed. - **Fixed** the raw `timeline.export` action passed `type`/`subtype` straight to `Timeline.Export`, which needs resolved `resolve.EXPORT_*` enum *values* — a JSON/MCP caller can't pass a live enum, so the action silently wrote nothing for every caller. It now resolves friendly format names (and `EXPORT_*` constant names) via the same `_timeline_export_spec` resolver that `export_timeline_checked` uses, and reports the resolved `export_type`/ `export_subtype`. - **Fixed** `export_timeline_checked` resolved enum constants against the module global `resolve` (which can be `None` and silently degrade the `EXPORT_*` args to strings); it now uses `get_resolve()`, matching the issue-#70 lesson. - **Added** an `api_truth` ↔ mitigation guard test: every `enum`-tagged catalog entry must declare a `mitigation` (the resolver/wrapper functions), each of which must exist in `src.server`. The next raw enum passthrough — a documented symbol with no real resolver, or a renamed/removed resolver — now fails CI. Added a `Timeline.Export` catalog entry and wired `mitigation` onto the `AutoSyncAudio`, `CreateSubtitlesFromAudio`, and CloudProject entries. ## What's New in v2.54.0 Hardens the rest of the enum-keyed settings APIs against the same silent-failure class fixed for `AutoSyncAudio` in v2.53.0 (issue #70). Several Resolve methods key their settings dict by `resolve.` enum attributes and silently reject the whole call when handed plain string keys — returning `False`/`None` with nothing applied and no error. - **Fixed** `CreateSubtitlesFromAudio` (both `timeline_ai.create_subtitles` and `timeline.subtitle_generation_probe`) now resolves human-readable `autoCaptionSettings` — `language`, `preset`, `line_break`, `chars_per_line`, `gap` — into live `SUBTITLE_*`/`AUTO_CAPTION_*` enum keys/values. Unknown keys and unresolvable values are dropped and reported in `ignored_settings` instead of poisoning the call, and generation is read-back verified against the timeline's subtitle track count (the boolean return is unreliable). - **Fixed** the `ProjectManager` CloudProject family (`create`/`load`/ `import_project`/`restore`) resolves `{cloudSettings}` into live `CLOUD_SETTING_*`/`CLOUD_SYNC_*` enums (`project_name`, `media_path`, `is_collab`, `sync_mode`, `is_camera_access`), dropping unknown keys into `ignored_settings`. - **Changed** the string→enum resolution is now a shared `_resolve_enum_settings` primitive driven by per-field specs, so the next enum-keyed API gets the same treatment without re-implementing it. - **Added** `api_truth` entries for `Timeline.CreateSubtitlesFromAudio` and the CloudProject family, documenting the silent-rejection + unreliable-return behavior alongside the existing `AutoSyncAudio` entry. ## What's New in v2.53.0 Two improvements to audio sync reliability and inventory control. `safe_auto_sync_audio` / `media_pool.auto_sync_audio` no longer fail silently on human-readable settings (issue #70). The previous normalizer recognized `syncBy`/`mode` but not `method`, and it forwarded *every* unrecognized key (`group_id`, `primary_clip_id`, …) straight into `MediaPool.AutoSyncAudio` — which silently rejects the whole call when it sees a key it doesn't understand, returning `False` with nothing linked and no error. - **Fixed** `method` (matching the tool's own parameter naming) is now accepted as an alias for the sync mode alongside `syncBy`/`sync_by`/`mode`/`syncMode`. - **Fixed** unrecognized settings keys are dropped instead of forwarded, so a stray `group_id`/`primary_clip_id` no longer poisons the call. Dropped keys are reported back in a new `ignored_settings` field on the response, so a rejection is no longer invisible. - **Fixed** the raw `media_pool.auto_sync_audio` action now routes settings through the same live `AUDIO_SYNC_*` enum resolution as the safe wrapper (previously it passed strings straight through). The Media Pool inventory walk is now configurable: - **Added** `media_analysis.inventory_exclude_bins` — a comma-separated list of folder names to skip entirely during the inventory walk (recursively). Empty by default, so every folder is indexed unless you opt out. - **Added** `media_analysis.inventory_limit` — the maximum clips to index per walk, configurable from the control panel and `setup`. The hard ceiling is raised from 2000 to 10000. - Adapted from PR #69 by @rgxdev; the default was changed to exclude nothing (the PR defaulted to excluding an `assets` bin, which would have silently stopped indexing existing `assets` folders on upgrade). ## What's New in v2.52.1 Analysis reuse no longer blocks on missing capabilities when every clip is satisfied by an existing report (issue #68). `build_plan` records `capability_gaps` from the *requested* options before the per-clip reuse decision runs; when a fully-reused plan only re-keys and imports existing reports into the current root, no fresh transcription/vision/ffprobe happens, so the missing-capability gate must not fire. - **Fixed** the missing-capability gate is now evaluated against the clips that still need fresh analysis, not the requested-options gaps. A clip is exempt only when it both skips execution and has an existing report path; any clip needing fresh work still enforces the gate. - **Fixed** extended the exemption to the entry points that short-circuit before `execute_plan_async` and were still blocking fully-reused runs: the `media_analysis` analyze action, metadata-publish analysis, and batch-job creation. The batch CLI `plan` preview no longer prints "Missing tools" for a fully-reusable plan. - **Changed** the reuse/capability logic is now a shared `plan_requires_capabilities()` / `executing_clips()` helper, replacing the duplicated inline comprehensions so every gate stays consistent. - Includes PR #68 by @diesdaas, which fixed the inner `execute_plan_async` gate and isolated the marker-param and host-vision tests from unrelated capability/destructive-hook coupling. ## What's New in v2.52.0 `edit_engine` tighten now carries audio. Previously `execute_tighten` assembled a video-only variant — a speech-driven dead-air cut came out silent, with nothing in the preview or readback to warn you (issue #67). - **Fixed** `plan_tighten` mirrors every kept video range onto its linked audio track(s) with identical source frames, so the assembled variant stays frame-locked and audible. Audio targets the item's detected linked audio tracks (same `GetLinkedItems` matching `execute_swap` uses), falling back to audio track 1 where a single linked A/V clip's audio lives. - **Added** `include_audio` parameter to `plan_tighten` (default `true`). Pass `include_audio=false` for the prior video-only assembly. - **Added** an `audio_accounting` block to the `execute_tighten` confirm preview and readback (planned vs. actual audio/video item counts), so a silent variant can no longer ship unnoticed. Old video-only plans re-executed against this build still work and are now loudly flagged as silent. ## What's New in v2.51.0 CLAP audio embeddings — the final phase of the post-program improvements. Detection-based like every other backend (never auto-installed); local compute, so nothing touches the caps ledger. - **Added** audio embedding backend detection: CLAP via `transformers` (laion/clap-htsat-unfused, preferred) or the `laion_clap` package, plus torch + ffmpeg. `capabilities` gains an `audio` block with install guidance and a `clap_audio` Tools-page entry. - **Added** `build_embeddings(kinds=["audio"])`: one CLAP window per shot (center-cropped to ~10 s, piped from the source media as raw PCM — read-only on source media, no temp files) plus a clip-level mean vector, stored as `embedding_kind="audio"` rows. Idempotent via content hashes; offline media is reported in `skipped_missing_media`; a missing backend is a graceful skip with install guidance. - **Added** `find_similar(kind="audio")`: shot/clip queries over the audio vectors, and free-text queries ("engine revving") via the CLAP text encoder. ## What's New in v2.50.0 The last JSON-fed readers now source from the DB-canonical analysis store (consistency/perf hygiene — the JSON export is lockstep with the DB, so this is shape-preserving by construction). - **Changed** `summarize_reports` aggregates from the DB (blob + human overlay) when every report dir on disk is covered by an ingested clip row; pre-v9 roots and MIXED roots (some clips not ingested) fall back WHOLESALE to the JSON walk — a partial DB view would silently under-report. The summary gains a `"source": "db"|"json"` key for observability; the F1 provenance map (source_reports / missing_reports) is unchanged. - **Changed** `build_analysis_index` sources local reports from the DB instead of re-parsing every `analysis.json`; job-linked EXTERNAL report paths (their rows live under another project's DB) and pre-v9 dirs keep the JSON read. The FTS schema and the query surface are identical; the result gains `report_sources` counts. - **Added** DB-vs-JSON parity tests (semantic equality with normalized ordering) plus wholesale-fallback regressions for mixed and pre-v9 roots; live-validated on the sample analysis root (summary, index counts, and FTS query results identical on both paths). ## What's New in v2.49.0 Cross-shot relationships (spec §4 — pattern recognition only): the shot page's Relationships group finally fills, and the edit engine can prefer vision-confirmed alternates. - **Added** schema v12 `shot_relationships` (same_setup_as / alt_take_of symmetric, continues_from directional — the source shot continues from the target) with supersede semantics (current rows have `superseded_at IS NULL`). - **Added** `media_analysis` actions `detect_shot_relationships` / `commit_shot_relationships` / `list_shot_relationships`: pairwise cosine over the per-shot visual vectors (transcript continuity as a second signal for continues_from) → a deferred confirmation payload with a representative frame PAIR per candidate (caps pre-checked; candidates live only in the detection-state stash until committed, so re-detect never leaves ghosts) → vision-confirmed rows. Representative frames use the shot's middle sample (first/last frames often catch fades). - **Added** the shot page's Relationships group now renders from the DB (`continues_from` shows on the continuing shot; cross-clip targets are clip-qualified). - **Changed** `plan_swap` prefers confirmed `alt_take_of` alternates over raw cosine similarity — confirmed takes sort first (and are unioned in even when the cosine search missed them); each alternate's rationale states which basis ranked it. ## What's New in v2.48.1 Bug fix surfaced by the first real-cut tighten pilot. - **Fixed** cross-root analysis reuse never landed in the current project's DB: when the registry matched a reusable report from another project's analysis root, `execute_plan_async` reported success but wrote no DB rows and no local export — so `media_ref` lookups against the current media pool (edit-engine planners, panel readers) found nothing. The reuse path now re-keys the report to the current project's clip identity, ingests it into the current root's DB, and writes a lockstep `analysis.json` export (provenance kept in `reused_from`). ## What's New in v2.48.0 Edit-engine hardening: trustworthy execute readback ahead of the first real-cut pilot. Live-validated end-to-end on a disposable synthetic-media project (24/24 checks). - **Added** `timeline_versioning(action="diff_timelines", params={from_timeline, to_timeline})`: structural diff (added/removed/moved/trimmed + summary) between two LIVE timelines by name — read-only, no archived snapshots needed. Built for edit-engine variants, which are new-name timelines with no shared version chain. The item walk and the snapshot comparison were factored out of the version-snapshot path (`capture_timeline_clip_usage` / `compare_usage_snapshots`) and reused. - **Fixed** `execute_swap` audio accounting: the lift was video-only while the replacement appended linked video+audio, so item counts drifted on every swap. The lift is now scoped to the target's video track plus its linked audio tracks (`GetLinkedItems`, with a media-id track-scan fallback; items with no linked audio and audio-only timelines are handled gracefully), and readback reports per-track-type `track_counts` before/after plus an `audio_accounting` block. - **Added** `execute_tighten` readback now includes `structural_diff` (source vs variant); `execute_selects` readback includes a `usage_summary` (per-track-type item counts — a diff against a source timeline is meaningless for a fresh assembly). - **Changed** the live edit-engine validation harness asserts the tighten structural diff, `diff_timelines` agreement, and swap track-count symmetry (24 checks, up from 20). ## What's New in v2.47.0 Edit-engine plan browser in the control panel (Media → Edit Plans) — the panel UX pass for the v2.45.0 edit engine. Chat-first: the panel surfaces plans and evidence; execution stays in chat behind the confirm-token gate. - **Added** a plan browser at `#analysis/review/plans`: every saved `edit_engine` plan with kind, summary, save time, and an `executed` chip; fingerprint-corrupt plans surface as warning rows instead of being hidden. - **Added** plan detail views per kind: selects decisions render with shot thumbnails, rank, duration, rationale, and a deep link to the shot page; tighten plans list each dead-air lift with its transcript-gap evidence and skipped items; swap plans show the current item plus numbered alternates with similarity scores. Executed plans show their execution readback. - **Added** a copyable per-kind execute chat prompt on each plan (the panel never executes; swaps include an `alternate_index` placeholder). - **Added** `/api/edit_plans` + `/api/edit_plans/` panel endpoints (DB/file only — no Resolve round-trips; decisions are enriched server-side with `resolve_clip_id` and a `thumb_frame_index` for the existing frames route). - **Changed** `edit_engine.list_plans` gained `include_corrupt` (default off; the MCP action shape is unchanged). ## What's New in v2.46.1 Test and hygiene hardening; no public tool surface changes. - **Fixed** the three `InventoryCacheReuseTests` failures that appeared whenever a live Resolve instance was running: the reuse/build-path tests now stub the read-only Resolve probe, so the suite is green with Resolve open or closed. - **Added** `src/utils/project_cleanup.delete_project_safely`: a retrying delete helper for disposable Resolve projects (switch away from the target, retry `DeleteProject` once after a pause, report the leftover by name on persistent failure). The live edit-engine validation harness now uses it during cleanup, so disposable pilot projects stop lingering in the library. ## What's New in v2.46.0 Community PR bundle: five contributed fixes and features (#62–#66), live-validated on Resolve Studio 21. - **Fixed** timeline marker frames are now correctly relative to the timeline start (#66): timecode params and the playhead default rebase by `GetStartFrame()`, so markers on hour-start timelines land where the UI shows them instead of an hour past the end. Raw `frame` params pass through unchanged (documented as relative). Contact sheets and marker thumbnail review rebase the other way with a legacy-absolute guard. - **Fixed** project lint no longer flags audio-only timelines as empty (#62); live lint state now reports per-type `video/audio/subtitle_item_count`. - **Added** `media_pool.check_proxy_media_compatibility` (#63): ffprobe-vs-source signature diagnostics (resolution/fps/frames/sample rate, expected codec/profile). Same-aspect downscales count as compatible — half-res proxies are the normal workflow. - **Added** readback verification envelopes (`verified_operation`) around `media_pool.link_proxy_checked` (#63) and `media_pool.append_to_timeline` (#64): preflight, execution, post-state readback, verification status, and a journal event. `link_proxy_checked` gains `check_compatibility` / `require_compatible` guards that refuse incompatible proxies before linking. - **Added** `bins` to declarative project specs (#65): missing media-pool bin paths plan as `ensure` actions and are created idempotently; existing bins are noops. Bin paths normalize to the `Master/` prefix so unprefixed spec bins converge instead of reporting perpetual drift. ## What's New in v2.45.0 The edit engine — Phase E, the final phase of the analysis + edit-engine program. Three evidence-driven loops on one shared skeleton: evidence query → dry-run plan with per-decision rationale → confirm token → versioned timeline ops → metric readback → brain_edits rows. - **Added** a new `edit_engine` MCP tool (compound tool count: 34): - `plan_selects` / `execute_selects` — ranks shots by deep-tier `editorial.select_potential` and best moments (clip-level fallback for standard-analyzed clips), story-spine order, duration budget; execution builds a NEW selects timeline from per-shot source ranges. Additive. - `plan_tighten` / `execute_tighten` — dead-air lifts from transcript-gap evidence per timeline item (no transcript → reported in `skipped`, never silently trimmed); execution assembles a tightened VARIANT timeline from keep ranges (true partial trims via the range-copy kernel) — the original timeline is never mutated. - `plan_swap` / `execute_swap` — alternates for a timeline item via the visual-similarity index, filtered to shots that can fill the slot exactly; execution replaces the item in place (lift + positioned append) on the version-archived timeline. - `list_plans` / `get_plan` — plans persist under `memory/edit_plans/` with content fingerprints; a stale or tampered plan refuses to execute. - **Added** `src/utils/edit_engine.py` (DB-only planning/evidence layer) and `tests/live_edit_engine_validation.py` (disposable-project live harness). execute_* actions are confirm-token gated and registered with the version-on-mutate hook (archive + brain_edits come from the same machinery as every other destructive op). - **Fixed** frame→shot mapping in the analysis store: frames now fall back to time-containment when a report's shots don't record `frame_indices_used` (commit paths that omit it previously produced no shot-level visual vectors). - **Validation**: full offline suite (1118 tests; 13 new). Live pilot on a disposable synthetic-media Resolve project (ffmpeg + spoken audio): 20/20 checks — selects timeline assembled (2 decisions), tighten variant removed exactly the 15.2s of transcript dead air while keeping the spoken 4.8s (original untouched), swap replaced the item with a 0.92 cosine alternate, brain_edits rationale rows present for all three loops, timeline versions archived. ## What's New in v2.44.0 Cross-clip entities + bin briefing v2 — Phase D of the analysis + edit-engine program. Recurring people/places/props found by clustering the visual embeddings, confirmed with one vision call per cluster. - **Added** schema v11 (`entities` + `entity_appearances`) and `src/utils/entities.py`: union-find clustering over the v10 CLIP frame vectors (cosine threshold, no new deps), representative-frame selection, ghost pruning across re-runs (labeled entities persist), and a detection-state stash so `entity_index` always resolves against the exact ordering the payload was issued with. - **Added** `media_analysis` actions: `detect_entities` (clusters + deferred one-frame-per-cluster confirmation payload, caps pre-checked), `commit_entities` (kind/label/description with conservative-label rules; `merge_with` collapses duplicate clusters), `list_entities`, `prepare_bin_briefing` (entities + per-clip summaries, text-only), and `commit_bin_summary` (host-synthesized briefing written above the v2.0 aggregate in `memory/bin_summary.md`). - **Added** a "Recurring across this bin" card on the panel's Review page (`/api/entities`), shown once labeled entities exist. - **Validation**: full offline suite (1105 tests; 10 new). Live on the real sample root: 3 clusters detected from 16 CLIP vectors; host-chat confirmation labeled the shattered-windshield POV and the white rental sedan and merged the sedan's two clusters; bin briefing synthesized and committed; panel card verified and screenshots regenerated. ## What's New in v2.43.0 Embeddings + similarity search — Phase C of the analysis + edit-engine program. "Find clips/shots like this," locally, with no vendor token cost. - **Added** `src/utils/embeddings.py` and schema v10 (`embeddings` table: one float32 vector per entity/kind/model, with content hashes so re-runs only re-embed what changed). Brute-force cosine — numpy when present. - **Added** `media_analysis` actions `build_embeddings` (idempotent; clip summaries, shot descriptions + deep field groups, transcript segments, sampled frames with per-shot mean vectors) and `find_similar` (query by free text, clip, or shot; `kind="text"|"visual"`; free-text visual queries go through the CLIP text encoder). - **Added** backend detection, never installation (the whisper pattern): text = ollama `nomic-embed-text` (serving probe) or sentence-transformers; visual = open_clip ViT-B-32. Capabilities and the Diagnostics → Tools page list availability with install guidance. - **Added** a `Semantic` toggle on the panel's Review search (shown only when a text backend is detected) backed by `/api/search/semantic`, which returns rows in the existing search-card shape. - **Validation**: full offline suite (1095 tests; 14 new, backends mocked). Live on the 2026-05-17 sample root: 54 text vectors in 1.2s via ollama with correct top hits for three editorial queries; 27 CLIP vectors with "cracked broken windshield glass" ranking the shattered-windshield frame first; panel endpoint verified and screenshots regenerated. ## What's New in v2.42.0 Deep shot-level vision tier — Phase B of the analysis + edit-engine program. Opt-in, estimate-first per-shot field filling for the Visual / Content / Production / Editorial / Cuttability groups the shot pages already render. - **Added** `src/utils/deep_vision.py` and three `media_analysis` actions: `deepen` (estimate → confirm_token → deferred host-vision payload per clip/shot), `commit_shot_vision` (writes `vision_deep_v1` provenance rows, updates the canonical blob, re-exports analysis.json in lockstep), and `vision_pending_sweep` (lists clips stuck in `pending_host_analysis`; `reoffer=true` returns the stored payload, `expire=true` stamps them). - **Added** deep depth to the analyze flow: `depth="deep"` extends the deferred payload with the per-shot schema and requires `confirm_deep=true` after a token-cost estimate. Caps pre-call refusal applies on both paths. - **Added** panel affordances: `Deepen analysis` (clip view) and `Deepen this shot` (shot view) copy ready-made chat prompts, per the chat-first UX. Shots with no sampled frames on disk get 1–2 frames re-extracted via ffmpeg, downscaled per caps (source media stays read-only). - **Fixed** a provenance bug in the analysis store: a source re-deriving an unchanged value no longer re-attributes the row (a deep pass would otherwise claim every untouched field as `vision_deep_v1`). - **Validation**: full offline suite (1081 tests; 15 new), and a real end-to-end deep pass on the 2026-05-17 sample clip — estimate → confirm → frames read by the host chat → commit → rows/blob/export parity → fields visible in the panel shot view. Control-panel guide screenshots regenerated from the live panel. ## What's New in v2.41.0 DB-canonical clip analysis (C1) — Phase A of the analysis + edit-engine program. The per-project SQLite DB is now the source of truth for clip analysis; `analysis.json` becomes a derived export written in lockstep. - **Added** schema v9 to the per-project timeline-brain DB: `clips`, `clip_aliases`, `analysis_reports` (canonical full payload), `shots`, `subjective_fields` + `field_changelog` (per-field provenance), `transcript_segments`, `frames`, and `qc_observations`. - **Added** `src/utils/analysis_store.py`: transactional ingest, export with human-correction overlay (human rows always win and survive re-analysis), alias-based clip lookup, shot ids stable under one-second boundary jitter, and a round-trip guard verified against a real sample analysis root. - **Added** `media_analysis` actions `db_status` (schema version + row counts) and `db_ingest` (one-shot migration of existing JSON reports and `corrections.json` sidecars into the DB). - **Changed** the analysis write path: `execute_plan` and `commit_vision` write DB rows first, then export the JSON. Panel clip/shot endpoints read DB-first with JSON fallback for pre-v9 reports and job-linked report dirs. - **Changed** `update_clip_field` / `update_shot_field` / `revert_field` to mirror corrections into the DB as row-level provenance (the `corrections.json` sidecar remains for compatibility). - **Fixed** eight V2 actions that were unreachable from MCP dispatch since v2.24.0 (`get_panel_state`, `set_panel_state`, `session_start_context`, `update_shot_field`, `update_clip_field`, `get_field_history`, `revert_field`, `list_corrections`): they were checked inside the project-root dispatch block but missing from its membership set. The control panel proxied to the helpers directly, which masked it. - **Fixed** the action-list drift guard to inspect async tool functions (media_analysis had drifted unchecked) and to fail on actions that are unreachable inside membership blocks — the exact class above. Four reachable-but-unadvertised actions (`coverage_report`, `get_resolve_ai_usage`, `get_ai_governance`, `set_ai_governance`) are now listed in the unknown-action error. - **Validation**: full offline suite (1066 tests; 12 new), round-trip guard on the real 2026-05-17 sample root, and a live headless pipeline run on synthetic media verifying rows-then-export parity, row-level corrections, and DB-first panel reads. ## What's New in v2.40.0 Control panel UX overhaul + docs refresh, from a full live audit of every panel view, with drift guards so neither can silently go stale again. - **Added** a governance mode toggle (Advisory / Enforce) to the AI Console, with corrected copy (the old text predated v2.39.0 enforce mode), and a Recent-runs list on the AI-ops ledger showing each run's actor. - **Added** chat-first onboarding: empty Overview, Review, and Inventory states show plain-language guidance with a copyable suggested prompt instead of zero-walls and MCP action names. - **Added** History as a first-class Media menu item, deep-linkable at `#analysis/review/history`; documented the full hash deep-link scheme. - **Changed** the top-level "Analysis" menu to "Media" (it collided with the Preferences page of the same name); "Analyze" is now "Inventory". Full vocabulary pass: humanized readiness chips and frame-sampling labels, no internal codenames, file names, or absolute paths in UI copy. - **Fixed** the README's linked screenshot rendering broken in the Docs reader: badge parsing no longer claims local linked images, and a new `/api/doc_asset/` route serves repo doc images (path-constrained). - **Fixed** poll hygiene: timers pause while the tab is hidden, panel-state polling backs off when unfocused, and unchanged inventory polls return a tiny 200 instead of a 304 that Chrome logged as an aborted request. - **Docs**: `docs/guides/control-panel.md` fully rewritten for the current IA with all screenshots regenerated from the live panel (`scripts/regen_panel_screenshots.py`). A new drift-guard test fails the suite — and the publish workflow, which now runs all three static guards on every tag — when the guide drifts from the panel's navigation or screenshots. ## What's New in v2.39.0 Governance enforce mode and actor identity — the staged Phase 3 of the Resolve 21 AI-ops work. - **Added** governance `mode` for the media-creating AI ops (motion deblur, speech generation): `advisory` (default, unchanged — confirm-preview warnings only) or `enforce`, where an over-tier run is blocked with `GOVERNANCE_BLOCKED` before token issuance, naming the exceeded dimensions. Escape hatches: raise the tier, relax the mode, or pass `override_governance=true` to consciously exceed the tier once. `set_ai_governance` accepts `mode` (preset now optional); `get_ai_governance` reports it. - **Added** instance-level actor identity (per the recorded concurrency design): each entry point declares itself — `stdio`, `network-sse`, `network-http`, `control-panel`, `batch-cli` — and AI-ops ledger rows, brain edits, and timeline versions now carry `actor` (`:`) alongside `initiator`. Schema v8 (additive columns); migration verified against a copy of a real project DB with all rows preserved. ## What's New in v2.38.0 Busy gate for long DaVinci Resolve operations — the first piece of the concurrency design for the stdio + networked two-instance setup. - **Added** cross-process registration for long synchronous Resolve calls (timeline export/import, scene-cut detection, subtitle generation, Dolby Vision analysis, folder/clip audio transcription). A tool call that arrives while one is running now waits up to 5 seconds and then returns a structured `RESOLVE_BUSY` error (new `busy` category, retryable, with `state.busy_with` and `state.age_seconds`) instead of hanging silently inside the scripting bridge. Stale registrations from crashed operations are ignored automatically; an operation never gates its own thread. - Design decisions recorded: single-editor/multi-client is the supported concurrency target; confirm tokens stay per-instance; actor identity is deferred to the governance phase. ## What's New in v2.37.3 Deep-audit fixes, rounds two and three: agent-facing action discovery, crash-safe user-state persistence, and resource hygiene. - **Fixed** three tools' unknown-action error lists drifting from their real dispatch: `timeline` omitted `clip_where` and `action_help`; `timeline_item_color` and `graph` omitted `action_help`. Agents recovering from a typo now see the full action set. A static AST test keeps every tool's advertised list in both-way sync with its dispatch (and verifies docstring-advertised actions are real). - **Fixed** user-state files being vulnerable to truncation by a crash mid-write. Affected files all reset to `{}` on corruption, so the next save would silently wipe remaining user data. Writers now use atomic temp-file + `os.replace`: `media-analysis-preferences.json` (all analysis/caps/governance/update defaults — including the `set_resolution_tier` and `set_caps_preset` paths, now routed through the shared writer), `update-check.json`, the dashboard's `analysis.json` transcription patch, and `transcript-corrections.json`. - **Fixed** `_safe_project_delete` discarding `SaveProject()`'s result when closing the current project before deletion; a failed save now surfaces as a warning in the response. - **Fixed** a file-descriptor leak: the parent kept its copy of the control panel's log handle open after spawning the detached child. - Audit classes verified clean: bare excepts, mutable default arguments, `asyncio.run` inside running loops, subprocess timeouts, docstring phantom actions, silent-success swallows in metadata/marker/archive write paths. ## What's New in v2.37.2 Static-audit fixes — four undefined-name references that silently fell back to defaults instead of erroring (the same bug class as the v2.37.0 confirm-token fix), plus a regression guard. - **Fixed** the `status://mcp_version` resource reporting update channel `"stable"` unconditionally; it now calls the real `get_update_channel()`, so beta/dev channel installs report correctly. - **Fixed** the `versioning_auto_run_idle_timeout_seconds` preference being silently ignored (auto-run idle timeout was always 90s) due to a misspelled preference-reader name in the destructive hook. - **Fixed** resolve-state snapshot tokens always falling back to a timestamp because `short_hash` was never imported; tokens are now content-stable. - **Fixed** the timeline-kernel live probe's MCP-stub fallback crashing with a `NameError` (missing `types` import) exactly when the mcp library is absent — the only case the fallback exists for. - **Added** a static test that runs pyflakes over `src/` and fails on any undefined name, so this bug class cannot reappear unnoticed. ## What's New in v2.37.1 Test-suite hygiene — no server behavior changed. - **Fixed** the legacy live-harness scripts (`test_all_tools`, `test_phase2`–`5`) exiting at import when Resolve is unavailable, which crashed pytest collection and surfaced as five loader errors under unittest discovery. They now skip cleanly under both runners and keep the hard-exit behavior when run as standalone scripts. (Adapted from a contribution by @diesdaas.) - **Fixed** pytest mis-collecting `test_resolve20_api.py`'s internal `test()` helper (renamed to `run_live_check()`), and made the batch-CLI synthetic-job test independent of which transcription backends the host has installed. - **CI**: the npm publish workflow no longer reports failure when the registry accepted the publish but npm's retried request hit a consumed OIDC token; it now verifies the published tarball shasum before failing. Runner actions bumped to their Node 24 majors. ## What's New in v2.37.0 Render format-id fix, offline-media diagnosis, and a setup doctor. - **Fixed** render helpers passing the display name from `GetRenderFormats()` (e.g. `QuickTime`) into `GetRenderCodecs`, `GetRenderResolutions`, and `SetCurrentRenderFormatAndCodec`, which expect the format id (e.g. `mov`). `GetRenderCodecs("QuickTime")` returned empty, so `probe_render_matrix` reported no QuickTime codecs and `prepare_render_job` could not target ProRes (e.g. `ProRes422LT` proxy renders). Display names and format ids are now both accepted as input and normalized to the id for Resolve API calls; `probe_render_matrix` rows include `format_id`. Closes #59. - **Fixed** the destructive confirm-token gate referencing a stale function name, which made it silently ignore the `destructive.require_confirm_token` preference and always fall back to the default. - **Added** a `diagnosis` block to `timeline.detect_missing_media`: deduplicated missing Media Pool items, volume/folder mounted checks, a primary cause (`volume_not_mounted` / `folder_not_found` / `files_missing_or_renamed`), and a recommended next step. Optional `sanitized`/`sanitize_paths` redacts raw media paths. - **Added** bounds to `timeline.build_relink_plan`: skips the broad scan by default when a source volume (e.g. a camera card) is not mounted, dedupes missing basenames, and caps the search with `max_depth`, `max_seconds` (default 20s), and `max_files_scanned` (default 50k), reporting per-candidate scan stats. - **Fixed** `media_analysis` accepting `vision: true/false` boolean shorthand (now normalized to the full options dict) and `timeline_markers.get_thumbnail` returning a structured error instead of raw `None` when no thumbnail is available. - **Added** `scripts/doctor.py`, a read-only setup diagnostic that checks the checkout, Python, Resolve app/scripting paths, and MCP client configs, and probes the scripting bridge end to end with OK/WARN/FAIL output (`--json` supported). ## What's New in v2.36.1 Bug fix — restore the `fusion_comp` MCP tool. - **Fixed** a regression from `32be0ec` (v2.33.0) that left `fusion_comp` unregistered: a new `_parse_pos` helper was inserted between the `@mcp.tool()` decorator and `def fusion_comp`, so the decorator landed on the private helper instead. As a result `_parse_pos` was exposed as a tool while **all** `fusion_comp` node-graph operations (`add_tool`, `connect`, `add_keyframe`, `get_keyframes`, `copy_tool`, `set_position`, …) were missing from the tool list. The decorator is restored to `fusion_comp` and `_parse_pos` is once again a plain internal helper. Live-validated on DaVinci Resolve Studio 21. ## What's New in v2.36.0 Optional networked transport — run the MCP server over the network, safely, with control-panel management. Local stdio remains the default and is unchanged. - **Added** `--transport stdio|sse|streamable-http` (default `stdio`). The networked modes bind to **loopback (127.0.0.1) by default** and **require a bearer token** on every request (from `$DAVINCI_MCP_TOKEN`, or generated + logged at startup). A non-loopback bind logs a loud security warning. stdio is untouched; you can run a local stdio instance and a networked instance against the same Resolve at once. - **Added** control-panel management (Setup → MCP): a Transport card showing the live mode / URL / token / loopback status, with Start/Stop buttons (loopback-only). Backed by `/api/mcp/transport/{start,stop}` and a transport field on `/api/mcp/status`. - The page-switch lock (v2.34.1) already serializes concurrent page switches across the local and networked instances. ## What's New in v2.35.2 Verification observability and a validator consolidation. - **Added** `resolve_control(action="verification_stats")` returns a process-level tally of readback-verification outcomes (verified / contradicted / unverified) since server start. A rising `contradicted` count means the Resolve API reported success but a readback disagreed. No connection required. - **Changed** `open_page` now validates its `page` argument through the declarative contract layer (`contracts.validate`) instead of a hand-written enum check — behavior unchanged; part of folding scattered validation into one place. ## What's New in v2.35.1 - **Added** `media_pool_item(action="extract_frames", clip_id, timestamps, output_dir?)` extracts still JPEGs from a clip's source media at the given timestamps (seconds) via ffmpeg. Source-safe: it reads the source and writes only to a scratch output directory — it never modifies, transcodes, or proxies the source. (Closes a read/write-symmetry gap: the analysis sampler existed internally but had no standalone frame-extraction tool.) ## What's New in v2.35.0 The Cut-IR executor — transcript-driven editing now closes the loop onto the timeline. - **Added** `timeline(action="apply_cuts", cuts, dry_run?, confirm_token?)` applies a CutList (from `propose_cuts`) to the timeline as lift / ripple deletes. It is **DRY-RUN by default**; applying is destructive and fully governed: confirm-token gated, and a timeline version is archived first (so it is reversible), through the existing destructive hook. Cuts apply latest-first so ripple deletes do not invalidate earlier spans. Live-validated end-to-end (propose -> token -> apply -> version archived). ## What's New in v2.34.1 Page-switch serialization — the concurrency primitive for safe multi-agent use. - **Added** `src/utils/page_lock.py` — Resolve has a single globally-active page, so two agents that flip pages concurrently corrupt each other. `page_lock()` serializes page switches: a reentrant intra-process lock plus a best-effort inter-process advisory file lock around the outermost section. The `open_page` action now routes through it. This must be in place before any concurrent-agent feature ships. - Networked transport, sandboxed scripting, and capability/role scoping (the rest of the safe remote/multi-user design) are security-critical and remain a separate, sign-off-gated phase — they are intentionally not shipped here. ## What's New in v2.34.0 First phase of transcript-driven editing: a Cut intermediate representation and a mechanical cut proposer. - **Added** `src/utils/cut_ir.py` — the Cut-IR: a typed representation of an editorial cut ({kind, span, action, confidence, rationale, evidence}) plus a deterministic Pass-1 detector that flags filler words, long pauses, and repeated lines from a timestamped transcript. No LLM. - **Added** `timeline(action="propose_cuts", cues?, long_pause_frames?)` — a DRY-RUN that runs Pass-1 over the timeline's subtitle transcript (or provided cues) and returns a CutList. It proposes only; it applies nothing. The semantic Pass-2 and the governed timeline executor are subsequent phases. ## What's New in v2.33.8 Bridge-call performance instrumentation. - **Added** `src/utils/bridge_metrics.py` — a counting proxy that wraps a Resolve handle and tallies attribute accesses and method calls (each a COM/socket round-trip), so the real bridge cost of an operation is measured rather than guessed. - **Added** `scripts/measure_bridge_cost.py` — runs a representative media-pool traversal through the proxy and reports round-trips per clip. A minimal name+type walk measured ~6.7 round-trips per clip, confirming round-trips scale linearly with traversal size. A property cache remains gated on profiling *repeated*-read patterns in real workflows (don't cache blind). ## What's New in v2.33.7 Read/write symmetry audit and a gap it surfaced. - **Added** `scripts/audit_readwrite_symmetry.py` + generated `docs/reference/readwrite-symmetry.md` — scans every tool's action surface and reports `set_`/`add_`/`create_` writes that lack a read counterpart, so write-without-read gaps surface before users hit them. A repeatable feature-discovery method. - **Added** `fusion_comp(action="get_frame_range")` — reads the comp's render frame range, the read counterpart to `set_frame_range` (a gap the audit found). ## What's New in v2.33.6 Internal consolidation: a declarative parameter-contract validator and centralized subprocess hygiene. - **Added** `src/utils/contracts.py` `validate(params, rules, invariants)` — one validator for required/type/enum/min/max/non-empty/parent-dir-exists plus custom invariants, returning consistent agent-friendly errors with coercion + defaults applied. Replaces scattered, hand-written validation. - **Changed** `export_frame_as_still` and `set_mark_in_out` (clip + timeline) now validate through contracts. Behavior is preserved (same rejections); `mark_in`/ `mark_out` are now coerced to int. - **Added** `src/utils/proc.py` `safe_run`/`safe_popen` — subprocess wrappers that default `stdin` to DEVNULL so a child can't consume the MCP stdio protocol stream. Inline Python execution now routes through `safe_run`. ## What's New in v2.33.5 A queryable ledger of verified Resolve API behavior. - **Added** `resolve_control(action="api_truth", query?)` returns behaviorally-verified facts about quirky or unreliable Resolve scripting-API behavior — methods that live on unexpected objects, return values that lie, silently-rejected string keys, and calls that don't exist. Each fact records the reality, a recommended approach, and the Resolve build it was verified on. No connection required. Backed by `src/utils/api_truth.py`, seeded from hard-won findings (AutoSyncAudio, Fusion Paste, FlowView positions, GetTimelineByName, project render methods, transcription truncation, the CreateProject modal, stdio subprocess hygiene) and meant to grow over time. ## What's New in v2.33.4 Internal reliability framework. - **Added** `verify_by_readback` (`src/utils/readback.py`) — a primitive for mutating Resolve ops that verifies an action by reading the real post-state back instead of trusting the API's frequently-unreliable return value. A contradiction (reported success but a failing readback) is logged as a reliability signal. - **Changed** Auto-sync audio now runs through `verify_by_readback` as its first user and reports a `verified` field alongside `linked`/`newly_linked`. Behavior is unchanged; the bespoke readback loop is replaced by the shared primitive. ## What's New in v2.33.3 Two read tools that surface existing project state. - **Added** `project_settings(action="project_summary")` returns a live structural readout — current page, timeline count and current timeline, and a media-pool inventory (folder/clip counts, clips by type, optional clip sample). A cheap "what's in this project right now" snapshot that needs no prior analysis. - **Added** `timeline(action="get_transcript")` reads the current timeline's subtitle track(s) as transcript text `{text, cue_count, has_subtitles, cues}`, with optional per-cue timecodes. Complements the clip-level `get_transcription`. ## What's New in v2.33.2 Documentation: a guide for hand-authoring DaVinci Resolve `.setting` template files. - **Added** `docs/authoring/setting-files/` — how to author Edit effects, transitions, titles, generators, and Fusion macros as `.setting` files: the Lua-table format, the `InstanceInput`/`UserControls` control catalog, thumbnail conventions, Templates install paths, and a set of hard-won gotchas (ordered vs unordered `Inputs`, `ControlGroup` anchoring, transition easing via `LUTLookup`, `KeyStretcher` on titles, the category-subfolder rule, OFX boilerplate, and more). Includes 13 copyable starter templates and is linked from `docs/SKILL.md`. ## What's New in v2.33.1 Clip transcription read-back and more trustworthy auto-sync reporting. - **Added** `media_pool_item(action="get_transcription")` returns `{text, truncated, status, has_transcription}`. Transcription could previously be triggered but never read back. Resolve's `Transcription` clip property is a preview that ends in an ellipsis when the full transcript is longer, so `truncated` tells callers the returned text is partial. - **Changed** Auto-sync audio now verifies linkage by reading each clip's `Synced Audio` property before and after the call and reporting `linked` / `newly_linked` / `already_linked`, instead of trusting `AutoSyncAudio`'s unreliable boolean. The boolean is still returned as `success`, but callers should trust `linked`. ## What's New in v2.33.0 Fusion node-graph layout and duplication, plus performance and robustness improvements across the compound server. Live-validated on DaVinci Resolve Studio 21.0.0. ### Fusion node layout & duplication - **Added** `fusion_comp(action="get_position")` and `set_position` — read and write a node's position on the FlowView canvas. `set_position` confirms the move by reading the position back. - **Added** `fusion_comp(action="copy_tool")` — duplicate a node, optionally renaming and repositioning it. Settings are carried through a temporary `.setting` file, which round-trips reliably across the Python bridge where the in-memory `SaveSettings()`/`Paste()` table form fails. - **Added** `fusion_comp(action="auto_arrange")` — lay tools out in a row (`direction="horizontal"`) or column (`"vertical"`) at a given spacing. ### Performance - **Changed** Resolve object inspection walks `dir(obj)` once instead of once for methods and again for properties, skips `inspect.signature()` for C-extension methods (slow and almost always raising there), and reads `__doc__` directly. Each attribute access on a Resolve object is a bridge round-trip, so this roughly halves inspection cost on the `resolve_control` path. - **Changed** Media-pool find-by-name lookups walk the folder tree lazily and stop at the first match instead of materializing the entire project tree. ### Robustness & fixes - **Fixed** `export_frame_as_still` rejects an empty path or a nonexistent target directory instead of silently returning failure. - **Fixed** `set_mark_in_out` (clip and timeline) rejects `mark_in > mark_out`. - **Fixed** Auto-sync audio resolves `AUDIO_SYNC_*` enum constants via the live Resolve handle, closing a path where a stale module handle silently degraded `AutoSyncAudio` to rejected string keys. - **Changed** Every `subprocess` call that can run while the MCP stdio server is active now sets `stdin=subprocess.DEVNULL`, so a child process cannot consume bytes from the JSON-RPC protocol stream; the spec-hook runner also captures its child's output. Applies to both the compound and granular launchers. ## What's New in v2.32.2 Fixes `fusion_comp(action="get_keyframes")` serialization. The handler iterated `Input.GetKeyFrames()` as if it returned `{time: value}`, but Fusion returns `{1-based index: frame_position}`. The result put the keyframe **index** in `time` and the **frame position** in `value` — the actual keyframed values were never reported. The handler now treats the dict values as frame positions and reads each keyframed value back via `GetInput(input_name, frame)`. - **Fixed** `get_keyframes` now returns `[{"time": , "value": }, ...]` in frame order (live-validated on DaVinci Resolve Studio 21.0.0: `Size` keyed `1.0@f0` / `1.4@f75` → `[{0.0: 1.0}, {75.0: 1.4}]`). - Follow-up to the `add_keyframe` fix in v2.32.1; flagged by @sandypoli-boop in #56. ## What's New in v2.32.1 Fixes `fusion_comp(action="add_keyframe")` so it actually **animates** the input. Previously the handler did `inp[time] = value` on the input directly. On an input with no animation spline, that only assigns a **static** value (last write wins) — no keyframe is created. Symptoms: `get_keyframes` returned `[]`, `get_input` at different times returned the same value, and the clip never animated. The handler now attaches a `BezierSpline` modifier the first time an input is animated, then sets the keyframe. A new optional `modifier` param lets callers pass e.g. `"Path"` for Point inputs such as `Center`. Behavior is unchanged for inputs that are already animated or otherwise connected. - **Fixed** `add_keyframe` now creates real, editable keyframes (live-validated on DaVinci Resolve Studio 21.0.0). - **Added** optional `modifier` param to `add_keyframe`. - Thanks to @sandypoli-boop for the diagnosis and fix ([#56](https://github.com/samuelgursky/davinci-resolve-mcp/pull/56)). ## What's New in v2.32.0 Adds **governance tiers** for the media-creating Resolve 21 AI ops (Phase 3, the final phase of the AI-ops build: ledger → console → governance). The two ops that render new files — `remove_motion_blur` and `generate_speech` — now have **soft, per-session limits** chosen by a named tier: | dimension | off | lenient | standard | strict | |---|---|---|---|---| | deblur runs | ∞ | 50 | 15 | 5 | | speech runs | ∞ | 50 | 15 | 5 | | media created | ∞ | 50 GB | 10 GB | 2 GB | | render time | ∞ | 1 h | 20 min | 5 min | Governance is **advisory** — it never hard-blocks (the ops are already confirm-token gated). When you're near or over the active tier, the confirmation dialog surfaces a warning before you proceed; the limits are computed from the v2.30.0 AI-ops ledger for the current session. - **New module** `src/utils/resolve_ai_governance.py` — tiers + `check()` (status for the next run) + `status()` (session usage vs tier). Default tier: `standard`. - **New MCP actions** `media_analysis(action="get_ai_governance")` and `media_analysis(action="set_ai_governance", preset, overrides?)`. Override keys: `deblur_runs`, `speech_runs`, `render_bytes`, `render_wall_clock_ms` (int or `"unlimited"`). - **Confirm preview** for the two creators now carries a `governance` block (current usage, projected, warnings, exceeded/near flags). - **Control panel** — the AI Console gains a **Governance** section: a tier picker (off/lenient/standard/strict, with each tier's thresholds) plus live consumption gauges, and the confirm dialog shows the warning inline. This completes the staged AI-ops build. Validated live against Resolve Studio 21.0.0.47 (tier switching, persistence, gauges, confirm-dialog warnings). ## What's New in v2.31.0 Adds the **AI Console** to the control panel — an interactive surface for the Resolve 21 local AI operations (Phase 2 of the staged AI-ops build: ledger → console → governance). A new **AI Console** tab runs the 21.0 ops against the current Media Pool folder or a specific clip: - **Capability matrix** — shows which AI methods this Resolve build exposes (green = available, grey = absent on older builds) and which Extra each gated method needs to actually run. - **Analysis** — Classify audio / Clear classification, IntelliSearch (with identify-faces and Better-mode toggles), Analyze for slate (16-color marker picker), Transcribe (with speaker-detection toggle), Clear transcription. - **Motion deblur** and **Speech generator** — full options forms; because both create new media files they route through a confirmation modal (the same confirm-token gate the MCP tools use) before running. - **Session** — Disable background tasks for the current Resolve session. - A live result readout, and the *Resolve 21 AI ops* ledger refreshes after each run so file/byte totals stay current. Backend: a loopback-only `POST /api/resolve_ai/run` endpoint dispatches each op to the consolidated `folder` / `media_pool_item` / `project_settings` / `resolve_control` tools, relaying the confirm-token two-step. No new MCP tools or Resolve API surface — the console reuses the existing v2.29.0 actions. Validated live end-to-end against Resolve Studio 21.0.0.47. ## What's New in v2.30.0 Adds the **Resolve 21 AI-ops ledger** — usage/time/file accounting for the Resolve-local AI operations added in v2.29.0 (audio classification, IntelliSearch, slate, motion-deblur, speech generation). These run on Resolve's own GPU/AI engine and do **not** consume the Claude-side analysis token budget, so they get their own ledger instead of being metered by the analysis-caps layer. **What's tracked.** Every run of the five 21.0 ops records: op name, op class (`analysis` vs `render`), clip id, success/failure, wall-clock time, and — for the two media-creating ops (`remove_motion_blur`, `generate_speech`) — the output file path and byte size. The reliable signal is invocation counts + the file/disk accounting for the creators; durations for the bool-returning analysis ops reflect the script-call time (some queue work inside Resolve). - **New table** `resolve_ai_op_usage` (timeline_brain DB schema v7). - **New module** `src/utils/resolve_ai_ledger.py` — `timed()` context manager + `record_op` / `get_usage` / `get_summary`. All writes are best-effort and never block or mask the underlying Resolve op. - **Instrumentation** wraps the consolidated `folder` / `media_pool_item` `perform_audio_classification` / `clear_audio_classification` / `analyze_for_intellisearch` / `analyze_for_slate` / `remove_motion_blur` handlers and `project_settings.generate_speech`. - **New MCP action** `media_analysis(action="get_resolve_ai_usage", session_only?, op?, limit?)` returns the per-op summary + recent runs. - **Control panel**: a read-only "Resolve 21 AI ops" card (`/api/resolve_ai_usage`) shows runs, success/fail, total time, and files/bytes created. Phase 1 of a staged build (ledger → interactive console → governance). Granular `--full` server instrumentation is deferred — the ledger covers the consolidated server, which is the default surface. Validated live against Resolve Studio 21.0.0.47. ## What's New in v2.29.0 Adds the **DaVinci Resolve 21.0** scripting-API additions. Every new method is runtime-detected (`_requires_method`/capability flags), so the tools stay inert on older Resolve builds and activate automatically on Resolve 21+. **New AI analysis actions** on the `folder` and `media_pool_item` compound tools (and mirrored as granular `--full` tools): - `perform_audio_classification` / `clear_audio_classification` — classify clip audio into categories and subcategories. - `analyze_for_intellisearch(identify_faces?, is_better_mode?)` — IntelliSearch analysis with optional face identification. Requires the *AI IntelliSearch* Extra. - `analyze_for_slate(marker_color?)` — slate/clapboard detection that drops a marker of the chosen color (validated against the 16 Resolve marker colors). Requires the *AI Slate ID* Extra. - `remove_motion_blur(deblur_option?)` — renders motion-deblurred copies. This **creates new media files** (source media is never modified) and is therefore **confirm-token gated**: the first call returns a preview + token, the second call (with the token) runs. **Speaker-detection transcription.** `transcribe_audio` now accepts an optional `use_speaker_detection` boolean (Resolve 21+); omit it to use the project's Speech Recognition setting. **Speech generation.** `project_settings(action="generate_speech", ...)` wraps `Project.GenerateSpeech` (AI text-to-speech). It creates a new audio item and optionally places it on the timeline, so it is also confirm-token gated. Requires the *AI Speech Generator* Extra. Granular `--full` tool: `generate_speech`. **Session control.** `resolve_control(action="disable_background_tasks_for_current_session")` wraps `Resolve.DisableBackgroundTasksForCurrentResolveSession()` to quiet background work during heavy scripted runs. **Capability surface.** The `media_analysis` transcription-capability report and the control panel's boot payload (`resolve.ai_features`) now list which 21.0 AI methods are available and which Extras each gated method needs. Notes: these are Resolve-local GPU/AI operations and do not consume the Claude-side analysis token budget, so they are not metered by the analysis-caps layer; the derivative-creating ones are protected by the confirm-token gate instead. The granular `--full` server grew from 329 to 341 tools. ## What's New in v2.28.1 Bug-fix release. **Audio transcription no longer passes an invalid `language` argument.** The `transcribe_audio` (clip) and `transcribe_folder_audio` tools in the full (`--full`) server were calling `TranscribeAudio(language)` with a language string, but the Resolve scripting API has never accepted a language positional — its signature is `TranscribeAudio(useSpeakerDetection=None)`. The string was silently coerced to a truthy boolean and misread as a speaker-detection flag, and the success message falsely claimed a transcription language. The language is controlled by the project's Speech Recognition setting, not per call. - `transcribe_audio(clip_name, use_speaker_detection=None)` — the `language` parameter is replaced with an optional `use_speaker_detection` boolean (Resolve 21+). Omit it to use the project's setting. - `transcribe_folder_audio(folder_name, use_speaker_detection=None)` — same change for the folder-level tool. - Both pass the boolean through only when supplied, so older Resolve builds (which take no argument) keep working. The consolidated 32-tool server was unaffected — its `folder`/`media_pool_item` `transcribe_audio` actions already called `TranscribeAudio()` correctly. ## What's New in v2.28.0 This release adds a structural timeline-diff engine, a declarative project spec you can `apply` like infrastructure-as-code, a project health `lint`, a clip query DSL, and a machine-readable `state` field on error responses. **Timeline version diff — see exactly what an edit changed.** Comparing two archived timeline versions now reports clips that were **added, removed, moved, and trimmed**, plus summary counts and before/after clip totals. A new reusable diff engine aligns clips by a rename-stable identity (so a reordered or renamed clip reads as a move/change, not a delete-and-re-add). - `timeline_versioning(action="diff_versions", timeline_name, from_version, to_version)` now returns `{added, removed, moved, trimmed, summary}` (the previous `added`/`removed`/`moved` keys are unchanged). - Dashboard endpoint `GET /api/timeline_versions/diff?timeline_name=&from_version=&to_version=` exposes the same diff to the control panel. **Declarative project spec + `apply` — reproducible project setup.** Describe a project's desired settings, color preset, timelines, and markers in a `project.dvr.yaml` (or `.json`), then reconcile the live project toward it. Runs are **idempotent** — applying twice is a no-op — and a dry run previews every change before anything is touched. - New MCP actions on `project_manager`: - `diff_to_spec(spec_path | spec)` — preview drift without mutating. - `plan_spec(spec_path | spec)` — the ordered action list (dry run). - `apply_spec(spec_path | spec, dry_run?, run_hooks?, continue_on_error?)` — reconcile. Color/HDR settings apply in dependency order; markers are only added when absent; an explicit `color_preset` can be overridden by explicit `settings`. Failures can abort on first error or accumulate. - New headless CLI commands: `davinci-resolve-mcp batch plan-spec SPEC` and `davinci-resolve-mcp batch apply SPEC [--dry-run] [--run-hooks] [--continue-on-error]`. Exit codes follow the existing convention (`0` ok, `2` partial, `3` fatal). - Optional before/after shell **hooks** in the spec run only when `run_hooks` is passed (opt-in). **Project health `lint` — a pre-flight before editing.** `project_manager(action="lint")` returns a graded issue list (errors / warnings / info) covering: no project, no current timeline, mixed frame rates across timelines, empty timelines, unset render format, unmanaged color science, offline media, and unanalyzed clips. **Clip query DSL — find clips in one call.** `timeline(action="clip_where", ...)` returns the clips on the current timeline matching named filters (AND), instead of enumerating tracks by hand. Live filters: `track_type`, `track_index`, `name_contains`, `duration_lt`, `duration_gt`. A typo'd filter name is rejected rather than silently matching everything. **Machine-readable error context.** Structured error responses can now carry an optional `state` object — a snapshot of the relevant values at failure time (e.g. which filter was unknown, which spec failed and where) — so an agent can react without parsing prose. Existing error fields are unchanged. ## What's New in v2.27.2 **Control panel under-counted analyzed clips after a Media Pool rename (issue #51)** — with every clip analyzed (e.g. 303/303 reports on disk), the overview and Media tab could report something like "108 / 303 analyzed". The panel only recognized a report when a folder's name exactly matched the clip's *current* display name, so renaming clips after analysis hid their existing reports even though the underlying media was unchanged. Root cause and fix: - **Lookups are keyed by a rename-stable hash, not the display-name folder.** Report folders are named `-`; the count now matches on the trailing hash (and the ids inside each report), so a renamed clip still resolves to its existing folder. Both the disk path and the jobs-DB fallback were corrected. - **The hash is now anchored to the normalized file path (canonical basis).** Previously the basis was a `clip_id`-first cascade, so the same media hashed differently depending on which fields a record carried — Resolve inventory (clip_id) vs path-based batch jobs (file path) disagreed on the same clip. Anchoring to the file path removes that cross-basis mismatch. Legacy folders (clip_id-based, or raw-path-based) still resolve via a migration-safe set of candidate hashes, so **no on-disk migration is required**. - **Writes reuse an existing report folder** (matched by canonical or legacy hash) instead of minting a new `-` directory, eliminating orphaned duplicate folders when a renamed clip is re-analyzed. - **A persisted clip index (`clips/index.json`)** maps every stable id found in a report (normalized + raw file path, clip_id, media_id) to its folder, so the count can still match a clip by any id it carries — including an offline clip that no longer reports a file path but retains its clip_id. The index is refreshed only when a report is added, removed, or rewritten (cheap signature check), so the recurring poll stays inexpensive. No public MCP tool surface changed. Adds regression tests in `tests/test_media_analysis.py` covering rename, cross-basis, legacy-folder reuse, the jobs-DB fallback, and the offline/no-path case. ## What's New in v2.27.1 **Faster control-panel startup with network source media (issue #50)** — on first open the control panel could sit on "connection pending" for a long time when Media Pool clips lived on mounted network storage, because the UI only treated the connection as live once the full media inventory finished loading, and that inventory probed every clip's file path on disk. Fixes and performance work: - **Connection state is decoupled from the media inventory.** The overview and diagnostics panels now derive "connected" from the `/api/boot` handshake (which returns as soon as the Resolve bridge is reachable) and show inventory loading separately, so Resolve reads as live immediately while clips stream in. - **Parallel, cached file-existence probing.** `os.path.exists` for every clip now runs in a thread pool and is memoized for a short TTL, instead of two serial `stat()` calls per clip — the dominant cost on network storage. - **Background polls reuse the cached Media Pool walk.** The recurring poll no longer re-runs the ~N serial `GetClipProperty` calls; it reuses the last walk and re-applies only the local, disk-backed analysis-status overlay. A cheap project-id check still catches a project switched directly in Resolve, and a manual refresh always does a full walk. - **Resolve scripting API access is serialized.** A re-entrant lock guards every scripting-API entry point, since the dashboard's threaded HTTP server could previously fire concurrent (thread-unsafe) Resolve calls at startup. - **ETag/304 on the inventory endpoint** skips transfer and table re-render when nothing changed; the last good inventory is cached client-side and painted instantly on reload; and the first inventory build is warmed in a background thread at server start. No public MCP tool surface changed. Adds regression tests in `tests/test_media_analysis.py` (path-existence probing, inventory cache reuse, project-switch detection, lock reentrancy). ## What's New in v2.27.0 **Frame-sampling modes (issue #46)** — how many frames a clip gets for visual analysis is now governed by a `sampling_mode`, decoupled from `depth` (which still controls which layers run). A fixed frame count over-sampled short clips and under-covered long ones; the demand-driven engine already scaled by duration/content, but the caps layer was flat-truncating its output back to 8 frames — that flat cap was the real cause of long-clip under-coverage. Four clearly-tiered modes, organized so token cost is predictable per tier: - **Economy** (`fixed`) — flat N evenly-spaced, content-blind frames. Cheapest and most predictable; good for proxies/triage. - **Balanced** (`per_minute`) — `clamp(minutes × frames_per_minute, floor, ceiling)` (defaults 4/min, 3–80). Cost is linear in footage length; content-blind. - **Thorough** (`adaptive_capped`, recommended/default) — content-aware: samples shot boundaries, representatives, and flash candidates, bounded to `[floor, ceiling]`. Best coverage with a bounded cost. - **Thorough (uncapped)** (`adaptive`) — content-aware with no per-clip ceiling (up to the 512-frame hard cap). Use only when clips are short or few. The first time you analyze without a saved default, the tool returns a `confirmation_required` response with a `sampling_mode_prompt`; choosing a mode saves it as your standing default (mirrors `timed_markers_default`). Pass `sampling_mode` per call any time for a one-off that doesn't change the default. Tunables (`frames_per_minute`, `frame_floor`, `frame_ceiling`) and the mode are all exposed in the control panel (Preferences → Frame sampling mode) with a live per-clip token-cost estimate; batch jobs honor the saved default. Analysis-caps presets were retuned so `frames_per_clip` is now a *safety ceiling* (minimal/standard/generous = 12/80/200), not the primary frame dial, and the per-clip/job/day vision-token caps were raised so the default Thorough mode isn't refused by the per-clip token cap. Cache reuse re-samples only when switching up the thoroughness rank; a richer prior report still satisfies a cheaper mode. Adds `tests/test_sampling_modes.py` (30 tests). Validated end-to-end on a synthetic multi-shot clip with real ffmpeg frame extraction. ## What's New in v2.26.1 **Python 3.13 / 3.14 support (issue #45)** — `npx davinci-resolve-mcp setup` previously hard-refused any interpreter outside 3.10–3.12, so it failed outright on Python 3.14. The 3.12 ceiling was based on a stale assumption that Resolve's scripting bridge has ABI incompatibilities on 3.13+. Verified empirically against DaVinci Resolve Studio 20.3.2.9: Python 3.14.4 connects and exercises the dict/list marshalling paths cleanly. The launcher and installer now enforce only the 3.10 floor (the `mcp[cli]` SDK requirement) with no upper cap. Python 3.13/3.14 are accepted with a soft heads-up; `setup`/`doctor` surface a precise, connection-aware hint only when Resolve is running but the bridge returns no connection on 3.13+. Sub-3.10 interpreters get an actionable error instead of a dead end. `server.py` warns (never exits) on 3.13+. Adds 6 version-gate unit tests. ## What's New in v2.26.0 **Fusion group-settings helpers** — Three new `fusion_comp` actions for authoring and patching `GroupOperator` macros without leaving the kernel. `group_settings_export` writes a live group to a `.setting` file and returns a parsed `published_inputs` summary using a balanced-brace walker so nested `UserControls` / `ControlGroup` tables are bounded correctly (the original flat-regex parser truncated `InstanceInput` bodies at the first inner `}`). `group_settings_splice_inputs` replaces the `Inputs = ordered() { ... }` block of one `.setting` with the matching block from another, preserving the source's outer structure and inner `Tools`. `group_settings_load` applies a `.setting` to a live group with an automatic timestamped backup, wrapped in `StartUndo`/`Lock`/`LoadSettings`/`Unlock`/`EndUndo(True)` so Fusion's Ctrl+Z reverses the change — verified live via direct BMD API. **bulk_set_expressions** — Companion to the existing `bulk_set_inputs`. Batch attach Fusion expressions across many timeline-item comps in one call. Each op requires timeline scope plus `tool_name`, `input_name`, `expression`. Returns per-op `success`/`error` rows + `op_count`, matching the bulk-inputs contract. Useful for animating many controls at once (`time/30`, etc.) under a single chat turn. **Headless batch-runner CLI** — New `davinci-resolve-mcp batch ` subcommand drives `src/utils/media_analysis_jobs` from outside an MCP/chat client so long analysis batches can run via cron, CI, or terminal without holding a chat turn open. The orchestration loop and durable state stay in the existing jobs engine; the CLI only handles argv, progress streaming, and exit codes (`0` ok / `2` partial / `3` fatal / `130` Ctrl+C). JSON mode (`--json`) emits one record per progress event for log scraping. Closes #42. **Adapted from PR #40** — Group-settings work originated as a contribution from @RaincloudTheDragon; PR #43 retains the keepable parts (parser, exporter, splicer, loader, `bulk_set_expressions`) with a balanced-brace fix on the parser and an undo+lock wrap on `group_settings_load`. The two AMZ-specific templates and the static checklist from #40 were dropped as out-of-scope for a general kernel. ## What's New in v2.25.0 **Agentic flow improvements** — A second-pass review against the Claude Certified Architect study material drove a sweep of correctness gains. Every tool error now returns a structured envelope (`code` / `category` / `retryable` / `reason` / `remediation` / `message`); `retryable` defaults are locked per category so a host can make a one-shot retry decision without inference. Compound-tool descriptions for `media_analysis` and `timeline_item_color` adopt XML semantic tags (``, ``, ``) for cheaper per-turn parsing. Repeated failures on the same `(scope, action)` pair attach an `escalation` block on the 3rd response — halts auto-retry loops with a `suggested_action` for the host. Batch manifests now always carry `partial_success`, `completed_clip_ids`, and `failed_clip_ids` for safe targeted retry. **MCP resources surface** — 8 read-only resource URIs the host can poll without paying a tool-turn cost: `status://mcp_version`, `status://resolve_connection`, `status://current_project`, `status://current_timeline`, `status://caps_preset`, `analysis://recent_reports`, `capabilities://installed_tools`, `capabilities://install_guidance`. Paired tools still work for hosts that don't consume resources. **MCP prompts surface** — 5 slash-command workflow templates: `/davinci-resolve:analyze_and_propose_grade`, `/davinci-resolve:match_bin_to_hero`, `/davinci-resolve:verify_timeline_coverage`, `/davinci-resolve:open_and_analyze_selection`, `/davinci-resolve:prep_color_handoff`. First-class agentic intent, no re-derivation from SKILL.md prose. **Color-grading evidence base** — `timeline_item_color.grade_evidence_base` composes `version_snapshot` + `node_graph` + `color_group` + coverage report into a single `evidence_base` summary string; the SKILL guide now teaches agents to lead any color recommendation with that line. `timeline_item_color.propose_grade` formalizes a recommendation as a validated structured plan (returns `plan_id` + `preview_path`; requires explicit `execute=true` re-call). `bulk_match_to_hero` drives CDL-delta or copy-grade across many targets with a `confirm_token` gate and dry-run preview. **Analysis caps layer** — Token-budget governance for analysis. 7 cap dimensions across vision/transcription/job/clip/day scopes, 4 named presets (`minimal` / `standard` / `generous` / `unlimited`), pre-call refusal with `CAPS_REFUSAL` / `budget_exhausted` / `retryable: false`. New `media_analysis` actions: `get_caps`, `set_caps_preset`. Token usage table in the analysis DB plus a control-panel widget with gauges + override inputs. Wall-clock timeout helper wraps vision/transcription call sites. **Timeline versioning + analysis↔timeline marriage** — New `timeline_versioning` MCP tool: every destructive timeline edit auto-archives the current timeline into an Archive bin (compound, captions, ripple, gap close, etc.), so versions can be diffed and rolled back. Run scoping, schema v4 migrations, concurrency safety, structural snapshots, action filtering, strict mode, auto-save preference, media-pool destructive coverage, thumbnails. Backed by new modules `timeline_versioning.py`, `timeline_brain_db.py`, `brain_edits.py`, `analysis_runs.py`, `media_pool_changes.py`, `destructive_hook.py`. Surfaced in the control panel's Review → History view. **Async opt-in for long-running ops** — `analyze_clip` / `analyze_file` / `commit_vision` accept `prefer_handle: true`. When set (and the estimated runtime exceeds the configured threshold), the response is a fast handoff with `job_id` + `status: "queued"`; poll `batch_job_status({job_id})`. Default behavior unchanged. **Aggregated provenance** — `summarize`, `review_timeline_markers`, and `grade_evidence_base` now return a `provenance` block: `source_reports[]` (clip_id, signature, report_path, analyzed_at), `missing_reports[]` (per reason: `no_report` / `stale_report` / `caps_refused`), and inline `[ref:]` citations in the human summary text. Multi-clip claims are now traceable. **Confirm-token gates on destructive batches** — `propose_grade`, `bulk_match_to_hero`, and other multi-target writes now require an explicit `confirm_token` on first execute (returned on the dry-run), with a `pending_user_decision` error if missing. **Action-help indirection** — `action_help(name=...)` returns the long-form guidance for a single action, keeping the top-level tool descriptions compact while preserving full per-action documentation. **Tool-choice hint emission** — Analyze responses include a `host_tool_choice_hint` block. Hosts that respect it pass `tool_choice={type:"tool", name:"media_analysis"}` on the next API turn, hard-locking the agent into the correct next call. **Update process hardening** — Five improvements layered onto the update-check path: active-job lock prevents updates mid-analysis, auto-stash strategy preserves uncommitted work across updates, restart-needed marker surfaces to the host, channels (`stable` / `beta` / `dev`), pre-update breaking-change scan, integrity SHA verification of downloaded artifacts, update history table, eager DB migration on update, and rollback to the previous build. New `analysis_caps.py` + `update_check.py` revisions. **Source-safe guardrails** — `destructive_hook.py` + decorator coverage tests ensure every destructive surface goes through the auto-archive path and never modifies, transcodes, or creates derivatives of source media. **Test surface** — 30+ new test modules covering error envelopes, failure tracking, partial-success manifests, `prefer_handle`, MCP resources, MCP prompts, provenance, XML description shape, `action_help`, `grade_evidence_base`, `propose_grade`, `bulk_match_to_hero`, `confirm_token`, the analysis caps layer, caps integration / events / history, timeline versioning, the timeline-brain DB, destructive decorator coverage, the destructive hook, update hardening, and update history. **Validation** — `tests/test_import.py`, `scripts/audit_api_parity.py`, `node bin/davinci-resolve-mcp.mjs --version`, `npm pack --dry-run`, and `git diff --check` all pass. 375 focused unit tests pass. Live Resolve validation covered the D1–F2 surface end-to-end against project CKY / Timeline 7 (D1 `retryable`, D2 XML descriptions, D3 partial-success on plans + CAPS_REFUSAL manifests, E1 8 MCP resource URIs, E2 escalation on 3× repeated failure, E3 `prefer_handle` job handoff with `batch_job_status` polling, F1 provenance block) — 6/6 PASS on the fourteenth-attempt smoke test. No source media was modified. ## What's New in v2.24.1 **`npx davinci-resolve-mcp` no longer breaks MCP clients when invoked without a subcommand.** The npm bootstrapper previously defaulted to `--help`, which wrote usage text to stdout and exited 0. MCP stdio clients (Hermes Agent, Claude Desktop, Cursor, etc.) read that as malformed JSON-RPC, retried three times, then dropped the connection. `bin/davinci-resolve-mcp.mjs` now defaults to the `server` subcommand when no arguments are supplied. Explicit `--help`, `-h`, `help`, `--version`, and `-v` continue to print to stdout as before, and existing configs that already pass `server` explicitly are unaffected. Reported in [#41](https://github.com/samuelgursky/davinci-resolve-mcp/issues/41). ## What's New in v2.24.0 **Host-chat vision protocol (V2)** — `analyze_*` actions now use `vision.provider="host_chat_paths"` by default. The analyze response is a deferred payload with absolute `frame_paths`, a per-shot `shot_table`, and a JSON schema; the host chat reads each frame as a local image, produces JSON per the schema, and calls `media_analysis(action="commit_vision", params={clip_id, visual, vision_token})` to finalize. `commit_vision` merges the visual report, rebuilds Media Pool clip markers, publishes metadata to Resolve, and preserves human corrections via `corrections.json`. Skipping the commit leaves the run in `pending_host_vision_analysis` — surfaced explicitly rather than silently downgraded. The legacy `chat_context`/`mcp_sampling` providers still resolve to the same host-chat path. **Trust-by-default analysis defaults** — `analyze_media` defaults to `include_transcription=true`, `persist=true`, `publish_metadata=true`, and `timed_markers="ask"` so source-safe no longer means underpowered. Agents that need a technical-only or read-only run must explicitly pass `include_visuals=false`, `include_transcription=false`, `publish_metadata=false`, `timed_markers="no"`, `session_only=true`, or `dry_run=true`. The `analyze_media` prompt and SKILL.md spell out the anti-regression rule. **Control panel: Review surface (Phase B)** — The local browser control panel gains a Review tab backed by new endpoints: `/api/clips`, `/api/clips/`, `/api/clips//shots`, `/api/clips//shots/`, `/api/clips//frames/`, `/api/clips//transcript`, `/api/clips//corrections`, `/api/clips/combined`, `/api/clips/export`, `/api/panel_state`, `/api/update/status`, `/api/update/apply`, and `/api/resolve/open_clip`. The UI ships a bin grid with thumbnails, a clip detail with shot strip, a shot detail with grouped V2 fields + frame grid, inline correction editors per subjective field, transcript correction + regeneration, an Open-in-Resolve bridge, and 2-second chat ↔ panel state polling. **Control panel MCP actions** — `resolve_control.open_control_panel`, `control_panel_status`, and `close_control_panel` manage the local panel subprocess via a pidfile. `save_state` / `restore_state` snapshot and restore Resolve playhead + selection state. `get_panel_state`, `set_panel_state`, and `session_start_context` share panel focus between chat and the UI through `panel_state.json`. **Correction tools** — New `media_analysis` actions for editing analysis without re-running it: `update_shot_field`, `update_clip_field`, `get_field_history`, `revert_field`, `list_corrections`. Writes land in `{clip_dir}/corrections.json` with append-only changelog + provenance (mirrors the V2 DB schema). `commit_vision` merges corrections on top of the fresh visual report so human edits survive re-analysis. **Media Pool item open-in-viewer** — `media_pool_item.open_in_viewer` selects a clip on the Media page and loads it into the source viewer, optionally setting mark in/out and bringing Resolve to the foreground via OS-level window activation. Useful for chat → Resolve hand-off. **Source-trust prompt grading** — `source_trust` parameter (`auto`/`filename`/`low`/`medium`/`high`) on analyze actions tunes the vision prompt to hedge identity/intent/value for archival or thin-evidence clips. **Analysis memory layer** — New `src/utils/analysis_memory.py` introduces per-project memory + heartbeat + bin summary + soul scaffolding under the analysis root. `regenerate_bin_summary_from_manifest` aggregates per-clip fields (primary use, select potential, style, energy arc, top tags/locations) into a bin briefing. Auto-initialized on analyze. **Control-panel polish** — Diagnostics + Overview restyled with a status-pill design system, navbar dropdowns fixed so top-level buttons no longer navigate on their own, Preferences consolidated (Dashboard Convenience + Storage pages removed), summary-style enum renamed to `full`/`concise`/`creative`/ `technical` with backwards compat, navbar version badge + update modal, source-trust dropdown wired through. **Server-side bug fixes** — `commit_vision` auto-publish now reflects per-row status correctly (no silent-lie pending), compact analyze responses by default (`verbose: true` for the full manifest), `resolve_output_root` skips slug append when the configured base already terminates in the slug, frame sampler reserves per-shot budget so shot starts aren't starved by flash candidates, and machine markers are no longer written to Resolve (V2 architecture). **Path hardening for GUI launches** — `media_analysis` now augments `PATH` with the standard tool dirs (`/opt/homebrew/bin`, `/usr/local/bin`, etc.) so ffprobe/ffmpeg resolve even when the MCP server is launched by a GUI app (Claude.app, Dock/Spotlight) that inherits launchd's bare PATH. **Documentation** — `AGENTS.md` adds the "Media Analysis Defaults Are Mandatory" section. `docs/SKILL.md` rewrites the `analyze_media` prompt guidance for the host-chat-paths protocol and adds the anti-regression rule. `docs/guides/media-analysis-guide.md` covers the deferred vision payload and commit step. **Validation**: static import checks, API parity audit, focused media-analysis + marker/range/v232/v233 unit tests, npm CLI smoke, `npm pack --dry-run`, and `git diff --check` all passed. No source media was modified. Resolve scripting behavior is additive (new actions; existing actions unchanged); live Resolve validation covered the control-panel + open_in_viewer + commit_vision auto-publish + corrections-merge paths during the V2 push sessions logged in MEMORY.md. ## What's New in v2.23.1 **Control panel navigation fixes** — The local browser control panel now keeps top-level dropdown buttons from navigating by themselves. Analysis, Diagnostics, Docs, and Preferences open their menus first; selecting a menu item is what changes the active view. **Project dropdown cleanup** — The project context dropdown is back to showing only the open/current project context plus a bottom `View All Projects` option. The full database browser stays in the Projects view, and the standalone Projects navbar button has been removed. **Validation**: static import checks, API parity audit, focused dashboard unit tests, npm CLI smoke tests, package dry-run, and `git diff --check` passed. A local dashboard smoke check verified the served HTML on `127.0.0.1:8765`. No Resolve scripting behavior changed; live Resolve mutation validation was not required. ## What's New in v2.23.0 **npm installer** — `npx davinci-resolve-mcp setup` is now the primary quick start. The npm package bootstraps a managed per-user install, runs the existing Python installer from that stable location, and keeps MCP client configs pointed at the managed virtual environment and `src/server.py`. **Local control panel** — Added a single-user browser control panel for server status, Resolve clip visibility, source-safe analysis jobs, analysis search, and preference management. It can be launched from source with `venv/bin/python -m src.control_panel` or from npm with `npx davinci-resolve-mcp control-panel`. **Durable media-analysis jobs and search** — `media_analysis` can now create, slice, inspect, cancel, resume, and list durable analysis jobs. Persisted reports refresh a single-user SQLite index with clip, marker, timeline occurrence, keyframe, and transcript search helpers through `build_index`, `index_status`, and `query_index`. **Release automation** — Added npm package metadata, package-content guards, and a tag-driven GitHub Actions workflow for trusted npm publishing with provenance. The workflow skips publish when the package version already exists, which keeps the first manual npm registration from fighting the later tag workflow. **Validation**: static import checks, API parity audit, focused media-analysis, update-check, and media-pool ingest unit tests passed. npm smoke tests, setup dry-run, package dry-run, and `git diff --check` passed. No source media was modified. ## What's New in v2.22.0 **Configurable MCP update prompting** — Update checks now carry a persisted policy: `prompt`, `auto`, `notify`, or `never`. The server still never blocks MCP stdio startup, but the installer can prompt users to update, continue, snooze for 24 hours, ignore the current release, enable safe auto-update, or disable checks. Safe auto-update is opt-in and only attempts a clean git fast-forward from checkouts with no local changes and a configured upstream. **MCP update controls** — `resolve_control.mcp_update_status` reports the local MCP version, cached or forced update status, and the current prompt decision. `set_mcp_update_policy`, `ignore_mcp_update`, `snooze_mcp_update`, and `clear_mcp_update_preferences` expose the same policy state through the compound server without requiring Resolve to be connected. **Conversation setup defaults** — New `setup` compound tool centralizes conversation-configurable defaults. It can read, set, dry-run, and clear preferences for media-analysis modality, slate detection, transcription, analysis persistence, metadata publish fields and overwrite policy, timed marker types/colors/counts, report style, preferred analysis roots, post-operation page behavior, and MCP update interval/snooze policy. These defaults shape future tool calls while preserving explicit confirmation for Resolve project writes. **Metadata field inventory** — `media_pool.metadata_field_inventory` gives assistant editors and metadata workflows a read-only map of clip metadata, clip-property keys, default analysis writeback fields, optional slate fields, and inferred Resolve Metadata-panel groups. This helps bridge analysis publishing to the fields Resolve actually exposes on a given clip/build. **Optional timed analysis markers** — `media_analysis.publish_clip_metadata` can now write source-frame Media Pool clip markers for slate claps, best moments, and QC warnings when the user opts in. If no marker preference exists, the tool returns a prompt with yes/no/default-yes/default-no choices rather than silently writing markers. **Validation**: static import checks, API parity audit, `git diff --check`, and focused update-check, media-analysis, and media-pool ingest unit tests passed. Media-pool ingest tests cover the new metadata inventory and Metadata-panel group hints. Live validation used DaVinci Resolve Studio 20.3.2.9 through the connected MCP server with a disposable project and synthetic media only. It verified `metadata_field_inventory`, `MediaPool.ExportMetadata()` header comparison, default analysis writeback field mapping, and `SetMetadata()` readback for analysis and slate fields. The standalone live metadata inventory harness is included for future release validation with a Resolve-compatible Python 3.10-3.12 interpreter. ## What's New in v2.21.0 **Resolve metadata publishing from analysis** — `media_analysis.publish_clip_metadata` turns source-safe analysis reports into Resolve-native clip metadata. It proposes field-specific merges for `Description`, `Comments`, `Keywords`, `People`, and optional slate-derived fields, preserves existing human metadata by default, writes provenance to third-party metadata, and requires `confirm=true` before mutating Resolve. **Slate-aware metadata proposals** — Metadata publishing can reuse `detect_sync_events` slate-clap evidence and, when chat-context sampling is available, inspect frames around the clap for high-confidence slate fields before proposing `Scene`, `Shot`, `Take`, `Camera #`, and `Roll/Card` writes. **MCP update visibility** — The installer and both MCP server entrypoints now perform a best-effort GitHub release check, cache the result under `logs/`, and surface the local MCP version plus last update-check status from `resolve_control.get_version`. Checks are informational only and never install code automatically. **Validation**: static/import checks, API parity audit, focused media-analysis, sync-event, and update-check unit tests passed. Live validation used DaVinci Resolve Studio 20.3.2.9 through the active Resolve script runner with disposable projects and synthetic media only. `tests/live_metadata_publish_validation.py` verified dry-run previews, confirmed metadata writes, human metadata preservation, keyword merging, third-party provenance, and cleanup; `tests/live_sync_event_validation.py` revalidated 2-pop/slate-clap detection and confirmed marker writes. ## What's New in v2.20.0 **Sync event detection helper** — `media_analysis.detect_sync_events` detects likely audio 2-pops and slate claps with FFprobe/FFmpeg, returns advisory frame/timecode positions, and suggests per-file `record_offset` values for `media_pool.setup_multicam_timeline(sync_mode="record_frame")`. The helper is source-safe and never installs FFmpeg automatically. It also returns marker suggestions; `media_analysis.add_sync_event_markers` writes Media Pool item markers only when called separately with `confirm=true`. **Validation**: static/import checks, API parity audit, focused media-analysis and multicam unit tests, and `tests/live_sync_event_validation.py` passed. The live run used DaVinci Resolve Studio 20.3.2.9, a disposable project, and synthetic audio only; it verified detection, confirmation refusal, confirmed Media Pool marker writes, and cleanup. ## What's New in v2.19.0 **Multicam setup support** — `media_pool.setup_multicam_timeline` creates a source-safe stacked prep timeline from Media Pool clips, with one angle per video track, optional matching audio tracks, and stack-start, manual record-frame, or source-timecode planning. Native multicam clip conversion remains a Resolve UI step because the public scripting API does not expose a multicam-create method; the current UI workflow is documented in the DaVinci Resolve 20 Manual, Edit > Chapter 42, "Multicam Editing." **Documentation**: added `docs/guides/multicam-setup-guide.md` and linked the helper from the README, docs index, AI skill reference, kernel coverage, ingest kernel, and API coverage notes so it is clearly listed as a helper rather than a native API feature. ## What's New in v2.18.0 **Edit-page title / Text+ text (undocumented keys)** — `timeline.title_property_scan`, `timeline.set_title_text`, and `timeline.bulk_set_title_text` use `TimelineItem.GetProperty` / `SetProperty` to discover and update generator Text+ payloads when `GetFusionCompCount()` is zero (no Fusion comp for `fusion_comp`). Heuristic key ranking and a minimal styled-text XML fallback are included; callers should confirm keys with `title_property_scan` on their Resolve build. ## What's New in v2.17.1 Operational and client-safety hardening for the v2.17 media-analysis release. **MCP tool metadata**: compound and granular tools now publish MCP `ToolAnnotations` with conservative read-only, destructive, idempotent, and external-resource hints. Compound tool annotations are intentionally conservative because each tool groups multiple actions behind an `action` parameter. **MCPSafe report cleanup**: explicitly annotated the granular tools highlighted by the public MCPSafe report, including project settings, media import, page switching, proxy linking, Gallery album reads, and timeline-item transforms. **Operational guardrails**: Resolve app-control subprocess fallbacks now use bounded timeouts and report non-zero exits. Best-effort Resolve object inspection and state probes now log swallowed exceptions at debug level instead of failing silently. **Correctness fix**: fixed the granular `media_pool.append_to_timeline(clip_infos=...)` path so it retains the current project handle while normalizing positioned appends against the active timeline start frame. **Documentation**: added `SECURITY.md` with the local stdio trust boundary, confirmation guidance for destructive tools, source-media safety boundaries, and private vulnerability reporting guidance. The README now links the security policy and summarizes the local-only auth posture. **Validation**: static/import checks, API parity audit, compileall, and 161 focused unit tests passed. Live validated against DaVinci Resolve Studio 20.3.2.9 with a direct external-scripting smoke test, `tests/live_v233_validation.py` passing 10/10 checks, and a v2.17.1 disposable-project `media_pool.append_to_timeline(clip_infos=...)` normalization probe passing 2/2 checks. The v2.17.1 probe used synthetic media only and verified the default relative `record_frame` path landed at timeline start frame 86400 + 12 = 86412, while `record_frame_mode="absolute"` preserved frame 86484. ## What's New in v2.17.0 Media analysis and editorial-assist expansion - `media_analysis` now reuses existing project reports when cache signatures satisfy the requested analysis layers, can review timeline marker contact sheets with chat-context vision, and `timeline` adds editor-facing helpers for story-spine reports, declarative variant creation, bulk item property writes, multi-item look application, thumbnail contact sheets, marker thumbnail review, and audio mix capability fallback reporting. **New `media_analysis` compound tool**: added `capabilities`, `install_guidance`, `resolve_output_root`, `plan`, `analyze_file`, `analyze_clip`, `analyze_bin`, `analyze_project`, `review_timeline_markers`, `summarize`, `get_report`, and `cleanup_artifacts`. **MCP prompts and visual review**: the compound server now registers `davinci_resolve_workflow` and `analyze_media` prompts. `analyze_media` defaults to chat-context visual analysis when MCP sampling is available, while `timeline_markers.get_thumbnail_image` returns current Resolve frames as MCP image content without writing a file. **Source-safe editorial helpers**: timeline actions now support `story_spine_report`, `create_variant_from_ranges`, `bulk_set_item_properties`, `apply_look_to_items`, `thumbnail_contact_sheet`, `marker_thumbnail_review`, and `audio_mix_capability_report`. Positioned timeline appends normalize `record_frame` relative to the active timeline start by default, matching Resolve's common 01:00:00:00 start-frame behavior. **Documentation reorganization**: moved durable references into `docs/guides`, `docs/kernels`, `docs/authoring`, `docs/notes`, `docs/process`, and `docs/reference`, added a compact docs index, and kept local gameplans/scratch artifacts ignored. **Privacy cleanup**: sanitized tracked live-test fixtures and scripts that had workstation-specific source-media paths while leaving public project contact information intact. **Validation**: static/import checks, API parity audit, and 141 focused unit tests passed. Live validated against DaVinci Resolve Studio 20.3.2.9 with a disposable `_mcp_media_analysis_v2170_probe` project and a generated synthetic clip only. The run covered source-adjacent output-root rejection, `media_analysis.plan`, session-only `analyze_file`, `story_spine_report`, `audio_mix_capability_report`, raw thumbnail retrieval, `thumbnail_contact_sheet`, and `review_timeline_markers`; the disposable project and temp artifacts were cleaned up. ## v2.16.0 Extension Authoring kernel expansion - adding lifecycle-aware Fuse, DCTL, ACES DCTL, and Resolve-page script probes around the existing authoring tools. **New `script_plugin` extension actions**: added `extension_capabilities`, `probe_fuse_lifecycle`, `probe_dctl_lifecycle`, `probe_script_lifecycle`, `safe_install_extension`, `safe_remove_extension`, `refresh_or_restart_required`, and `extension_boundary_report`. **Lifecycle and cleanup guards**: safe extension installs require `_mcp_` names and MCP markers by default. Safe removal refuses to delete unmarked files unless explicitly overridden. The kernel classifies Fuse and ACES DCTL installs as restart-required, regular LUT DCTLs as `refresh_luts`-driven, and Resolve-page scripts as menu-refresh-only. **Documented support map**: added [`docs/kernels/extension-authoring-kernel.md`](docs/kernels/extension-authoring-kernel.md) and updated the Fuse/DCTL and script authoring docs with live lifecycle findings. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with MCP-marked `_mcp_` extension files only. Final probe result: 14 supported, 1 partially supported installed-Lua-script execution boundary, 1 intentional unsupported unmarked-source guard, and 0 errors. All generated extension files and the disposable project were cleaned up. ## v2.15.0 Project / Database / Archive kernel expansion - adding disposable project lifecycle guards, settings snapshots and write/restore probes, database switch dry-runs, preset lifecycle probing, archive safety validation, and project boundary reporting. **New `project_manager` lifecycle actions**: added `project_capabilities`, `probe_project_lifecycle`, `probe_project_settings`, `safe_project_create`, `safe_project_export`, `safe_project_import`, `safe_project_archive`, `safe_project_restore`, `safe_project_delete`, `safe_set_project_settings`, `project_settings_snapshot`, `database_capabilities`, `safe_set_current_database`, `preset_lifecycle_probe`, and `project_boundary_report`. **Operational guardrails**: safe project mutation defaults to `_mcp_` disposable names and temp paths. Database switching dry-runs by default because Resolve closes open projects when changing databases. Archive source media, render cache, and proxy media flags are rejected unless explicitly opted in. **Documented support map**: added [`docs/kernels/project-lifecycle-kernel.md`](docs/kernels/project-lifecycle-kernel.md) with project CRUD, DRP import/export, archive/restore, folder, settings, database, layout preset, render preset, page, keyframe, and cloud-infrastructure boundaries. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with disposable `_mcp_` projects only. Final probe result: 35 supported, 5 partially supported lifecycle/archive/keyframe/render-preset boundaries, 1 intentional unsupported archive media-flag guard, 1 not-applicable archive restore boundary, and 0 errors. Disposable projects, layout presets, and temp work files were cleaned up. ## v2.14.0 Audio / Fairlight kernel expansion - adding audio track/item probes, source audio mapping reports, guarded audio property writes, voice isolation capabilities, auto-sync planning, transcription/subtitle probes, and Fairlight boundary reporting. **New `timeline` audio actions**: added `audio_capabilities`, `probe_audio_track`, `probe_audio_item`, `safe_set_audio_properties`, `voice_isolation_capabilities`, `audio_mapping_report`, `safe_auto_sync_audio`, `transcription_capabilities`, `subtitle_generation_probe`, and `fairlight_boundary_report`. **Audio state and mapping**: the kernel snapshots audio track state, timeline item audio properties, source audio channel mapping, MediaPoolItem audio mapping, and track/item voice isolation availability. **Guarded AI and sync surfaces**: auto-sync dry-runs by default and normalizes Resolve audio-sync constants. Subtitle generation dry-runs unless `allow_generate=True`; transcription capability reporting is read-only by default. **Documented support map**: added [`docs/kernels/audio-fairlight-kernel.md`](docs/kernels/audio-fairlight-kernel.md) with track/item state, voice isolation, mapping, transcription, subtitle, auto-sync, and Fairlight insertion boundaries. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with generated synthetic video and audio-only media. Final probe result: 13 supported, 3 partially supported audio property/auto-sync/audio-insert boundaries, and 0 errors. The disposable project and generated media were cleaned up. ## v2.13.0 Timeline Conform / Interchange kernel expansion - adding timeline structure snapshots, source range reporting, gap/overlap detection, guarded interchange export/import, round-trip comparison, missing-media detection, and relink planning around Resolve's public timeline APIs. **New `timeline` conform actions**: added `conform_capabilities`, `probe_timeline_structure`, `detect_gaps_overlaps`, `source_range_report`, `export_timeline_checked`, `import_timeline_checked`, `compare_timelines`, `probe_interchange_roundtrip`, `detect_missing_media`, `build_relink_plan`, and `conform_boundary_report`. **Interchange probing**: export aliases now cover FCPXML, DRT, EDL, AAF, OTIO, FCP 7 XML, and EDL subtype variants. FCPXML directory-style exports are normalized with a `primary_file` path for import. **Conform analysis**: the kernel reports track/item structure, same-track gaps and overlaps, source ranges with handles, missing/offline media, and relink candidates without mutating user source media. **Documented support map**: added [`docs/kernels/timeline-conform-interchange-kernel.md`](docs/kernels/timeline-conform-interchange-kernel.md) with export, round-trip, missing-media, relink planning, and format-survival boundaries. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with a generated synthetic gapped timeline. Final probe result: 17 supported, 1 partially supported FCPXML round-trip survivability boundary, and 0 errors. The disposable project, generated media, and imported round-trip timelines were cleaned up. ## v2.12.0 Fusion Composition kernel expansion - adding safe Fusion graph inspection, tool creation, input writes, connection validation, scoped bulk writes, and boundary reporting around Resolve's public Fusion comp API. **New `fusion_comp` kernel actions**: added `fusion_graph_capabilities`, `probe_fusion_comp`, `probe_fusion_tool`, `safe_add_tool`, `safe_set_inputs`, `safe_connect_tools`, and `fusion_boundary_report`. **Timeline item graph automation**: the kernel can target timeline item Fusion comps via `timeline_item`, `clip_id`, or `timeline_item_id`, then add tools, write inputs with readback, inspect ports, connect tools, set frame ranges, and export the comp through `timeline_item_fusion`. **Scoped bulk writes**: `bulk_set_inputs` remains the safe batch path for applying input updates across multiple explicitly scoped timeline-item comps, so agent workflows do not accidentally mutate the active Fusion page comp. **Documented support map**: added [`docs/kernels/fusion-composition-kernel.md`](docs/kernels/fusion-composition-kernel.md) with tool availability, input/output, scope, comp export, and page-state boundaries. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with a generated synthetic timeline item Fusion comp. Final probe result: 18 supported, 0 unsupported, 0 partially supported, and 0 errors. The disposable project, generated media, and exported temp comp were cleaned up. ## v2.11.0 Color / Grade kernel expansion - adding safe grade inspection, CDL validation, node graph probing, grade copy, LUT export, version restore, Gallery, and color group boundary reporting around Resolve's public Color API. **New `timeline_item_color` kernel actions**: added `grade_capabilities`, `probe_grade_item`, `probe_node_graph`, `safe_set_cdl`, `safe_copy_grade`, `safe_apply_drx`, `safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`, `color_group_capabilities`, `gallery_capabilities`, and `grade_boundary_report`. **Grade and graph probing**: the kernel snapshots item grade versions, graph availability, node counts, node LUT/cache/label/tools metadata, color-group assignment, and cache state without guessing at opaque node internals. **Safe mutation helpers**: CDL payloads are validated and normalized before `SetCDL`; grade copy resolves target timeline item IDs first; LUT export is guarded to temp paths by default; DRX apply requires an existing DRX path and documents that it replaces the target graph. **Color groups and Gallery**: color-group capability probes cover project groups plus pre/post graph availability. Gallery capability probes report album state and classify still export as UI/page dependent when Resolve returns false. **Documented support map**: added [`docs/kernels/color-grade-kernel.md`](docs/kernels/color-grade-kernel.md) with graph, LUT, DRX, version, Gallery, color-group, and AI-tool boundaries. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with a generated synthetic color-bar timeline. Final probe result: 25 supported, 2 version/page-dependent Gallery/DRX export boundaries, 1 not-applicable DRX apply path because no DRX could be produced in that run, and 0 errors. The disposable project, generated media, and temp LUT exports were cleaned up. ## v2.10.0 Review Annotation kernel expansion - adding a unified marker, custom data, flag, clip color, copy/move, and review report layer across timeline, timeline item, and media pool item scopes. **New `timeline_markers` kernel actions**: added `annotation_capabilities`, `probe_annotations`, `normalize_marker_payload`, `copy_annotations`, `move_annotations`, `sync_marker_custom_data`, `clear_annotations_by_scope`, `export_review_report`, and `annotation_boundary_report`. **Unified annotation scopes**: the new helpers normalize marker payloads, frame/timecode aliases, custom data aliases, and marker colors before touching Resolve. `probe_annotations` snapshots timeline, current timeline item, and media pool item annotations when the current playhead can resolve them. **Review metadata copying**: `copy_annotations` and `move_annotations` can copy marker payloads between timeline, timeline item, and media pool item scopes using direct frame numbers. When supported by both scopes, flags and clip color can travel with the marker payload. **Read-only review reports**: `export_review_report` and `annotation_boundary_report` produce agent-friendly summaries without mutating media or projects. **Documented support map**: added [`docs/kernels/review-annotation-kernel.md`](docs/kernels/review-annotation-kernel.md) with the scope matrix, field support, frame-space caveats, and live probe findings. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with a generated synthetic timeline. Final probe result: 44 supported, 1 expected unsupported invalid-color boundary, and 0 errors. The disposable project and generated media were cleaned up after report generation. ## v2.9.0 Render / Deliver kernel expansion — adding a safer render planning, settings, format/codec compatibility, queue lifecycle, and Quick Export boundary layer. **New `render` kernel actions**: added `render_capabilities`, `probe_render_matrix`, `probe_render_settings`, `validate_render_settings`, `safe_set_render_settings`, `prepare_render_job`, `render_job_lifecycle_probe`, `quick_export_capabilities`, `safe_quick_export`, and `export_render_boundary_report`. **Render compatibility matrix**: `probe_render_matrix` walks available render formats, codecs, and resolutions so agents can choose what this specific Resolve install can actually deliver. **Job-safe rendering helpers**: render settings validation now checks documented setting keys, value types, frame ranges, and temp-target requirements. `prepare_render_job` creates queued jobs without starting renders, while `render_job_lifecycle_probe` validates add/status/delete behavior safely. **Guarded Quick Export**: `safe_quick_export` validates temp targets, forces `EnableUpload=False`, and requires `allow_render=True` before it can actually start Quick Export. **Documented support map**: added [`docs/kernels/render-deliver-kernel.md`](docs/kernels/render-deliver-kernel.md) with format/codec, settings, render job, and Quick Export boundaries. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with a two-second generated synthetic timeline. Final probe result: 23 supported, 1 version/page-dependent `GetRenderSettings` readback boundary, and 0 errors. The probe rendered one tiny synthetic output, then cleaned up the disposable project and generated files. ## v2.8.0 Media Pool / Ingest kernel expansion — applying the timeline edit kernel probe pattern to import, organization, metadata, annotation, and media-link boundary workflows while preserving source media integrity. **New `media_pool` kernel actions**: added `ingest_capabilities`, `probe_media_pool`, `probe_ingest_item`, `safe_import_media`, `safe_import_sequence`, `safe_import_folder`, `organize_clips`, `copy_metadata`, `normalize_metadata`, `probe_clip_properties`, `safe_relink`, `safe_unlink`, `link_proxy_checked`, `link_full_resolution_checked`, `set_clip_marks`, `clear_clip_marks`, `copy_clip_annotations`, and `media_pool_boundary_report`. **Safe ingest and organization**: safe import helpers validate paths, sequence patterns, frame ranges, and optional target folders before calling Resolve. `organize_clips` can move clips to existing folders or create missing folder paths explicitly. All helpers support dry-run where useful for planning. **Metadata and annotation workflows**: bulk metadata normalization, metadata copying, clip property probes, mark in/out bulk operations, and annotation copy now have agent-friendly wrappers over Resolve's lower-level clip APIs. **Documented support map**: added [`docs/kernels/media-pool-ingest-kernel.md`](docs/kernels/media-pool-ingest-kernel.md) so agents and users can inspect the supported, partial, unsupported, and version/page-dependent ingest boundaries directly. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with generated synthetic video, audio, still, image sequence, and non-media fixtures. Final probe result: 56 supported, 1 expected unsupported non-media text import, and 0 errors. The disposable project and generated media were cleaned up after report generation. ## v2.7.0 Timeline edit kernel expansion — turning the v2.6.0 duplicate helper into a broader, live-probed edit layer for clip duplication, linked audio, range edits, state copying, and capability reporting while preserving source media integrity. **Expanded `timeline.duplicate_clips` action**: duplication now supports `selected=True`, explicit `record_frame`, `track_offset`, and placement modes `same_time`, `offset`, `at_playhead`, `track_above`, `after_source`, and `next_gap`. `include_linked=True` duplicates linked audio and restores the video/audio link state. `copy_clips` is an alias for duplication, and `move_clips` duplicates successfully first before deleting the original source items. **Timeline range operations**: added `copy_range`, `duplicate_range`, `overwrite_range`, and `lift_range`. Range copies rebuild exact source segments with positioned append operations. `overwrite_range` deletes whole destination overlaps before appending. `lift_range` safely deletes whole matching items and requires explicit `allow_partial_item_delete=True` for whole-item deletion when a requested range only partially overlaps an item. **State copying groups**: duplicate/copy operations can now copy transform, crop, composite, audio, retime, dynamic zoom, scaling, stabilization, clip color, markers, flags, enabled state, cache, voice isolation, Fusion comps, grades, takes, and keyframes where Resolve exposes readable/writable item APIs. Transition cloning is accepted as a requested group but reported unsupported because Resolve's public scripting API does not expose transition cloning. **Capability and boundary probes**: added `timeline.edit_kernel_capabilities` for a maintained support map and `timeline.probe_edit_kernel_item` for read-only inspection of item methods, properties, keyframes, and linked items. Added `src/utils/timeline_kernel_live_probe.py` plus offline report/parser tests so future work can expand the technical boundary without guessing. **Documented limits**: added [`docs/kernels/timeline-edit-kernel.md`](docs/kernels/timeline-edit-kernel.md), which records the supported, partially supported, unsupported, and version/page-dependent surfaces. Known public-API boundaries include transition cloning, direct razor/split edits, true partial lifts, source-less item append cloning, and opaque speed-ramp internals. **Validation**: live validated against DaVinci Resolve Studio 20.3.2.9 with disposable projects and synthetic media. Final exhaustive probe result: 255 supported, 4 partially supported, 138 unsupported, 4 version/page dependent, and 0 errors. Static/unit checks include `tests/test_import.py`, `scripts/audit_api_parity.py`, `git diff --check`, the focused timeline/helper unit suite, and the full live duplicate/range/probe harness. ## v2.6.0 Timeline clip duplication — adding an Alt-drag-style helper for duplicating existing video timeline items without creating proxy media, renders, or source derivatives. **New `timeline.duplicate_clips` action**: `timeline(action="duplicate_clips")` duplicates video timeline items by re-appending the same Media Pool item with the same source trim via `MediaPool.AppendToTimeline([{clipInfo}])`. It accepts timeline item IDs from `timeline.get_items`, an optional `target_track_index`, and `record_frame_offset`; each result reports per-clip success and the duplicated timeline item ID when Resolve exposes or recovers it. **Resolve append-result hardening**: duplicate results now tolerate thin `AppendToTimeline` return objects that lack readable `GetUniqueId()` or `GetName()` methods, then scan the target video track to recover the real item handle. Bad inputs now return clean per-clip errors for non-video items, invalid offsets, and nonexistent target tracks. **Live-tested source trim semantics**: validation against Resolve Studio 20.3.2.9 confirmed that positioned `AppendToTimeline` treats `endFrame` as an exclusive source boundary in this workflow. `duplicate_clips` now uses `TimelineItem.GetDuration()` and `GetSourceStartFrame()` where available, so the duplicate preserves the original duration and source start. **Validation**: added `tests/live_duplicate_clips_validation.py`, which creates a disposable project, imports synthetic media, places a trimmed clip, duplicates it to another track, verifies record frame/duration/source trim/media identity, checks the invalid-track error path, and deletes the project. Focused unit coverage now includes anonymous append objects, source-start preference, video-only `mediaType`, and target-track ID recovery. ## v2.5.0 Three new compound tools for *authoring and conversationally executing* Resolve extensions: Fusion Fuse plugins, DCTL color transforms, and Resolve-page Lua/Python scripts. Plus a documentation pass on six adjacent Resolve extension systems. **New `fuse_plugin` tool**: generate, install, list, read, remove, and validate Fusion Fuse plugins (`.fuse`). **18 template kinds** spanning color (`color_matrix`, `per_pixel`, `channel_op`), geometric (`transform`, `spatial_warp`), text/shapes (`text_overlay`, `shape_generator`), source/temporal (`source_generator`, `time_displace`), filters (`builtin_blur`, `builtin_resize`, `variable_blur` SAT-based), modifiers (`modifier`, `point_modifier`), display shaders (`view_lut`, `dctl_kernel`), and reference (`controls_demo`, `notifychanged_demo`). Each generator produces ready-to-install Lua (or Lua + GLSL / Lua + DCTL) source that passes `luac -p` syntax checks across all option branches. **Live-verified in DaVinci Resolve Studio 20.3.2.9**: generated Fuses register on Resolve restart and instantiate via `comp:AddTool`; the `text_overlay` template was confirmed rendering glyphs into the viewer. The `view_lut` template supports `float`, `vec2`, `vec3_rgb`, and `vec4_rgba` shader parameter types. Includes a path-bug fix: corrected install path on macOS to `Fusion/Fuses/` (the SDK doc lists `Support/Fusion/Fuses/`, but Fusion's own `MapPath("Fuses:")` returns the path without `/Support/`). **New `dctl` tool**: generate, install, list, read, remove, and validate DCTL color-transform files plus ACES IDT/ODT transforms. **8 template kinds** — `transform`, `transform_alpha` (Resolve 19.1+ alpha modes), `transition` (with `TRANSITION_PROGRESS`), `matrix` (3x3 color matrix), `kernel` (TODO stub), `lut_apply` (wraps an external `.cube` LUT via `DEFINE_LUT`/`APPLY_LUT`), `aces_idt`, `aces_odt`. UI-parameter syntax covers all six DCTL UI types (slider float/int, value box, checkbox, combo, color picker) with optional tooltips. Per-template `suggested_category` so callers know whether to install to the regular LUT directory or the separate ACES Transforms tree. Subdir support with strict path-traversal guards. Validator catches missing entry points, brace imbalance, and float literals missing the required `f` suffix. Regular DCTLs pick up via `project_settings(action='refresh_luts')`; ACES DCTLs require a Resolve restart. **New `script_plugin` tool — conversational Lua/Python execution**: generate, install, and **execute** Resolve-page scripts that appear in the Workspace → Scripts menu. Two template kinds: `scaffold` (minimal stub) and `media_rules` (a comprehensive rules-and-variables DSL with sources, extract patterns, transforms, targets, actions, conditions, dry-run mode, external CSV/JSON data with exact/regex/fuzzy matching, and per-rule metadata — ~22k chars Lua engine and ~18k chars Python engine, both first-class). **Two new actions close the conversational loop**: `run_inline(source, language)` runs an ad-hoc Lua/Python snippet inside Resolve and streams stdout + return value back into the conversation; `execute(name, category, language)` runs an installed script the same way. Python uses subprocess with full stdout/stderr capture; Lua uses `fusion.RunScript()` against a temp file with completion-sentinel polling and `app:SetData()` bridge for return values (Resolve 20.x's `fusion.Execute()` is a no-op from the Python bridge — that quirk is encoded in the implementation). **Live-verified end-to-end** on Resolve Studio 20.3.2.9: Python `run_inline` returned project list and walked media pool; Lua `run_inline` enumerated `MapPath` symbols with stdout AND return value captured. **`list_templates` action** on all three new tools enumerates available kinds. **Resolve developer-package reference consolidation**: extension-system notes were consolidated back into README/SKILL guidance, while dedicated authoring docs remain in `docs/authoring/fuse-dctl-authoring.md` and `docs/authoring/script-plugin-authoring.md`. **Test coverage**: 185 offline tests across 7 modules (`test_fuse_dctl_authoring.py` and `test_script_plugin.py` both new in this release), all green in <2s. Includes hermetic round-trip tests with mocked install paths, DSL-coverage tests confirming every documented source/action/target/transform is in both Lua and Python engines, and Python subprocess execution tests with real captured stdout/stderr. **Compound tool count: 27 → 30**. Granular tool count unchanged at 328. ## v2.4.1 Release process hardening — documenting the version bump, validation, tag, and GitHub Release checklist. **Release checklist documented**: added `docs/process/release-process.md` with semantic version guidance, required version surfaces, validation requirements, tag/release commands, and release-note template. **Live-test requirement clarified**: Resolve behavior changes must be validated live with disposable projects and synthetic media before release. Docs-only releases do not require a live Resolve run when no behavior changed. ## v2.4.0 Timeline source range extraction — adding a compound workflow helper for frame-pull and conform preparation. **New `timeline.extract_source_frame_ranges` action**: `timeline(action="extract_source_frame_ranges")` scans every video clip on the current timeline and returns per-source frame ranges, clip occurrences, timeline positions, source offsets, applied handles, and timeline item IDs. Clip names prefer the basename from the Media Pool `File Path`, with audio extensions skipped by default. **Handle-aware source ranges**: fixed handles default to 24 frames. Passing `handles=0` switches to gap-only auto handles, using neighboring timeline gaps up to `gap_max` frames. Returned `source_range_final` and `frame_ranges` endpoints are inclusive/inclusive for downstream extraction tools. **Inclusive endpoint fix**: live validation caught and fixed the off-by-one where Resolve's exclusive source boundary was being returned as an inclusive final frame. A 48-frame synthetic clip with `handles=0` now returns `source_used_inclusive_end=47` and `source_range_final=[0, 47]`. **Live Resolve validation**: verified against DaVinci Resolve Studio 20.3.2.9 in a disposable project with synthetic media. Added unit coverage in `tests/test_extract_source_frame_ranges.py` for zero-handle and fixed-handle ranges. ## v2.3.4 Marker API hardening for Issue #34 — making the compound marker tools match the parameter shapes agents and users naturally send. **Marker parameter aliases fixed**: `timeline_markers`, `media_pool_item_markers`, and `timeline_item_markers` now accept `frame`, `frame_id`, and `frameId` consistently for add/get/update/delete operations. Marker lookup and delete paths also accept `customData` as an alias for `custom_data`. **Timeline marker ergonomics improved**: `timeline_markers(action="add")` can now add at the current playhead when no frame/timecode is provided, and also accepts explicit `timecode` input. Optional marker fields now have sensible defaults (`color="Blue"`, `name` from note or `"Marker"`, `note=""`, `duration=1`). **Resolve overload fallback**: marker creation first uses the documented six-argument `AddMarker(..., customData)` call, and falls back to the five-argument form when `customData` is empty and a Resolve build rejects the optional parameter. **Live Resolve validation**: verified against DaVinci Resolve Studio 20.3.2.9 with `tests/live_marker_validation.py`. The harness creates a disposable project, imports synthetic media, inserts a visible timeline generator, and live-tests timeline, media-pool-item, and timeline-item marker add/get/update/delete alias paths. A `--keep-open` mode leaves a marked timeline open for visual inspection. ## v2.3.3 Granular layer hardening — closing exposure gaps and dropped-dict-key bugs surfaced by an exhaustive parity audit of every documented Resolve scripting method against both server layers. **Cloud project helper rewritten** (Critical): `src/utils/cloud_operations.py` was calling `pm.CreateCloudProject(project_name, folder_path)` with positional arguments — but the documented Resolve API signature is `CreateCloudProject({cloudSettings})`, a single dict. Same bug affected `ImportCloudProject` and `RestoreCloudProject`. Helper now builds proper `{cloudSettings}` dicts and exposes all 5 documented keys (`PROJECT_NAME`, `PROJECT_MEDIA_PATH`, `IS_COLLAB`, `SYNC_MODE`, `IS_CAMERA_ACCESS`) per docs lines 576-594. Granular wrappers (`create_cloud_project_tool`, `import_cloud_project_tool`, `restore_cloud_project_tool`) updated to expose the full settings surface; `load_cloud_project_tool` added (was missing entirely from granular). **Silent-drop bugs fixed** (Critical): - **`render_with_quick_export()` (granular)** previously dropped the documented `{param_dict}` (TargetDir, CustomName, VideoQuality, EnableUpload). Now forwards all four keys per docs line 179. - **`timeline_create_compound_clip()` (granular)** previously dropped the documented `{clipInfo}` dict (`name`, `startTimecode`). Now exposes both keys per docs line 369. **Missing granular tools added**: - **`append_to_timeline`** — both simple `clip_ids` form and positioned `clip_infos` form (`MediaPool.AppendToTimeline` was completely absent from granular layer; only compound had it). - **`auto_sync_audio`** — with proper `{audioSyncSettings}` dict mapping per docs lines 600-614 (`sync_mode`, `channel_number` with `'automatic'`/`'mix'` aliases, `retain_embedded_audio`, `retain_video_metadata`). - **`load_cloud_project_tool`** — was missing entirely; compound had it. - **`rename_color_group`** — wraps `ColorGroup.SetName` (compound had it via `color_group(action="set_name")` but no granular tool). **Removed 4 undocumented cloud method wrappers**: - `get_cloud_projects` resource → `GetCloudProjectList` not in API docs - `export_project_to_cloud_tool` → `ExportToCloud`/`ExportProjectToCloud` not in API docs - `add_user_to_cloud_project_tool` → `AddUserToCloudProject` not in API docs - `remove_user_from_cloud_project_tool` → `RemoveUserFromCloudProject` not in API docs **Removed 9 legacy granular gallery tools** that wrapped undocumented or renamed methods (`gallery.GetAlbums()`, `gallery.CreateAlbum()`, `still.GetTimecode()`, `still.IsGrabbed()`, etc.). The proper documented Gallery and GalleryStillAlbum wrappers (lines 743+ of the previous gallery.py — all 14 of those, e.g. `get_gallery_still_albums`, `create_gallery_still_album`, `import_stills_to_album`, `export_stills_from_album`, `get_album_stills`, `set_still_label`) cover the documented API surface and remain. Removed: `get_color_presets`, `save_color_preset`, `apply_color_preset`, `delete_color_preset`, `create_color_preset_album`, `delete_color_preset_album`, `export_lut`, `get_lut_formats`, `export_all_powergrade_luts`. **Removed 2 granular project optimized-media tools** that wrapped undocumented Resolve methods (`Project.GenerateOptimizedMedia`, `Project.DeleteOptimizedMedia`, `MediaPool.SetClipSelection` — none in API docs). Removed: `generate_optimized_media`, `delete_optimized_media`. Use the Resolve UI for optimized-media generation; `set_optimized_media_mode` (which uses the documented `Project.SetSetting("OptimizedMediaMode", ...)`) is preserved. **Deprecated method call fixed**: `timeline(action="get_items_in_track")` was calling the deprecated `tl.GetItemsInTrack()` form (docs line 989, marked deprecated) instead of the supported `tl.GetItemListInTrack()` (line 350). Every other call site already used the correct form. **New: API parity CI guard** at `scripts/audit_api_parity.py`. Parses `docs/reference/resolve_scripting_api.txt` and verifies (1) no `from api.X` broken imports remain, (2) every documented Resolve method appears somewhere in `src/`, (3) wrappers calling undocumented methods are flagged for review. Includes an allowlist for legitimate undocumented-but-real Resolve API surface (Fusion compositing API, UIManager methods like `OpenProjectSettings`/`LoadUILayout`/`SaveUILayout`, internal type-discrimination helpers like `TimelineItem.GetType`/`GetMediaType`). Run with `python3 scripts/audit_api_parity.py` — currently passes all three checks cleanly. **Tool count: 328 granular tools** (was 354 before v2.3.2; net change since v2.3.1 is −26 broken/duplicate/undocumented tools removed and +4 missing tools added). 20 new unit tests against Resolve stubs covering the cloud settings builder, audio sync settings builder, and AppendToTimeline clipInfo builder. All 41 tests pass without a live Resolve connection. **Live disposable Resolve validation**: every new and changed v2.3.3 granular tool was exercised against DaVinci Resolve Studio 20.3.2.9 in a disposable project with synthetic temp media via `tests/live_v233_validation.py`. 10/10 checks passed: `append_to_timeline` (simple + positioned + failure path), `auto_sync_audio` (settings dict + invalid input rejection), `import_media` image-sequence form, `timeline_create_compound_clip` (info dict forwarded — compound clip created with explicit name), `rename_color_group` (renamed a real color group), `render_with_quick_export` (params dict forwarded — Resolve's structured `{JobStatus, Error}` response confirms the dict reached it), and the compound-side `GetItemListInTrack` deprecated→supported fix. ## v2.3.2 API parity sweep — closing documented overloads and dropped parameters that the v2.3.1 audit surfaced. - **Positioned `CreateTimelineFromClips` via `clip_infos`** — `media_pool(action="create_timeline_from_clips", params={"clip_infos": [...]})` and the granular `create_timeline_from_clips(clip_infos=[...])` now expose the documented `MediaPool.CreateTimelineFromClips(name, [{clipInfo}, ...])` overload (4 keys: `mediaPoolItem`, `startFrame`, `endFrame`, `recordFrame`) - **Image-sequence `ImportMedia` via `clip_infos`** — both layers now expose `MediaPool.ImportMedia([{FilePath, StartIndex, EndIndex}, ...])` for DPX/EXR/etc. sequence imports. PascalCase keys preserved per Resolve docs - **Positioned `AddItemListToMediaPool` via `item_infos`** — `media_storage(action="import_to_pool", params={"item_infos": [{media, startFrame, endFrame}, ...]})` and granular `add_items_to_media_pool_from_storage(item_infos=[...])` now expose the documented `MediaStorage.AddItemListToMediaPool([{itemInfo}, ...])` overload - **`Timeline.AddTrack` dict form** — replaced the legacy bare-string `sub_type` argument with the documented `newTrackOptions` dict (`audio_type`, `index`). Granular `timeline_add_track(track_type, audio_type=, index=)` and compound `timeline(action="add_track", params={"track_type", "options": {audio_type, index}})` - **`CreateSubtitlesFromAudio` actually wired up** — granular `timeline_create_subtitles_from_audio` previously advertised `language` and `preset` parameters then silently dropped them. Now maps user strings (e.g. `"korean"`, `"netflix"`, `"double"`) to `resolve.AUTO_CAPTION_*` constants per docs lines 720-761, and exposes the missing `chars_per_line`, `line_break`, `gap` keys - **Granular `import_media` no longer crashes** — the granular `import_media` tool was importing from a deleted `api.media_operations` module and would throw `ModuleNotFoundError` on first call. Rewritten to call `MediaPool.ImportMedia` directly and to share the new `clip_infos` overload - **`SetRenderSettings` docstring completeness** — granular `set_render_settings` now documents all 27 keys per docs lines 765-799 (previously omitted `EncodingProfile`, `MultiPassEncode`, `AlphaMode`, `NetworkOptimization`, `PixelAspectRatio`, `ClipStartFrame`, `TimelineStartTimecode`, `ReplaceExistingFilesInPlace`) - **Removed 18 broken granular tools (+ 7 broken resources)** that imported from a deleted `api.*` namespace and would crash with `ModuleNotFoundError` on first call. All 25 had working equivalents elsewhere or wrapped undocumented Resolve methods. Granular tool count is now **336** (was 354). Migration map for any caller that was hitting them: - `delete_media` → `media_pool(action="delete_clips")` - `move_media_to_bin` → `media_pool(action="move_clips")` - `auto_sync_audio` (granular tool) → `media_pool(action="auto_sync_audio")` - `unlink_clips` → `media_pool(action="unlink")` - `relink_clips` → `media_pool(action="relink")` - `create_bin` → `media_pool(action="add_subfolder")` - `list_media_pool_bins` (resource) → `folder(action="get_subfolders")` - `get_media_pool_bin_contents` (resource) → `folder(action="get_clips")` - `get_timeline_tracks` (resource) → `timeline(action="get_track_count")` + `timeline(action="get_items_in_track")` - `create_empty_timeline` → `media_pool(action="create_timeline")` - `delete_timeline` → `media_pool(action="delete_timelines")` - `add_marker` (granular timeline tool) → `timeline_markers(action="add")` - `add_clip_to_timeline` → `media_pool(action="append_to_timeline")` - `apply_lut` (granular graph tool) → `graph(action="set_lut")` - `copy_grade` → `timeline_item_color(action="copy_grades")` - `get_render_presets` (resource) → `render(action="list_presets")` - `add_to_render_queue` → `render(action="add_job")` - `start_render` (granular project tool) → `render(action="start")` - `get_render_queue_status` (resource) → `render(action="list_jobs")` + `render(action="get_job_status")` - `clear_render_queue` (granular project tool) → `render(action="delete_all_jobs")` - `create_sub_clip`, `get_current_color_node`, `get_color_wheel_params`, `set_color_wheel_param`, `add_node`: removed — these wrapped undocumented Resolve methods that were never exposed in the official scripting API. No replacement exists; use the Resolve UI for now. ## v2.3.1 - **Positioned `AppendToTimeline` via `clip_infos`** — `media_pool(action="append_to_timeline", params={"clip_infos": [...]})` now exposes the documented `MediaPool.AppendToTimeline([{clipInfo}, ...])` overload, accepting per-entry `clip_id`/`media_pool_item_id`, `start_frame`, `end_frame`, `record_frame`, `track_index`, and optional `media_type`. Each appended item returns its `timeline_item_id` for follow-up Fusion ops - **Positioned append failure reporting** — the same call now returns `{"error": ...}` when Resolve fails to produce valid timeline items, including falsey `AppendToTimeline()` results and returned item handles without a timeline item id - **Live disposable Resolve validation** — verified the fix against DaVinci Resolve Studio 20.3.2 with synthetic temp media in a disposable project: valid `clip_infos` append returned `success`, `count=1`, and `timeline_item_id`; invalid `clip_infos` calls returned errors ## v2.3.0 - **Resolve 20.2.2 API sync** — added the 12 scripting methods introduced across Resolve 20.0-20.2.2, with compatibility guards so older Resolve builds return clear "requires Resolve 20.x" errors instead of crashing - **Resolve 20 live validation** — revalidated the new API surface against DaVinci Resolve Studio 20.3.2, bringing live-tested coverage to 331/336 methods (98.5%) - **Official scripting docs refreshed** — `docs/reference/resolve_scripting_api.txt` now tracks the Resolve 20 scripting README bundled with the installed 20.3.2 developer package - **AI skill reference updated** — merged PR #30's `docs/SKILL.md` and updated it for the Resolve 20 method count, granular server, version guards, and source media integrity guidance - **Stale Resolve handle recovery** — both server modes now validate cached Resolve handles and reconnect cleanly after Resolve restarts or Project Manager transitions ## v2.2.0 - **Granular server modularized internally** — `src/resolve_mcp_server.py` is now a thin entrypoint, with the granular implementation split across `src/granular/resolve_control.py`, `project.py`, `timeline.py`, `timeline_item.py`, `media_pool.py`, `folder.py`, `media_pool_item.py`, `gallery.py`, `graph.py`, and `media_storage.py` - **Installer now emits env blocks for every generated stdio config** — standard `.mcp.json`, VS Code `.vscode/mcp.json`, Zed `context_servers`, and manual snippets now include `RESOLVE_SCRIPT_API`, `RESOLVE_SCRIPT_LIB`, and `PYTHONPATH` - **Windows Resolve 20.3 hardening** — on Windows, the installer also emits `PYTHONHOME` derived from the selected interpreter's base install so Resolve binds against the intended Python instead of a newer globally registered one - **Windows stdio transport hardening** — server entrypoints now run FastMCP through strict LF-only stdio wrappers to avoid client disconnects caused by platform newline translation in Windows pipes - **`set_cdl` accepts arrays cleanly** — both compound and granular servers now normalize JSON array, tuple, and numeric CDL values into Resolve's required string form like `"1.0 1.0 1.0"` - **`fusion_comp` can target timeline item comps** — node graph actions can now operate on a clip's Fusion comp via `clip_id`, `timeline_item_id`, or `timeline_item`, and `bulk_set_inputs` applies scoped input changes across multiple timeline comps - **`python src/server.py --full` now stays intact** — the compound entrypoint now correctly launches the granular server instead of importing it and exiting ## v2.1.0 - **New `fusion_comp` tool** — 20-action tool exposing the full Fusion composition node graph API. Add/delete/find nodes, wire connections, set/get parameters, manage keyframes, control undo grouping, set render ranges, and trigger renders — all on the currently active Fusion page composition - **`timeline_item_fusion` cache actions** — added `get_cache_enabled` and `set_cache` actions for Fusion output cache control directly on timeline items - **Fusion node graph reference** — docstring includes common tool IDs (Merge, TextPlus, Background, Transform, ColorCorrector, DeltaKeyer, etc.) for discoverability ## v2.0.9 - **Cross-platform sandbox path redirect** — `_resolve_safe_dir()` now handles macOS (`/var/folders`, `/private/var`), Linux (`/tmp`, `/var/tmp`), and Windows (`AppData\Local\Temp`) sandbox paths that Resolve can't write to. Redirects to `~/Documents/resolve-stills` instead of Desktop - **Auto-cleanup for `grab_and_export`** — exported files are read into the response (DRX as inline text, images as base64) then deleted from disk automatically. Zero file accumulation. Pass `cleanup: false` to keep files on disk - **Both servers in sync** — `server.py` and `resolve_mcp_server.py` now share the same version and both use `_resolve_safe_dir()` for all Resolve-facing temp paths (project export, LUT export, still export) ## v2.0.8 - **New `grab_and_export` action on `gallery_stills`** — combines `GrabStill()` + `ExportStills()` in a single atomic call, keeping the live GalleryStill reference for reliable export. Returns a file manifest with exported image + companion `.drx` grade file - **Format fallback chain** — if the requested format fails, automatically retries with tif then dpx - **macOS sandbox path redirect** — `/var/folders` and `/private/var` paths are redirected to `~/Desktop/resolve-stills` since Resolve's process can't write to sandboxed temp directories - **Key finding documented** — `ExportStills` requires the Gallery panel to be visible on the Color page. All 9 supported formats (dpx, cin, tif, jpg, png, ppm, bmp, xpm, drx) produce a companion `.drx` grade file alongside the image ## v2.0.7 - **Security: path traversal protection for layout preset tools** — `export_layout_preset`, `import_layout_preset`, and `delete_layout_preset` now validate that resolved file paths stay within the expected Resolve presets directory, preventing path traversal via crafted preset names - **Security: document destructive tool risk** — added Security Considerations section noting that `quit_app`/`restart_app` tools can terminate Resolve; MCP clients should require user confirmation before invoking ## v2.0.6 - **Fix color group operations crash** — `timeline_item_color` unpacked `_check()` as `(proj, _, _)` but `_check()` returns `(pm, proj, err)`, so `proj` got the ProjectManager instead of the Project, crashing `assign_color_group` and `remove_from_color_group` ## v2.0.5 - **Lazy connection recovery** — full server (`--full` mode) now auto-reconnects and auto-launches Resolve, matching the compound server behavior - **Null guards on all chained API calls** — `GetProjectManager()`, `GetCurrentProject()`, `GetCurrentTimeline()` failures now return clear errors instead of `NoneType` crashes - **Helper functions** — `get_resolve()`, `get_project_manager()`, `get_current_project()` replace 178 boilerplate blocks ## v2.0.4 - **Fix apply_grade_from_drx parameter** — renamed `mode` to `grade_mode` to match Resolve API; corrected documentation from replace/append to actual keyframe alignment modes (0=No keyframes, 1=Source Timecode aligned, 2=Start Frames aligned) - **Backward compatible** — still accepts `mode` for existing clients, `grade_mode` takes precedence ## v2.0.3 - **Fix GetNodeGraph crash** — `GetNodeGraph(0)` returns `False` in Resolve; now calls without args unless `layer_index` is explicitly provided - **Falsy node graph check** — guard checks `not g` instead of `g is None` to catch `False` returns ## v2.0.2 - **Antigravity support** — Google's agentic AI coding assistant added as 10th MCP client - **Alphabetical client ordering** — MCP_CLIENTS list sorted for easier maintenance ## v2.0.1 - **26-tool compound server** — all 324 API methods grouped into 26 context-efficient tools (default) - **Universal installer** — single `python install.py` for macOS/Windows/Linux, 10 MCP clients - **Dedicated timeline_item actions** — retime/speed, transform, crop, composite, audio, keyframes with validation - **Lazy Resolve connection** — server starts instantly, connects when first tool is called - **Bug fixes** — CreateMagicMask param type, GetCurrentClipThumbnailImage args, Python 3.13+ warning