davinci-resolve-mcp 2.82.0 → 2.82.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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.82.1
+
+Corrects the Resolve version the v2.82.0 subtitle-style validation was actually
+run against.
+
+### Fixed
+
+- **v2.82.0 claimed the subtitle-style write path was confirmed on Resolve 21.
+  It was confirmed on Resolve Studio 19.1.3.** The validation itself stands —
+  Resolve opened the patched track and re-serialised it to its own zstd form
+  with the patched values intact — but it was run against 19.1.3, which is the
+  build that was installed. Corrected in `api_truth`, the codec header, and the
+  changelog. If anything this widens the supported range rather than narrowing
+  it, but the version on the claim has to be the one actually tested.
+- **`GetFairlightPresets` / `ApplyFairlightPresetToCurrentTimeline` require
+  Resolve 20.2.2+**, now recorded in the `api_truth` Fairlight entry. On 19.1.3
+  both are absent (confirmed live), so on older builds the per-parameter gap
+  really is the whole story and the preset workaround is unavailable.
+
 ## What's New in v2.82.0
 
 Caption styling, which the scripting API cannot touch at all, is now readable
@@ -21,7 +40,7 @@ Blackmagic.
   position vector (param 17). New codec at
   `resolve-advanced/vendor/drp-format/subtitle-style.js`.
 
-  Verified live on Resolve 21 (2026-08-06): a patched track opens without error
+  Verified live on Resolve Studio 19.1.3 (2026-08-06): a patched track opens without error
   and, once Resolve next re-serialises it, is written back out in Resolve's own
   zstd form with the patched values intact — so Resolve genuinely parses the
   write rather than passing the bytes through. Read side verified against a

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.82.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.82.1-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.2
 
-**Totals:** 26 missing capabilities, 29 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 30 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -131,7 +131,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 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). The gap is PER-PARAMETER control specifically: a whole saved mix CAN be applied wholesale via Project.ApplyFairlightPresetToCurrentTimeline(name), with the available names from Resolve.GetFairlightPresets() — so 'no Fairlight write path exists' would be too strong.
+- **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). The gap is PER-PARAMETER control specifically: a whole saved mix CAN be applied wholesale via Project.ApplyFairlightPresetToCurrentTimeline(name), with the available names from Resolve.GetFairlightPresets() — so 'no Fairlight write path exists' would be too strong. Both methods require Resolve 20.2.2+; on 19.1.3 they are absent (confirmed live 2026-08-06), so on older builds the per-parameter gap really is the whole story.
 - **Workaround / current handling:** To reapply a known mix, save it once as a Fairlight preset in the UI and apply it per-timeline with ApplyFairlightPresetToCurrentTimeline (exposed as resolve_control get_fairlight_presets + project_settings apply_fairlight_preset). Dial individual levels/pan/EQ/automation/FairlightFX in the Fairlight UI; beyond presets, only voice-isolation state and channel-mapping reads are scriptable.
 - **Tags:** missing-method, audio, fairlight
 
@@ -182,7 +182,7 @@ equivalent, blocking full automation.
 
 - **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 API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on 21.0 (2026-08-06): Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks.
+- **Workaround / current handling:** No API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on Studio 19.1.3 (2026-08-06): Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks.
 - **Tags:** missing-method, subtitle, style, preset
 
 ### Speech recognition engine selection and SRT import
@@ -222,6 +222,15 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** SetCurrentFolder to the target bin first (media_pool set_current_folder), import, then restore the previous current folder if it matters.
 - **Tags:** media-pool, import
 
+### SetClipColor (undocumented value space; marker constants are a decoy)
+
+- **Object:** `TimelineItem / MediaPoolItem`
+- **Signature:** `(colorName) -> bool`
+- **Behavior:** SetClipColor accepts exactly 16 names — the Edit-page clip-colour palette — and refuses everything else with a bare False, no exception and no other signal. Enumerated live on Studio 19.1.3.7 (2026-08-06) against both objects; the accepted set is IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, Pink, Tan, Beige, Brown, Chocolate. The empty string is refused too. The trap is that the scripting reference documents colorName as a bare string with no enumerated values, while exporting the MARKER palette as constants (resolve.MARKER_ROSE, resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary reachable from the API surface is the wrong one. Cyan, Red, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream are all marker-only and all refused. Five names overlap both palettes (Blue, Green, Yellow, Pink, Purple), which is why the decoy survives: reasoning from the marker constants scores 5 of 16 and looks like the right vocabulary with a few gaps.
+- **Workaround / current handling:** Pass only the 16 clip-colour names; on False, treat it as an invalid name rather than an item/lock/page problem. The set is pinned in utils/clip_colors.py and named in the refusal remediation, but deliberately NOT enforced — it was measured on one build and a later Resolve could extend it.
+- **Reference:** [issue #124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124)
+- **Tags:** timeline-item, media-pool, silent-failure, undocumented-enum
+
 ### Project.SetCurrentRenderFormatAndCodec
 
 - **Object:** `Project`
@@ -443,6 +452,15 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #59](https://github.com/samuelgursky/davinci-resolve-mcp/issues/59)
 - **Tags:** render, deliver, silent-failure, id-vs-label
 
+### TimelineItem.SetClipColor on generator/title items
+
+- **Object:** `TimelineItem`
+- **Signature:** `(colorName) -> bool`
+- **Behavior:** On a generator or title item SetClipColor returns True with a VALID colour name and the colour does not persist — GetClipColor still reads '' immediately afterwards, and ClearClipColor changes nothing because there is nothing to clear. Measured on Studio 19.1.3.7 (2026-08-06) on a Solid Color generator. A media-backed item on the SAME timeline in the same session persists correctly (SetClipColor('Teal') -> True, GetClipColor -> 'Teal'), so the bool is honest for some items and a lie for others, with nothing in the return value to tell them apart. A timeline item's colour is also independent of its backing MediaPoolItem's: colouring the item leaves the pool clip at ''.
+- **Workaround / current handling:** Never trust the bool alone — read GetClipColor back and compare. To mark a generator or title, use a timeline marker at its start instead; markers read back reliably.
+- **Reference:** [issue #124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124)
+- **Tags:** timeline-item, silent-failure, generator, readback-lies
+
 ### Project.SetRenderSettings (inherits the loaded preset)
 
 - **Object:** `Project`

package/install.py

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

package/resolve-advanced/vendor/drp-format/subtitle-style.js

@@ -167,7 +167,7 @@ function unwrapEffectFilters(raw) {
  * *compressor* (the bundled fzstd is decompress-only); the cost is a larger
  * blob, which does not matter here.
  *
- * Confirmed live against Resolve 21 (2026-08-06): a subtitle track patched with
+ * Confirmed live against Resolve Studio 19.1.3 (2026-08-06): a subtitle track patched with
  * a 0x80 payload opens without error, and once Resolve next re-serialises that
  * track it writes the style back out as 0x81 zstd with the font descriptor and
  * position preserved exactly — i.e. Resolve genuinely parses the 0x80 form into

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.82.0"
+VERSION = "2.82.1"
 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/granular/timeline_item.py

@@ -1,6 +1,7 @@
 """Timeline item property, keyframe, and clip-level tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+from src.utils.clip_colors import clip_color_refusal
 
 resolve = ResolveProxy()
 
@@ -1528,7 +1529,32 @@ def ti_set_clip_color(color: str, item_index: int = 0, track_type: str = "video"
     item, err = _get_timeline_item(track_type, track_index, item_index)
     if err:
         return err
-    return {"success": bool(item.SetClipColor(color))}
+    returned = bool(item.SetClipColor(color))
+    readback = item.GetClipColor() or ""
+    if not returned:
+        refusal = clip_color_refusal(color)
+        return {
+            "success": False,
+            "color": color,
+            "error": f"SetClipColor refused '{color}'",
+            "reason": refusal["reason"],
+            "remediation": refusal["remediation"],
+            "valid_colors": refusal["state"]["valid_colors"],
+        }
+    if readback != color:
+        # Generator and title items take the call, return True, and drop the
+        # colour (issue #124, Studio 19.1.3.7). Media-backed items persist.
+        return {
+            "success": False,
+            "color": color,
+            "readback": readback,
+            "error": "SetClipColor returned True but the colour did not persist",
+            "remediation": (
+                "Generator and title items accept and discard clip colours; colour "
+                "a media-backed item, or use a timeline marker instead."
+            ),
+        }
+    return {"success": True, "color": color, "readback": readback}
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.82.0"
+VERSION = "2.82.1"
 
 import base64
 import os
@@ -46,6 +46,7 @@ for p in [current_dir, project_dir]:
 from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
+from src.utils import clip_colors as _clip_colors
 from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
@@ -9006,6 +9007,66 @@ def _safe_int(value: Any, default: int, *, minimum: Optional[int] = None, maximu
     return parsed
 
 
+def _set_clip_color_checked(obj, color, *, kind: str):
+    """SetClipColor, with the bare bool turned into something a caller can act on.
+
+    Two measured failures hide behind that bool (issue #124, enumerated live on
+    Studio 19.1.3.7):
+
+    - A name outside the 16-name Edit-page palette is refused with `False` and
+      nothing else. The marker constants are the only colour vocabulary the
+      scripting reference enumerates, so they are what an agent reaches for, and
+      most of them are refused.
+    - On generator and title items the call returns `True` and the colour does
+      not persist — `GetClipColor` still reads empty afterwards. Media-backed
+      items on the same timeline persist correctly, so the bool is honest for
+      some items and a lie for others.
+
+    So the return value is never trusted on its own: the colour is read back and
+    the response reports what actually stuck.
+    """
+    returned = bool(obj.SetClipColor(color))
+    readback = None
+    if _has_method(obj, "GetClipColor"):
+        try:
+            readback = obj.GetClipColor()
+        except Exception:  # pragma: no cover - defensive; getter is documented
+            readback = None
+    persisted = (readback == color) if readback is not None else None
+
+    if not returned:
+        refusal = _clip_colors.clip_color_refusal(color)
+        return _err(
+            f"SetClipColor refused '{color}' on this {kind}",
+            code="CLIP_COLOR_REJECTED",
+            category="invalid_input",
+            reason=refusal["reason"],
+            remediation=refusal["remediation"],
+            state=refusal["state"],
+        )
+    if persisted is False:
+        # The generator/title case. Reporting success here is the silent lie.
+        return {
+            "success": False,
+            "color": color,
+            "readback": readback,
+            "warnings": [{
+                "code": "CLIP_COLOR_NOT_PERSISTED",
+                "message": (
+                    f"SetClipColor returned True on this {kind} but the colour did "
+                    f"not persist — GetClipColor reads {readback!r}. Measured on "
+                    "generator and title items, which take the call and drop it; "
+                    "media-backed items on the same timeline persist correctly."
+                ),
+                "remediation": (
+                    "Colour a media-backed item, or mark the generator another way "
+                    "(a timeline marker at its start reads back reliably)."
+                ),
+            }],
+        }
+    return {"success": True, "color": color, "readback": readback}
+
+
 def _filter_to_keys(settings: Any, allowed) -> Tuple[Dict[str, Any], list]:
     """Whitelist a settings/options dict to the keys a Resolve API documents.
 
@@ -17783,7 +17844,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_clip_color":
         return {"color": clip.GetClipColor()}
     elif action == "set_clip_color":
-        return {"success": bool(clip.SetClipColor(p["color"]))}
+        return _set_clip_color_checked(clip, p["color"], kind="media pool item")
     elif action == "clear_clip_color":
         return {"success": bool(clip.ClearClipColor())}
     elif action == "link_proxy":
@@ -22251,7 +22312,7 @@ def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None)
     elif action == "get_clip_color":
         return {"color": item.GetClipColor()}
     elif action == "set_clip_color":
-        return {"success": bool(item.SetClipColor(p["color"]))}
+        return _set_clip_color_checked(item, p["color"], kind="timeline item")
     elif action == "clear_clip_color":
         return {"success": bool(item.ClearClipColor())}
     return _unknown(action, ["add","get_all","get_by_custom_data","update_custom_data","get_custom_data","delete_by_color","delete_at_frame","delete_by_custom_data","add_flag","get_flags","clear_flags","get_clip_color","set_clip_color","clear_clip_color"])

package/src/utils/api_truth.py

@@ -863,7 +863,10 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "mix CAN be applied wholesale via "
                    "Project.ApplyFairlightPresetToCurrentTimeline(name), with the "
                    "available names from Resolve.GetFairlightPresets() — so "
-                   "'no Fairlight write path exists' would be too strong.",
+                   "'no Fairlight write path exists' would be too strong. Both "
+                   "methods require Resolve 20.2.2+; on 19.1.3 they are absent "
+                   "(confirmed live 2026-08-06), so on older builds the "
+                   "per-parameter gap really is the whole story.",
         "recommended": "To reapply a known mix, save it once as a Fairlight preset "
                        "in the UI and apply it per-timeline with "
                        "ApplyFairlightPresetToCurrentTimeline (exposed as "
@@ -1005,7 +1008,7 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "a normalised position vector (param 17). Exposed as "
                        "project_db list_subtitle_styles / set_subtitle_style "
                        "(font family/size/weight/italic + position). Confirmed "
-                       "live on 21.0 (2026-08-06): Resolve opens a patched track "
+                       "live on Studio 19.1.3 (2026-08-06): Resolve opens a patched track "
                        "and re-serialises it back to its own zstd form with the "
                        "patched values intact, so it genuinely parses the write. "
                        "Caveats: whole-TRACK style not per-caption, project must "
@@ -1421,6 +1424,60 @@ API_TRUTH: List[Dict[str, Any]] = [
         "issue": 59,
         "mitigation": ["_render_format_id", "_render_codec_id"],
     },
+    {
+        "symbol": "SetClipColor (undocumented value space; marker constants are a decoy)",
+        "object": "TimelineItem / MediaPoolItem",
+        "signature": "(colorName) -> bool",
+        "reality": "SetClipColor accepts exactly 16 names — the Edit-page clip-colour "
+                   "palette — and refuses everything else with a bare False, no "
+                   "exception and no other signal. Enumerated live on Studio "
+                   "19.1.3.7 (2026-08-06) against both objects; the accepted set is "
+                   "IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, "
+                   "Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, "
+                   "Pink, Tan, Beige, Brown, Chocolate. The empty string is refused "
+                   "too. The trap is that the scripting reference documents "
+                   "colorName as a bare string with no enumerated values, while "
+                   "exporting the MARKER palette as constants (resolve.MARKER_ROSE, "
+                   "resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary "
+                   "reachable from the API surface is the wrong one. Cyan, Red, "
+                   "Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream "
+                   "are all marker-only and all refused. Five names overlap both "
+                   "palettes (Blue, Green, Yellow, Pink, Purple), which is why the "
+                   "decoy survives: reasoning from the marker constants scores 5 of "
+                   "16 and looks like the right vocabulary with a few gaps.",
+        "recommended": "Pass only the 16 clip-colour names; on False, treat it as an "
+                       "invalid name rather than an item/lock/page problem. The set "
+                       "is pinned in utils/clip_colors.py and named in the refusal "
+                       "remediation, but deliberately NOT enforced — it was measured "
+                       "on one build and a later Resolve could extend it.",
+        "tags": ["timeline-item", "media-pool", "silent-failure", "undocumented-enum"],
+        "submit": "missing",
+        "issue": 124,
+        "mitigation": ["_set_clip_color_checked", "ti_set_clip_color"],
+    },
+    {
+        "symbol": "TimelineItem.SetClipColor on generator/title items",
+        "object": "TimelineItem",
+        "signature": "(colorName) -> bool",
+        "reality": "On a generator or title item SetClipColor returns True with a "
+                   "VALID colour name and the colour does not persist — GetClipColor "
+                   "still reads '' immediately afterwards, and ClearClipColor "
+                   "changes nothing because there is nothing to clear. Measured on "
+                   "Studio 19.1.3.7 (2026-08-06) on a Solid Color generator. A "
+                   "media-backed item on the SAME timeline in the same session "
+                   "persists correctly (SetClipColor('Teal') -> True, GetClipColor "
+                   "-> 'Teal'), so the bool is honest for some items and a lie for "
+                   "others, with nothing in the return value to tell them apart. A "
+                   "timeline item's colour is also independent of its backing "
+                   "MediaPoolItem's: colouring the item leaves the pool clip at ''.",
+        "recommended": "Never trust the bool alone — read GetClipColor back and "
+                       "compare. To mark a generator or title, use a timeline marker "
+                       "at its start instead; markers read back reliably.",
+        "tags": ["timeline-item", "silent-failure", "generator", "readback-lies"],
+        "submit": "bug",
+        "issue": 124,
+        "mitigation": ["_set_clip_color_checked", "ti_set_clip_color"],
+    },
     {
         "symbol": "Project.SetRenderSettings (inherits the loaded preset)",
         "object": "Project",

package/src/utils/clip_colors.py

@@ -0,0 +1,94 @@
+"""The value space of SetClipColor, and an honest refusal when a name misses.
+
+`SetClipColor(colorName) --> Bool` is documented with `colorName` as a bare
+string and no enumerated values anywhere in the scripting reference. The same
+reference *does* export a discoverable colour vocabulary — the marker constants
+(`resolve.MARKER_ROSE`, `resolve.MARKER_FUCHSIA`, …) — so the only colour names
+reachable from the API surface come from the marker palette, and those are
+largely the ones `SetClipColor` refuses. Issue #124 named this a decoy
+vocabulary, which is exactly right.
+
+Enumerated live on **DaVinci Resolve Studio 19.1.3.7 (macOS, 2026-08-06)**
+against both objects that expose the method. Both accept the same 16 names —
+the Edit-page clip-colour palette — and refuse everything else with a bare
+`False`, including every marker-only name and the empty string.
+
+The five names that overlap the two palettes (Blue, Green, Yellow, Pink,
+Purple) are what makes this trap so durable: an agent reasoning from the marker
+constants gets five hits out of sixteen and concludes the vocabulary is right.
+
+This set is deliberately NOT enforced. It was measured on one build, and a
+future Resolve could extend it; hard-rejecting an unlisted name would turn a
+working call into a failure on a build we have not seen. Callers pass the name
+through, and when Resolve refuses, the remediation names the measured-valid set.
+"""
+
+VERIFIED_ON = "DaVinci Resolve Studio 19.1.3.7 (macOS, 2026-08-06)"
+
+# Accepted by BOTH TimelineItem.SetClipColor and MediaPoolItem.SetClipColor.
+CLIP_COLORS = (
+    "Orange", "Apricot", "Yellow", "Lime", "Olive", "Green", "Teal", "Navy",
+    "Blue", "Purple", "Violet", "Pink", "Tan", "Beige", "Brown", "Chocolate",
+)
+
+# Measured refused. Kept explicit because these are the names an agent actually
+# reaches for: every one is either a marker constant or a common colour word.
+REFUSED_NAMES = (
+    "Cyan", "Red", "Fuchsia", "Rose", "Lavender", "Sky", "Mint", "Lemon",
+    "Sand", "Cocoa", "Cream", "Apple", "Magenta", "White", "Black", "Gray",
+    "Grey", "",
+)
+
+# The marker-palette names that are NOT clip colours — the decoy set proper.
+MARKER_ONLY_NAMES = (
+    "Cyan", "Red", "Fuchsia", "Rose", "Lavender", "Sky", "Mint", "Lemon",
+    "Sand", "Cocoa", "Cream",
+)
+
+
+def is_known_clip_color(color) -> bool:
+    """True if `color` is in the measured-valid set. Case-sensitive, as Resolve is."""
+    return isinstance(color, str) and color in CLIP_COLORS
+
+
+def clip_color_refusal(color) -> dict:
+    """Error payload for a SetClipColor that came back False.
+
+    Separates 'you used a marker name' from 'Resolve refused for another
+    reason', because the caller cannot tell them apart from the bare bool.
+    """
+    marker_decoy = isinstance(color, str) and color in MARKER_ONLY_NAMES
+    if marker_decoy:
+        reason = (
+            f"'{color}' is a MARKER colour, not a clip colour. The scripting "
+            "reference enumerates the marker constants and nothing else, so it "
+            "is the vocabulary an agent finds first — and SetClipColor refuses "
+            "most of it with a bare False."
+        )
+    elif is_known_clip_color(color):
+        reason = (
+            f"'{color}' is a valid clip colour on {VERIFIED_ON}, so this refusal "
+            "is about the item or the session, not the name. Note that "
+            "SetClipColor returns True WITHOUT persisting on generator and title "
+            "items — check GetClipColor rather than the bool."
+        )
+    else:
+        reason = (
+            f"'{color}' is not in the clip-colour palette. SetClipColor refuses "
+            "undocumented names with a bare False and no other signal."
+        )
+    return {
+        "reason": reason,
+        "remediation": (
+            "Use one of the 16 Edit-page clip colours: "
+            + ", ".join(CLIP_COLORS)
+            + f". Measured on {VERIFIED_ON}; the set is not enforced here because "
+            "a later build could extend it."
+        ),
+        "state": {
+            "requested_color": color,
+            "valid_colors": list(CLIP_COLORS),
+            "is_marker_only_name": marker_decoy,
+            "verified_on": VERIFIED_ON,
+        },
+    }