davinci-resolve-mcp 2.57.3 → 2.57.5

package/CHANGELOG.md

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

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.57.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.57.5-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)

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.0
 
-**Totals:** 14 missing capabilities, 9 bugs / unreliable behaviors.
+**Totals:** 18 missing capabilities, 11 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -21,14 +21,21 @@ it and stays in sync via a drift guard.
 ### Scope & completeness
 
 This list is **not guaranteed exhaustive.** It combines (a) issues hit
-while building this MCP server and (b) a `dir()` surface audit of the live
+while building this MCP server, (b) a `dir()` surface audit of the live
 Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,
-Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set.
+Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set,
+and (c) a live mutating harness (`tests/live_api_gap_verification.py`)
+that attempts each operation against a disposable project built from
+synthetic media and confirms it fails while a related control succeeds.
 That catches absent methods and documented constraints, but not subtler
 issues: parameters that exist yet misbehave, version-specific regressions,
 or capabilities we simply never exercised. New findings are added as
 `submit`-tagged `api_truth` entries and this document is regenerated.
 
+Note: `hasattr()`/`getattr()` cannot be used to probe this API — the
+Python bridge fabricates a callable for any attribute name (see the
+`hasattr` bug below). Method existence here was checked with `dir()`.
+
 ## Missing Capabilities (please add)
 
 Functionality that exists in the Resolve UI but has no scripting API
@@ -95,7 +102,7 @@ equivalent, blocking full automation.
 ### Clip speed / retime ratio and speed ramps
 
 - **Object:** `TimelineItem`
-- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list (21.0.0).
+- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list AND by live mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'|'RetimeSpeed'|'ClipSpeed', 50) all return False, while SetProperty('RetimeProcess', 1) returns True.
 - **Workaround / current handling:** Set clip speed/retime in the Resolve UI; no scripted equivalent exists.
 - **Tags:** missing-method, timeline, retime, speed
 
@@ -109,7 +116,7 @@ equivalent, blocking full automation.
 ### Fairlight audio levels / pan / EQ / automation / FairlightFX
 
 - **Object:** `TimelineItem / Timeline`
-- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs (21.0.0).
+- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs AND by live mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO transform key, not audio pan, so it misleadingly succeeds).
 - **Workaround / current handling:** Mix in the Fairlight UI; only voice-isolation state and channel-mapping reads are scriptable.
 - **Tags:** missing-method, audio, fairlight
 
@@ -134,6 +141,34 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Create Smart/Power Bins in the Resolve UI; only regular bins are scriptable.
 - **Tags:** missing-method, media-pool, bins
 
+### Per-subtitle text content and timing editing
+
+- **Object:** `TimelineItem (subtitle track)`
+- **Behavior:** TimelineItem on a subtitle track exposes only 21 standard transform/composite properties (Pan, Tilt, ZoomX, Opacity, Crop, etc.). There are no methods to get or set subtitle text (GetText/SetText), start time, end time, or duration for individual subtitle items. Subtitles created via CreateSubtitlesFromAudio or imported via the Resolve UI cannot have their content or timing read or modified programmatically. Verified via dir() and GetProperty() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No workaround exists — subtitle text and timing are completely inaccessible from the scripting API. Must be edited in the Resolve UI.
+- **Tags:** missing-method, subtitle, text, timing
+
+### Subtitle track styling and presets
+
+- **Object:** `TimelineItem / Timeline / Project`
+- **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. TimelineItem.GetProperty() on subtitle items returns only transform/composite keys. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No workaround exists — subtitle styling is UI-only. Burn-in overlays via Fusion titles are a visual alternative but do not produce proper subtitle tracks.
+- **Tags:** missing-method, subtitle, style, preset
+
+### Speech recognition engine selection and SRT import
+
+- **Object:** `Timeline`
+- **Behavior:** Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) always uses the built-in Resolve speech recognition engine. There is no API parameter to select an alternative provider (e.g. whisper-cli, Google Speech, AWS Transcribe). The language selection via resolve.AUTO_CAPTION_LANGUAGE_* is the only customization; the engine itself cannot be changed. Furthermore, there is no API method to import an SRT file into a subtitle track programmatically — File -> Import -> Subtitle is UI-only.
+- **Workaround / current handling:** No workaround exists for provider selection or SRT import. External transcripts must be converted to SRT and imported through the Resolve UI.
+- **Tags:** missing-method, subtitle, transcription, speech-recognition, asr
+
+### Media Pool folder rename
+
+- **Object:** `MediaPool`
+- **Behavior:** MediaPool exposes AddSubFolder(name), DeleteSubFolders([names]), and MoveFolders([names], targetFolder) but no RenameSubFolder(oldName, newName) method. Folders can be created, deleted, and moved, but their names cannot be changed through the API. Verified via dir() on Resolve 21.0.0.
+- **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
+- **Tags:** missing-method, media-pool, folder
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return
@@ -206,3 +241,19 @@ values, or automation-hostile modal prompts.
 - **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
+
+### hasattr() / getattr() on Resolve API objects (attribute fabrication)
+
+- **Object:** `(all Resolve scripting objects)`
+- **Behavior:** The Python bridge returns a callable for ANY attribute name, so hasattr(obj, 'TotallyMadeUpMethod') is always True and getattr never raises. This makes capability detection by hasattr impossible — verified on 21.0.0 (hasattr reported SetStart, Razor, AddNode, GenerateProxy, AddSmartBin etc. as present though none exist). Only dir() lists the real methods.
+- **Workaround / current handling:** Never probe method existence with hasattr/getattr; test membership against dir(obj) instead. Calling a fabricated method typically returns None/False with no error.
+- **Tags:** bridge, introspection, silent-failure
+
+### MediaPoolItem.SetClipProperty('Reel Name', ...)
+
+- **Object:** `MediaPoolItem`
+- **Signature:** `(propertyName, propertyValue) -> bool`
+- **Behavior:** Setting the 'Reel Name' clip property returns True but the value is silently dropped on read-back when the project is configured to derive reel names automatically (General Options > 'Assist using reel names from the:' set to source clip file / embedding / filename pattern). The same True-but-unpersisted behavior occurs via SetMetadata('Reel Name', ...). Other clip properties on the same clip (e.g. 'Comments') write and persist normally, so this is field-specific, not a bridge/permission failure. Verified on Resolve 21.0.0; reported as issue #77.
+- **Workaround / current handling:** After writing 'Reel Name', read it back with GetClipProperty('Reel Name') and refuse to report success on mismatch; surface the project-setting gate to the caller (server._verify_clip_property_writeback).
+- **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
+- **Tags:** unreliable-return, silent-failure, metadata, reel-name

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.57.3"
+VERSION = "2.57.5"
 # 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.3",
+  "version": "2.57.5",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/scripts/gen_api_limitations.py

@@ -85,14 +85,21 @@ def render() -> str:
         "### Scope & completeness",
         "",
         "This list is **not guaranteed exhaustive.** It combines (a) issues hit",
-        "while building this MCP server and (b) a `dir()` surface audit of the live",
+        "while building this MCP server, (b) a `dir()` surface audit of the live",
         "Resolve API objects (ProjectManager, Project, MediaPool, MediaPoolItem,",
-        "Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set.",
+        "Timeline, TimelineItem, Graph) diffed against Resolve's UI feature set,",
+        "and (c) a live mutating harness (`tests/live_api_gap_verification.py`)",
+        "that attempts each operation against a disposable project built from",
+        "synthetic media and confirms it fails while a related control succeeds.",
         "That catches absent methods and documented constraints, but not subtler",
         "issues: parameters that exist yet misbehave, version-specific regressions,",
         "or capabilities we simply never exercised. New findings are added as",
         "`submit`-tagged `api_truth` entries and this document is regenerated.",
         "",
+        "Note: `hasattr()`/`getattr()` cannot be used to probe this API — the",
+        "Python bridge fabricates a callable for any attribute name (see the",
+        "`hasattr` bug below). Method existence here was checked with `dir()`.",
+        "",
         "## Missing Capabilities (please add)",
         "",
         "Functionality that exists in the Resolve UI but has no scripting API",

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.57.3"
+VERSION = "2.57.5"
 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.3"
+VERSION = "2.57.5"
 
 import base64
 import os
@@ -6559,6 +6559,78 @@ def _safe_clip_call(clip, method_name: str, *args):
         return None, str(exc)
 
 
+# Clip-property keys whose SetClipProperty/SetMetadata write returns True but is
+# silently dropped by Resolve under common project configurations (issue #77).
+# For these we read the value back and refuse to report success unless it stuck.
+_WRITEBACK_VERIFY_KEYS = frozenset({"Reel Name"})
+
+# Per-key hint explaining the most common cause of a non-persisting write.
+_WRITEBACK_VERIFY_HINTS = {
+    "Reel Name": (
+        "Reel Name is commonly gated by the project setting "
+        "'General Options > Assist using reel names from the:'. When that is "
+        "set to derive reel names from the source clip / embedding / filename "
+        "pattern, Resolve ignores scripted writes to 'Reel Name' (the call "
+        "still returns True). Set that option to blank/manual, or assign reel "
+        "names in the Resolve UI; the scripting API cannot override the gate."
+    ),
+}
+
+
+def _normalize_clip_property_value(value):
+    """Coerce a clip-property value to a comparable, trimmed string."""
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _verify_clip_property_writeback(clip, key, value):
+    """Confirm a just-written, known-unreliable clip property actually persisted.
+
+    Returns a structured failure dict when Resolve accepted the write (returned
+    True) but the value did not stick on read-back; returns ``None`` when the
+    write verified, the key is not in the watch list, or we cannot read it back
+    (in which case we don't override the original success). See issue #77.
+    """
+    if key not in _WRITEBACK_VERIFY_KEYS:
+        return None
+    actual, err = _safe_clip_call(clip, "GetClipProperty", key)
+    if err is not None:
+        return None  # can't read back — don't contradict the reported result
+    if isinstance(actual, dict):  # GetClipProperty('') style dict, just in case
+        actual = actual.get(key)
+    if _normalize_clip_property_value(actual) == _normalize_clip_property_value(value):
+        return None
+    return {
+        "success": False,
+        "verified": False,
+        "key": key,
+        "requested": value,
+        "actual": actual,
+        "error": (
+            f"Resolve reported success writing {key!r} but the value did not "
+            f"persist (read-back returned {actual!r})."
+        ),
+        "hint": _WRITEBACK_VERIFY_HINTS.get(key),
+    }
+
+
+def _verify_writeback(clip, written):
+    """Verify a batch of just-written {key: value} pairs.
+
+    Returns the first silent-revert failure dict, else ``None``. Only keys in
+    ``_WRITEBACK_VERIFY_KEYS`` are checked, so ordinary writes pay nothing.
+    """
+    if not isinstance(written, dict):
+        return None
+    for key, value in written.items():
+        if key in _WRITEBACK_VERIFY_KEYS:
+            fail = _verify_clip_property_writeback(clip, key, value)
+            if fail:
+                return fail
+    return None
+
+
 def _media_pool_item_summary(clip):
     if not clip:
         return None
@@ -10213,7 +10285,17 @@ def _normalize_metadata(root, mp, p: Dict[str, Any]):
         third_party_ok = True
         for key, value in third_party.items():
             third_party_ok = bool(clip.SetThirdPartyMetadata(key, value)) and third_party_ok
-        results.append({"clip_id": clip_id, "success": ok and third_party_ok})
+        row = {"clip_id": clip_id, "success": ok and third_party_ok}
+        if ok and metadata:
+            silent = _verify_writeback(clip, metadata)
+            if silent:
+                row["success"] = False
+                row["verified"] = False
+                row["unpersisted"] = {silent["key"]: silent["actual"]}
+                row["error"] = silent["error"]
+                if silent.get("hint"):
+                    row["hint"] = silent["hint"]
+        results.append(row)
     return {"success": all(row.get("success") for row in results), "count": len(results), "missing": missing, "results": results}
 
 
@@ -15696,8 +15778,18 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"metadata": _ser(clip.GetMetadata(p.get("key", "")))}
     elif action == "set_metadata":
         if "metadata" in p:
-            return {"success": bool(clip.SetMetadata(p["metadata"]))}
-        return {"success": bool(clip.SetMetadata(p["key"], p["value"]))}
+            ok = bool(clip.SetMetadata(p["metadata"]))
+            if ok:
+                silent = _verify_writeback(clip, p["metadata"])
+                if silent:
+                    return silent
+            return {"success": ok}
+        ok = bool(clip.SetMetadata(p["key"], p["value"]))
+        if ok:
+            silent = _verify_clip_property_writeback(clip, p["key"], p["value"])
+            if silent:
+                return silent
+        return {"success": ok}
     elif action == "get_third_party_metadata":
         return {"metadata": _ser(clip.GetThirdPartyMetadata(p.get("key", "")))}
     elif action == "set_third_party_metadata":
@@ -15707,7 +15799,12 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_clip_property":
         return {"properties": _ser(clip.GetClipProperty(p.get("key", "")))}
     elif action == "set_clip_property":
-        return {"success": bool(clip.SetClipProperty(p["key"], p["value"]))}
+        ok = bool(clip.SetClipProperty(p["key"], p["value"]))
+        if ok:
+            silent = _verify_clip_property_writeback(clip, p["key"], p["value"])
+            if silent:
+                return silent
+        return {"success": ok}
     elif action == "get_clip_color":
         return {"color": clip.GetClipColor()}
     elif action == "set_clip_color":

package/src/utils/api_truth.py

@@ -290,7 +290,10 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "MotionEstimation) and transform/crop/composite/opacity keys — "
                    "not the speed value itself. There is no way to set a clip to a "
                    "given % speed, reverse it, or author a speed ramp. Verified "
-                   "against the documented SetProperty key list (21.0.0).",
+                   "against the documented SetProperty key list AND by live "
+                   "mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'"
+                   "|'RetimeSpeed'|'ClipSpeed', 50) all return False, while "
+                   "SetProperty('RetimeProcess', 1) returns True.",
         "recommended": "Set clip speed/retime in the Resolve UI; no scripted "
                        "equivalent exists.",
         "tags": ["missing-method", "timeline", "retime", "speed"],
@@ -319,7 +322,10 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "automation, or to add/configure FairlightFX. SetProperty covers "
                    "video transform only; the audio surface is read-only "
                    "(GetSourceAudioChannelMapping, GetAudioMapping, voice "
-                   "isolation). Verified via dir() + SetProperty docs (21.0.0).",
+                   "isolation). Verified via dir() + SetProperty docs AND by live "
+                   "mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'"
+                   "|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO "
+                   "transform key, not audio pan, so it misleadingly succeeds).",
         "recommended": "Mix in the Fairlight UI; only voice-isolation state and "
                        "channel-mapping reads are scriptable.",
         "tags": ["missing-method", "audio", "fairlight"],
@@ -360,6 +366,94 @@ API_TRUTH: List[Dict[str, Any]] = [
         "tags": ["missing-method", "media-pool", "bins"],
         "submit": "missing",
     },
+    {
+        "symbol": "Per-subtitle text content and timing editing",
+        "object": "TimelineItem (subtitle track)",
+        "reality": "TimelineItem on a subtitle track exposes only 21 standard "
+                   "transform/composite properties (Pan, Tilt, ZoomX, Opacity, "
+                   "Crop, etc.). There are no methods to get or set subtitle "
+                   "text (GetText/SetText), start time, end time, or duration "
+                   "for individual subtitle items. Subtitles created via "
+                   "CreateSubtitlesFromAudio or imported via the Resolve UI "
+                   "cannot have their content or timing read or modified "
+                   "programmatically. Verified via dir() and GetProperty() on "
+                   "Resolve 21.0.0.48.",
+        "recommended": "No workaround exists — subtitle text and timing are "
+                       "completely inaccessible from the scripting API. Must "
+                       "be edited in the Resolve UI.",
+        "tags": ["missing-method", "subtitle", "text", "timing"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Subtitle track styling and presets",
+        "object": "TimelineItem / Timeline / Project",
+        "reality": "There is no API method to set or query subtitle font "
+                   "family, font size, text color, background color, outline, "
+                   "shadow, position, alignment, or to apply/query subtitle "
+                   "style presets. TimelineItem.GetProperty() on subtitle "
+                   "items returns only transform/composite keys. "
+                   "Timeline.GetSetting() and Project.GetSetting() return "
+                   "None for all probed subtitle-style keys (e.g. "
+                   "'subtitleFontName', 'subtitleFontSize', "
+                   "'subtitleTextColor', 'subtitleBackgroundColor', "
+                   "'subtitlePosition', 'subtitleAlignment', "
+                   "'subtitlePreset', 'subtitleStyle'). Verified via dir(), "
+                   "GetProperty(), and GetSetting() on Resolve 21.0.0.48.",
+        "recommended": "No workaround exists — subtitle styling is UI-only. "
+                       "Burn-in overlays via Fusion titles are a visual "
+                       "alternative but do not produce proper subtitle tracks.",
+        "tags": ["missing-method", "subtitle", "style", "preset"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Speech recognition engine selection and SRT import",
+        "object": "Timeline",
+        "reality": "Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) "
+                   "always uses the built-in Resolve speech recognition "
+                   "engine. There is no API parameter to select an alternative "
+                   "provider (e.g. whisper-cli, Google Speech, AWS Transcribe). "
+                   "The language selection via resolve.AUTO_CAPTION_LANGUAGE_* "
+                   "is the only customization; the engine itself cannot be "
+                   "changed. Furthermore, there is no API method to import an "
+                   "SRT file into a subtitle track programmatically — "
+                   "File -> Import -> Subtitle is UI-only.",
+        "recommended": "No workaround exists for provider selection or SRT "
+                       "import. External transcripts must be converted to SRT "
+                       "and imported through the Resolve UI.",
+        "tags": ["missing-method", "subtitle", "transcription",
+                 "speech-recognition", "asr"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "Media Pool folder rename",
+        "object": "MediaPool",
+        "reality": "MediaPool exposes AddSubFolder(name), "
+                   "DeleteSubFolders([names]), and "
+                   "MoveFolders([names], targetFolder) but no "
+                   "RenameSubFolder(oldName, newName) method. Folders can be "
+                   "created, deleted, and moved, but their names cannot be "
+                   "changed through the API. Verified via dir() on Resolve "
+                   "21.0.0.",
+        "recommended": "Delete and recreate the folder with the desired name, "
+                       "or rename in the Resolve UI.",
+        "tags": ["missing-method", "media-pool", "folder"],
+        "submit": "missing",
+    },
+    {
+        "symbol": "hasattr() / getattr() on Resolve API objects (attribute fabrication)",
+        "object": "(all Resolve scripting objects)",
+        "reality": "The Python bridge returns a callable for ANY attribute name, so "
+                   "hasattr(obj, 'TotallyMadeUpMethod') is always True and getattr "
+                   "never raises. This makes capability detection by hasattr "
+                   "impossible — verified on 21.0.0 (hasattr reported SetStart, "
+                   "Razor, AddNode, GenerateProxy, AddSmartBin etc. as present "
+                   "though none exist). Only dir() lists the real methods.",
+        "recommended": "Never probe method existence with hasattr/getattr; test "
+                       "membership against dir(obj) instead. Calling a fabricated "
+                       "method typically returns None/False with no error.",
+        "tags": ["bridge", "introspection", "silent-failure"],
+        "submit": "bug",
+    },
     {
         "symbol": "subprocess inheriting stdin under the MCP stdio server",
         "object": "(server runtime)",
@@ -370,6 +464,29 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "run while serving over stdio.",
         "tags": ["runtime", "stdio", "subprocess"],
     },
+    {
+        "symbol": "MediaPoolItem.SetClipProperty('Reel Name', ...)",
+        "object": "MediaPoolItem",
+        "signature": "(propertyName, propertyValue) -> bool",
+        "reality": "Setting the 'Reel Name' clip property returns True but the "
+                   "value is silently dropped on read-back when the project is "
+                   "configured to derive reel names automatically "
+                   "(General Options > 'Assist using reel names from the:' set "
+                   "to source clip file / embedding / filename pattern). The "
+                   "same True-but-unpersisted behavior occurs via "
+                   "SetMetadata('Reel Name', ...). Other clip properties on the "
+                   "same clip (e.g. 'Comments') write and persist normally, so "
+                   "this is field-specific, not a bridge/permission failure. "
+                   "Verified on Resolve 21.0.0; reported as issue #77.",
+        "recommended": "After writing 'Reel Name', read it back with "
+                       "GetClipProperty('Reel Name') and refuse to report "
+                       "success on mismatch; surface the project-setting gate to "
+                       "the caller (server._verify_clip_property_writeback).",
+        "tags": ["unreliable-return", "silent-failure", "metadata", "reel-name"],
+        "submit": "bug",
+        "issue": 77,
+        "mitigation": ["_verify_clip_property_writeback", "_verify_writeback"],
+    },
 ]