davinci-resolve-mcp 2.57.0 → 2.57.2

package/AGENTS.md

@@ -69,6 +69,10 @@ semantics.
 - Release checklist and validation rules: `docs/process/release-process.md`
 - Kernel workflow support maps: `docs/kernels/`
 - API coverage and live-test status: `docs/reference/api-coverage.md`
+- Blackmagic-facing API gaps/bugs (generated from `api_truth`):
+  `docs/reference/api-limitations.md` — when you document a new Resolve API
+  limitation, add a `submit`-tagged entry to `src/utils/api_truth.py` and
+  regenerate with `scripts/gen_api_limitations.py` (a drift guard enforces it)
 - Bundled Resolve API text: `docs/reference/resolve_scripting_api.txt`
 
 ## Key Paths

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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.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.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.57.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.57.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)
@@ -168,3 +168,6 @@ Samuel Gursky (samgursky@gmail.com)
 
 - [@rgxdev](https://github.com/rgxdev) — configurable Media Pool inventory walk
   (exclude bins + inventory limit), [#69](https://github.com/samuelgursky/davinci-resolve-mcp/pull/69) (v2.53.0)
+- [@swayll](https://github.com/swayll) — Source Track Selector investigation
+  ([#74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)); confirmed
+  + documented API limitation (v2.57.1)

package/docs/process/release-process.md

@@ -29,6 +29,11 @@ Every release bump must update all version surfaces:
 - README version badge
 - README current stats or latest-release summary when they changed
 - `CHANGELOG.md` latest release entry
+- `docs/reference/api-limitations.md` when any `submit`-tagged entry in
+  `src/utils/api_truth.py` was added or changed (a newly documented Resolve API
+  gap/bug, a closed won't-fix issue, etc.). Regenerate it — do not hand-edit:
+  `venv/bin/python scripts/gen_api_limitations.py`. The
+  `tests.test_api_limitations_doc` drift guard fails the suite if it is stale.
 - `docs/SKILL.md` when tool discovery, examples, or behavior changed
 - `docs/guides/control-panel.md` when the control panel UI changed, plus
   regenerated screenshots: start the panel against a project with analysis
@@ -48,6 +53,7 @@ Always run static checks before release:
 ```bash
 venv/bin/python tests/test_import.py
 venv/bin/python scripts/audit_api_parity.py
+venv/bin/python scripts/gen_api_limitations.py --check
 venv/bin/python -m unittest tests.test_static_undefined_names tests.test_action_list_drift tests.test_panel_docs_drift
 node bin/davinci-resolve-mcp.mjs --help
 node bin/davinci-resolve-mcp.mjs --version
@@ -86,6 +92,17 @@ env RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci R
   venv/bin/python tests/live_v233_validation.py
 ```
 
+For Fusion comp changes (masks, Text+/title text), run the issue #73 harness,
+which creates a disposable Fusion-title project, exercises `add_fusion_mask` and
+`set_text_plus` / `get_text_plus`, and deletes the project:
+
+```bash
+env RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting" \
+  RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so" \
+  PYTHONPATH="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting/Modules" \
+  venv/bin/python tests/live_fusion_mask_title_validation.py
+```
+
 One-off live harnesses are acceptable during review, but reusable coverage
 should live under `tests/`. Do not commit generated media or disposable project
 artifacts.

package/docs/reference/api-coverage.md

@@ -44,6 +44,25 @@ maps `shot_descriptions[shot_index]` onto Media Pool shot markers, and triggers
 metadata writeback for that clip. Works with any MCP client whose chat model
 is vision-capable; no `sampling/createMessage` support required.
 
+Some Edit-page behavior is simply not reachable through public scripting. The
+**Source/Auto Track Selector** (the patch panel that chooses which video track a
+clip lands on) has no get/set in the API, and the `Insert*IntoTimeline` family
+(titles, generators, OFX, Fusion comps) takes no `trackIndex` — they always drop
+onto the selector's current target (V1 in practice). Locking lower tracks does
+not redirect the insert; it just makes the insert fail. Titles and generators
+can't be relocated afterward either, since they have no `MediaPoolItem` for
+`AppendToTimeline`/`MoveClips` to act on. For media-backed clips you *can* target
+a track via `MediaPool.AppendToTimeline`'s clipInfo `trackIndex` (exposed as
+`media_pool.append_to_timeline` with `clip_infos`). This limitation is recorded
+in the verified `api_truth` ledger (query `resolve_control api_truth "track"`);
+see issue #74.
+
+The full catalogue of verified scripting-API gaps and bugs — curated for
+submission to Blackmagic Design's developer feedback — lives in
+[api-limitations.md](api-limitations.md). It is generated from the `submit`-tagged
+`api_truth` entries (`scripts/gen_api_limitations.py`) and kept in sync by a drift
+guard, so it never goes stale.
+
 | Class | Methods | Tools | Description |
 |-------|---------|-------|-------------|
 | Resolve | 22 | 22 | App control, pages, layout presets, render/burn-in presets, keyframe mode |

package/docs/reference/api-limitations.md

@@ -0,0 +1,141 @@
+# DaVinci Resolve Scripting API — Limitations & Feedback
+
+<!-- GENERATED FILE — do not edit by hand.
+     Source: src/utils/api_truth.py (entries tagged `submit`).
+     Regenerate: venv/bin/python scripts/gen_api_limitations.py -->
+
+This is a curated, behaviorally-verified list of DaVinci Resolve scripting
+API gaps and bugs encountered while building this MCP server, intended for
+submission to Blackmagic Design's developer feedback. Every item was
+observed against live Resolve; each entry notes the current workaround (or
+that none exists).
+
+**Verified on:** DaVinci Resolve Studio 21.0.0
+
+**Totals:** 6 missing capabilities, 9 bugs / unreliable behaviors.
+
+The authoritative source is the runtime-queryable `api_truth` ledger
+(`resolve_control api_truth "<query>"`); this document is generated from
+it and stays in sync via a drift guard.
+
+## Missing Capabilities (please add)
+
+Functionality that exists in the Resolve UI but has no scripting API
+equivalent, blocking full automation.
+
+### Timeline.GetTimelineByName
+
+- **Object:** `Project`
+- **Behavior:** Does not exist. Timelines are looked up by index.
+- **Workaround / current handling:** Iterate GetTimelineByIndex(1..GetTimelineCount()).
+- **Tags:** missing-method, timeline
+
+### Source Track Selector / destination track for Insert*IntoTimeline
+
+- **Object:** `Timeline`
+- **Behavior:** There is no API to read or set the Source/Auto Track Selector (the Edit-page patch panel that picks the destination track). InsertTitleIntoTimeline, InsertFusionTitleIntoTimeline, InsertGeneratorIntoTimeline, InsertFusionGeneratorIntoTimeline, InsertOFXGeneratorIntoTimeline and InsertFusionCompositionIntoTimeline take no trackIndex and always drop the clip on the selector's current target (V1 in practice). Locking lower video tracks does NOT redirect the insert — verified live on 21.0.0: locking V1 makes the insert FAIL rather than land on V2. Titles/generators also can't be moved afterward (no MediaPoolItem, so AppendToTimeline clipInfo and MoveClips don't apply).
+- **Workaround / current handling:** Accept the limitation for titles/generators (insert lands on V1). For clips that DO have a MediaPoolItem, target a track with MediaPool.AppendToTimeline's clipInfo 'trackIndex' instead (exposed as media_pool append_to_timeline clip_infos). See issue #74.
+- **Reference:** [issue #74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)
+- **Tags:** missing-method, timeline, title, generator, track
+
+### Per-clip audio channel-format conversion (Stereo<->Mono)
+
+- **Object:** `MediaPoolItem / TimelineItem`
+- **Behavior:** No scripting method converts an individual clip's audio channel format. ConvertTimelineToStereo is timeline-wide, and CreateStereoClip builds a 3D *visual* stereoscopic clip, not an audio mono->stereo change. The Edit-page 'Clip Attributes > Audio' channel mapping is UI-only.
+- **Workaround / current handling:** Use the supported surface: timeline add_track with audioType (create mono/stereo tracks), get_track_sub_type (query format), convert_to_stereo (timeline-wide), and timeline_item get_source_audio_channel_mapping. Per-clip conversion is not possible. See issue #73.
+- **Reference:** [issue #73](https://github.com/samuelgursky/davinci-resolve-mcp/issues/73)
+- **Tags:** missing-method, audio, channel
+
+### Native multicam clip creation
+
+- **Object:** `MediaPool`
+- **Behavior:** There is no method to create a native multicam clip from a set of angles. Angles can be stacked onto tracks programmatically, but the multicam-clip conversion is a UI-only step.
+- **Workaround / current handling:** Prepare a stacked timeline (media_pool setup_multicam_timeline) and finish the multicam-clip conversion in the Resolve UI.
+- **Tags:** missing-method, media-pool, multicam
+
+### Transition create / copy / clone
+
+- **Object:** `Timeline / TimelineItem`
+- **Behavior:** The scripting API exposes no method to add, read, copy, or clone an edit transition (cross-dissolve, etc.). Transitions applied in the UI are invisible to and unmodifiable by scripts.
+- **Workaround / current handling:** Apply/duplicate transitions in the Resolve UI; no scripted equivalent exists.
+- **Tags:** missing-method, timeline, transition
+
+### Cloud project enumeration / export / user management
+
+- **Object:** `ProjectManager`
+- **Behavior:** Only CreateCloudProject, LoadCloudProject, ImportCloudProject and RestoreCloudProject exist. There is no GetCloudProjectList (list available cloud projects), no ExportToCloud, and no Add/RemoveUserToCloudProject — so cloud collaboration can't be fully automated.
+- **Workaround / current handling:** Drive cloud project listing, export, and collaborator management from the Resolve UI; only create/load/import/restore are scriptable.
+- **Tags:** missing-method, project, cloud
+
+## Bugs / Unreliable Behavior (please fix)
+
+Methods that exist but misbehave — silent failures, unreliable return
+values, or automation-hostile modal prompts.
+
+### MediaPool.AutoSyncAudio
+
+- **Object:** `MediaPool`
+- **Signature:** `(clips, settings) -> bool`
+- **Behavior:** The boolean return does not reflect whether clips actually linked, and string enum keys in `settings` are silently rejected (the call returns False).
+- **Workaround / current handling:** Resolve the AUDIO_SYNC_* enum constants via the live resolve handle, and verify by reading each clip's 'Synced Audio' property (see verify_by_readback).
+- **Tags:** unreliable-return, silent-failure, audio, enum
+
+### Timeline.CreateSubtitlesFromAudio
+
+- **Object:** `Timeline`
+- **Signature:** `(autoCaptionSettings) -> bool`
+- **Behavior:** Same failure mode as AutoSyncAudio: the autoCaptionSettings dict is keyed by resolve.SUBTITLE_* enum constants with resolve.AUTO_CAPTION_* enum values, so plain string keys like {'language': 'korean'} are silently rejected (returns False, no subtitle track created). The boolean is also unreliable.
+- **Workaround / current handling:** Resolve the SUBTITLE_*/AUTO_CAPTION_* constants via the live resolve handle (server._normalize_auto_caption_settings) and verify by reading the timeline's subtitle track count before/after (server._safe_create_subtitles).
+- **Tags:** unreliable-return, silent-failure, subtitle, enum
+
+### ProjectManager CloudProject family (Create/Load/Import/RestoreCloudProject)
+
+- **Object:** `ProjectManager`
+- **Signature:** `(..., cloudSettings) -> Project | bool`
+- **Behavior:** All four take an enum-keyed {cloudSettings} dict (resolve.CLOUD_SETTING_* keys, resolve.CLOUD_SYNC_* sync-mode values). Plain string keys are silently rejected, so a settings dict built from human-readable keys yields no project / False.
+- **Workaround / current handling:** Resolve the CLOUD_SETTING_*/CLOUD_SYNC_* constants via the live resolve handle (server._normalize_cloud_settings) before calling, and treat the bool return from Import/RestoreCloudProject as advisory.
+- **Tags:** silent-failure, project, cloud, enum
+
+### Timeline.Export
+
+- **Object:** `Timeline`
+- **Signature:** `(fileName, exportType, exportSubtype) -> bool`
+- **Behavior:** exportType/exportSubtype must be resolve.EXPORT_* enum *values* resolved from the live handle. A JSON/MCP caller cannot pass a live enum, and a plain string ('fcpxml', or even the constant name 'EXPORT_FCPXML_1_10') is silently rejected with no file written.
+- **Workaround / current handling:** Map a friendly format/subtype to the EXPORT_* constant and resolve it against the live handle (server._timeline_export_spec) before calling; verify the output file exists afterward.
+- **Tags:** silent-failure, timeline, export, enum
+
+### ProjectManager.DeleteProject
+
+- **Object:** `ProjectManager`
+- **Signature:** `(projectName) -> bool`
+- **Behavior:** Returns False (no deletion) when the target project is, or recently was, the current project, and is flaky on the first attempt — so a single bool() call leaves the project undeleted with no useful error.
+- **Workaround / current handling:** Load/close away from the target first, then retry; use src/utils/project_cleanup.py:delete_project_safely.
+- **Tags:** unreliable-return, project, flaky
+
+### Composition.Paste
+
+- **Object:** `Fusion Composition`
+- **Behavior:** Passing tool.SaveSettings()'s in-memory table to Paste() / LoadSettings() fails across the Python bridge with an OrderedDict/null-argument error and creates no node, while reporting nothing useful.
+- **Workaround / current handling:** Duplicate via AddTool(RegID) + SaveSettings(path)/LoadSettings(path) through a temp .setting FILE, which round-trips reliably. Identify the new node by name diff.
+- **Tags:** fusion, bridge, silent-failure
+
+### FlowView.SetPos / FlowView.GetPosTable
+
+- **Object:** `Fusion FlowView (comp.CurrentFrame.FlowView)`
+- **Behavior:** Node positions are read/written through the FlowView, not the tool. SetPos returns nothing reliable; GetPosTable returns a 1-indexed table (or dict/tuple depending on bridge).
+- **Workaround / current handling:** Use comp.CurrentFrame.FlowView.SetPos(tool, x, y); confirm with GetPosTable and a liberal position parser.
+- **Tags:** fusion, unreliable-return
+
+### MediaPoolItem.GetClipProperty('Transcription')
+
+- **Object:** `MediaPoolItem`
+- **Behavior:** Returns a PREVIEW of the transcription that ends in an ellipsis when the full transcript is longer than the property exposes.
+- **Workaround / current handling:** Treat a trailing ellipsis as truncation (see media_pool_item get_transcription's `truncated` flag).
+- **Tags:** transcription, truncation
+
+### ProjectManager.CreateProject (with a dirty Untitled project)
+
+- **Object:** `ProjectManager`
+- **Behavior:** Returns None and pops a modal 'Save Current Project' dialog when the current unsaved/Untitled project blocks the switch. SaveProject() on an Untitled project re-triggers the same modal.
+- **Workaround / current handling:** CloseProject(current) to discard the untitled project without a prompt, then CreateProject; restore with LoadProject afterward.
+- **Tags:** project, modal, silent-failure

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.57.0"
+VERSION = "2.57.2"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

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

package/scripts/gen_api_limitations.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Generate the Blackmagic-facing DaVinci Resolve API limitations report.
+
+The single source of truth is the ``submit``-tagged entries in
+``src/utils/api_truth.py`` (see ``submittable_limitations``). This script renders
+them into ``docs/reference/api-limitations.md`` — a curated, behaviorally-verified
+list that can be submitted to Blackmagic Design's developer feedback, split into
+capabilities they should *add* and behaviors they should *fix*.
+
+The output is deterministic (no timestamps) so ``tests.test_api_limitations_doc``
+can assert the committed file matches. Regenerate after editing any ``submit``
+entry:
+
+    venv/bin/python scripts/gen_api_limitations.py
+
+Run with ``--check`` to fail (exit 1) when the committed doc is stale.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from src.utils.api_truth import (  # noqa: E402
+    VERIFIED_ON,
+    submittable_limitations,
+)
+
+DOC_PATH = REPO_ROOT / "docs" / "reference" / "api-limitations.md"
+ISSUE_URL = "https://github.com/samuelgursky/davinci-resolve-mcp/issues"
+
+
+def _render_entry(entry: dict) -> str:
+    lines = [f"### {entry['symbol']}", ""]
+    obj = entry.get("object")
+    if obj:
+        lines.append(f"- **Object:** `{obj}`")
+    sig = entry.get("signature")
+    if sig:
+        lines.append(f"- **Signature:** `{sig}`")
+    lines.append(f"- **Behavior:** {entry['reality']}")
+    rec = entry.get("recommended")
+    if rec:
+        lines.append(f"- **Workaround / current handling:** {rec}")
+    issue = entry.get("issue")
+    if issue is not None:
+        lines.append(f"- **Reference:** [issue #{issue}]({ISSUE_URL}/{issue})")
+    tags = entry.get("tags")
+    if tags:
+        lines.append(f"- **Tags:** {', '.join(tags)}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render() -> str:
+    groups = submittable_limitations()
+    missing = groups["missing"]
+    bugs = groups["bug"]
+
+    out = [
+        "# DaVinci Resolve Scripting API — Limitations & Feedback",
+        "",
+        "<!-- GENERATED FILE — do not edit by hand.",
+        "     Source: src/utils/api_truth.py (entries tagged `submit`).",
+        "     Regenerate: venv/bin/python scripts/gen_api_limitations.py -->",
+        "",
+        "This is a curated, behaviorally-verified list of DaVinci Resolve scripting",
+        "API gaps and bugs encountered while building this MCP server, intended for",
+        "submission to Blackmagic Design's developer feedback. Every item was",
+        "observed against live Resolve; each entry notes the current workaround (or",
+        "that none exists).",
+        "",
+        f"**Verified on:** {VERIFIED_ON}",
+        "",
+        f"**Totals:** {len(missing)} missing capabilities, {len(bugs)} bugs / "
+        "unreliable behaviors.",
+        "",
+        "The authoritative source is the runtime-queryable `api_truth` ledger",
+        "(`resolve_control api_truth \"<query>\"`); this document is generated from",
+        "it and stays in sync via a drift guard.",
+        "",
+        "## Missing Capabilities (please add)",
+        "",
+        "Functionality that exists in the Resolve UI but has no scripting API",
+        "equivalent, blocking full automation.",
+        "",
+    ]
+    for entry in missing:
+        out.append(_render_entry(entry))
+
+    out += [
+        "## Bugs / Unreliable Behavior (please fix)",
+        "",
+        "Methods that exist but misbehave — silent failures, unreliable return",
+        "values, or automation-hostile modal prompts.",
+        "",
+    ]
+    for entry in bugs:
+        out.append(_render_entry(entry))
+
+    return "\n".join(out).rstrip() + "\n"
+
+
+def main(argv: list[str]) -> int:
+    content = render()
+    if "--check" in argv:
+        current = DOC_PATH.read_text() if DOC_PATH.exists() else ""
+        if current != content:
+            print(
+                f"STALE: {DOC_PATH.relative_to(REPO_ROOT)} is out of date.\n"
+                "Run: venv/bin/python scripts/gen_api_limitations.py",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"OK: {DOC_PATH.relative_to(REPO_ROOT)} is up to date.")
+        return 0
+    DOC_PATH.write_text(content)
+    print(f"Wrote {DOC_PATH.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.57.0"
+VERSION = "2.57.2"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.57.0"
+VERSION = "2.57.2"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -10,6 +10,19 @@ Each entry is a small dict. Grow it opportunistically — every readback recipe
 every fix that uncovers a surprising behavior should add an entry. Facts are
 stamped with the Resolve build they were verified on so drift is visible when a
 new version ships.
+
+Optional keys on an entry feed the Blackmagic-facing limitations report
+(``docs/reference/api-limitations.md``, generated by
+``scripts/gen_api_limitations.py``):
+
+  - ``submit``: ``"missing"`` (a capability Blackmagic should add) or ``"bug"``
+    (a behavior Blackmagic should fix). Entries without ``submit`` are internal
+    quirks/tips and stay out of the report.
+  - ``issue``: GitHub issue number (int) that drove the finding, for cross-ref.
+
+When you add or change a ``submit``-tagged entry, regenerate the report
+(``venv/bin/python scripts/gen_api_limitations.py``) or the
+``tests.test_api_limitations_doc`` drift guard fails.
 """
 from typing import Any, Dict, List, Optional
 
@@ -28,6 +41,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "resolve handle, and verify by reading each clip's "
                        "'Synced Audio' property (see verify_by_readback).",
         "tags": ["unreliable-return", "silent-failure", "audio", "enum"],
+        "submit": "bug",
         "mitigation": ["_normalize_auto_sync_settings", "_safe_auto_sync_audio"],
     },
     {
@@ -44,6 +58,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "and verify by reading the timeline's subtitle track count "
                        "before/after (server._safe_create_subtitles).",
         "tags": ["unreliable-return", "silent-failure", "subtitle", "enum"],
+        "submit": "bug",
         "mitigation": ["_normalize_auto_caption_settings", "_safe_create_subtitles"],
     },
     {
@@ -59,6 +74,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "before calling, and treat the bool return from "
                        "Import/RestoreCloudProject as advisory.",
         "tags": ["silent-failure", "project", "cloud", "enum"],
+        "submit": "bug",
         "mitigation": ["_normalize_cloud_settings"],
     },
     {
@@ -75,6 +91,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "(server._timeline_export_spec) before calling; verify the "
                        "output file exists afterward.",
         "tags": ["silent-failure", "timeline", "export", "enum"],
+        "submit": "bug",
         "mitigation": ["_timeline_export_spec", "_timeline_export_value"],
     },
     {
@@ -88,6 +105,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "recommended": "Load/close away from the target first, then retry; use "
                        "src/utils/project_cleanup.py:delete_project_safely.",
         "tags": ["unreliable-return", "project", "flaky"],
+        "submit": "bug",
     },
     {
         "symbol": "Composition.Paste",
@@ -100,6 +118,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "LoadSettings(path) through a temp .setting FILE, which "
                        "round-trips reliably. Identify the new node by name diff.",
         "tags": ["fusion", "bridge", "silent-failure"],
+        "submit": "bug",
     },
     {
         "symbol": "FlowView.SetPos / FlowView.GetPosTable",
@@ -110,6 +129,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "recommended": "Use comp.CurrentFrame.FlowView.SetPos(tool, x, y); confirm "
                        "with GetPosTable and a liberal position parser.",
         "tags": ["fusion", "unreliable-return"],
+        "submit": "bug",
     },
     {
         "symbol": "Timeline.GetTimelineByName",
@@ -117,6 +137,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "reality": "Does not exist. Timelines are looked up by index.",
         "recommended": "Iterate GetTimelineByIndex(1..GetTimelineCount()).",
         "tags": ["missing-method", "timeline"],
+        "submit": "missing",
     },
     {
         "symbol": "Project render methods (AddRenderJob, SetRenderSettings, ...)",
@@ -136,6 +157,7 @@ API_TRUTH: List[Dict[str, Any]] = [
         "recommended": "Treat a trailing ellipsis as truncation (see "
                        "media_pool_item get_transcription's `truncated` flag).",
         "tags": ["transcription", "truncation"],
+        "submit": "bug",
     },
     {
         "symbol": "ProjectManager.CreateProject (with a dirty Untitled project)",
@@ -147,6 +169,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "without a prompt, then CreateProject; restore with "
                        "LoadProject afterward.",
         "tags": ["project", "modal", "silent-failure"],
+        "submit": "bug",
     },
     {
         "symbol": "Timeline.InsertFusionCompositionIntoTimeline",
@@ -158,6 +181,83 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "need a comp to operate on.",
         "tags": ["fusion", "timeline"],
     },
+    {
+        "symbol": "Source Track Selector / destination track for Insert*IntoTimeline",
+        "object": "Timeline",
+        "reality": "There is no API to read or set the Source/Auto Track Selector "
+                   "(the Edit-page patch panel that picks the destination track). "
+                   "InsertTitleIntoTimeline, InsertFusionTitleIntoTimeline, "
+                   "InsertGeneratorIntoTimeline, InsertFusionGeneratorIntoTimeline, "
+                   "InsertOFXGeneratorIntoTimeline and "
+                   "InsertFusionCompositionIntoTimeline take no trackIndex and "
+                   "always drop the clip on the selector's current target (V1 in "
+                   "practice). Locking lower video tracks does NOT redirect the "
+                   "insert — verified live on 21.0.0: locking V1 makes the insert "
+                   "FAIL rather than land on V2. Titles/generators also can't be "
+                   "moved afterward (no MediaPoolItem, so AppendToTimeline clipInfo "
+                   "and MoveClips don't apply).",
+        "recommended": "Accept the limitation for titles/generators (insert lands "
+                       "on V1). For clips that DO have a MediaPoolItem, target a "
+                       "track with MediaPool.AppendToTimeline's clipInfo 'trackIndex' "
+                       "instead (exposed as media_pool append_to_timeline clip_infos). "
+                       "See issue #74.",
+        "tags": ["missing-method", "timeline", "title", "generator", "track"],
+        "submit": "missing",
+        "issue": 74,
+    },
+    {
+        "symbol": "Per-clip audio channel-format conversion (Stereo<->Mono)",
+        "object": "MediaPoolItem / TimelineItem",
+        "reality": "No scripting method converts an individual clip's audio "
+                   "channel format. ConvertTimelineToStereo is timeline-wide, and "
+                   "CreateStereoClip builds a 3D *visual* stereoscopic clip, not an "
+                   "audio mono->stereo change. The Edit-page 'Clip Attributes > "
+                   "Audio' channel mapping is UI-only.",
+        "recommended": "Use the supported surface: timeline add_track with audioType "
+                       "(create mono/stereo tracks), get_track_sub_type (query "
+                       "format), convert_to_stereo (timeline-wide), and "
+                       "timeline_item get_source_audio_channel_mapping. Per-clip "
+                       "conversion is not possible. See issue #73.",
+        "tags": ["missing-method", "audio", "channel"],
+        "submit": "missing",
+        "issue": 73,
+    },
+    {
+        "symbol": "Native multicam clip creation",
+        "object": "MediaPool",
+        "reality": "There is no method to create a native multicam clip from a set "
+                   "of angles. Angles can be stacked onto tracks programmatically, "
+                   "but the multicam-clip conversion is a UI-only step.",
+        "recommended": "Prepare a stacked timeline (media_pool setup_multicam_timeline) "
+                       "and finish the multicam-clip conversion in the Resolve UI.",
+        "tags": ["missing-method", "media-pool", "multicam"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Transition create / copy / clone",
+        "object": "Timeline / TimelineItem",
+        "reality": "The scripting API exposes no method to add, read, copy, or "
+                   "clone an edit transition (cross-dissolve, etc.). Transitions "
+                   "applied in the UI are invisible to and unmodifiable by scripts.",
+        "recommended": "Apply/duplicate transitions in the Resolve UI; no scripted "
+                       "equivalent exists.",
+        "tags": ["missing-method", "timeline", "transition"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Cloud project enumeration / export / user management",
+        "object": "ProjectManager",
+        "reality": "Only CreateCloudProject, LoadCloudProject, ImportCloudProject "
+                   "and RestoreCloudProject exist. There is no GetCloudProjectList "
+                   "(list available cloud projects), no ExportToCloud, and no "
+                   "Add/RemoveUserToCloudProject — so cloud collaboration can't be "
+                   "fully automated.",
+        "recommended": "Drive cloud project listing, export, and collaborator "
+                       "management from the Resolve UI; only create/load/import/"
+                       "restore are scriptable.",
+        "tags": ["missing-method", "project", "cloud"],
+        "submit": "missing",
+    },
     {
         "symbol": "subprocess inheriting stdin under the MCP stdio server",
         "object": "(server runtime)",
@@ -190,3 +290,17 @@ def lookup_api_truth(query: Optional[str] = None) -> List[Dict[str, Any]]:
         if q in hay:
             out.append(e)
     return out
+
+
+def submittable_limitations() -> Dict[str, List[Dict[str, Any]]]:
+    """Group ``submit``-tagged entries for the Blackmagic-facing report.
+
+    Returns ``{"missing": [...], "bug": [...]}`` — entries Blackmagic should add
+    vs. behaviors they should fix — preserving API_TRUTH order within each group.
+    """
+    groups: Dict[str, List[Dict[str, Any]]] = {"missing": [], "bug": []}
+    for e in API_TRUTH:
+        kind = e.get("submit")
+        if kind in groups:
+            groups[kind].append(e)
+    return groups